@devframes/plugin-code-server 0.9.8 → 0.9.9

package/README.md

@@ -11,13 +11,13 @@ auto-authenticated `<iframe>`. The launcher is a **Vue** SPA built on the shared
 
 ## How it works
 
-- **Detection** — on startup it probes the resolved binary with `--version`.
+- **Detection**: on startup it probes the resolved binary with `--version`.
   When none is found, the launcher renders install instructions instead of a
   launch button.
-- **Launch** — the launcher's button starts the editor as a managed child
+- **Launch**: the launcher's button starts the editor as a managed child
   process bound to a free port, scoped to the workspace. Readiness is probed
   before the iframe loads.
-- **Auto-auth** — the devframe generates fresh auth material per launch and hands
+- **Auto-auth**: the devframe generates fresh auth material per launch and hands
   it to the already-authorized devframe client, so the editor opens already
   signed in. `code-server` uses a session cookie (`HASHED_PASSWORD`);
   `code serve-web` uses a connection token on the URL (`?tkn=`).
@@ -50,12 +50,12 @@ pnpx @devframes/plugin-code-server        # dev server + launcher
 import { createCodeServerDevframe } from '@devframes/plugin-code-server'
 
 export default createCodeServerDevframe({
-  // backend: 'code-server',    // 'code-server' | 'ms-code-serve-web' (default: auto)
-  // mode: 'local',             // 'local' | 'tunnel'
-  // serverPort: 8080,          // force a port (default: free port near 8080)
-  // startOnBoot: true,         // launch during setup instead of on demand
-  // reuseExistingServer: true, // adopt a server already answering on the port
-  // tunnel: { name: 'my-box' },
+  // backend: 'code-server' | 'ms-code-serve-web' (default: auto)
+  // mode: 'local' | 'tunnel'
+  // serverPort: 8080 (default: free port near 8080)
+  // startOnBoot: true (default: on demand)
+  // reuseExistingServer: true (adopt a server on the port)
+  // tunnel: { name: 'my-box' }
 })
 ```
 
@@ -84,7 +84,7 @@ Status (minus the connect descriptor) is mirrored into the
 ## UI
 
 The launcher is a Vue SPA (`src/spa`). `LauncherView.vue` is a pure,
-state-driven view decoupled from RPC — every phase renders in isolation and has
+state-driven view decoupled from RPC, so every phase renders in isolation and has
 a Storybook story; `App.vue` wires the live connection to it and mounts the
 editor in a full-bleed, auto-authenticated iframe (`EditorFrame.vue`).
 

package/dist/cli.d.mts

@@ -2,8 +2,8 @@ import { CodeServerOptions } from "./types.mjs";
 import { CacHandle, CreateCacOptions } from "devframe/adapters/cac";
 //#region src/cli.d.ts
 /**
- * Build a standalone CLI for the code-server panel — `dev` / `build` / `mcp`
- * subcommands, backed by {@link createCodeServerDevframe}. Used by the package
+ * Build a standalone CLI for the code-server panel, exposing `dev` / `build` /
+ * `mcp` subcommands, backed by {@link createCodeServerDevframe}. Used by the package
  * `bin` (`devframe-code-server`).
  */
 declare function createCodeServerCli(options?: CodeServerOptions, cliOptions?: CreateCacOptions): CacHandle;

package/dist/cli.mjs

@@ -1,9 +1,9 @@
-import { t as createCodeServerDevframe } from "./src-CNJYQ3UQ.mjs";
+import { t as createCodeServerDevframe } from "./src-5dhTkOqj.mjs";
 import { createCac } from "devframe/adapters/cac";
 //#region src/cli.ts
 /**
-* Build a standalone CLI for the code-server panel — `dev` / `build` / `mcp`
-* subcommands, backed by {@link createCodeServerDevframe}. Used by the package
+* Build a standalone CLI for the code-server panel, exposing `dev` / `build` /
+* `mcp` subcommands, backed by {@link createCodeServerDevframe}. Used by the package
 * `bin` (`devframe-code-server`).
 */
 function createCodeServerCli(options = {}, cliOptions = {}) {

package/dist/client/index.d.mts

@@ -1,5 +1,5 @@
 import { CodeServerBackend, CodeServerConnect, CodeServerDetection, CodeServerLogin, CodeServerMode, CodeServerServerInfo, CodeServerSharedState, CodeServerStartResult, CodeServerStatus, CodeServerStatusResult } from "../types.mjs";
-import { o as STATE_KEY } from "../constants-DtQz38ex.mjs";
+import { o as STATE_KEY } from "../constants-BbInB7V-.mjs";
 import { DevframeConnectionStatus, DevframeRpcClient, DevframeRpcClientOptions } from "devframe/client";
 import { ConnectionMeta } from "devframe/types";
 //#region src/client/index.d.ts

package/dist/client/index.mjs

@@ -2,7 +2,7 @@ import { connectDevframe } from "devframe/client";
 //#region src/constants.ts
 /**
 * Shared-state key holding the serializable, secret-free server status and
-* detection result. Authentication material is never published here — it is
+* detection result. Authentication material is never published here; it is
 * returned only from the `start` / `status` RPCs to the already-authorized
 * client (see {@link import('./types').CodeServerConnect}).
 */

package/dist/{constants-DtQz38ex.d.mts → constants-BbInB7V-.d.mts}

@@ -3,7 +3,7 @@
 declare const PLUGIN_ID = "devframes_plugin_code-server";
 /**
  * Shared-state key holding the serializable, secret-free server status and
- * detection result. Authentication material is never published here — it is
+ * detection result. Authentication material is never published here; it is
  * returned only from the `start` / `status` RPCs to the already-authorized
  * client (see {@link import('./types').CodeServerConnect}).
  */

package/dist/constants.d.mts

@@ -1,2 +1,2 @@
-import { a as SESSION_COOKIE_BASE, c as TERMINAL_SESSION_TITLE, i as PLUGIN_ID, l as getCookieSessionName, n as DEFAULT_PORT, o as STATE_KEY, r as DEFAULT_START_TIMEOUT, s as TERMINAL_SESSION_ICON, t as DEFAULT_CODE_SERVER_PORT } from "./constants-DtQz38ex.mjs";
+import { a as SESSION_COOKIE_BASE, c as TERMINAL_SESSION_TITLE, i as PLUGIN_ID, l as getCookieSessionName, n as DEFAULT_PORT, o as STATE_KEY, r as DEFAULT_START_TIMEOUT, s as TERMINAL_SESSION_ICON, t as DEFAULT_CODE_SERVER_PORT } from "./constants-BbInB7V-.mjs";
 export { DEFAULT_CODE_SERVER_PORT, DEFAULT_PORT, DEFAULT_START_TIMEOUT, PLUGIN_ID, SESSION_COOKIE_BASE, STATE_KEY, TERMINAL_SESSION_ICON, TERMINAL_SESSION_TITLE, getCookieSessionName };

package/dist/constants.mjs

@@ -3,7 +3,7 @@
 const PLUGIN_ID = "devframes_plugin_code-server";
 /**
 * Shared-state key holding the serializable, secret-free server status and
-* detection result. Authentication material is never published here — it is
+* detection result. Authentication material is never published here; it is
 * returned only from the `start` / `status` RPCs to the already-authorized
 * client (see {@link import('./types').CodeServerConnect}).
 */

package/dist/index.d.mts

@@ -1,11 +1,11 @@
 import { CodeServerBackend, CodeServerConnect, CodeServerDetection, CodeServerLogin, CodeServerMode, CodeServerOptions, CodeServerServerInfo, CodeServerSharedState, CodeServerStartRequest, CodeServerStartResult, CodeServerStatus, CodeServerStatusResult, CodeServerTunnelOptions } from "./types.mjs";
-import { i as PLUGIN_ID, l as getCookieSessionName, n as DEFAULT_PORT, o as STATE_KEY, t as DEFAULT_CODE_SERVER_PORT } from "./constants-DtQz38ex.mjs";
+import { i as PLUGIN_ID, l as getCookieSessionName, n as DEFAULT_PORT, o as STATE_KEY, t as DEFAULT_CODE_SERVER_PORT } from "./constants-BbInB7V-.mjs";
 import { DevframeDefinition } from "devframe";
 //#region src/index.d.ts
 /**
  * Build a {@link DevframeDefinition} for the code-server panel. The same
  * definition runs standalone (`createCac`), mounts into a Vite host
- * (`/vite`), or docks inside a hub — its `setup` only relies on the core
+ * (`/vite`), or docks inside a hub, since its `setup` only relies on the core
  * devframe RPC + shared-state surface.
  *
  * @experimental This plugin is experimental and may change without a major

package/dist/index.mjs

@@ -1,3 +1,3 @@
-import { t as createCodeServerDevframe } from "./src-CNJYQ3UQ.mjs";
+import { t as createCodeServerDevframe } from "./src-5dhTkOqj.mjs";
 import { DEFAULT_CODE_SERVER_PORT, DEFAULT_PORT, PLUGIN_ID, STATE_KEY, getCookieSessionName } from "./constants.mjs";
 export { DEFAULT_CODE_SERVER_PORT, DEFAULT_PORT, PLUGIN_ID, STATE_KEY, createCodeServerDevframe, createCodeServerDevframe as default, getCookieSessionName };

package/dist/node/index.d.mts

@@ -62,12 +62,28 @@ declare class CodeServerSupervisor {
   status(): CodeServerStatusResult;
   /**
    * Launch the editor (if not already up) and resolve once it is reachable.
-   * Idempotent while starting/running — returns the live status instead of
+   * Idempotent while starting/running; returns the live status instead of
    * spawning a second process. In tunnel mode it resolves as soon as either
    * the `vscode.dev` URL or a device-login prompt is seen, so the action never
    * blocks on interactive authentication.
    */
   start(req?: CodeServerStartRequest): Promise<CodeServerStartResult>;
+  /** Adopt an already-running local server on the target port, if one answers. */
+  private tryAdopt;
+  /** Resolve the port to launch on: 0 for tunnels/dynamic, a forced port, or a free one. */
+  private resolveInitialPort;
+  /** The child's environment: inherited env, caller overrides, then profile shaping. */
+  private buildLaunchEnv;
+  /** Buffer output and latch the port / login / ready-URL signals from each line. */
+  private consumeOutput;
+  private latchPort;
+  private latchLogin;
+  private latchReadyUrl;
+  private handleChildError;
+  private handleChildExit;
+  /** Wait for the dynamic port then readiness, and flip to `running`. */
+  private finalizeLocalStart;
+  private handleStartFailure;
   /** Stop the editor process and reset to `stopped`. */
   stop(): CodeServerStatusResult;
   /** Kill the process on host shutdown / test teardown. */
@@ -89,7 +105,7 @@ declare class CodeServerSupervisor {
   /**
    * Resolve the hub's terminals subsystem when this devframe is mounted in a
    * hub. `ctx.terminals` only exists on a `DevframeHubContext`, so it is
-   * duck-typed — standalone runtimes (CLI / Vite / build) have no such property
+   * duck-typed: standalone runtimes (CLI / Vite / build) have no such property
    * and fall back to a direct child process.
    */
   private resolveHubTerminals;
@@ -103,6 +119,10 @@ declare class CodeServerSupervisor {
    * readiness / port / log wiring in `start()` is identical.
    */
   private launchProcess;
+  /** Spawn through the hub's terminals subsystem so it shows as a terminal session. */
+  private launchViaHub;
+  /** Spawn the editor binary directly (standalone runtimes with no hub). */
+  private launchDirect;
   private appendLog;
   private lastLog;
   private publish;
@@ -119,8 +139,8 @@ declare class CodeServerSupervisor {
  * The internal launch profile the supervisor drives. One of three "kinds":
  * the two local {@link CodeServerBackend}s plus the `code tunnel` profile
  * selected by `mode: 'tunnel'`. Each profile owns the backend-specific pieces
- * — binary, arguments, auth env, readiness detection, and how the client
- * ultimately reaches the editor — while the supervisor owns the shared
+ * (binary, arguments, auth env, readiness detection, and how the client
+ * ultimately reaches the editor), while the supervisor owns the shared
  * spawn / log / publish lifecycle.
  */
 type CodeServerProfileKind = 'code-server' | 'serve-web' | 'tunnel';
@@ -181,14 +201,14 @@ interface DetectCodeServerResult {
 /**
  * Probe the host for a usable code-server binary by running
  * `<bin> --version`. Resolves to `installed: false` when the binary is
- * missing (ENOENT), errors, or exits non-zero — never throws — so the
+ * missing (ENOENT), errors, or exits non-zero (never throws), so the
  * launcher can fall back to install instructions.
  *
  * `code-server --version` prints e.g. `4.96.4 abc123 with Code 1.96.4`; the
  * first semver-looking token is taken as the version. Matching a semver
  * pattern (rather than the leading whitespace token) keeps cold-start i18n
- * noise — e.g. an `i18next: …` initialization line printed before the version
- * — from leaking into the reported version.
+ * noise (e.g. an `i18next: …` initialization line printed before the version)
+ * from leaking into the reported version.
  */
 declare function detectCodeServer(bin?: string, timeoutMs?: number): Promise<DetectCodeServerResult>;
 //#endregion
@@ -473,7 +493,7 @@ declare const diagnostics: Diagnostics<{
  * status into shared state, and register the control RPC functions. Returns
  * the supervisor so callers can launch/stop or dispose it on shutdown.
  *
- * Works in any devframe runtime (CLI, Vite, embedded, build) — it only relies
+ * Works in any devframe runtime (CLI, Vite, embedded, build), since it only relies
  * on the core `ctx.rpc` shared-state surface, not on the hub.
  */
 declare function setupCodeServer(ctx: DevframeNodeContext, options?: CodeServerOptions): Promise<CodeServerSupervisor>;

package/dist/node/index.mjs

@@ -60,6 +60,7 @@ const serveWebProfile = {
 		...c.extraArgs
 	],
 	buildEnv: (_c, base) => ({ ...base }),
+	/** serve-web has no health endpoint; the root responds (200/redirect) once up. */
 	healthPath: "/",
 	matchPort: (line) => {
 		const m = line.match(/available at https?:\/\/[^:]+:(\d+)/i);
@@ -113,14 +114,14 @@ function resolveProfile(mode, backend) {
 /**
 * Probe the host for a usable code-server binary by running
 * `<bin> --version`. Resolves to `installed: false` when the binary is
-* missing (ENOENT), errors, or exits non-zero — never throws — so the
+* missing (ENOENT), errors, or exits non-zero (never throws), so the
 * launcher can fall back to install instructions.
 *
 * `code-server --version` prints e.g. `4.96.4 abc123 with Code 1.96.4`; the
 * first semver-looking token is taken as the version. Matching a semver
 * pattern (rather than the leading whitespace token) keeps cold-start i18n
-* noise — e.g. an `i18next: …` initialization line printed before the version
-* — from leaking into the reported version.
+* noise (e.g. an `i18next: …` initialization line printed before the version)
+* from leaking into the reported version.
 */
 function detectCodeServer(bin = "code-server", timeoutMs = 5e3) {
 	return new Promise((resolve) => {
@@ -326,7 +327,7 @@ var CodeServerSupervisor = class {
 	}
 	/**
 	* Launch the editor (if not already up) and resolve once it is reachable.
-	* Idempotent while starting/running — returns the live status instead of
+	* Idempotent while starting/running; returns the live status instead of
 	* spawning a second process. In tunnel mode it resolves as soon as either
 	* the `vscode.dev` URL or a device-login prompt is seen, so the action never
 	* blocks on interactive authentication.
@@ -338,151 +339,177 @@ var CodeServerSupervisor = class {
 		const folder = req.folder ?? this.workspace;
 		const isLocal = this.profile.kind !== "tunnel";
 		if (isLocal && this.reuseExistingServer) {
-			const target = this.forcedPort && this.forcedPort !== 0 ? this.forcedPort : DEFAULT_CODE_SERVER_PORT;
-			if (this.profile.healthPath && await probeHealth(target, this.profile.healthPath)) {
-				this.adopted = true;
-				this.launchCtx = this.baseCtx(folder, target, "");
-				this.server = {
-					status: "running",
-					port: target,
-					startedAt: Date.now()
-				};
-				this.publish();
-				return this.status();
-			}
+			const adopted = await this.tryAdopt(folder);
+			if (adopted) return adopted;
 		}
 		const secret = randomBytes(32).toString("hex");
-		const initialPort = !isLocal ? 0 : this.forcedPort !== void 0 && this.forcedPort !== 0 ? this.forcedPort : this.forcedPort === 0 ? 0 : await getPort({
-			host: "127.0.0.1",
-			port: DEFAULT_CODE_SERVER_PORT
-		});
+		const initialPort = await this.resolveInitialPort(isLocal);
 		const ctx = this.baseCtx(folder, initialPort, secret);
 		this.launchCtx = ctx;
 		this.adopted = false;
 		this.readyUrl = void 0;
 		const args = this.profile.buildArgs(ctx);
-		const baseEnv = {};
-		for (const [k, v] of Object.entries(process.env)) if (v !== void 0) baseEnv[k] = v;
-		Object.assign(baseEnv, this.extraEnv);
-		const env = this.profile.buildEnv(ctx, baseEnv);
+		const env = this.buildLaunchEnv(ctx);
 		this.logBuffer = [];
-		let actualPort = initialPort;
-		let portResolver;
-		let portRejecter;
+		const signals = {
+			isLocal,
+			actualPort: initialPort
+		};
 		const portPromise = isLocal && initialPort === 0 ? new Promise((resolve, reject) => {
-			portResolver = resolve;
-			portRejecter = reject;
+			signals.resolvePort = resolve;
+			signals.rejectPort = reject;
 		}) : Promise.resolve(initialPort);
-		let readyUrlResolver;
-		let loginResolver;
 		const readyUrlPromise = new Promise((resolve) => {
-			readyUrlResolver = resolve;
+			signals.resolveReadyUrl = resolve;
 		});
 		const loginPromise = new Promise((resolve) => {
-			loginResolver = resolve;
+			signals.resolveLogin = resolve;
 		});
 		const child = await this.launchProcess(args, env, folder);
 		this.registerCleanup();
 		this.proc = child;
 		this.server = {
 			status: "starting",
-			port: isLocal ? actualPort || void 0 : void 0,
+			port: isLocal ? signals.actualPort || void 0 : void 0,
 			pid: child.pid,
 			startedAt: Date.now()
 		};
 		this.publish();
-		const capture = (chunk) => {
-			const text = chunk.toString("utf8");
-			this.appendLog(text);
-			for (const line of text.split("\n")) {
-				if (isLocal && actualPort === 0 && this.profile.matchPort) {
-					const port = this.profile.matchPort(line);
-					if (port) {
-						actualPort = port;
-						this.server.port = port;
-						this.publish();
-						portResolver?.(port);
-						portResolver = void 0;
-					}
-				}
-				if (this.profile.matchLogin) {
-					const login = this.profile.matchLogin(line);
-					if (login && this.proc === child) {
-						this.server = {
-							...this.server,
-							login
-						};
-						this.publish();
-						loginResolver?.(login);
-					}
-				}
-				if (this.profile.matchReadyUrl) {
-					const url = this.profile.matchReadyUrl(line);
-					if (url && this.proc === child) {
-						this.readyUrl = url;
-						readyUrlResolver?.(url);
-					}
-				}
-			}
+		child.stdout?.on("data", (chunk) => this.consumeOutput(chunk, child, signals));
+		child.stderr?.on("data", (chunk) => this.consumeOutput(chunk, child, signals));
+		child.on("error", (error) => this.handleChildError(child, error, signals));
+		child.on("exit", (code) => this.handleChildExit(child, code, signals));
+		try {
+			if (!isLocal) return await this.awaitTunnel(child, readyUrlPromise, loginPromise);
+			return await this.finalizeLocalStart(child, portPromise);
+		} catch (error) {
+			const reason = error instanceof Error ? error.message : String(error);
+			return this.handleStartFailure(child, reason, isLocal, signals.actualPort);
+		}
+	}
+	/** Adopt an already-running local server on the target port, if one answers. */
+	async tryAdopt(folder) {
+		const target = this.forcedPort && this.forcedPort !== 0 ? this.forcedPort : DEFAULT_CODE_SERVER_PORT;
+		if (!this.profile.healthPath || !await probeHealth(target, this.profile.healthPath)) return void 0;
+		this.adopted = true;
+		this.launchCtx = this.baseCtx(folder, target, "");
+		this.server = {
+			status: "running",
+			port: target,
+			startedAt: Date.now()
 		};
-		child.stdout?.on("data", capture);
-		child.stderr?.on("data", capture);
-		child.on("error", (error) => {
-			if (this.proc !== child) return;
-			this.server = {
-				status: "error",
-				error: error.message
-			};
-			this.reset();
-			portRejecter?.(error);
-			this.publish();
+		this.publish();
+		return this.status();
+	}
+	/** Resolve the port to launch on: 0 for tunnels/dynamic, a forced port, or a free one. */
+	async resolveInitialPort(isLocal) {
+		if (!isLocal) return 0;
+		if (this.forcedPort !== void 0 && this.forcedPort !== 0) return this.forcedPort;
+		if (this.forcedPort === 0) return 0;
+		return getPort({
+			host: "127.0.0.1",
+			port: DEFAULT_CODE_SERVER_PORT
 		});
-		child.on("exit", (code) => {
-			if (this.proc !== child) return;
-			const exitCode = code ?? 0;
-			const crashed = this.server.status !== "stopped" && exitCode !== 0;
-			this.reset();
-			this.server = crashed ? {
-				status: "error",
-				error: this.lastLog() || `${this.bin} exited with code ${exitCode}`
-			} : { status: "stopped" };
-			if (crashed) diagnostics.DP_CODE_SERVER_0005({ code: exitCode }, { method: "warn" });
-			this.reflectHub(crashed ? "error" : "stopped");
+	}
+	/** The child's environment: inherited env, caller overrides, then profile shaping. */
+	buildLaunchEnv(ctx) {
+		const baseEnv = {};
+		for (const [k, v] of Object.entries(process.env)) if (v !== void 0) baseEnv[k] = v;
+		Object.assign(baseEnv, this.extraEnv);
+		return this.profile.buildEnv(ctx, baseEnv);
+	}
+	/** Buffer output and latch the port / login / ready-URL signals from each line. */
+	consumeOutput(chunk, child, s) {
+		const text = chunk.toString("utf8");
+		this.appendLog(text);
+		for (const line of text.split("\n")) {
+			this.latchPort(line, s);
+			this.latchLogin(line, child, s);
+			this.latchReadyUrl(line, child, s);
+		}
+	}
+	latchPort(line, s) {
+		if (!s.isLocal || s.actualPort !== 0 || !this.profile.matchPort) return;
+		const port = this.profile.matchPort(line);
+		if (!port) return;
+		s.actualPort = port;
+		this.server.port = port;
+		this.publish();
+		s.resolvePort?.(port);
+		s.resolvePort = void 0;
+	}
+	latchLogin(line, child, s) {
+		const login = this.profile.matchLogin?.(line);
+		if (!login || this.proc !== child) return;
+		this.server = {
+			...this.server,
+			login
+		};
+		this.publish();
+		s.resolveLogin?.(login);
+	}
+	latchReadyUrl(line, child, s) {
+		const url = this.profile.matchReadyUrl?.(line);
+		if (!url || this.proc !== child) return;
+		this.readyUrl = url;
+		s.resolveReadyUrl?.(url);
+	}
+	handleChildError(child, error, s) {
+		if (this.proc !== child) return;
+		this.server = {
+			status: "error",
+			error: error.message
+		};
+		this.reset();
+		s.rejectPort?.(error);
+		this.publish();
+	}
+	handleChildExit(child, code, s) {
+		if (this.proc !== child) return;
+		const exitCode = code ?? 0;
+		const crashed = this.server.status !== "stopped" && exitCode !== 0;
+		this.reset();
+		this.server = crashed ? {
+			status: "error",
+			error: this.lastLog() || `${this.bin} exited with code ${exitCode}`
+		} : { status: "stopped" };
+		if (crashed) diagnostics.DP_CODE_SERVER_0005({ code: exitCode }, { method: "warn" });
+		this.reflectHub(crashed ? "error" : "stopped");
+		this.session = void 0;
+		s.rejectPort?.(/* @__PURE__ */ new Error(`${this.bin} exited before binding (code ${exitCode})`));
+		this.publish();
+	}
+	/** Wait for the dynamic port then readiness, and flip to `running`. */
+	async finalizeLocalStart(child, portPromise) {
+		const port = await Promise.race([portPromise, new Promise((_, reject) => setTimeout(() => reject(/* @__PURE__ */ new Error("timeout waiting for dynamic port allocation")), this.startTimeout))]);
+		if (!await this.waitForReady(port, this.profile.healthPath)) throw new Error(this.lastLog() || "startup timed out");
+		if (this.proc !== child) return this.status();
+		this.server = {
+			status: "running",
+			port,
+			pid: child.pid,
+			startedAt: this.server.startedAt
+		};
+		this.publish();
+		return this.status();
+	}
+	handleStartFailure(child, reason, isLocal, actualPort) {
+		if (this.proc === child) {
+			this.terminate(child);
+			this.reflectHub("error");
 			this.session = void 0;
-			portRejecter?.(/* @__PURE__ */ new Error(`${this.bin} exited before binding (code ${exitCode})`));
-			this.publish();
-		});
-		try {
-			if (!isLocal) return await this.awaitTunnel(child, readyUrlPromise, loginPromise);
-			const port = await Promise.race([portPromise, new Promise((_, reject) => setTimeout(() => reject(/* @__PURE__ */ new Error("timeout waiting for dynamic port allocation")), this.startTimeout))]);
-			if (!await this.waitForReady(port, this.profile.healthPath)) throw new Error(this.lastLog() || "startup timed out");
-			if (this.proc !== child) return this.status();
 			this.server = {
-				status: "running",
-				port,
-				pid: child.pid,
-				startedAt: this.server.startedAt
+				status: "error",
+				error: reason
 			};
+			this.reset();
 			this.publish();
-			return this.status();
-		} catch (error) {
-			if (this.proc === child) {
-				this.terminate(child);
-				this.reflectHub("error");
-				this.session = void 0;
-				this.server = {
-					status: "error",
-					error: error instanceof Error ? error.message : String(error)
-				};
-				this.reset();
-				this.publish();
-			}
-			if (!isLocal) throw diagnostics.DP_CODE_SERVER_0006({ timeout: this.startTimeout });
-			throw diagnostics.DP_CODE_SERVER_0002({
-				port: actualPort,
-				timeout: this.startTimeout
-			});
 		}
+		if (!isLocal) throw diagnostics.DP_CODE_SERVER_0006({ timeout: this.startTimeout });
+		throw diagnostics.DP_CODE_SERVER_0002({
+			port: actualPort,
+			timeout: this.startTimeout
+		});
 	}
 	/** Stop the editor process and reset to `stopped`. */
 	stop() {
@@ -590,7 +617,7 @@ var CodeServerSupervisor = class {
 	/**
 	* Resolve the hub's terminals subsystem when this devframe is mounted in a
 	* hub. `ctx.terminals` only exists on a `DevframeHubContext`, so it is
-	* duck-typed — standalone runtimes (CLI / Vite / build) have no such property
+	* duck-typed: standalone runtimes (CLI / Vite / build) have no such property
 	* and fall back to a direct child process.
 	*/
 	resolveHubTerminals() {
@@ -614,45 +641,58 @@ var CodeServerSupervisor = class {
 	*/
 	async launchProcess(args, env, folder) {
 		const hub = this.resolveHubTerminals();
-		if (hub) {
-			const stale = hub.sessions.get(this.sessionId);
-			if (stale) hub.remove?.(stale);
-			try {
-				const session = await hub.startChildProcess({
-					command: this.bin,
-					args,
-					cwd: folder,
-					env: {
-						...env,
-						PASSWORD: ""
-					}
-				}, {
-					id: this.sessionId,
-					title: TERMINAL_SESSION_TITLE,
-					description: folder,
-					icon: TERMINAL_SESSION_ICON,
-					restartable: false
-				});
-				const child = session.getChildProcess();
-				if (!child) throw new Error("editor process handle was unavailable");
-				this.session = session;
-				return child;
-			} catch (error) {
-				const reason = error instanceof Error ? error.message : String(error);
-				const orphan = hub.sessions.get(this.sessionId);
-				if (orphan) hub.remove?.(orphan);
-				this.session = void 0;
-				this.server = {
-					status: "error",
-					error: reason
-				};
-				this.publish();
-				throw diagnostics.DP_CODE_SERVER_0003({
-					bin: this.bin,
-					reason
-				});
-			}
+		return hub ? this.launchViaHub(hub, args, env, folder) : this.launchDirect(args, env, folder);
+	}
+	/** Spawn through the hub's terminals subsystem so it shows as a terminal session. */
+	async launchViaHub(hub, args, env, folder) {
+		const stale = hub.sessions.get(this.sessionId);
+		if (stale) hub.remove?.(stale);
+		try {
+			const session = await hub.startChildProcess({
+				command: this.bin,
+				args,
+				cwd: folder,
+				/**
+				* The hub merges `process.env`, so neutralize PASSWORD explicitly
+				* (code-server authenticates via HASHED_PASSWORD).
+				*/
+				env: {
+					...env,
+					PASSWORD: ""
+				}
+			}, {
+				id: this.sessionId,
+				title: TERMINAL_SESSION_TITLE,
+				description: folder,
+				icon: TERMINAL_SESSION_ICON,
+				/**
+				* Restart re-runs the supervisor's start flow (fresh port + secret),
+				* not this raw process, so hide the panel's generic restart.
+				*/
+				restartable: false
+			});
+			const child = session.getChildProcess();
+			if (!child) throw new Error("editor process handle was unavailable");
+			this.session = session;
+			return child;
+		} catch (error) {
+			const reason = error instanceof Error ? error.message : String(error);
+			const orphan = hub.sessions.get(this.sessionId);
+			if (orphan) hub.remove?.(orphan);
+			this.session = void 0;
+			this.server = {
+				status: "error",
+				error: reason
+			};
+			this.publish();
+			throw diagnostics.DP_CODE_SERVER_0003({
+				bin: this.bin,
+				reason
+			});
 		}
+	}
+	/** Spawn the editor binary directly (standalone runtimes with no hub). */
+	launchDirect(args, env, folder) {
 		try {
 			return spawn(this.bin, args, {
 				cwd: folder,
@@ -746,7 +786,7 @@ function probeHealth(port, path) {
 * status into shared state, and register the control RPC functions. Returns
 * the supervisor so callers can launch/stop or dispose it on shutdown.
 *
-* Works in any devframe runtime (CLI, Vite, embedded, build) — it only relies
+* Works in any devframe runtime (CLI, Vite, embedded, build), since it only relies
 * on the core `ctx.rpc` shared-state surface, not on the hub.
 */
 async function setupCodeServer(ctx, options = {}) {

package/dist/{src-CNJYQ3UQ.mjs → src-5dhTkOqj.mjs}

@@ -2,7 +2,7 @@ import { PLUGIN_ID } from "./constants.mjs";
 import { defineDevframe } from "devframe";
 //#region package.json
 var name = "@devframes/plugin-code-server";
-var version = "0.9.8";
+var version = "0.9.9";
 var description = "Devframe plugin that runs VS Code in the browser as an embedded editor panel.";
 var homepage = "https://github.com/devframes/devframe#readme";
 //#endregion
@@ -14,7 +14,7 @@ const remoteAssets = {
 /**
 * Build a {@link DevframeDefinition} for the code-server panel. The same
 * definition runs standalone (`createCac`), mounts into a Vite host
-* (`/vite`), or docks inside a hub — its `setup` only relies on the core
+* (`/vite`), or docks inside a hub, since its `setup` only relies on the core
 * devframe RPC + shared-state surface.
 *
 * @experimental This plugin is experimental and may change without a major
@@ -38,6 +38,10 @@ function createCodeServerDevframe(options = {}) {
 		homepage,
 		description,
 		icon: "ph:code-duotone",
+		/**
+		* Leave undefined so `resolveBasePath` picks `/` standalone and
+		* `/__<id>/` when hosted. Authors override via `options.basePath`.
+		*/
 		basePath: options.basePath,
 		cli: {
 			command: options.command ?? "devframe-code-server",
@@ -45,6 +49,11 @@ function createCodeServerDevframe(options = {}) {
 			portRange: options.portRange,
 			random: options.random,
 			distDir: resolvedDist,
+			/**
+			* Gate the standalone launcher by default; `maybeOpenBrowser` folds the
+			* current OTP into the `--open` URL so the tab lands already trusted.
+			* Hosted adapters supply their own auth layer and ignore this.
+			*/
 			auth: options.auth ?? true
 		},
 		async setup(ctx) {

package/dist/types.d.mts

@@ -4,11 +4,11 @@ type CodeServerStatus = 'stopped' | 'starting' | 'running' | 'error';
 /**
  * Which editor server binary the plugin launches in `mode: 'local'`:
  *
- * - `'code-server'` — Coder's open-source
+ * - `'code-server'`: Coder's open-source
  *   [code-server](https://github.com/coder/code-server) (`code-server …`). The
  *   plugin runs it with password auth and hands the client a session cookie, so
  *   the embedded editor opens already signed in.
- * - `'ms-code-serve-web'` — Microsoft's official
+ * - `'ms-code-serve-web'`: Microsoft's official
  *   [`code serve-web`](https://code.visualstudio.com/docs/remote/vscode-server)
  *   (ships with the `code` CLI). The plugin generates a connection token and
  *   hands it to the client as a `?tkn=` query parameter.
@@ -17,9 +17,9 @@ type CodeServerBackend = 'code-server' | 'ms-code-serve-web';
 /**
  * How the editor is served:
  *
- * - `'local'` — a local server ({@link CodeServerBackend}) embedded from this
+ * - `'local'`: a local server ({@link CodeServerBackend}) embedded from this
  *   machine's origin.
- * - `'tunnel'` — Microsoft's `code tunnel`, which registers a remote tunnel and
+ * - `'tunnel'`: Microsoft's `code tunnel`, which registers a remote tunnel and
  *   embeds the hosted `vscode.dev` editor. First launch prints a device-login
  *   prompt (surfaced as {@link CodeServerLogin}); authentication is handled by
  *   `vscode.dev` itself, not this plugin.
@@ -70,7 +70,7 @@ interface CodeServerServerInfo {
 }
 /**
  * The full shared-state payload broadcast to subscribed clients. Deliberately
- * carries no authentication material — see {@link CodeServerConnect}.
+ * carries no authentication material; see {@link CodeServerConnect}.
  */
 interface CodeServerSharedState {
   detection: CodeServerDetection;
@@ -79,7 +79,7 @@ interface CodeServerSharedState {
 /**
  * How the client reaches the running editor. May carry a secret (session
  * cookie or connection token), so it is returned only from the `start` /
- * `status` RPCs to the already-authorized client — never published to shared
+ * `status` RPCs to the already-authorized client, never published to shared
  * state.
  *
  * - `url` set → embed it verbatim (tunnel mode's `vscode.dev` URL).
@@ -98,11 +98,11 @@ interface CodeServerConnect {
     value: string;
   };
 }
-/** Result of the `status` query — shared state plus connect info when running. */
+/** Result of the `status` query: shared state plus connect info when running. */
 interface CodeServerStatusResult extends CodeServerSharedState {
   connect?: CodeServerConnect;
 }
-/** Result of the `start` action — identical shape to {@link CodeServerStatusResult}. */
+/** Result of the `start` action, identical shape to {@link CodeServerStatusResult}. */
 type CodeServerStartResult = CodeServerStatusResult;
 /** Wire payload for the `start` RPC. */
 interface CodeServerStartRequest {
@@ -169,7 +169,7 @@ interface CodeServerOptions {
   random?: boolean;
   /**
    * Require the trust handshake on the standalone launcher server. Enabled
-   * by default — `--open` embeds the current OTP in the opened URL, so the
+   * by default; `--open` embeds the current OTP in the opened URL, so the
    * tab authenticates automatically without extra prompts. Hosted adapters
    * manage their own auth and ignore this.
    */

package/dist/vite.mjs

@@ -1,4 +1,4 @@
-import { t as createCodeServerDevframe } from "./src-CNJYQ3UQ.mjs";
+import { t as createCodeServerDevframe } from "./src-5dhTkOqj.mjs";
 import { devframeViteBridge, devframeVitePlugin } from "@devframes/vite/single";
 //#region src/vite.ts
 /**

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@devframes/plugin-code-server",
   "type": "module",
-  "version": "0.9.8",
+  "version": "0.9.9",
   "description": "Devframe plugin that runs VS Code in the browser as an embedded editor panel.",
   "author": "Anthony Fu <anthonyfu117@hotmail.com>",
   "license": "MIT",
@@ -40,8 +40,8 @@
     "dist"
   ],
   "peerDependencies": {
-    "@devframes/plugin-code-server--assets": "0.9.8",
-    "devframe": "0.9.8",
+    "@devframes/plugin-code-server--assets": "0.9.9",
+    "devframe": "0.9.9",
     "vite": "^8.0.0"
   },
   "peerDependenciesMeta": {
@@ -53,19 +53,19 @@
     }
   },
   "dependencies": {
-    "@devframes/vite": "0.9.8",
+    "@devframes/vite": "0.9.9",
     "cac": "^7.0.0"
   },
   "devDependencies": {
     "@antfu/design": "^0.4.0",
-    "@devframes/plugin-code-server--assets": "0.9.8",
+    "@devframes/plugin-code-server--assets": "0.9.9",
     "@iconify-json/ph": "^1.2.2",
     "@storybook/addon-docs": "^10.5.10",
     "@storybook/vue3-vite": "^10.5.10",
     "@types/node": "^26.4.0",
     "@vitejs/plugin-vue": "^6.0.8",
     "colorjs.io": "^0.7.1",
-    "devframe": "0.9.8",
+    "devframe": "0.9.9",
     "storybook": "^10.5.10",
     "tsdown": "^0.22.14",
     "unocss": "^66.8.1",