codehost 0.1.0 → 0.1.1

package/README.md

@@ -20,15 +20,32 @@ directly; a tiny Cloudflare Worker only brokers the handshake.
 
 ## Quickstart
 
-On the machine you want to edit (needs the `code` CLI and [Bun](https://bun.sh)):
+On the machine you want to edit, run the one-line installer — it installs
+[Bun](https://bun.sh) if needed, the `codehost` CLI, and then `codehost setup`
+(picks a token, installs VS Code, and starts a server):
 
 ```bash
-bunx codehost serve -d -t <token>
+# macOS / Linux
+curl -fsSL https://codehost.dev/install.sh | sh
+
+# Windows (PowerShell)
+powershell -c "irm codehost.dev/install.ps1 | iex"
 ```
 
-Then open **https://codehost.dev**, enter the same `<token>`, and your server
-appears in the list. Click **Connect** — VS Code loads in the page, served
-entirely over the peer-to-peer data channel.
+Already have Bun? `bun add -g codehost && codehost setup` does the same. Or, for
+a specific directory/token in one shot:
+
+```bash
+bunx codehost setup ~/my-project -t <token>
+```
+
+Then open **https://codehost.dev**, enter the token printed by `setup`, and your
+server appears in the list. Click **Connect** — VS Code loads in the page,
+served entirely over the peer-to-peer data channel.
+
+> Use `setup` (not `bunx codehost serve`) for the first run: `setup` installs
+> everything and self-heals the native WebRTC module that a bare `bunx` can't
+> fetch on its own.
 
 The `<token>` is a shared secret: anyone with it can see and connect to the
 servers in that room, so treat it like a password. It must be **at least 12
@@ -39,11 +56,25 @@ weaker tokens (e.g. `Str0ng-Token-99`).
 ## CLI
 
 ```bash
+codehost setup [dir] [-t <token>]           # token + VS Code + daemon, one shot
 codehost serve [dir] -t <token> [options]   # serve a directory (default: cwd)
 codehost list                                # list daemonized servers (oxmgr)
 codehost stop <name>                         # stop a daemonized server
+codehost update                              # fetch the latest VS Code CLI now
 ```
 
+**`codehost setup`** is the easy path: it reuses (or generates and saves to
+`~/.codehost/config.json`) a strong room token, ensures a working VS Code,
+starts the server under oxmgr, and prints the token + URL. Pass `-t` to set a
+token explicitly, or `--new-token` to rotate the saved one.
+
+**VS Code is auto-installed.** On first `serve`, codehost uses a `code` already
+on your `PATH` if present; otherwise it downloads Microsoft's standalone VS Code
+CLI for your OS/arch (verifying its sha256), caches it under `~/.codehost/vscode/`,
+and re-checks the stable channel at most once per day. Force a refresh with
+`codehost update`, or point at a specific binary with the `CODEHOST_CODE_BIN`
+environment variable.
+
 `serve` options:
 
 | flag | default | meaning |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codehost",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "type": "module",
   "bin": {
     "codehost": "./src/cli/index.ts"

package/public/install.ps1

@@ -0,0 +1,43 @@
+# codehost installer — https://codehost.dev
+#
+#   powershell -c "irm codehost.dev/install.ps1 | iex"
+#
+# Ensures Bun is installed, installs the `codehost` CLI globally (which fetches
+# the native WebRTC binary via Bun's lifecycle scripts), then runs `codehost
+# setup` to pick a token, install VS Code, and start a server daemon.
+#
+# Env override: $env:CODEHOST_NO_SETUP = "1"  -> install only, skip setup.
+
+$ErrorActionPreference = "Stop"
+
+function Info($m) { Write-Host "[codehost] $m" -ForegroundColor Cyan }
+function Fail($m) { Write-Host "[codehost] $m" -ForegroundColor Red; exit 1 }
+
+# Bun installs its global bin under %USERPROFILE%\.bun\bin by default.
+$bunBin = Join-Path $env:USERPROFILE ".bun\bin"
+if (Test-Path $bunBin) { $env:Path = "$bunBin;$env:Path" }
+
+if (-not (Get-Command bun -ErrorAction SilentlyContinue)) {
+  Info "Bun not found - installing from bun.sh..."
+  Invoke-RestMethod https://bun.sh/install.ps1 | Invoke-Expression
+  if (Test-Path $bunBin) { $env:Path = "$bunBin;$env:Path" }
+}
+
+if (-not (Get-Command bun -ErrorAction SilentlyContinue)) {
+  Fail "Bun install did not land on PATH. Open a new terminal and re-run."
+}
+
+Info "installing the codehost CLI (bun add -g codehost)..."
+bun add -g codehost
+
+if (-not (Get-Command codehost -ErrorAction SilentlyContinue)) {
+  Fail "codehost installed but not on PATH. Add $bunBin to PATH and run: codehost setup"
+}
+
+if ($env:CODEHOST_NO_SETUP -eq "1") {
+  Info "installed. Run ``codehost setup`` in the directory you want to serve."
+  exit 0
+}
+
+Info "running ``codehost setup``..."
+codehost setup

package/public/install.sh

@@ -0,0 +1,55 @@
+#!/bin/sh
+# codehost installer — https://codehost.dev
+#
+#   curl -fsSL https://codehost.dev/install.sh | sh
+#
+# Ensures Bun is installed, installs the `codehost` CLI globally (which fetches
+# the native WebRTC binary via Bun's lifecycle scripts), then runs `codehost
+# setup` to pick a token, install VS Code, and start a server daemon.
+#
+# Env overrides:
+#   CODEHOST_NO_SETUP=1   install only; don't run `codehost setup`
+set -eu
+
+info() { printf '\033[1;36m[codehost]\033[0m %s\n' "$1"; }
+err()  { printf '\033[1;31m[codehost]\033[0m %s\n' "$1" >&2; }
+
+# Bun installs its global bin here by default; make sure it's on PATH for both
+# the bun we may install and the `codehost` we're about to install.
+BUN_INSTALL="${BUN_INSTALL:-$HOME/.bun}"
+export BUN_INSTALL
+export PATH="$BUN_INSTALL/bin:$PATH"
+
+if ! command -v bun >/dev/null 2>&1; then
+  info "Bun not found — installing from bun.sh…"
+  if command -v curl >/dev/null 2>&1; then
+    curl -fsSL https://bun.sh/install | bash
+  elif command -v wget >/dev/null 2>&1; then
+    wget -qO- https://bun.sh/install | bash
+  else
+    err "need curl or wget to install Bun. Install one and re-run."
+    exit 1
+  fi
+  export PATH="$BUN_INSTALL/bin:$PATH"
+fi
+
+if ! command -v bun >/dev/null 2>&1; then
+  err "Bun install did not land on PATH. Open a new shell or add $BUN_INSTALL/bin to PATH, then re-run."
+  exit 1
+fi
+
+info "installing the codehost CLI (bun add -g codehost)…"
+bun add -g codehost
+
+if ! command -v codehost >/dev/null 2>&1; then
+  err "codehost installed but not on PATH. Add $BUN_INSTALL/bin to your PATH and run: codehost setup"
+  exit 1
+fi
+
+if [ "${CODEHOST_NO_SETUP:-}" = "1" ]; then
+  info "installed. Run \`codehost setup\` in the directory you want to serve."
+  exit 0
+fi
+
+info "running \`codehost setup\`…"
+exec codehost setup

package/src/cli/commands/serve.ts

@@ -7,7 +7,7 @@ import { SignalingClient } from "../../shared/signaling-client";
 import { RtcDaemon } from "../rtc-daemon";
 import { launchVscode } from "../vscode";
 import { Tunnel } from "../tunnel";
-import { daemonName, startDaemon } from "../oxmgr";
+import { launchServeDaemon } from "../daemonize";
 
 export const DEFAULT_SIGNAL_URL = "wss://signal.codehost.dev";
 
@@ -74,16 +74,15 @@ export const serveCommand: CommandModule<{}, ServeArgs> = {
 
     // `-d`: re-launch this same `serve` (without -d) under oxmgr, then exit.
     if (argv.daemon) {
-      const label = argv.name ?? dir.split("/").pop() ?? host;
-      const name = daemonName(label);
-      const command = buildForegroundCommand(dir, argv);
-      console.log(`[codehost] starting daemon "${name}" via oxmgr`);
-      const ok = startDaemon({ name, command, cwd: dir });
-      if (ok) {
-        console.log(`[codehost] daemon started. View: codehost list · Stop: codehost stop ${name}`);
-        process.exit(0);
-      }
-      process.exit(1);
+      const { ok } = launchServeDaemon({
+        dir,
+        token: argv.token,
+        signal: argv.signal,
+        name: argv.name,
+        port: argv.port,
+        host,
+      });
+      process.exit(ok ? 0 : 1);
     }
 
     // peerId is fixed up front so VS Code can be mounted under /vs/<peerId>,
@@ -135,19 +134,3 @@ export const serveCommand: CommandModule<{}, ServeArgs> = {
     await new Promise<never>(() => {});
   },
 };
-
-/**
- * Reconstruct the exact foreground `serve` invocation (without -d) for oxmgr to
- * run. Uses the same runtime + entry script that launched us, so it works both
- * for `bunx codehost` and local `bun src/cli/index.ts`.
- */
-function buildForegroundCommand(dir: string, argv: ServeArgs): string {
-  const parts = [process.execPath, process.argv[1], "serve", dir, "-t", argv.token, "--signal", argv.signal];
-  if (argv.name) parts.push("--name", argv.name);
-  if (argv.port) parts.push("--port", String(argv.port));
-  return parts.map(quote).join(" ");
-}
-
-function quote(s: string): string {
-  return /[^A-Za-z0-9_\/:=.-]/.test(s) ? `'${s.replace(/'/g, `'\\''`)}'` : s;
-}

package/src/cli/commands/setup.ts

@@ -0,0 +1,96 @@
+import { hostname } from "node:os";
+import { resolve } from "node:path";
+import type { CommandModule } from "yargs";
+import { generateToken, validateToken, TOKEN_REQUIREMENTS } from "../../shared/token";
+import { readConfig, writeConfig } from "../config";
+import { launchServeDaemon } from "../daemonize";
+import { resolveCodeBinary } from "../vscode-install";
+import { DEFAULT_SIGNAL_URL } from "./serve";
+
+const PAGE_URL = "https://codehost.dev";
+
+interface SetupArgs {
+  dir: string;
+  token?: string;
+  newToken: boolean;
+  name?: string;
+  signal: string;
+  port?: number;
+}
+
+export const setupCommand: CommandModule<{}, SetupArgs> = {
+  command: "setup [dir]",
+  describe: "One-shot: pick a token, ensure VS Code, and start a daemonized server",
+  builder: (y) =>
+    y
+      .positional("dir", { describe: "Directory to serve (defaults to cwd)", type: "string", default: "." })
+      .option("token", {
+        alias: "t",
+        describe: "Room token (generated + saved if omitted)",
+        type: "string",
+      })
+      .option("new-token", {
+        describe: "Generate a fresh token even if one is saved",
+        type: "boolean",
+        default: false,
+      })
+      .option("name", { describe: "Display name for this server (defaults to hostname)", type: "string" })
+      .option("signal", { describe: "Signaling server URL", type: "string", default: DEFAULT_SIGNAL_URL })
+      .option("port", { describe: "Fixed port for the local VS Code server", type: "number" }) as any,
+  handler: async (argv) => {
+    const dir = resolve(process.cwd(), argv.dir);
+    const host = hostname();
+
+    // 1. Resolve the room token: validate an explicit one, otherwise reuse the
+    //    saved token (stable room URL) or mint and persist a strong new one.
+    const token = resolveToken(argv);
+    console.log(`[codehost] room token: ${token}`);
+
+    // 2. Make sure a working VS Code is available, installing/upgrading the
+    //    managed CLI if the system `code` is missing or broken. Doing it here
+    //    surfaces download progress before we hand off to the daemon.
+    console.log("[codehost] checking VS Code…");
+    const codeBin = await resolveCodeBinary();
+    console.log(`[codehost] using VS Code: ${codeBin}`);
+
+    // 3. Start the WebRTC + VS Code server under oxmgr.
+    const { ok, name } = launchServeDaemon({
+      dir,
+      token,
+      signal: argv.signal,
+      name: argv.name,
+      port: argv.port,
+      host,
+    });
+    if (!ok) process.exit(1);
+
+    // 4. Tell the user how to connect.
+    console.log("");
+    console.log(`[codehost] ✓ server "${name}" is live, serving ${dir}`);
+    console.log(`[codehost] open ${PAGE_URL} and enter your token to connect.`);
+    console.log(`[codehost] manage it with: codehost list · codehost stop ${name}`);
+  },
+};
+
+function resolveToken(argv: SetupArgs): string {
+  if (argv.token) {
+    const t = argv.token.trim();
+    const check = validateToken(t);
+    if (!check.ok) {
+      console.error(`[codehost] ${check.reason}`);
+      console.error(`[codehost] room token requires: ${TOKEN_REQUIREMENTS}`);
+      process.exit(1);
+    }
+    // Persist an explicit token too, so later `setup` runs reuse the same room.
+    writeConfig({ ...readConfig(), token: t });
+    return t;
+  }
+
+  const config = readConfig();
+  if (config.token && !argv.newToken) return config.token;
+
+  const token = generateToken();
+  writeConfig({ ...config, token });
+  console.log("[codehost] generated a new room token (saved to ~/.codehost/config.json)");
+  return token;
+}

package/src/cli/commands/update.ts

@@ -0,0 +1,19 @@
+import type { CommandModule } from "yargs";
+import { resolveCodeBinary } from "../vscode-install";
+
+export const updateCommand: CommandModule = {
+  command: "update",
+  describe: "Download the latest VS Code CLI now (ignores the daily check throttle)",
+  handler: async () => {
+    if (process.env.CODEHOST_CODE_BIN) {
+      console.log(`[codehost] CODEHOST_CODE_BIN is set; nothing to update (${process.env.CODEHOST_CODE_BIN})`);
+      return;
+    }
+    if (Bun.which("code")) {
+      console.log("[codehost] using system `code` on PATH; update it with your package manager.");
+      return;
+    }
+    const bin = await resolveCodeBinary({ force: true });
+    console.log(`[codehost] up to date: ${bin}`);
+  },
+};

package/src/cli/config.ts

@@ -0,0 +1,27 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+// Persistent CLI config under ~/.codehost (same root as the managed VS Code
+// cache in vscode-install.ts). Currently just the reusable room token so
+// `codehost setup` lands on a stable room URL across runs.
+
+const CONFIG_FILE = join(homedir(), ".codehost", "config.json");
+
+export interface CliConfig {
+  /** Room token reused by `setup` until --new-token or an explicit -t. */
+  token?: string;
+}
+
+export function readConfig(): CliConfig {
+  try {
+    return JSON.parse(readFileSync(CONFIG_FILE, "utf8")) as CliConfig;
+  } catch {
+    return {};
+  }
+}
+
+export function writeConfig(config: CliConfig): void {
+  mkdirSync(dirname(CONFIG_FILE), { recursive: true });
+  writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2));
+}

package/src/cli/daemonize.ts

@@ -0,0 +1,54 @@
+import { daemonName, startDaemon } from "./oxmgr";
+
+export interface ServeDaemonOptions {
+  /** Absolute directory to serve. */
+  dir: string;
+  /** Room token (already validated). */
+  token: string;
+  /** Signaling server URL. */
+  signal: string;
+  /** Display name; also seeds the oxmgr process label. */
+  name?: string;
+  /** Fixed local VS Code port. */
+  port?: number;
+  /** Hostname, used as a label fallback. */
+  host: string;
+}
+
+export interface ServeDaemonResult {
+  ok: boolean;
+  /** oxmgr process name this server was registered under. */
+  name: string;
+}
+
+/**
+ * Launch a foreground `codehost serve` (without -d) under oxmgr so it survives
+ * the shell and restarts on failure. Shared by `serve -d` and `setup`.
+ */
+export function launchServeDaemon(opts: ServeDaemonOptions): ServeDaemonResult {
+  const label = opts.name ?? opts.dir.split("/").pop() ?? opts.host;
+  const name = daemonName(label);
+  const command = buildForegroundCommand(opts);
+  console.log(`[codehost] starting daemon "${name}" via oxmgr`);
+  const ok = startDaemon({ name, command, cwd: opts.dir });
+  if (ok) {
+    console.log(`[codehost] daemon started. View: codehost list · Stop: codehost stop ${name}`);
+  }
+  return { ok, name };
+}
+
+/**
+ * Reconstruct the exact foreground `serve` invocation (without -d) for oxmgr to
+ * run. Uses the same runtime + entry script that launched us, so it works both
+ * for `bunx codehost` and local `bun src/cli/index.ts`.
+ */
+function buildForegroundCommand(opts: ServeDaemonOptions): string {
+  const parts = [process.execPath, process.argv[1], "serve", opts.dir, "-t", opts.token, "--signal", opts.signal];
+  if (opts.name) parts.push("--name", opts.name);
+  if (opts.port) parts.push("--port", String(opts.port));
+  return parts.map(quote).join(" ");
+}
+
+function quote(s: string): string {
+  return /[^A-Za-z0-9_\/:=.-]/.test(s) ? `'${s.replace(/'/g, `'\\''`)}'` : s;
+}

package/src/cli/index.ts

@@ -1,16 +1,20 @@
 #!/usr/bin/env bun
 import yargs from "yargs";
 import { hideBin } from "yargs/helpers";
+import { setupCommand } from "./commands/setup";
 import { serveCommand } from "./commands/serve";
 import { listCommand } from "./commands/list";
 import { stopCommand } from "./commands/stop";
+import { updateCommand } from "./commands/update";
 
 yargs(hideBin(process.argv))
   .scriptName("codehost")
   .usage("$0 <command> [options]")
+  .command(setupCommand)
   .command(serveCommand)
   .command(listCommand)
   .command(stopCommand)
+  .command(updateCommand)
   .demandCommand(1, "Specify a command, e.g. `codehost serve`")
   .strict()
   .help()

package/src/cli/rtc-daemon.ts

@@ -1,3 +1,5 @@
+import { spawnSync } from "node:child_process";
+import { dirname } from "node:path";
 import { createRequire } from "node:module";
 import type {
   DataChannel,
@@ -10,7 +12,61 @@ import { ICE_SERVERS, type RtcSignal } from "../shared/rtc";
 // resolves correctly from the project's node_modules. So load it via require;
 // the `import type` above is erased at build time and triggers no runtime load.
 const require = createRequire(import.meta.url);
-const ndc = require("node-datachannel") as typeof import("node-datachannel");
+const ndc = loadNodeDataChannel();
+
+/**
+ * Load the native node-datachannel addon, self-healing the common failure where
+ * its prebuilt `.node` was never fetched. That happens under `bunx codehost`:
+ * bunx skips install lifecycle scripts (and `trustedDependencies` only applies
+ * to `bun install`), so node-datachannel's `install` step — which downloads the
+ * binary via `prebuild-install` — never runs. On the first load failure we run
+ * that prebuild-install ourselves, then retry. A normal `bun add -g` install
+ * already has the binary, so this is a no-op there.
+ */
+function loadNodeDataChannel(): typeof import("node-datachannel") {
+  try {
+    return require("node-datachannel") as typeof import("node-datachannel");
+  } catch (firstErr) {
+    if (!fetchNodeDataChannelBinary()) throw nativeLoadError(firstErr);
+    try {
+      return require("node-datachannel") as typeof import("node-datachannel");
+    } catch (secondErr) {
+      throw nativeLoadError(secondErr);
+    }
+  }
+}
+
+/** Run node-datachannel's bundled `prebuild-install` to fetch the prebuilt
+ *  binary. Returns true if it exited cleanly. */
+function fetchNodeDataChannelBinary(): boolean {
+  let pkgDir: string;
+  let prebuildBin: string;
+  try {
+    pkgDir = dirname(require.resolve("node-datachannel/package.json"));
+    // prebuild-install is a dependency of node-datachannel; resolve its CLI
+    // entry from the package's own module scope.
+    prebuildBin = require.resolve("prebuild-install/bin.js", { paths: [pkgDir] });
+  } catch {
+    return false;
+  }
+  console.log("[codehost] fetching node-datachannel native binary (prebuild-install)…");
+  const r = spawnSync(process.execPath, [prebuildBin, "-r", "napi"], {
+    cwd: pkgDir,
+    stdio: "inherit",
+  });
+  return r.status === 0;
+}
+
+function nativeLoadError(cause: unknown): Error {
+  return new Error(
+    "Failed to load the native WebRTC module (node-datachannel). Its prebuilt " +
+      "binary could not be fetched automatically. Install codehost globally so " +
+      "install scripts run — `bun add -g codehost` (or `npm i -g codehost`) — " +
+      "and ensure network access. If your platform has no prebuilt, a C++ " +
+      "toolchain + cmake is needed to build from source. " +
+      `(cause: ${(cause as Error)?.message ?? cause})`,
+  );
+}
 
 export interface RtcDaemonOptions {
   /** Relay a signal to a viewer peer via the signaling channel. */

package/src/cli/vscode-install.ts

@@ -0,0 +1,222 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { readdir } from "node:fs/promises";
+import { homedir, tmpdir } from "node:os";
+import { join } from "node:path";
+
+// Resolves a runnable VS Code CLI binary for `code serve-web`. Strategy
+// ("managed, prefer system"): honor an explicit override, then a system `code`
+// on PATH, otherwise download + cache Microsoft's standalone ~31MB "VS Code
+// CLI" binary for this platform. The standalone CLI fully supports serve-web
+// with the same flags as a full install. Update cadence is "check but cache":
+// the managed binary's version is re-checked against the stable channel at most
+// once per ~24h; otherwise the cached binary is used with no network call.
+
+const CACHE_ROOT = join(homedir(), ".codehost", "vscode");
+const STATE_FILE = join(CACHE_ROOT, "state.json");
+const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
+const UPDATE_API = "https://update.code.visualstudio.com/api/update";
+
+interface Manifest {
+  url: string;
+  version: string;
+  productVersion: string;
+  sha256hash: string;
+}
+
+interface State {
+  /** Commit-style version id from the manifest. */
+  version: string;
+  /** Human version, e.g. "1.123.0". */
+  productVersion: string;
+  /** Absolute path to the extracted `code`/`code.exe`. */
+  binPath: string;
+  /** Wall-clock ms of the last manifest check. */
+  checkedAt: number;
+}
+
+/**
+ * Return a path (or bare `"code"`) that can be spawned to run `serve-web`.
+ * Downloads and caches the standalone CLI on first use when no system VS Code
+ * is available. `opts.force` skips the 24h throttle (used by `codehost update`).
+ */
+export async function resolveCodeBinary(opts: { force?: boolean } = {}): Promise<string> {
+  const override = process.env.CODEHOST_CODE_BIN;
+  if (override) {
+    if (!existsSync(override)) {
+      throw new Error(`CODEHOST_CODE_BIN points to a missing file: ${override}`);
+    }
+    return override;
+  }
+
+  // Prefer a user-owned `code` on PATH — but only if it actually runs. A broken
+  // or stub `code` should fall through to a managed install/upgrade.
+  const system = Bun.which("code");
+  if (system && runsOk(system)) return system;
+
+  return ensureManagedBinary(opts.force ?? false);
+}
+
+async function ensureManagedBinary(force: boolean): Promise<string> {
+  const key = platformKey();
+  const state = readState();
+
+  const fresh = state && existsSync(state.binPath) && Date.now() - state.checkedAt < CHECK_INTERVAL_MS;
+  if (fresh && !force) return state!.binPath;
+
+  let manifest: Manifest;
+  try {
+    manifest = await fetchManifest(key);
+  } catch (err) {
+    // Offline: fall back to whatever we have cached, otherwise fail loudly.
+    if (state && existsSync(state.binPath)) {
+      console.warn(`[codehost] could not check for VS Code updates (${(err as Error).message}); using cached ${state.productVersion}`);
+      return state.binPath;
+    }
+    throw new Error(
+      `Unable to download VS Code and none is cached: ${(err as Error).message}. ` +
+        `Install VS Code's \`code\` CLI manually, or set CODEHOST_CODE_BIN to an existing binary.`,
+    );
+  }
+
+  // Already on the latest stable: just refresh the throttle timestamp.
+  if (state && state.version === manifest.version && existsSync(state.binPath)) {
+    writeState({ ...state, checkedAt: Date.now() });
+    return state.binPath;
+  }
+
+  console.log(`[codehost] installing VS Code ${manifest.productVersion} (${key})…`);
+  const binPath = await downloadAndExtract(manifest, key);
+  writeState({
+    version: manifest.version,
+    productVersion: manifest.productVersion,
+    binPath,
+    checkedAt: Date.now(),
+  });
+  console.log(`[codehost] VS Code ${manifest.productVersion} ready at ${binPath}`);
+  return binPath;
+}
+
+/** Map this host to a `cli-<os>-<arch>` key understood by the update API. */
+function platformKey(): string {
+  const arch = process.arch; // "x64" | "arm64" | "arm" | ...
+  if (process.platform === "darwin") {
+    return arch === "arm64" ? "cli-darwin-arm64" : "cli-darwin-x64";
+  }
+  if (process.platform === "win32") {
+    return arch === "arm64" ? "cli-win32-arm64" : "cli-win32-x64";
+  }
+  // Linux: distinguish musl (Alpine) from glibc, and map arch.
+  const os = isMusl() ? "alpine" : "linux";
+  if (arch === "arm64") return `cli-${os}-arm64`;
+  if (arch === "arm") return `cli-${os}-armhf`;
+  return `cli-${os}-x64`;
+}
+
+/** True if `<bin> --version` exits cleanly — i.e. the binary actually works. */
+function runsOk(bin: string): boolean {
+  const r = spawnSync(bin, ["--version"], { stdio: "ignore", timeout: 10_000 });
+  return r.status === 0;
+}
+
+function isMusl(): boolean {
+  if (existsSync("/etc/alpine-release")) return true;
+  // `ldd --version` mentions "musl" on musl systems; ignore failures.
+  const r = spawnSync("ldd", ["--version"], { encoding: "utf8" });
+  return /musl/i.test(`${r.stdout ?? ""}${r.stderr ?? ""}`);
+}
+
+async function fetchManifest(key: string): Promise<Manifest> {
+  const res = await fetch(`${UPDATE_API}/${key}/stable/latest`);
+  if (!res.ok) throw new Error(`manifest HTTP ${res.status} for ${key}`);
+  const m = (await res.json()) as Partial<Manifest>;
+  if (!m.url || !m.version || !m.sha256hash) {
+    throw new Error(`malformed manifest for ${key}`);
+  }
+  return {
+    url: m.url,
+    version: m.version,
+    productVersion: m.productVersion ?? m.version,
+    sha256hash: m.sha256hash,
+  };
+}
+
+async function downloadAndExtract(manifest: Manifest, key: string): Promise<string> {
+  mkdirSync(CACHE_ROOT, { recursive: true });
+  const isZip = manifest.url.endsWith(".zip");
+  const tmpArchive = join(tmpdir(), `codehost-vscode-${manifest.version}${isZip ? ".zip" : ".tar.gz"}`);
+
+  const res = await fetch(manifest.url);
+  if (!res.ok) throw new Error(`download HTTP ${res.status}`);
+  await Bun.write(tmpArchive, res);
+
+  await verifySha256(tmpArchive, manifest.sha256hash);
+
+  // Extract into a fresh temp dir, then move the single binary into the cache.
+  const extractDir = join(tmpdir(), `codehost-vscode-x-${manifest.version}`);
+  rmSync(extractDir, { recursive: true, force: true });
+  mkdirSync(extractDir, { recursive: true });
+  // bsdtar (macOS / Windows 10+) extracts .zip via `tar -xf`; GNU tar handles
+  // the Linux .tar.gz with `-xzf`.
+  const tarArgs = isZip ? ["-xf", tmpArchive] : ["-xzf", tmpArchive];
+  const tar = spawnSync("tar", [...tarArgs, "-C", extractDir], { encoding: "utf8" });
+  if (tar.status !== 0) {
+    throw new Error(`failed to extract VS Code archive: ${tar.stderr ?? tar.error?.message ?? "tar error"}`);
+  }
+
+  const exe = process.platform === "win32" ? "code.exe" : "code";
+  const found = await findFile(extractDir, exe);
+  if (!found) throw new Error(`extracted archive did not contain ${exe}`);
+
+  const destDir = join(CACHE_ROOT, manifest.version);
+  rmSync(destDir, { recursive: true, force: true });
+  mkdirSync(destDir, { recursive: true });
+  const destBin = join(destDir, exe);
+  renameSync(found, destBin);
+  if (process.platform !== "win32") {
+    const { chmodSync } = await import("node:fs");
+    chmodSync(destBin, 0o755);
+  }
+
+  rmSync(tmpArchive, { force: true });
+  rmSync(extractDir, { recursive: true, force: true });
+  return destBin;
+}
+
+async function verifySha256(path: string, expected: string): Promise<void> {
+  const hasher = new Bun.CryptoHasher("sha256");
+  hasher.update(await Bun.file(path).arrayBuffer());
+  const actual = hasher.digest("hex");
+  if (actual.toLowerCase() !== expected.toLowerCase()) {
+    rmSync(path, { force: true });
+    throw new Error(`sha256 mismatch (expected ${expected}, got ${actual})`);
+  }
+}
+
+/** Shallow-first search for a file named `name` under `dir`. */
+async function findFile(dir: string, name: string): Promise<string | null> {
+  const entries = await readdir(dir, { withFileTypes: true });
+  for (const e of entries) {
+    if (e.isFile() && e.name === name) return join(dir, e.name);
+  }
+  for (const e of entries) {
+    if (e.isDirectory()) {
+      const hit = await findFile(join(dir, e.name), name);
+      if (hit) return hit;
+    }
+  }
+  return null;
+}
+
+function readState(): State | null {
+  try {
+    return JSON.parse(readFileSync(STATE_FILE, "utf8")) as State;
+  } catch {
+    return null;
+  }
+}
+
+function writeState(state: State): void {
+  mkdirSync(CACHE_ROOT, { recursive: true });
+  writeFileSync(STATE_FILE, JSON.stringify(state, null, 2));
+}

package/src/cli/vscode.ts

@@ -1,4 +1,5 @@
 import { spawn, type Subprocess } from "bun";
+import { resolveCodeBinary } from "./vscode-install";
 
 export interface VscodeServer {
   port: number;
@@ -37,8 +38,9 @@ export async function launchVscode(opts: LaunchOptions): Promise<VscodeServer> {
     "--accept-server-license-terms",
   ];
 
-  console.log(`[codehost] launching: code ${args.join(" ")}`);
-  const proc = spawn(["code", ...args], {
+  const codeBin = await resolveCodeBinary();
+  console.log(`[codehost] launching: ${codeBin} ${args.join(" ")}`);
+  const proc = spawn([codeBin, ...args], {
     cwd: opts.dir,
     stdout: "inherit",
     stderr: "inherit",