coderaft 0.0.31 → 0.0.32

package/README.md

@@ -100,6 +100,9 @@ Creates a code-server handler without binding to a port.
 | `defaultFolder`   | `string`              | Workspace folder opened when no input is given in the URL.                   |
 | `connectionToken` | `string`              | Shared auth secret. Disabled for localhost, auto-generated for remote hosts. |
 | `host`            | `string`              | Host/interface to bind. Used to infer whether to require a token.            |
+| `baseURL`         | `string`              | Base URL the server is mounted under (e.g. `/code`). Defaults to `/`.        |
+| `proxyURI`        | `string`              | Proxy URI template for forwarded ports (see [Port Proxy](#port-proxy)).      |
+| `extensions`      | `string[]`            | Extensions to preinstall before start (see [Extensions](#extensions)).       |
 | `vscode`          | `VSCodeServerOptions` | Extra options forwarded to VS Code's internal `createServer()`.              |
 
 Returns a `CodeServerHandler`:
@@ -163,17 +166,48 @@ await instance.close();
 
 Options cross an IPC boundary, so nested values (`vscode`, etc.) must be JSON-compatible.
 
+## Extensions
+
+Preinstall extensions when an instance starts by passing an `extensions` array. Ids resolve from the [Open VSX](https://open-vsx.org) registry by default — the same gallery the in-editor Extensions view uses.
+
+```ts
+import { startCodeServer } from "coderaft";
+
+const instance = await startCodeServer({
+  defaultFolder: "/path/to/workspace",
+  extensions: [
+    "esbenp.prettier-vscode", // gallery id
+    "dbaeumer.vscode-eslint@3.0.24", // pin a version
+    "/abs/path/to/local.vsix", // local .vsix file
+  ],
+});
+```
+
+Works with `createCodeServer`, `startCodeServer`, and `spawnCodeServer`, and on the CLI:
+
+```sh
+coderaft --install-extension esbenp.prettier-vscode --install-extension dbaeumer.vscode-eslint
+```
+
+- **Idempotent** — already-installed extensions are skipped, so warm restarts pay no cost. Installs run only when something is missing.
+- **Non-blocking on failure** — a bad id or a gallery outage is logged as a warning; the server still starts.
+- Installs into the server's extensions dir (`--extensions-dir`, default `~/.vscode-server-oss/extensions`), so they persist across restarts.
+
+> [!NOTE]
+> Installation runs in a short-lived child process before the server boots (VS Code's extension CLI calls `process.exit()` when done). The first cold start with new extensions takes ~1s longer per extension; subsequent starts are instant.
+
 ## CLI Options
 
 ### Server
 
-| Option                        | Description                                         |
-| ----------------------------- | --------------------------------------------------- |
-| `-p, --port <port>`           | Port to listen on (default: `$PORT` or `6063`)      |
-| `-H, --host <host>`           | Host/interface to bind                              |
-| `--base-url <path>`           | Base URL the server is mounted under (default: `/`) |
-| `--socket-path <path>`        | Path to a socket file to listen on                  |
-| `--print-startup-performance` | Print startup timing to stdout                      |
+| Option                        | Description                                                            |
+| ----------------------------- | ---------------------------------------------------------------------- |
+| `-p, --port <port>`           | Port to listen on (default: `$PORT` or `6063`)                         |
+| `-H, --host <host>`           | Host/interface to bind                                                 |
+| `--base-url <path>`           | Base URL the server is mounted under (default: `/`)                    |
+| `--proxy-uri <template>`      | Proxy URI template for forwarded ports (see [Port Proxy](#port-proxy)) |
+| `--socket-path <path>`        | Path to a socket file to listen on                                     |
+| `--print-startup-performance` | Print startup timing to stdout                                         |
 
 ### Auth
 
@@ -241,12 +275,13 @@ Options cross an IPC boundary, so nested values (`vscode`, etc.) must be JSON-co
 
 ### Features
 
-| Option                               | Description                                       |
-| ------------------------------------ | ------------------------------------------------- |
-| `--enable-sync`                      | Enable settings sync                              |
-| `--enable-proposed-api <ext-id>`     | Enable proposed API for an extension (repeatable) |
-| `--disable-workspace-trust`          | Disable workspace trust                           |
-| `--disable-getting-started-override` | Disable getting started override                  |
+| Option                               | Description                                                                       |
+| ------------------------------------ | --------------------------------------------------------------------------------- |
+| `--enable-sync`                      | Enable settings sync                                                              |
+| `--install-extension <ext-id>`       | Preinstall an extension from Open VSX (repeatable, see [Extensions](#extensions)) |
+| `--enable-proposed-api <ext-id>`     | Enable proposed API for an extension (repeatable)                                 |
+| `--disable-workspace-trust`          | Disable workspace trust                                                           |
+| `--disable-getting-started-override` | Disable getting started override                                                  |
 
 ### Remote
 
@@ -291,6 +326,32 @@ Options cross an IPC boundary, so nested values (`vscode`, etc.) must be JSON-co
 | `--crash-reporter-directory <dir>` | Crash reporter directory            |
 | `--crash-reporter-id <id>`         | Crash reporter ID                   |
 
+## Port Proxy
+
+When a VS Code extension or the terminal opens a local URL (e.g. `http://localhost:3000`), coderaft proxies it through the browser. By default, ports are proxied via a path-based scheme:
+
+```
+https://example.com/proxy/3000/
+```
+
+When using `--base-url`, the base path is automatically prepended:
+
+```sh
+coderaft --base-url /code
+# → https://example.com/code/proxy/3000/
+```
+
+For subdomain-based proxying, use `--proxy-uri` with a `{{port}}` placeholder:
+
+```sh
+coderaft --proxy-uri "https://{{port}}.proxy.example.com/"
+# → https://3000.proxy.example.com/
+```
+
+Subdomain proxying requires external infrastructure (wildcard DNS + reverse proxy) — coderaft's built-in proxy handler only supports path-based routing.
+
+The `VSCODE_PROXY_URI` environment variable can also be used and takes the same template format.
+
 ## Sponsors
 
 <p align="center">

package/code.mjs

@@ -4,7 +4,7 @@ import { tmpdir } from "node:os";
 import { fileURLToPath } from "node:url";
 
 // Auto-updated by scripts/pack.ts
-const codeArchiveHash = "1e825760090ea31b";
+const codeArchiveHash = "02cc4256d084fb3a";
 
 const archivePath = fileURLToPath(new URL("./code.tar.zst", import.meta.url));
 

package/dist/_chunks/_args.mjs

@@ -8,6 +8,7 @@ const cliOptions = {
 		short: "H"
 	},
 	"base-url": { type: "string" },
+	"proxy-uri": { type: "string" },
 	"server-base-path": { type: "string" },
 	"socket-path": { type: "string" },
 	"print-startup-performance": { type: "boolean" },
@@ -44,6 +45,10 @@ const cliOptions = {
 	"disable-update-check": { type: "boolean" },
 	"disable-experiments": { type: "boolean" },
 	"enable-sync": { type: "boolean" },
+	"install-extension": {
+		type: "string",
+		multiple: true
+	},
 	"disable-extensions": { type: "boolean" },
 	"disable-extension": {
 		type: "string",
@@ -135,6 +140,7 @@ const helpText = `
     -p, --port <port>                    Port to listen on (default: $PORT or 6063)
     -H, --host <host>                    Host/interface to bind
         --base-url <path>                Base URL the server is mounted under (default: /)
+        --proxy-uri <template>           Proxy URI template ({{port}} is replaced with port number)
         --socket-path <path>             Path to a socket file to listen on
         --print-startup-performance      Print startup timing to stdout
 
@@ -180,6 +186,7 @@ const helpText = `
 
   Features:
         --enable-sync                    Enable settings sync
+        --install-extension <ext-id>     Preinstall an extension from Open VSX before start (repeatable)
         --disable-extensions             Disable all installed extensions
         --disable-extension <ext-id>     Disable specific extension (repeatable)
         --enable-proposed-api <ext-id>   Enable proposed API for extension (repeatable)

package/dist/_chunks/libs/httpxy.mjs

@@ -80,7 +80,7 @@ function setupOutgoing(outgoing, options, req, forward) {
 }
 function joinURL(base, path) {
 	if (!base || base === "/") return path || "/";
-	if (!path) return base;
+	if (!path || path === "/") return base || "/";
 	const baseHasTrailing = base[base.length - 1] === "/";
 	const pathHasLeading = path[0] === "/";
 	if (baseHasTrailing && pathHasLeading) return base + path.slice(1);
@@ -562,4 +562,4 @@ function _createProxyFn(type, server) {
 		return callbackPromise;
 	};
 }
-export { createProxyServer as t };
+export { createProxyServer };

package/dist/_chunks/server.mjs

@@ -1,12 +1,24 @@
-import { n as __require, t as __exportAll } from "./rolldown-runtime.mjs";
-import { t as createProxyServer } from "./libs/httpxy.mjs";
+import { createProxyServer } from "./libs/httpxy.mjs";
+import { createRequire } from "node:module";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { createReadStream, readFileSync, readdirSync, unlinkSync } from "node:fs";
+import { fork } from "node:child_process";
 import { randomBytes, randomUUID } from "node:crypto";
 import { createServer } from "node:http";
 import { extname, join, normalize, sep } from "node:path";
 import { stat } from "node:fs/promises";
 import { loadCode } from "#code";
+var __defProp = Object.defineProperty;
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) __defProp(target, name, {
+		get: all[name],
+		enumerable: true
+	});
+	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
+	return target;
+};
+var __require = /* @__PURE__ */ createRequire(import.meta.url);
 if (process.platform === "android") {
 	if (process.execPath.includes("linker64") || process.execPath.startsWith("/apex/")) {
 		const resolved = process.env.TERMUX_EXEC__PROC_SELF_EXE || "/data/data/com.termux/files/usr/bin/node";
@@ -82,6 +94,76 @@ if (process.platform === "android") {
 	};
 	_syncESM();
 }
+function readInstalledExtensions(extensionsDir) {
+	try {
+		const raw = readFileSync(join(extensionsDir, "extensions.json"), "utf8");
+		const entries = JSON.parse(raw);
+		return new Set(entries.map((e) => e.identifier?.id?.toLowerCase()).filter((id) => typeof id === "string"));
+	} catch {
+		return /* @__PURE__ */ new Set();
+	}
+}
+function specId(spec) {
+	const at = spec.indexOf("@", 1);
+	return (at === -1 ? spec : spec.slice(0, at)).toLowerCase();
+}
+function pendingExtensions(specs, extensionsDir) {
+	const installed = readInstalledExtensions(extensionsDir);
+	return specs.filter((spec) => {
+		if (spec.toLowerCase().endsWith(".vsix")) return true;
+		return !installed.has(specId(spec));
+	});
+}
+async function ensureExtensions(specs, opts) {
+	const pending = opts.force ? specs : pendingExtensions(specs, opts.extensionsDir);
+	if (pending.length === 0) return;
+	console.log(`[coderaft] Installing ${pending.length} extension${pending.length === 1 ? "" : "s"}: ${pending.join(", ")}`);
+	await runInstall(pending, opts);
+	const installed = readInstalledExtensions(opts.extensionsDir);
+	for (const spec of pending) {
+		if (spec.toLowerCase().endsWith(".vsix")) continue;
+		if (!installed.has(specId(spec))) console.warn(`[coderaft] Extension failed to install: ${spec}`);
+	}
+}
+function runInstall(specs, opts) {
+	const installPath = fileURLToPath(import.meta.resolve("#install"));
+	return new Promise((resolve, reject) => {
+		const child = fork(installPath, {
+			stdio: [
+				"ignore",
+				"pipe",
+				"inherit",
+				"ipc"
+			],
+			env: {
+				...process.env,
+				CODERAFT_INSTALL: JSON.stringify({
+					ids: specs,
+					extensionsDir: opts.extensionsDir,
+					userDataDir: opts.userDataDir,
+					serverDataDir: opts.serverDataDir,
+					force: opts.force,
+					preRelease: opts.preRelease
+				})
+			}
+		});
+		let buf = "";
+		child.stdout?.on("data", (chunk) => {
+			buf += chunk.toString();
+			const lines = buf.split("\n");
+			buf = lines.pop() ?? "";
+			for (const line of lines) {
+				if (/^\s*(info|debug|trace)\s+\[/.test(line)) continue;
+				if (line.trim()) console.log(line);
+			}
+		});
+		child.once("exit", () => {
+			if (buf.trim() && !/^\s*(info|debug|trace)\s+\[/.test(buf)) console.log(buf);
+			resolve();
+		});
+		child.once("error", reject);
+	});
+}
 const STATIC_MIME = {
 	".js": "text/javascript",
 	".mjs": "text/javascript",
@@ -158,9 +240,19 @@ async function createCodeServer(opts = {}) {
 	const mintKey = randomBytes(32);
 	process.env.CODE_SERVER_PARENT_PID ??= String(process.pid);
 	process.env.NODE_EXEC_PATH ??= process.execPath;
-	cleanupStaleLocks(opts.vscode?.["user-data-dir"] ?? join(_os.homedir(), ".vscode-server-oss", "data"));
+	if (opts.proxyURI) process.env.VSCODE_PROXY_URI = opts.proxyURI;
+	else if (baseURL) process.env.VSCODE_PROXY_URI ??= `${baseURL}/proxy/{{port}}/`;
+	const serverDataDir = opts.vscode?.["server-data-dir"] ?? join(_os.homedir(), ".vscode-server-oss");
+	const userDataDir = opts.vscode?.["user-data-dir"] ?? join(serverDataDir, "data");
+	const extensionsDir = opts.vscode?.["extensions-dir"] ?? join(serverDataDir, "extensions");
+	cleanupStaleLocks(userDataDir);
 	watchChildProcessHealth();
 	const { modulesDir } = await loadCode();
+	if (opts.extensions?.length) await ensureExtensions(opts.extensions, {
+		extensionsDir,
+		userDataDir,
+		serverDataDir
+	});
 	const vsRootPath = join(modulesDir, "code-server", "lib", "vscode");
 	const _log = console.log;
 	console.log = (...args) => {
@@ -177,6 +269,7 @@ async function createCodeServer(opts = {}) {
 	}
 	const vscodeServer = await (await mod.loadCodeWithNls()).createServer(null, {
 		"default-folder": defaultFolder,
+		"extensions-dir": extensionsDir,
 		...baseURL ? { "server-base-path": baseURL } : {},
 		...withoutToken ? { "without-connection-token": true } : { "connection-token": connectionToken },
 		"reconnection-grace-time": "30",
@@ -418,4 +511,4 @@ function sendJson(res, status, body) {
 	});
 	res.end(payload);
 }
-export { server_exports as n, startCodeServer as r, createCodeServer as t };
+export { createCodeServer, ensureExtensions, readInstalledExtensions, server_exports, startCodeServer };

package/dist/cli.mjs

@@ -210,7 +210,7 @@ else startMain();
 function startWorker() {
 	process.on("message", async (msg) => {
 		if (msg.type === "start") {
-			const { startCodeServer } = await import("./_chunks/server.mjs").then((n) => n.n);
+			const { startCodeServer } = await import("./_chunks/server.mjs").then((n) => n.server_exports);
 			const handle = await startCodeServer(msg.opts);
 			process.send({
 				type: "ready",
@@ -244,8 +244,10 @@ async function startMain() {
 		host: values.host,
 		socketPath: values["socket-path"],
 		baseURL: values["base-url"] ?? values["server-base-path"],
+		proxyURI: values["proxy-uri"],
 		defaultFolder: dir || values["default-folder"],
 		connectionToken: values["connection-token"] ?? values.token,
+		extensions: values["install-extension"],
 		vscode
 	};
 	const interactive = process.stdout.isTTY && !values["no-tui"];
@@ -257,7 +259,7 @@ async function startMain() {
 	} });
 	process.on("exit", () => tui?.destroy());
 	if (values["no-fork"]) {
-		const { startCodeServer } = await import("./_chunks/server.mjs").then((n) => n.n);
+		const { startCodeServer } = await import("./_chunks/server.mjs").then((n) => n.server_exports);
 		let handle;
 		let shuttingDown = false;
 		const shutdown = () => {

package/dist/index.d.mts

@@ -99,6 +99,27 @@ interface CreateCodeServerOptions {
    * routes (`/healthz`, `/_static/*`, `/proxy/*`, `/login`, …).
    */
   baseURL?: string;
+  /**
+   * URI template for proxied ports. `{{port}}` is replaced with the port number.
+   *
+   * Path-based (default): `baseURL + "/proxy/{{port}}/"` (e.g. `/code/proxy/3000/`)
+   * Subdomain-based: `https://{{port}}.proxy.example.com/`
+   *
+   * Passed to VS Code as `VSCODE_PROXY_URI`.
+   */
+  proxyURI?: string;
+  /**
+   * Extensions to preinstall before the server boots. Each entry is anything
+   * VS Code's CLI accepts: a gallery id (`esbenp.prettier-vscode`), an id pinned
+   * to a version (`esbenp.prettier-vscode@12.4.0`), or a path to a local
+   * `.vsix`. Gallery ids resolve from Open VSX (https://open-vsx.org) by
+   * default.
+   *
+   * Installation is idempotent — already-installed extensions are skipped, so
+   * warm restarts pay no cost. Failures (bad id, gallery outage) are logged and
+   * never block startup.
+   */
+  extensions?: string[];
   /** Extra options forwarded to VS Code's `createServer()`. */
   vscode?: VSCodeServerOptions;
 }
@@ -183,4 +204,30 @@ declare class SpawnedCodeServer extends EventEmitter {
   reload(): Promise<void>;
 }
 declare function spawnCodeServer(opts?: SpawnCodeServerOptions): Promise<SpawnedCodeServer>;
-export { type CodeServerHandle, type CodeServerHandler, type CreateCodeServerOptions, type SpawnCodeServerOptions, type SpawnProcessOptions, SpawnedCodeServer, type StartCodeServerOptions, createCodeServer, spawnCodeServer, startCodeServer };
+interface EnsureExtensionsOptions {
+  /** Directory extensions are installed into (must match the running server). */
+  extensionsDir: string;
+  /** VS Code user data directory. */
+  userDataDir: string;
+  /** VS Code server data directory. */
+  serverDataDir?: string;
+  /** Reinstall even if an extension with the same id is already present. */
+  force?: boolean;
+  /** Install pre-release versions when available. */
+  preRelease?: boolean;
+}
+/**
+ * Read the ids of already-installed extensions (lowercased) from the
+ * `extensions.json` manifest VS Code maintains in the extensions directory.
+ * Returns an empty set when the directory or manifest doesn't exist yet.
+ */
+declare function readInstalledExtensions(extensionsDir: string): Set<string>;
+/**
+ * Ensure the given extensions are installed before the server boots. Missing
+ * extensions are installed from the gallery (Open VSX by default) in a forked
+ * child process — `spawnCli` calls `process.exit()` when done, so it cannot run
+ * in the server process. Best-effort: install failures are logged, not thrown,
+ * so a bad id or a gallery outage never blocks startup.
+ */
+declare function ensureExtensions(specs: string[], opts: EnsureExtensionsOptions): Promise<void>;
+export { type CodeServerHandle, type CodeServerHandler, type CreateCodeServerOptions, type EnsureExtensionsOptions, type SpawnCodeServerOptions, type SpawnProcessOptions, SpawnedCodeServer, type StartCodeServerOptions, createCodeServer, ensureExtensions, readInstalledExtensions, spawnCodeServer, startCodeServer };

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { r as startCodeServer, t as createCodeServer } from "./_chunks/server.mjs";
+import { createCodeServer, ensureExtensions, readInstalledExtensions, startCodeServer } from "./_chunks/server.mjs";
 import { fileURLToPath } from "node:url";
 import { fork } from "node:child_process";
 import { EventEmitter } from "node:events";
@@ -168,4 +168,4 @@ async function terminateChild(proc) {
 		proc.kill("SIGTERM");
 	});
 }
-export { SpawnedCodeServer, createCodeServer, spawnCodeServer, startCodeServer };
+export { SpawnedCodeServer, createCodeServer, ensureExtensions, readInstalledExtensions, spawnCodeServer, startCodeServer };

package/install.mjs

@@ -0,0 +1,33 @@
+// Forked child entry used to preinstall extensions through VS Code's own CLI
+// (`spawnCli`). This runs in a dedicated process because `spawnCli` calls
+// `process.exit()` once installs settle — doing it in-process would tear down
+// the parent's long-lived server. Config is passed via the `CODERAFT_INSTALL`
+// env var (JSON); progress is logged to stdout/stderr by VS Code itself.
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { loadCode } from "#code";
+
+const cfg = JSON.parse(process.env.CODERAFT_INSTALL || "{}");
+
+// Suppress server-main.js's standalone auto-boot (same trick as server.ts):
+// the module top-level is `process.env.CODE_SERVER_PARENT_PID || <boot>()`, so
+// a truthy value makes the import side-effect-free and lets us drive the CLI.
+process.env.CODE_SERVER_PARENT_PID ??= String(process.pid);
+
+const { modulesDir } = await loadCode();
+const vsRoot = join(modulesDir, "code-server", "lib", "vscode");
+const mod = await import(pathToFileURL(join(vsRoot, "out/server-main.js")).href);
+const serverModule = await mod.loadCodeWithNls();
+
+// `spawnCli` consumes a VS Code NativeParsedArgs object. Extensions resolve
+// against the gallery baked into the patched server-main.js, which defaults to
+// Open VSX (https://open-vsx.org/vscode/gallery).
+await serverModule.spawnCli({
+  _: [],
+  "install-extension": cfg.ids,
+  "extensions-dir": cfg.extensionsDir,
+  "user-data-dir": cfg.userDataDir,
+  "server-data-dir": cfg.serverDataDir,
+  ...(cfg.force ? { force: true } : {}),
+  ...(cfg.preRelease ? { "pre-release": true } : {}),
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "coderaft",
-  "version": "0.0.31",
+  "version": "0.0.32",
   "repository": "pithings/coderaft",
   "bin": {
     "coderaft": "./dist/cli.mjs"
@@ -12,6 +12,7 @@
     "tar.mjs",
     "code.mjs",
     "worker.mjs",
+    "install.mjs",
     "android-preload.cjs",
     "code.tar.zst"
   ],
@@ -23,6 +24,7 @@
   "imports": {
     "#code": "./code.mjs",
     "#worker": "./worker.mjs",
+    "#install": "./install.mjs",
     "#android-preload": "./android-preload.cjs"
   },
   "scripts": {

package/dist/_chunks/rolldown-runtime.mjs

@@ -1,13 +0,0 @@
-import { createRequire } from "node:module";
-var __defProp = Object.defineProperty;
-var __exportAll = (all, no_symbols) => {
-	let target = {};
-	for (var name in all) __defProp(target, name, {
-		get: all[name],
-		enumerable: true
-	});
-	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
-	return target;
-};
-var __require = /* @__PURE__ */ createRequire(import.meta.url);
-export { __require as n, __exportAll as t };