@codeyam-editor/codeyam-editor 0.1.1 → 0.1.2

package/npm/utils.js

@@ -6,6 +6,18 @@ 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 binary. 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" },
+  "darwin-x64":   { pkg: "@codeyam-editor/codeyam-editor-darwin-x64",   binary: "codeyam-editor" },
+  "linux-x64":    { pkg: "@codeyam-editor/codeyam-editor-linux-x64",    binary: "codeyam-editor" },
+  "win32-x64":    { pkg: "@codeyam-editor/codeyam-editor-win32-x64",    binary: "codeyam-editor.exe" },
+};
+
 /**
  * Platform-correct executable filename for the codeyam-editor binary.
  * Windows requires the `.exe` extension; on Unix the binary has no extension.
@@ -15,36 +27,95 @@ 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. */
+/** 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();
-  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)
+  const devCandidates = [
+    path.join(rootDir, "target", "debug", name),
+    path.join(rootDir, "target", "release", name),
   ];
-
-  for (const candidate of candidates) {
-    if (fs.existsSync(candidate)) {
-      return candidate;
-    }
+  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);
   }
@@ -70,6 +141,224 @@ function uiDistDir() {
   return path.join(rootDir, "ui", "dist");
 }
 
+/**
+ * True when `cwd` IS the editor repo root (or is nested under it), so the
+ * wrapper is being used to develop the editor itself rather than against an
+ * external client project. Compares realpath-resolved paths so a symlinked
+ * checkout (`~/work/foo` → `/Volumes/dev/foo`) still matches — the same
+ * convention `crates/control-api/src/state.rs:203` documents for the
+ * server-side identity probe.
+ *
+ * Pure and synchronous (uses `fs.realpathSync`). On a realpath failure (an
+ * unreadable path, race with a moved file) the un-resolved value is used as
+ * a fallback — the same defensive shape `canonicalisePath` uses, so the
+ * wrapper never bails on a transient fs hiccup.
+ *
+ * Gate for the dev wrapper's passthrough `cargo build`: when the target
+ * project is the editor itself, rebuilding makes sense (the developer is
+ * iterating on editor source). When it is any other project, the rebuild
+ * does nothing of value and ripples into the stale-binary watcher's
+ * SIGUSR1 re-exec, resetting the user's session for no reason. The
+ * `CODEYAM_DEV_REBUILD=1` env preserves the one legitimate "editing the
+ * editor against a client project" workflow.
+ */
+function isSelfHostTarget(cwd, repoRoot) {
+  const safeReal = (p) => {
+    try {
+      return fs.realpathSync(p);
+    } catch {
+      return p;
+    }
+  };
+  const cwdReal = safeReal(cwd);
+  const repoReal = safeReal(repoRoot);
+  if (cwdReal === repoReal) return true;
+  const sep = path.sep;
+  return cwdReal.startsWith(repoReal.endsWith(sep) ? repoReal : repoReal + sep);
+}
+
+/**
+ * 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 +416,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 +437,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 +643,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 +704,43 @@ 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,
+  platformPackageInfo,
+  PLATFORM_PACKAGES,
   findBinary,
   ensureBinary,
+  isSelfHostTarget,
+  staleBinaryBanner,
+  enforceFreshBinary,
   uiDistDir,
   tryConnect,
   isPortInUse,
@@ -274,10 +749,21 @@ module.exports = {
   readServerState,
   clearServerState,
   requestServerShutdown,
+  fetchServerIdentity,
+  canonicalisePath,
+  classifyPortHolder,
+  formatForeignListenerError,
+  formatCrossProjectError,
   tryKillPid,
   findListeningPids,
   stopServer,
   restartServer,
   ensureServer,
+  awaitServerReadyOrChildExit,
   killChildProcess,
+  deepMergeJson,
+  stripUnderscoreTopLevelKeys,
+  readMergedEditorConfig,
+  resolveLauncherPort,
+  resolveWrappedAppPort,
 };