feat: add local VS Code extension installation command

Build the debug adapter, package a local VSIX, and install it through the configurable VS Code CLI. Document setup and exclude development files from the package.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

.gitignore

@@ -2,3 +2,4 @@ target/
 vscode/node_modules/
 vscode/out/
 vscode/.vscode-test/
+vscode/*.vsix

CHANGELOG.md

@@ -6,6 +6,8 @@ All notable changes to this project will be documented in this file.
 
 ### Added
 
+- Add `mise run install-extension` to build the debug adapter, package the VS Code
+  extension, and install it locally using `code` (or `VSCODE_CLI`).
 - Add a standalone Rust `runa-dap` stdio debug adapter for VS Code actor debugging.
 - Expose `behavior.rn` for every actor in the graphical and VS Code trees, with
   actor-specific gutter breakpoints and source diagnostics.

README.md

@@ -260,6 +260,12 @@ the runtime contract.
 
 ## VS Code client
 
+To install into your regular VS Code instance, run `npm --prefix vscode ci`
+followed by `mise run install-extension`, then reload the window. This builds the
+Rust debug adapter and packages/installs the extension using the local `code`
+CLI. Set `VSCODE_CLI` to choose another executable, such as `code-insiders`.
+See [extension setup](vscode/README.md#run-from-source) for debugger configuration.
+
 With Node.js 22+ and npm installed, run `npm --prefix vscode ci`. In VS Code,
 open this repository and launch **Run Runa Extension** from Run and Debug
 (F5). Start `mise run start`, then use **Runa: Connect to Local Image**

mise.toml

@@ -17,6 +17,10 @@ run = [
 description = "Test the extension in VS Code (requires a display or xvfb-run)"
 run = "npm --prefix vscode run test:host"
 
+[tasks.install-extension]
+description = "Package and install the extension in local VS Code"
+run = ["cargo build -p runa-dap", "npm --prefix vscode run install:local"]
+
 [tasks.start]
 description = "Start the Runa image server on localhost"
 run = "cargo run -p runa"

vscode/.prettierignore

@@ -2,3 +2,4 @@ node_modules/
 out/
 package-lock.json
 .vscode-test/
+*.vsix

vscode/.vscodeignore

@@ -0,0 +1,10 @@
+src/**
+test/**
+integration/**
+scripts/**
+.vscode-test/**
+.prettier*
+tsconfig.json
+out/test/**
+out/integration/**
+*.vsix

vscode/README.md

@@ -9,6 +9,24 @@ hosts actors or starts its own image.
 
 Requirements: VS Code 1.96+, Node.js 22+, npm, and the repository's Rust toolchain.
 
+To package and install the extension in your regular local VS Code instance,
+run from the repository root:
+
+```sh
+npm --prefix vscode ci
+mise run install-extension
+```
+
+This builds `runa-dap`, compiles the extension, packages `vscode/runa.vsix`, and
+installs it with `code --install-extension ... --force`. Reload the VS Code window
+after installation. Set `VSCODE_CLI` to a different CLI executable if necessary,
+for example `VSCODE_CLI=code-insiders mise run install-extension`.
+Set `runa.debugAdapterPath` to the absolute path of `target/debug/runa-dap`
+to enable debugging (or install `runa-dap` on PATH). Installation does not change
+your VS Code settings or start an image. The VSIX uses the local extension ID
+`runa.runa`; packaging is local-only and skips the currently absent license and
+repository metadata checks, not publication.
+
 From the repository root:
 
 ```sh

vscode/package.json

@@ -1,5 +1,6 @@
 {
   "name": "runa",
+  "publisher": "runa",
   "displayName": "Runa — Rune Actors",
   "description": "Edit image source files and inspect and control actors in a trusted localhost Runa image.",
   "version": "0.0.0",
@@ -21,6 +22,8 @@
   ],
   "scripts": {
     "compile": "tsc -p .",
+    "package": "npm run compile && vsce package --allow-missing-repository --no-rewrite-relative-links --skip-license --out runa.vsix",
+    "install:local": "npm run package && node scripts/install-local.cjs",
     "lint": "tsc -p . --noEmit && prettier --check .",
     "format": "prettier --write .",
     "test": "npm run compile && node --test out/test/*.test.js",
@@ -32,6 +35,7 @@
     "ws": "^8.18.3"
   },
   "devDependencies": {
+    "@vscode/vsce": "^4.1.0",
     "@vscode/test-electron": "^2.5.2",
     "@types/node": "^22.0.0",
     "@types/vscode": "~1.96.0",

vscode/scripts/install-local.cjs

@@ -0,0 +1,17 @@
+const { spawnSync } = require("node:child_process");
+const { resolve } = require("node:path");
+
+const command = process.env.VSCODE_CLI || "code";
+const result = spawnSync(
+  command,
+  ["--install-extension", resolve(__dirname, "../runa.vsix"), "--force"],
+  { stdio: "inherit" },
+);
+if (result.error) {
+  console.error(`Could not run ${command}: ${result.error.message}`);
+  console.error("Set VSCODE_CLI to the VS Code CLI executable if it is not on PATH.");
+  process.exitCode = 1;
+} else if (result.status !== 0) {
+  console.error(`VS Code extension installation failed (${result.signal || result.status}).`);
+  process.exitCode = result.status || 1;
+}