Developing Bun Console

Prerequisites

• Java 25. WebStorm’s bundled JBR works: point JAVA_HOME at <WebStorm>/jbr.
• Bun 1.4+ on PATH (runtime tests and the plugin itself).
• Node.js installed at C:/Program Files/nodejs/node.exe for the debugger tests (the Bun debug adapter runs on Node.js; the tests configure that interpreter path).
• The Gradle wrapper pins Gradle 9.3.1 and the IntelliJ Platform Gradle Plugin 2.x.

Build and test

$env:JAVA_HOME = "$env:LOCALAPPDATA\Programs\WebStorm\jbr"
.\gradlew.bat -PwebstormPath="$env:LOCALAPPDATA\Programs\WebStorm" test buildPlugin verifyPlugin
bun test .\tests\runtime\bootstrap.test.mjs

Without -PwebstormPath, Gradle downloads WebStorm 2026.2.3. The plugin archive is written to build/distributions/bun-console-<version>.zip.

• test runs the IDE tests in src/test/kotlin in a headless WebStorm (one JVM per test class; about four minutes). They start real Bun processes and, for the debugger tests, WebStorm’s Bun debug adapter.
• bun test tests/runtime/bootstrap.test.mjs tests the runtime script directly over its socket protocol (seconds).
• -PplatformType=IU runs the same tests in IntelliJ IDEA Ultimate 2026.2.3 instead of WebStorm, without the Bun plugin (IDEA does not bundle it), so the debugger tests are skipped there. IDEA’s licensing component fails headless; ConsoleTestCase ignores only that error in this run.
• verifyPlugin runs Plugin Verifier against the target IDE. It must report Compatible; only the approved Experimental DAP usages may be listed (see debugger-blocker.md).

Sandbox IDE

On Windows, double-click run-ide.bat (or run it): it uses the Java bundled with WebStorm (%WEBSTORM_PATH%, default %LOCALAPPDATA%\Programs\WebStorm), so nothing needs to be set up. The same by hand:

.\gradlew.bat -PwebstormPath="$env:LOCALAPPDATA\Programs\WebStorm" runIde

runIde starts WebStorm with the plugin in a separate profile under build/isolated-ide; your own WebStorm settings and windows are not touched. Open tests/runtime/fixtures as the project: it contains manual test files (see its README) that follow the acceptance checks.

In the sandbox IDE the plugin writes a development trace to build/bun-console-trace.log: every input, output fragment, status and tab change, editor switch and message exchanged with Bun. It is enabled only by the bun.console.trace system property that runIde sets.

Layout

Path	Contents
src/main/resources/runtime/bootstrap.mjs	The Bun side: REPL, context bindings, lazy modules, socket protocol
src/main/kotlin/dev/bunconsole/runtime	Bun process, input preparation (ConsoleImports), declarations, trace
src/main/kotlin/dev/bunconsole/service	BunConsoleProjectService: lifecycle, contexts, reloads, status
src/main/kotlin/dev/bunconsole/debug	Debugger attachment and paused-frame evaluation
src/main/kotlin/dev/bunconsole/ui	Tool window, input, tabs, actions, completion
tests/runtime	Runtime tests and the manual-test fixtures
docs/	Acceptance checks, debugger notes, publishing guide, investigation notes

Runtime protocol

The IDE listens on a loopback port and starts Bun with the port and a one-time token in its environment; the bootstrap connects back and sends {"event":"ready","token":…}. Requests are JSON lines {id, op, …} answered by {id, ok, …}; console output travels as {event: "output", text, level} on the same socket, so it stays in order with results.

Operation	Purpose
eval	Run console input (code, imports, declarations); replies with text and the user’s globals
load	Make a file the editor context (path, declared, dependencies) without running it
add_file / remove_file	Add or remove a pinned/added context file
add_symbol	Bind one top-level declaration of a file
reload_file	Re-read a changed context file; it runs again on next use
cached_files	Loaded module paths, to detect changed dependencies
ping	Answered outside the command queue; a late answer means the JavaScript thread is busy

Further notes

• Acceptance checks — automated and manual checks before a release.
• Debugger integration — why and how the Experimental DAP facade is used.
• Publishing — Marketplace and GitHub release guide.
• Phase 0 findings and the original handout — the initial investigation and requirements.
• WebStorm startup issue — an IDE error unrelated to the plugin.