@codeyam-editor/codeyam-editor 0.1.0-staging.01efa1a

package/npm/utils.js

@@ -0,0 +1,823 @@
+const { execSync, spawn, spawnSync } = require("child_process");
+const net = require("net");
+const path = require("path");
+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.
+ * Accepts an explicit platform so the helper is testable across platforms.
+ */
+function binaryName(platform = process.platform) {
+  return platform === "win32" ? "codeyam-editor.exe" : "codeyam-editor";
+}
+
+/**
+ * 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 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, 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;
+
+  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 and `cargo` is not on PATH. " +
+      "Install Rust from https://rustup.rs/ or reinstall @codeyam-editor/codeyam-editor."
+    );
+    process.exit(1);
+  }
+
+  console.error("Building codeyam-editor...");
+  try {
+    execSync("cargo build", { cwd: rootDir, stdio: "inherit" });
+  } catch {
+    console.error("Failed to build. Is Rust installed? https://rustup.rs/");
+    process.exit(1);
+  }
+
+  const binary = findBinary();
+  if (!binary) {
+    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) => {
+    const socket = new net.Socket();
+    socket.setTimeout(300);
+    socket.once("connect", () => { socket.destroy(); resolve(true); });
+    socket.once("error", () => { socket.destroy(); resolve(false); });
+    socket.once("timeout", () => { socket.destroy(); resolve(false); });
+    socket.connect(port, host);
+  });
+}
+
+/** Check if a port is in use (tries both IPv4 and IPv6). */
+async function isPortInUse(port) {
+  return (await tryConnect(port, "127.0.0.1")) || (await tryConnect(port, "::1"));
+}
+
+/**
+ * Poll a port until something is listening, or timeout.
+ * Returns true if the port became active, false on timeout.
+ */
+async function waitForPort(port, timeoutMs = 10000, intervalMs = 200) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (await isPortInUse(port)) return true;
+    await new Promise((r) => setTimeout(r, intervalMs));
+  }
+  return false;
+}
+
+/**
+ * Poll until a port stops listening, or timeout.
+ * Returns true if the port became inactive, false on timeout.
+ */
+async function waitForPortToClose(port, timeoutMs = 10000, intervalMs = 200) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (!(await isPortInUse(port))) return true;
+    await new Promise((r) => setTimeout(r, intervalMs));
+  }
+  return false;
+}
+
+function readServerState() {
+  try {
+    return JSON.parse(fs.readFileSync(serverStatePath, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function clearServerState() {
+  try {
+    fs.unlinkSync(serverStatePath);
+  } 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);
+
+  try {
+    const resp = await fetch(`http://127.0.0.1:${port}/api/editor-server/shutdown`, {
+      method: "POST",
+      signal: controller.signal,
+    });
+    return resp.ok;
+  } catch {
+    return false;
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+/**
+ * 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
+    // depending on Node version. Drop the signal so Node maps to a
+    // platform TerminateProcess. Less graceful, but the child does exit.
+    if (process.platform === "win32") {
+      process.kill(pid);
+    } else {
+      process.kill(pid, "SIGINT");
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Send the platform-correct termination signal to a spawned child process.
+ * Used by editor.js / editor-dev.js / container.js when the user hits Ctrl+C —
+ * `child.kill("SIGINT")` is unreliable on Windows.
+ */
+function killChildProcess(child) {
+  if (!child) return;
+  if (process.platform === "win32") {
+    child.kill();
+  } else {
+    child.kill("SIGINT");
+  }
+}
+
+function findListeningPids(port) {
+  // Process discovery on Windows is best-effort — `lsof` is not installed and
+  // a `netstat -ano` parser is a follow-up. The API-shutdown path and the
+  // PID-file path together stop the server cleanly in normal operation.
+  if (process.platform === "win32") return [];
+
+  const result = spawnSync("lsof", [`-tiTCP:${port}`, "-sTCP:LISTEN"], {
+    encoding: "utf8",
+  });
+
+  if (result.error) return [];
+
+  return result.stdout
+    .split(/\s+/)
+    .map((line) => parseInt(line, 10))
+    .filter((pid) => Number.isInteger(pid));
+}
+
+/** Stop the Rust backend server if it is running. */
+async function stopServer(port = 14199) {
+  if (!(await isPortInUse(port))) {
+    clearServerState();
+    return false;
+  }
+
+  if (await requestServerShutdown(port)) {
+    if (await waitForPortToClose(port, 10000, 200)) {
+      clearServerState();
+      return true;
+    }
+  }
+
+  const state = readServerState();
+  if (state && Number.isInteger(state.pid) && tryKillPid(state.pid)) {
+    if (await waitForPortToClose(port, 5000, 200)) {
+      clearServerState();
+      return true;
+    }
+  }
+
+  for (const pid of findListeningPids(port)) {
+    tryKillPid(pid);
+  }
+
+  if (await waitForPortToClose(port, 5000, 200)) {
+    clearServerState();
+    return true;
+  }
+
+  throw new Error(`Server on port ${port} did not stop cleanly`);
+}
+
+/** Stop any existing server on the port, then start a fresh one. */
+async function restartServer(port = 14199) {
+  if (await isPortInUse(port)) {
+    console.error(`Stopping existing server on port ${port}...`);
+    await stopServer(port);
+  }
+  return ensureServer(port);
+}
+
+/**
+ * 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) {
+  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,
+  });
+
+  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);
+  }
+
+  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,
+  waitForPort,
+  waitForPortToClose,
+  readServerState,
+  clearServerState,
+  requestServerShutdown,
+  fetchServerIdentity,
+  canonicalisePath,
+  classifyPortHolder,
+  formatForeignListenerError,
+  formatCrossProjectError,
+  tryKillPid,
+  findListeningPids,
+  stopServer,
+  restartServer,
+  ensureServer,
+  awaitServerReadyOrChildExit,
+  killChildProcess,
+  deepMergeJson,
+  stripUnderscoreTopLevelKeys,
+  readMergedEditorConfig,
+  resolveLauncherPort,
+  resolveWrappedAppPort,
+};