Auto-install iii-lsp binary in VS Code extension

.github/workflows/ci.yml

@@ -109,5 +109,8 @@ jobs:
       - name: Install dependencies
         run: npm ci
 
+      - name: Run tests
+        run: npm test
+
       - name: Package check (dry run)
-        run: npx @vscode/vsce package --out tmp.vsix && rm -f tmp.vsix
+        run: npm run package:check

iii-lsp-vscode/AGENTS.md

@@ -0,0 +1,11 @@
+# iii-lsp-vscode Agent Notes
+
+Use containers for Node commands. Do not install host-global Node packages.
+
+```bash
+cd iii-lsp-vscode
+docker build -t iii-lsp-vscode-dev .
+docker run --rm -u "$(id -u):$(id -g)" -v "$PWD:/workspace" -w /workspace iii-lsp-vscode-dev npm ci
+docker run --rm -u "$(id -u):$(id -g)" -v "$PWD:/workspace" -w /workspace iii-lsp-vscode-dev npm test
+docker run --rm -u "$(id -u):$(id -g)" -v "$PWD:/workspace" -w /workspace iii-lsp-vscode-dev npm run package:check
+```

iii-lsp-vscode/Dockerfile

@@ -0,0 +1,3 @@
+FROM node:20-bookworm
+
+WORKDIR /workspace

iii-lsp-vscode/Makefile

@@ -0,0 +1,29 @@
+.PHONY: image install test package-check build install-cursor clean
+
+IMAGE ?= iii-lsp-vscode-dev
+VSIX ?= iii-lsp.vsix
+NPM_CACHE ?= /tmp/npm-cache
+
+DOCKER_RUN = docker run --rm -u "$$(id -u):$$(id -g)" -e npm_config_cache=$(NPM_CACHE) -v "$(CURDIR):/workspace" -w /workspace $(IMAGE)
+
+image:
+	docker build -t $(IMAGE) .
+
+install: image
+	$(DOCKER_RUN) npm ci
+
+test: image
+	$(DOCKER_RUN) npm test
+
+package-check: image
+	$(DOCKER_RUN) npm run package:check
+
+build: image
+	$(DOCKER_RUN) npm ci
+	$(DOCKER_RUN) npx vsce package --out $(VSIX)
+
+install-cursor: build
+	cursor --install-extension $(VSIX) --force
+
+clean:
+	rm -f $(VSIX) iii-lsp-cursor.vsix iii-lsp-smoke.vsix tmp.vsix

iii-lsp-vscode/README.md

@@ -1,6 +1,8 @@
 # III Language Server - VS Code Extension
 
-Autocompletion, hover documentation, and diagnostics for [III engine](https://github.com/iii-org) functions and triggers.
+Autocompletion, hover documentation, and diagnostics for [III engine](https://github.com/iii-hq/iii) functions and triggers.
+
+![III LSP demo](./lsp.gif)
 
 ## Supported Languages
 
@@ -10,21 +12,20 @@ Autocompletion, hover documentation, and diagnostics for [III engine](https://gi
 
 ## Prerequisites
 
-1. **iii-lsp binary** - Build it from the `iii-lsp/` crate:
+1. **iii-lsp binary** - The extension downloads and installs the pinned `iii-lsp/v0.1.0` binary on first activation.
 
-   ```bash
-   cd iii-lsp
-   cargo build --release
-   ```
+   The binary is stored under VS Code's extension global storage directory and the absolute path is saved to `iii-lsp.serverPath` in global settings.
 
-   Then either:
-   - Add `iii-lsp/target/release` to your `PATH`, or
-   - Set the binary path in the extension settings (see below)
+   To use a custom binary instead, set `iii-lsp.serverPath` to an existing executable path before activation.
 
 2. **III engine** running locally (default: `ws://127.0.0.1:49134`)
 
 ## Installation
 
+After the extension is installed, open a supported TypeScript, TSX, Python, or Rust file to activate it. On first activation, the extension downloads the matching `iii-lsp/v0.1.0` binary, verifies its SHA-256 checksum, installs it under extension global storage, and saves the installed path to `iii-lsp.serverPath`.
+
+If automatic install fails, the extension warns and falls back to the configured `iii-lsp.serverPath` or `iii-lsp` on `PATH`.
+
 ### From source (development)
 
 1. Install dependencies:
@@ -62,11 +63,29 @@ Autocompletion, hover documentation, and diagnostics for [III engine](https://gi
    code --install-extension iii-lsp-*.vsix
    ```
 
+### Local smoke test with Cursor
+
+Build a local VSIX and install it in Cursor:
+
+```bash
+cd iii-lsp-vscode
+make build
+cursor --install-extension iii-lsp.vsix --force
+```
+
+Open a supported file to activate the extension:
+
+```bash
+cursor ../iii-lsp/src/main.rs
+```
+
+After activation, `iii-lsp.serverPath` should point to the downloaded binary in Cursor settings. To install the same VSIX in VS Code instead, replace `cursor` with `code`.
+
 ## Settings
 
 | Setting | Default | Description |
 |---------|---------|-------------|
-| `iii-lsp.serverPath` | `""` (uses `iii-lsp` from PATH) | Path to the `iii-lsp` binary |
+| `iii-lsp.serverPath` | `""` (auto-filled after first activation) | Path to the installed or custom `iii-lsp` binary |
 | `iii-lsp.engineUrl` | `ws://127.0.0.1:49134` | WebSocket URL of the III engine |
 
 Configure via **Settings** > search "III LSP", or in `settings.json`:

iii-lsp-vscode/extension.js

@@ -1,12 +1,24 @@
-const { workspace } = require("vscode");
+const vscode = require("vscode");
 const { LanguageClient, TransportKind } = require("vscode-languageclient/node");
 
+const { ensureServerBinary } = require("./installer");
+
 let client;
 
-function activate(context) {
-  const config = workspace.getConfiguration("iii-lsp");
-  const serverPath = config.get("serverPath") || "iii-lsp";
+async function activate(context) {
+  const config = vscode.workspace.getConfiguration("iii-lsp");
   const engineUrl = config.get("engineUrl") || "ws://127.0.0.1:49134";
+  let serverPath;
+
+  try {
+    serverPath = await ensureServerBinary(context, vscode);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    vscode.window.showWarningMessage(
+      `Failed to install iii-lsp binary. Falling back to configured path or PATH lookup. ${message}`
+    );
+    serverPath = config.get("serverPath") || "iii-lsp";
+  }
 
   const serverOptions = {
     run: {