coderaft 0.0.24 → 0.0.26

package/README.md

@@ -135,6 +135,34 @@ interface CodeServerHandle {
 }
 ```
 
+### `spawnCodeServer(options)`
+
+Runs the code-server in a forked Node.js child process — useful for isolating VS Code's singletons from the host or restarting the server without taking the host down. Accepts the same options as `startCodeServer`, plus a `spawn` sub-object (`env`, `execArgv`, `stdio`, `startupTimeout`).
+
+```ts
+import { spawnCodeServer } from "coderaft";
+
+const instance = await spawnCodeServer({
+  port: 6063,
+  defaultFolder: "/path/to/workspace",
+});
+
+console.log(`Ready at ${instance.url}`);
+
+// Notify on unexpected worker exits (not fired during close/reload):
+instance.on("exit", (code, signal) => {
+  console.warn(`worker died code=${code} signal=${signal}`);
+});
+
+// Restart the worker in place (reads fresh url/port/connectionToken after):
+await instance.reload();
+
+// Graceful shutdown — SIGTERM to the worker, then SIGKILL after 5s:
+await instance.close();
+```
+
+Options cross an IPC boundary, so nested values (`vscode`, etc.) must be JSON-compatible.
+
 ## CLI Options
 
 ### Server

package/dist/_chunks/server.mjs

@@ -317,11 +317,19 @@ async function startCodeServer(opts = {}) {
 	const address = server.address();
 	const actualPort = address && typeof address === "object" && "port" in address ? address.port : void 0;
 	const basePath = normalizeBaseURL(opts.baseURL ?? opts.vscode?.["server-base-path"]);
+	let url;
+	if (socketPath) url = `unix:${socketPath}`;
+	else {
+		const baseUrl = new URL(`http://localhost:${actualPort}${basePath}/`);
+		if (handler.connectionToken) baseUrl.searchParams.set("tkn", handler.connectionToken);
+		const rawUrl = opts.formatURL ? opts.formatURL(baseUrl) ?? baseUrl : baseUrl;
+		url = rawUrl instanceof URL ? rawUrl.toString() : rawUrl;
+	}
 	return {
 		server,
 		port: actualPort,
 		socketPath,
-		url: socketPath ? `unix:${socketPath}` : handler.connectionToken ? `http://localhost:${actualPort}${basePath}/?tkn=${handler.connectionToken}` : `http://localhost:${actualPort}${basePath}/`,
+		url,
 		connectionToken: handler.connectionToken,
 		async close() {
 			await handler.dispose();

package/dist/index.d.mts

@@ -1,4 +1,6 @@
+import { ChildProcess } from "node:child_process";
 import { IncomingMessage, Server, ServerResponse } from "node:http";
+import { EventEmitter } from "node:events";
 import { Duplex } from "node:stream";
 /**
  * Options for `createServer()` from VS Code server
@@ -81,6 +83,12 @@ interface VSCodeServerOptions {
 interface CreateCodeServerOptions {
   /** Workspace folder opened when no input is given in the URL. */
   defaultFolder?: string;
+  /**
+   * Customize the URL returned by the server. Called with the base URL after
+   * auth params are applied. Return a modified URL, a string, or `undefined`
+   * to keep the original.
+   */
+  formatURL?: (url: URL) => string | URL | undefined;
   /** Connection token (shared auth secret). Auto-generated if omitted. */
   connectionToken?: string;
   /** Host/interface to bind (used to infer local-only access for token default). */
@@ -120,4 +128,59 @@ interface CodeServerHandle {
 }
 declare function createCodeServer(opts?: CreateCodeServerOptions): Promise<CodeServerHandler>;
 declare function startCodeServer(opts?: StartCodeServerOptions): Promise<CodeServerHandle>;
-export { type CodeServerHandle, type CodeServerHandler, type CreateCodeServerOptions, type StartCodeServerOptions, createCodeServer, startCodeServer };
+interface SpawnProcessOptions {
+  /** Extra environment variables merged into the worker's `process.env`. */
+  env?: NodeJS.ProcessEnv;
+  /** Node.js exec argv forwarded to the worker (e.g. `["--inspect"]`). */
+  execArgv?: string[];
+  /**
+   * stdio for the forked worker. Defaults to `"inherit"` for stdout/stderr and
+   * `"ignore"` for stdin. Pass `"pipe"` to capture output via `handle.proc`.
+   */
+  stdio?: "inherit" | "pipe" | "ignore";
+  /**
+   * Max ms to wait for the worker to report `ready`. Defaults to 60000.
+   * On timeout, the worker is killed and the promise rejects.
+   */
+  startupTimeout?: number;
+}
+interface SpawnCodeServerOptions extends StartCodeServerOptions {
+  /** Options for the forked worker process. */
+  spawn?: SpawnProcessOptions;
+}
+interface SpawnedCodeServer {
+  /**
+   * Emitted when the handle loses its worker: crash, explicit kill, or a
+   * `reload()` whose respawn failed (the old worker is already gone; the
+   * failure also rejects the `reload()` promise). Not emitted for `close()`
+   * or the successful half of `reload()`.
+   */
+  on(event: "exit", listener: (code: number | null, signal: NodeJS.Signals | null) => void): this;
+  /**
+   * Emitted for worker `error` events (spawn failure, IPC send failure) and
+   * for post-ready fatal errors forwarded by the worker (uncaughtException,
+   * unhandledRejection).
+   */
+  on(event: "error", listener: (err: Error) => void): this;
+  on(event: string, listener: (...args: unknown[]) => void): this;
+}
+declare class SpawnedCodeServer extends EventEmitter {
+  #private;
+  /** The forked worker process (changes after `reload`). */
+  proc: ChildProcess;
+  url: string;
+  /** TCP port the server is bound to, or `undefined` when listening on a unix socket. */
+  port?: number;
+  /** Unix socket path the server is bound to, or `undefined` when listening on TCP. */
+  socketPath?: string;
+  connectionToken: string;
+  private constructor();
+  /** Spawn a new worker and resolve with a handle once it reports ready. */
+  static spawn(opts?: SpawnCodeServerOptions): Promise<SpawnedCodeServer>;
+  /** Terminate the worker process. Sends SIGTERM, then SIGKILL after 5s. Idempotent. */
+  close(): Promise<void>;
+  /** Kill the current worker and spawn a new one with the original options. */
+  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 };

package/dist/index.mjs

@@ -1,2 +1,171 @@
 import { r as startCodeServer, t as createCodeServer } from "./_chunks/server.mjs";
-export { createCodeServer, startCodeServer };
+import { fileURLToPath } from "node:url";
+import { fork } from "node:child_process";
+import { EventEmitter } from "node:events";
+var SpawnedCodeServer = class SpawnedCodeServer extends EventEmitter {
+	proc;
+	url;
+	port;
+	socketPath;
+	connectionToken;
+	#opts;
+	#detach;
+	#reloading;
+	#closed = false;
+	constructor(opts, state) {
+		super();
+		this.#opts = opts;
+		this.#adopt(state);
+	}
+	static async spawn(opts = {}) {
+		return new SpawnedCodeServer(opts, await spawnWorker(opts));
+	}
+	async close() {
+		if (this.#closed) return;
+		this.#closed = true;
+		if (this.#reloading) try {
+			await this.#reloading;
+		} catch {}
+		this.#detach();
+		await terminateChild(this.proc);
+	}
+	async reload() {
+		if (this.#closed) throw new Error("SpawnedCodeServer is closed");
+		if (this.#reloading) return this.#reloading;
+		this.#reloading = (async () => {
+			this.#detach();
+			await terminateChild(this.proc);
+			if (this.#closed) throw new Error("SpawnedCodeServer was closed during reload");
+			let next;
+			try {
+				next = await spawnWorker(this.#opts);
+			} catch (err) {
+				const dead = this.proc;
+				queueMicrotask(() => this.emit("exit", dead.exitCode, dead.signalCode));
+				throw err;
+			}
+			if (this.#closed) {
+				await terminateChild(next.proc);
+				throw new Error("SpawnedCodeServer was closed during reload");
+			}
+			this.#adopt(next);
+		})();
+		try {
+			await this.#reloading;
+		} finally {
+			this.#reloading = void 0;
+		}
+	}
+	#adopt(state) {
+		this.proc = state.proc;
+		this.url = state.url;
+		this.port = state.port;
+		this.socketPath = state.socketPath;
+		this.connectionToken = state.connectionToken;
+		this.#detach = this.#attachListeners(state.proc);
+	}
+	#attachListeners(proc) {
+		const onExit = (code, signal) => this.emit("exit", code, signal);
+		const onError = (err) => this.emit("error", err);
+		const onMessage = (msg) => {
+			if (msg?.type === "error") this.emit("error", new Error(msg.message ?? "worker error"));
+		};
+		proc.on("exit", onExit);
+		proc.on("error", onError);
+		proc.on("message", onMessage);
+		return () => {
+			proc.off("exit", onExit);
+			proc.off("error", onError);
+			proc.off("message", onMessage);
+		};
+	}
+};
+function spawnCodeServer(opts = {}) {
+	return SpawnedCodeServer.spawn(opts);
+}
+async function spawnWorker(opts) {
+	const { spawn: spawnOpts = {}, ...serverOpts } = opts;
+	const { env, execArgv, stdio = "inherit", startupTimeout = 6e4 } = spawnOpts;
+	const workerPath = fileURLToPath(import.meta.resolve("#worker"));
+	const childEnv = {
+		...process.env,
+		...env
+	};
+	delete childEnv.CODE_SERVER_PARENT_PID;
+	const proc = fork(workerPath, {
+		stdio: [
+			"ignore",
+			stdio,
+			stdio,
+			"ipc"
+		],
+		env: childEnv,
+		...execArgv !== void 0 ? { execArgv } : {}
+	});
+	const ready = await new Promise((resolve, reject) => {
+		const onMessage = (msg) => {
+			if (msg?.type === "ready") {
+				cleanup();
+				resolve(msg);
+			} else if (msg?.type === "error") {
+				cleanup();
+				reject(new Error(msg.message ?? "worker error"));
+			}
+		};
+		const onExit = (code) => {
+			cleanup();
+			reject(/* @__PURE__ */ new Error(`coderaft worker exited before ready (code=${code})`));
+		};
+		const onError = (err) => {
+			cleanup();
+			proc.kill("SIGKILL");
+			reject(err);
+		};
+		const timer = setTimeout(() => {
+			cleanup();
+			proc.kill("SIGKILL");
+			reject(/* @__PURE__ */ new Error(`coderaft worker did not become ready within ${startupTimeout}ms`));
+		}, startupTimeout);
+		timer.unref?.();
+		const cleanup = () => {
+			clearTimeout(timer);
+			proc.off("message", onMessage);
+			proc.off("exit", onExit);
+			proc.off("error", onError);
+		};
+		proc.on("message", onMessage);
+		proc.once("exit", onExit);
+		proc.once("error", onError);
+		proc.send({
+			type: "start",
+			opts: serverOpts
+		}, (err) => {
+			if (err) {
+				cleanup();
+				reject(err);
+			}
+		});
+	});
+	return {
+		proc,
+		url: ready.url,
+		port: ready.port,
+		socketPath: ready.socketPath,
+		connectionToken: ready.connectionToken
+	};
+}
+async function terminateChild(proc) {
+	if (proc.exitCode !== null || proc.signalCode !== null) return;
+	await new Promise((resolve) => {
+		const timer = setTimeout(() => {
+			if (proc.exitCode === null && proc.signalCode === null) proc.kill("SIGKILL");
+		}, 5e3);
+		timer.unref?.();
+		proc.once("exit", () => {
+			clearTimeout(timer);
+			resolve();
+		});
+		proc.kill("SIGTERM");
+	});
+}
+export { SpawnedCodeServer, createCodeServer, spawnCodeServer, startCodeServer };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "coderaft",
-  "version": "0.0.24",
+  "version": "0.0.26",
   "repository": "pithings/coderaft",
   "bin": {
     "coderaft": "./dist/cli.mjs"
@@ -11,12 +11,18 @@
     "ThirdPartyNotices.txt",
     "tar.mjs",
     "code.mjs",
+    "worker.mjs",
     "android-preload.cjs",
     "code.tar.zst"
   ],
   "type": "module",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": "./dist/index.mjs"
+  },
   "imports": {
     "#code": "./code.mjs",
+    "#worker": "./worker.mjs",
     "#android-preload": "./android-preload.cjs"
   },
   "scripts": {

package/worker.mjs

@@ -0,0 +1,64 @@
+// Forked worker entry used by `spawnCodeServer`. Starts a coderaft code server
+// on IPC `{ type: "start", opts }` and replies with `{ type: "ready", ... }`.
+// On SIGTERM/SIGINT, gracefully closes the server before exiting so the parent's
+// `handle.close()` cleanly disposes VS Code and releases sockets/locks.
+import { startCodeServer } from "./dist/index.mjs";
+
+let handle;
+let shuttingDown = false;
+
+process.on("message", async (msg) => {
+  if (msg?.type !== "start") return;
+  try {
+    handle = await startCodeServer(msg.opts);
+    process.send?.({
+      type: "ready",
+      url: handle.url,
+      port: handle.port,
+      socketPath: handle.socketPath,
+      connectionToken: handle.connectionToken,
+    });
+  } catch (err) {
+    // Flush the error message over IPC before exiting — `process.exit` can
+    // tear down the channel before the message reaches the parent, which
+    // would leave the parent rejecting with the generic `exited before ready`.
+    const exit = () => process.exit(1);
+    if (process.send) {
+      process.send({ type: "error", message: err?.message ?? String(err) }, exit);
+    } else {
+      exit();
+    }
+  }
+});
+
+const shutdown = async (signal) => {
+  if (shuttingDown) return;
+  shuttingDown = true;
+  try {
+    await handle?.close();
+  } catch (err) {
+    console.error(`[coderaft worker] close failed on ${signal}:`, err);
+  }
+  process.exit(0);
+};
+
+process.on("SIGTERM", () => shutdown("SIGTERM"));
+process.on("SIGINT", () => shutdown("SIGINT"));
+
+// Forward fatal async errors to the parent before exiting. Without this, the
+// parent only sees an anonymous non-zero exit and has to scrape stderr for the
+// reason — which is the exact failure mode the pre-ready IPC flush avoids.
+const forwardFatal = (kind) => (err) => {
+  if (shuttingDown) return;
+  shuttingDown = true;
+  const detail = err?.stack ?? err?.message ?? String(err);
+  const exit = () => process.exit(1);
+  if (process.send) {
+    process.send({ type: "error", message: `[${kind}] ${detail}` }, exit);
+  } else {
+    exit();
+  }
+};
+
+process.on("uncaughtException", forwardFatal("uncaughtException"));
+process.on("unhandledRejection", forwardFatal("unhandledRejection"));