@codeyam-editor/codeyam-editor 0.1.1 → 0.1.3

package/npm/utils.js

@@ -6,6 +6,24 @@ const fs = require("fs");
 const rootDir = path.resolve(__dirname, "..");
 const serverStatePath = path.join(rootDir, ".codeyam", "server-state.json");
 
+/**
+ * Map (process.platform, process.arch) → the platform sub-package that
+ * carries the matching native binaries. Each sub-package ships TWO
+ * binaries side-by-side in its `bin/` dir: the `codeyam-editor` monolith
+ * and the dedicated `codeyam-editor-pty-broker` daemon (its own
+ * executable file / inode, for a stable honest process name). They live
+ * in the same dir so the broker auto-spawn's sibling-of-current-exe
+ * resolution finds the broker next to the monolith with no copying.
+ * Kept as a small data table so adding a new platform (e.g. linux/arm64)
+ * is one entry, not a new branch.
+ */
+const PLATFORM_PACKAGES = {
+  "darwin-arm64": { pkg: "@codeyam-editor/codeyam-editor-darwin-arm64", binary: "codeyam-editor", broker: "codeyam-editor-pty-broker" },
+  "darwin-x64":   { pkg: "@codeyam-editor/codeyam-editor-darwin-x64",   binary: "codeyam-editor", broker: "codeyam-editor-pty-broker" },
+  "linux-x64":    { pkg: "@codeyam-editor/codeyam-editor-linux-x64",    binary: "codeyam-editor", broker: "codeyam-editor-pty-broker" },
+  "win32-x64":    { pkg: "@codeyam-editor/codeyam-editor-win32-x64",    binary: "codeyam-editor.exe", broker: "codeyam-editor-pty-broker.exe" },
+};
+
 /**
  * Platform-correct executable filename for the codeyam-editor binary.
  * Windows requires the `.exe` extension; on Unix the binary has no extension.
@@ -15,36 +33,118 @@ function binaryName(platform = process.platform) {
   return platform === "win32" ? "codeyam-editor.exe" : "codeyam-editor";
 }
 
-/** Find the compiled binary — check npm-installed location first, then dev builds. */
+/**
+ * Platform-correct executable filename for the dedicated broker binary.
+ * Mirrors {@link binaryName} for the second shipped binary.
+ */
+function brokerBinaryName(platform = process.platform) {
+  return platform === "win32" ? "codeyam-editor-pty-broker.exe" : "codeyam-editor-pty-broker";
+}
+
+/** Look up the platform sub-package metadata for a given platform/arch pair. */
+function platformPackageInfo(platform = process.platform, arch = process.arch) {
+  return PLATFORM_PACKAGES[`${platform}-${arch}`] || null;
+}
+
+/**
+ * Resolve the native binary path.
+ *
+ * Production install (npm install @codeyam-editor/codeyam-editor):
+ *   npm installed the matching @codeyam-editor/codeyam-editor-<plat>-<arch>
+ *   sub-package via optionalDependencies. require.resolve finds the binary
+ *   inside that sibling package.
+ *
+ * Dev checkout (`cargo build` in the repo):
+ *   No platform sub-package installed; fall through to target/debug or
+ *   target/release.
+ *
+ * Returns null if no binary can be found at any of these locations — the
+ * caller (ensureBinary / cli.js) decides whether to error or to invoke
+ * `cargo build` based on whether a Cargo.toml is present.
+ */
 function findBinary() {
-  const name = binaryName();
-  const candidates = [
-    path.join(rootDir, "bin", name),                   // npm install (postinstall)
-    path.join(rootDir, "target", "debug", name),       // local dev (debug)
-    path.join(rootDir, "target", "release", name),     // local dev (release)
-  ];
-
-  for (const candidate of candidates) {
-    if (fs.existsSync(candidate)) {
-      return candidate;
+  const info = platformPackageInfo();
+  if (info) {
+    try {
+      const resolved = require.resolve(`${info.pkg}/bin/${info.binary}`, {
+        paths: [rootDir],
+      });
+      if (fs.existsSync(resolved)) return resolved;
+    } catch (e) {
+      if (e.code !== "MODULE_NOT_FOUND") throw e;
     }
   }
 
+  const name = binaryName();
+  // Target directories to search, in precedence order. A custom
+  // CARGO_TARGET_DIR (cloud VMs set CARGO_TARGET_DIR=/codeyam-build-target)
+  // wins over the default ./target — cargo builds ONLY into the configured
+  // dir, so ./target may be stale or absent. Honoring it here keeps
+  // `ensureBinary` from building successfully and then failing to locate the
+  // result. CARGO_TARGET_DIR may be absolute or relative to the workspace
+  // root; path.resolve handles both (an absolute value ignores rootDir).
+  const targetDirs = [];
+  const customTarget = process.env.CARGO_TARGET_DIR;
+  if (customTarget) {
+    targetDirs.push(path.resolve(rootDir, customTarget));
+  }
+  targetDirs.push(path.join(rootDir, "target"));
+
+  const devCandidates = [];
+  for (const dir of targetDirs) {
+    devCandidates.push(path.join(dir, "debug", name));
+    devCandidates.push(path.join(dir, "release", name));
+  }
+  for (const candidate of devCandidates) {
+    if (fs.existsSync(candidate)) return candidate;
+  }
+
   return null;
 }
 
-/** Return the binary path — build from source only if no pre-built binary exists. */
+/**
+ * Return the binary path, building from source if we're in a dev checkout.
+ *
+ * Production install: if findBinary returns null, the platform sub-package
+ * is missing — npm install failed silently (likely because the user's
+ * platform isn't in the build matrix). Emit a clear, actionable error
+ * naming the expected sub-package, and exit 1. **Do not** fall through to
+ * `cargo build` — there's no Cargo.toml in the npm install dir, and the
+ * resulting "could not find Cargo.toml" error is misleading to users.
+ *
+ * Dev checkout: `Cargo.toml` is present at rootDir → run `cargo build`,
+ * same as the legacy behavior.
+ */
 function ensureBinary() {
   const existing = findBinary();
   if (existing) return existing;
 
-  // No pre-built binary; try building from source (local dev workflow).
+  const isDevCheckout = fs.existsSync(path.join(rootDir, "Cargo.toml"));
+
+  if (!isDevCheckout) {
+    const info = platformPackageInfo();
+    if (!info) {
+      console.error(
+        `codeyam-editor: unsupported platform ${process.platform}/${process.arch}.\n` +
+        `Supported: darwin/arm64, darwin/x64, linux/x64, win32/x64.`
+      );
+    } else {
+      console.error(
+        `codeyam-editor: native binary missing.\n` +
+        `Expected at ${info.pkg}/bin/${info.binary} — npm should have installed ` +
+        `that sub-package as an optionalDependency.\n` +
+        `Try: npm install --force ${info.pkg}@$(npm view @codeyam-editor/codeyam-editor version)`
+      );
+    }
+    process.exit(1);
+  }
+
   try {
     execSync("cargo --version", { stdio: "ignore" });
   } catch {
     console.error(
-      "codeyam-editor binary not found. Try reinstalling:\n" +
-      "  npm install @codeyam-editor/codeyam-editor\n"
+      "codeyam-editor binary not found and `cargo` is not on PATH. " +
+      "Install Rust from https://rustup.rs/ or reinstall @codeyam-editor/codeyam-editor."
     );
     process.exit(1);
   }
@@ -62,14 +162,255 @@ function ensureBinary() {
     console.error("Binary not found after build.");
     process.exit(1);
   }
+  verifyBrokerBinaryPresent(binary);
   return binary;
 }
 
+/**
+ * Resolve the dedicated broker binary path. Mirrors {@link findBinary}:
+ * the published platform sub-package ships it next to the monolith, and
+ * a dev `cargo build` produces it under target/debug|release. Returns
+ * null if it can't be located — the Rust broker auto-spawn then falls
+ * back to the monolith `editor pty-broker daemon` shim, so a missing
+ * broker binary degrades gracefully rather than breaking the editor.
+ */
+function findBrokerBinary() {
+  const info = platformPackageInfo();
+  if (info && info.broker) {
+    try {
+      const resolved = require.resolve(`${info.pkg}/bin/${info.broker}`, {
+        paths: [rootDir],
+      });
+      if (fs.existsSync(resolved)) return resolved;
+    } catch (e) {
+      if (e.code !== "MODULE_NOT_FOUND") throw e;
+    }
+  }
+
+  const name = brokerBinaryName();
+  const targetDirs = [];
+  const customTarget = process.env.CARGO_TARGET_DIR;
+  if (customTarget) {
+    targetDirs.push(path.resolve(rootDir, customTarget));
+  }
+  targetDirs.push(path.join(rootDir, "target"));
+
+  for (const dir of targetDirs) {
+    for (const profile of ["debug", "release"]) {
+      const candidate = path.join(dir, profile, name);
+      if (fs.existsSync(candidate)) return candidate;
+    }
+  }
+  return null;
+}
+
+/**
+ * Best-effort check that the dedicated broker binary sits next to the
+ * monolith (the layout the broker auto-spawn's sibling resolution
+ * expects). Logs a one-line note when it's missing — never throws or
+ * exits, because the Rust side degrades to the monolith shim. `monolith`
+ * is the resolved monolith binary path; the broker is expected as its
+ * sibling.
+ */
+function verifyBrokerBinaryPresent(monolith) {
+  const sibling = path.join(path.dirname(monolith), brokerBinaryName());
+  if (fs.existsSync(sibling)) return;
+  const located = findBrokerBinary();
+  if (located) return;
+  console.error(
+    "Note: dedicated broker binary (codeyam-editor-pty-broker) not found next to " +
+    `${monolith}. The PTY broker will fall back to the monolith \`editor pty-broker daemon\` ` +
+    "shim. Reinstall the platform sub-package, or run `cargo build -p codeyam-pty-broker`."
+  );
+}
+
 /** Resolve the UI dist directory for the binary to serve. */
 function uiDistDir() {
   return path.join(rootDir, "ui", "dist");
 }
 
+/**
+ * Loud banner printed when `cargo build` failed and a wrapper is about to fall
+ * back to a stale binary. Shared by both wrappers (editor.js server boot,
+ * editor-dev.js passthrough/launch) so the refusal text and the documented
+ * CODEYAM_ALLOW_STALE escape hatch stay identical. `action` names what would
+ * run on the stale binary, e.g. "run editor commands" / "start the editor
+ * server".
+ */
+function staleBinaryBanner(action = "run editor commands") {
+  return [
+    "",
+    "============================================================",
+    "  cargo build FAILED — the editor source does not compile.",
+    `  Refusing to ${action} on a STALE binary,`,
+    "  which would run code that no longer matches the source.",
+    "",
+    "  Fix the compile error above, then re-run.",
+    "  To deliberately run the last-good binary anyway, set",
+    "  CODEYAM_ALLOW_STALE=1.",
+    "============================================================",
+    "",
+  ].join("\n");
+}
+
+/**
+ * Enforce a fresh binary before a wrapper runs it. A no-op when the rebuild
+ * succeeded (`buildOk` true). When it failed, print the stale-binary banner and
+ * `process.exit(1)` — UNLESS `CODEYAM_ALLOW_STALE=1`, in which case print a
+ * one-line override notice and return so the caller proceeds on the last-good
+ * binary. This is the single code path the passthrough, launch, and
+ * server-boot call sites share, so they cannot diverge on whether they honor
+ * the override. `continueVerb` tailors the override notice ("continuing with"
+ * vs "launching with").
+ */
+function enforceFreshBinary(buildOk, { action, continueVerb = "continuing with" } = {}) {
+  if (buildOk) {
+    return;
+  }
+  console.error(staleBinaryBanner(action));
+  if (process.env.CODEYAM_ALLOW_STALE !== "1") {
+    process.exit(1);
+  }
+  console.error(
+    `CODEYAM_ALLOW_STALE=1 set — ${continueVerb} the existing (stale) binary.`,
+  );
+}
+
+function isPlainJsonObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+// Mirrors `deep_merge_json` in crates/types/src/config.rs:1284.
+// Objects merge by key (`null` in overlay removes the key); arrays merge
+// by index (extra overlay items appended, base items past overlay length
+// retained); scalars replace. The JS and Rust sides MUST match — any
+// divergence shows up as "the CLI sees port X but `npm run editor`
+// opens port Y", which is exactly the bug this whole helper exists to
+// prevent.
+function deepMergeJson(base, overlay) {
+  if (isPlainJsonObject(base) && isPlainJsonObject(overlay)) {
+    for (const k of Object.keys(overlay)) {
+      const v = overlay[k];
+      if (v === null) {
+        delete base[k];
+      } else if (Object.prototype.hasOwnProperty.call(base, k)) {
+        base[k] = deepMergeJson(base[k], v);
+      } else {
+        base[k] = v;
+      }
+    }
+    return base;
+  }
+  if (Array.isArray(base) && Array.isArray(overlay)) {
+    for (let i = 0; i < overlay.length; i++) {
+      if (i < base.length) {
+        base[i] = deepMergeJson(base[i], overlay[i]);
+      } else {
+        base.push(overlay[i]);
+      }
+    }
+    return base;
+  }
+  return overlay;
+}
+
+// Mirrors the post-merge strip in `merged_config_value`
+// (crates/types/src/config.rs:1272). Any top-level key starting with
+// `_` is documentation-only (`_README`, `_examples`, …) and is removed
+// before the merged config is used by the launcher or handed to the
+// Rust binary. Mutates in place; returns the same object for chaining.
+function stripUnderscoreTopLevelKeys(value) {
+  if (isPlainJsonObject(value)) {
+    for (const k of Object.keys(value)) {
+      if (k.startsWith("_")) delete value[k];
+    }
+  }
+  return value;
+}
+
+/**
+ * Read `<projectDir>/.codeyam/editor.json` and deep-merge an optional
+ * sibling `editor.local.json` on top, returning the merged plain object.
+ *
+ * This is the JS-side equivalent of `merged_config_value` in
+ * crates/types/src/config.rs — same merge rules, same underscore-prefix
+ * strip. Launcher scripts call this *before* the Rust binary is built
+ * (they invoke `cargo build` themselves), so shelling out to
+ * `codeyam-editor editor config-show` is not an option.
+ *
+ * Returns `{}` if the base file is missing (a freshly cloned repo with
+ * no `.codeyam/` directory should not throw at require-time). Throws
+ * on malformed JSON, naming the offending file path so the user knows
+ * which file to fix.
+ */
+function readMergedEditorConfig(projectDir = rootDir) {
+  const basePath = path.join(projectDir, ".codeyam", "editor.json");
+  if (!fs.existsSync(basePath)) return {};
+
+  let merged;
+  try {
+    merged = JSON.parse(fs.readFileSync(basePath, "utf8"));
+  } catch (e) {
+    throw new Error(`Failed to parse ${basePath}: ${e.message}`);
+  }
+  if (!isPlainJsonObject(merged)) merged = {};
+
+  const overlayPath = path.join(projectDir, ".codeyam", "editor.local.json");
+  if (fs.existsSync(overlayPath)) {
+    let overlay;
+    try {
+      overlay = JSON.parse(fs.readFileSync(overlayPath, "utf8"));
+    } catch (e) {
+      throw new Error(`Failed to parse ${overlayPath}: ${e.message}`);
+    }
+    if (isPlainJsonObject(overlay)) {
+      deepMergeJson(merged, overlay);
+    }
+  }
+
+  return stripUnderscoreTopLevelKeys(merged);
+}
+
+/**
+ * Resolve a port for a launcher in priority order:
+ * explicit env var → merged-config value → hard fallback.
+ *
+ * Exported so each launcher's port resolution can be unit-tested
+ * without spawning a process. The fallback is the historical hard-coded
+ * value (14199 / 5173 / 3000 depending on which slot the caller is
+ * resolving) and exists so a fresh checkout with no override file and
+ * no env var still works.
+ */
+function resolveLauncherPort(envValue, mergedValue, fallback) {
+  if (envValue !== undefined && envValue !== null && envValue !== "") {
+    const parsed = parseInt(envValue, 10);
+    if (Number.isFinite(parsed)) return parsed;
+  }
+  if (typeof mergedValue === "number" && Number.isFinite(mergedValue)) {
+    return mergedValue;
+  }
+  return fallback;
+}
+
+/**
+ * Resolve the wrapped-app port (the port the launcher logs and probes).
+ * Mirrors `resolve_app_port` in
+ * `crates/codeyam-editor/src/commands/start.rs`: `env > apps[0].port >
+ * config.port`. Any divergence between this helper and the Rust resolver
+ * shows up as "the launcher waits on port X but the backend binds Y",
+ * which is the failure mode this whole helper exists to prevent.
+ *
+ * `merged` is the deep-merged editor.json + editor.local.json blob; pass
+ * `null`/`undefined` when no config is available so the launcher's
+ * env-and-fallback path still works on a project with no `.codeyam/`.
+ */
+function resolveWrappedAppPort(merged, envValue, fallback) {
+  const appsZeroPort = merged && merged.apps && merged.apps[0] && merged.apps[0].port;
+  const topLevelPort = merged && merged.port;
+  const mergedValue = typeof appsZeroPort === "number" ? appsZeroPort : topLevelPort;
+  return resolveLauncherPort(envValue, mergedValue, fallback);
+}
+
 /** Try to connect to a specific host:port. Returns true if something is listening. */
 function tryConnect(port, host) {
   return new Promise((resolve) => {
@@ -127,6 +468,10 @@ function clearServerState() {
   } catch {}
 }
 
+// Default ports across stopServer / restartServer / ensureServer /
+// requestServerShutdown are a backstop for any future caller that
+// forgets to pass an explicit port. Every production call site now
+// resolves the port from `readMergedEditorConfig` + `resolveLauncherPort`.
 async function requestServerShutdown(port = 14199, timeoutMs = 1500) {
   const controller = new AbortController();
   const timeout = setTimeout(() => controller.abort(), timeoutMs);
@@ -144,6 +489,121 @@ async function requestServerShutdown(port = 14199, timeoutMs = 1500) {
   }
 }
 
+/**
+ * GET /api/codeyam-server-identity from the listener on `port` with a
+ * sub-second timeout. Returns the parsed `{projectDir, pid, version,
+ * startedAt}` body on a 2xx response, or `null` on any failure
+ * (timeout, non-200, parse failure, connection refused).
+ *
+ * `null` carries two distinct meanings that the caller must
+ * disambiguate by also checking `isPortInUse`:
+ *   - port is free → no listener at all
+ *   - port is in use → something is listening, but it's not a
+ *     codeyam-editor server (or it's an old build that predates this
+ *     endpoint).
+ */
+async function fetchServerIdentity(port, timeoutMs = 500) {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), timeoutMs);
+
+  try {
+    const resp = await fetch(`http://127.0.0.1:${port}/api/codeyam-server-identity`, {
+      method: "GET",
+      signal: controller.signal,
+    });
+    if (!resp.ok) return null;
+    const body = await resp.json();
+    if (!body || typeof body !== "object" || typeof body.projectDir !== "string") {
+      return null;
+    }
+    return body;
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+/**
+ * Resolve the canonical (symlink-followed) path for `dir`, falling back to
+ * `dir` if `fs.realpath` fails (e.g. the path no longer exists). Both
+ * sides of the identity check route through this so a `~/work/foo`
+ * symlink and a `/Volumes/dev/foo` direct path compare equal.
+ */
+async function canonicalisePath(dir) {
+  try {
+    return await fs.promises.realpath(dir);
+  } catch {
+    return dir;
+  }
+}
+
+/**
+ * Build the "port held by a non-codeyam-editor process" error string.
+ * Lives next to `classifyPortHolder` so the wording is tested without
+ * a running server — both launchers (`ensureServer` and `editor.js`'s
+ * `--restart`) print this exact message on a "foreign" classification.
+ */
+function formatForeignListenerError(port) {
+  return (
+    `Port ${port} is in use, but no codeyam-editor server responded ` +
+    `at /api/codeyam-server-identity. Free the port or change ` +
+    `controlPort in .codeyam/editor.local.json.`
+  );
+}
+
+/**
+ * Build the "another project's editor is on this port" error string.
+ * `verb` is the action the launcher would have taken ("attach" /
+ * "restart"); the wording is otherwise identical so both launcher
+ * paths share the same advice.
+ */
+function formatCrossProjectError(port, holder, verb) {
+  const pidNote = Number.isInteger(holder.identity && holder.identity.pid)
+    ? ` (pid ${holder.identity.pid})`
+    : "";
+  return (
+    `Refusing to ${verb} a codeyam-editor server for a different project.\n` +
+    `  This project: ${holder.wantDir}\n` +
+    `  Server on port ${port}${pidNote}: ${holder.haveDir}\n` +
+    `\n` +
+    `Change controlPort in .codeyam/editor.local.json, e.g.:\n` +
+    `  codeyam-editor editor config-override proxy.controlPort 14399`
+  );
+}
+
+/**
+ * Classify whatever is listening on `port` relative to `projectDir`.
+ * Returns one of:
+ *   - `{ kind: "free" }`                    — nothing on the port
+ *   - `{ kind: "foreign" }`                 — port held by a non-editor process
+ *   - `{ kind: "cross-project", wantDir, haveDir, identity }`
+ *                                           — held by another project's editor
+ *   - `{ kind: "same-project", identity }`  — held by THIS project's editor
+ *
+ * Pure: every effect (network, fs) is bounded; no console output, no
+ * process.exit. The launcher decides what to do with each kind. Splitting
+ * the policy (what to print, when to exit) from the classification keeps
+ * the helper testable without mocking process.exit, and lets `ensureServer`
+ * and `editor.js`'s `--restart` block share the same logic with different
+ * wording.
+ */
+async function classifyPortHolder(port, projectDir = process.cwd()) {
+  if (!(await isPortInUse(port))) {
+    return { kind: "free" };
+  }
+  const identity = await fetchServerIdentity(port);
+  if (identity === null) {
+    return { kind: "foreign" };
+  }
+  const wantDir = await canonicalisePath(projectDir);
+  const haveDir = await canonicalisePath(identity.projectDir);
+  if (wantDir !== haveDir) {
+    return { kind: "cross-project", wantDir, haveDir, identity };
+  }
+  return { kind: "same-project", identity };
+}
+
 function tryKillPid(pid) {
   try {
     // On Windows, `process.kill(pid, "SIGINT")` either errors or no-ops
@@ -235,23 +695,59 @@ async function restartServer(port = 14199) {
   return ensureServer(port);
 }
 
-/** Start the Rust backend server if not already running. Returns the child process (or null if already running). */
+/**
+ * Start the Rust backend server if not already running, refusing to attach
+ * if the existing listener belongs to a different project (or to a foreign
+ * process that doesn't speak the identity endpoint at all). Returns the
+ * spawned child on a fresh start, or `null` when we attached to an
+ * already-running same-project server. Exits the process non-zero on a
+ * mismatch — silently choosing a different port would just relocate the
+ * surprise.
+ */
 async function ensureServer(port = 14199) {
-  if (await isPortInUse(port)) {
-    console.error(`Server already running on port ${port}`);
-    return null;
+  const holder = await classifyPortHolder(port);
+  switch (holder.kind) {
+    case "foreign":
+      console.error(formatForeignListenerError(port));
+      process.exit(1);
+      break;
+    case "cross-project":
+      console.error(formatCrossProjectError(port, holder, "attach"));
+      process.exit(1);
+      break;
+    case "same-project":
+      console.error(`Server already running on port ${port}`);
+      return null;
+    case "free":
+    default:
+      break;
   }
 
   const binary = ensureBinary();
+  // UI bundle is embedded in the Rust binary; CODEYAM_EDITOR_UI_DIR is
+  // now an explicit dev-override only.
   const child = spawn(binary, ["start", "--no-open", "--port", String(port)], {
     stdio: "inherit",
     cwd: process.cwd(),
     detached: false,
-    env: { ...process.env, CODEYAM_EDITOR_UI_DIR: uiDistDir() },
+    env: process.env,
   });
 
-  const ready = await waitForPort(port);
-  if (!ready) {
+  const { outcome, exitedBeforeBind } = await awaitServerReadyOrChildExit(child, port);
+
+  if (outcome === "exited" || (outcome === "timeout" && exitedBeforeBind !== null)) {
+    const { code, signal } = exitedBeforeBind ?? { code: null, signal: null };
+    const detail = signal != null ? `signal ${signal}` : `code ${code}`;
+    console.error(
+      `codeyam-editor server exited (${detail}) before binding port ${port}. ` +
+        "Likely a preflight bail; see output above.",
+    );
+    // Always propagate as a real failure — even on code 0 the caller
+    // needs to know the server isn't running.
+    process.exit(code != null && code !== 0 ? code : 1);
+  }
+
+  if (outcome === "timeout") {
     console.error("Server failed to start within 10 seconds");
     child.kill();
     process.exit(1);
@@ -260,12 +756,45 @@ async function ensureServer(port = 14199) {
   return child;
 }
 
+/**
+ * Race a child process's exit against a port-becomes-listening poll.
+ * Returns `{ outcome, exitedBeforeBind }` where `outcome` is one of
+ * `"ready"` (port bound first), `"timeout"` (poll exhausted before the
+ * port bound and the child is still alive), or `"exited"` (child exited
+ * before the port bound). `exitedBeforeBind` is `{ code, signal }` if
+ * the child exited at any point during the race, else `null`.
+ *
+ * Exists as its own helper so the silent-clean-exit branch of
+ * `ensureServer` is unit-testable without spawning the real Rust
+ * binary. `waitForPortFn` defaults to `waitForPort`; tests pass a fake
+ * that resolves synchronously.
+ */
+async function awaitServerReadyOrChildExit(child, port, waitForPortFn = waitForPort) {
+  let exitedBeforeBind = null;
+  const exitPromise = new Promise((resolve) => {
+    child.once("exit", (code, signal) => {
+      exitedBeforeBind = { code, signal };
+      resolve("exited");
+    });
+  });
+  const portPromise = waitForPortFn(port).then((ok) => (ok ? "ready" : "timeout"));
+  const outcome = await Promise.race([portPromise, exitPromise]);
+  return { outcome, exitedBeforeBind };
+}
+
 module.exports = {
   rootDir,
   serverStatePath,
   binaryName,
+  brokerBinaryName,
+  platformPackageInfo,
+  PLATFORM_PACKAGES,
   findBinary,
+  findBrokerBinary,
+  verifyBrokerBinaryPresent,
   ensureBinary,
+  staleBinaryBanner,
+  enforceFreshBinary,
   uiDistDir,
   tryConnect,
   isPortInUse,
@@ -274,10 +803,21 @@ module.exports = {
   readServerState,
   clearServerState,
   requestServerShutdown,
+  fetchServerIdentity,
+  canonicalisePath,
+  classifyPortHolder,
+  formatForeignListenerError,
+  formatCrossProjectError,
   tryKillPid,
   findListeningPids,
   stopServer,
   restartServer,
   ensureServer,
+  awaitServerReadyOrChildExit,
   killChildProcess,
+  deepMergeJson,
+  stripUnderscoreTopLevelKeys,
+  readMergedEditorConfig,
+  resolveLauncherPort,
+  resolveWrappedAppPort,
 };