@codeyam-editor/codeyam-editor 0.1.0-staging.27ed016 → 0.1.0-staging.2b41530

package/npm/cli.js

@@ -1,14 +1,17 @@
 #!/usr/bin/env node
 
 const { spawn } = require("child_process");
-const { ensureBinary, uiDistDir } = require("./utils");
+const { ensureBinary } = require("./utils");
 
 const binary = ensureBinary();
 
+// The Rust binary embeds `ui/dist` at build time, so no `CODEYAM_EDITOR_UI_DIR`
+// is required. Devs who want to override the bundle can still export the env
+// var manually — the binary's resolver checks it first.
 const child = spawn(binary, process.argv.slice(2), {
   stdio: "inherit",
   cwd: process.cwd(),
-  env: { ...process.env, CODEYAM_EDITOR_UI_DIR: uiDistDir() },
+  env: process.env,
 });
 
 child.on("exit", (code) => {

package/npm/container.js

@@ -8,12 +8,26 @@ const path = require("path");
  * inline monitoring UI at http://localhost:14199.
  */
 
-const { ensureServer, rootDir, killChildProcess } = require("./utils");
+const {
+  ensureServer,
+  rootDir,
+  killChildProcess,
+  readMergedEditorConfig,
+  resolveLauncherPort,
+} = require("./utils");
 const { open } = require("./open");
 
-const PORT = 14199;
-
 async function main() {
+  // Same resolution order as the editor launcher: env var
+  // (CODEYAM_EDITOR_PORT) → merged editor.json + editor.local.json
+  // (proxy.controlPort) → hard fallback (14199).
+  const merged = readMergedEditorConfig(rootDir);
+  const PORT = resolveLauncherPort(
+    process.env.CODEYAM_EDITOR_PORT,
+    merged.proxy && merged.proxy.controlPort,
+    14199,
+  );
+
   const serverChild = await ensureServer(PORT);
   const url = `http://localhost:${PORT}`;
   console.error(`Container UI: ${url}`);

package/npm/editor-dev.js

@@ -18,8 +18,16 @@
 
 const { execSync, spawn } = require("child_process");
 const path = require("path");
-const fs = require("fs");
-const { ensureServer, restartServer, waitForPort, ensureBinary, uiDistDir, rootDir, killChildProcess } = require("./utils");
+const {
+  ensureServer,
+  restartServer,
+  waitForPort,
+  ensureBinary,
+  rootDir,
+  killChildProcess,
+  readMergedEditorConfig,
+  resolveLauncherPort,
+} = require("./utils");
 const { open } = require("./open");
 
 // Tell the Rust binary to emit "codeyam-editor-dev" in all instructions,
@@ -62,31 +70,38 @@ if (require.main === module) {
     const child = spawn(binary, args, {
       stdio: "inherit",
       cwd: process.cwd(),
-      env: { ...process.env, CODEYAM_EDITOR_UI_DIR: uiDistDir() },
+      env: process.env,
     });
     child.on("exit", (code) => {
       process.exit(code ?? 1);
     });
   } else {
     // --- Launcher mode: build everything, start server, open browser ---
-    const SERVER_PORT = 14199;
     const shouldRestart = args.includes("--restart");
 
-    const readProjectPort = () => {
-      try {
-        const configPath = path.join(process.cwd(), ".codeyam", "editor.json");
-        const config = JSON.parse(fs.readFileSync(configPath, "utf8"));
-        return config.port || 3000;
-      } catch {
-        return 3000;
-      }
-    };
-
     const launcherMain = async () => {
       const projectDir = process.cwd();
       console.error(`Editor repo: ${rootDir}`);
       console.error(`Target project: ${projectDir}`);
 
+      // Editor server's control port is owned by the editor repo's
+      // merged config (rootDir), not the target project's. The target
+      // project's own `editor.local.json` only contributes to the
+      // app/dev-server port below.
+      const editorMerged = readMergedEditorConfig(rootDir);
+      const SERVER_PORT = resolveLauncherPort(
+        process.env.CODEYAM_EDITOR_PORT,
+        editorMerged.proxy && editorMerged.proxy.controlPort,
+        14199,
+      );
+
+      // Target project's dev-server port comes from its own
+      // editor.json + editor.local.json (developers iterating on the
+      // editor against a real client project rely on the override
+      // file here too).
+      const projectMerged = readMergedEditorConfig(projectDir);
+      const appPort = resolveLauncherPort(undefined, projectMerged.port, 3000);
+
       buildBinary();
 
       // Build the UI from the editor repo
@@ -101,7 +116,6 @@ if (require.main === module) {
         ? await restartServer(SERVER_PORT)
         : await ensureServer(SERVER_PORT);
 
-      const appPort = readProjectPort();
       const viteInternalPort = appPort + 1;
       console.error(`Waiting for dev server on port ${viteInternalPort}...`);
       const viteReady = await waitForPort(viteInternalPort, 15000, 300);

package/npm/editor.js

@@ -16,14 +16,20 @@ const { execSync } = require("child_process");
 const fs = require("fs");
 const os = require("os");
 const path = require("path");
-const { ensureServer, stopServer, isPortInUse, waitForPort, rootDir, killChildProcess } = require("./utils");
+const {
+  ensureServer,
+  stopServer,
+  waitForPort,
+  rootDir,
+  killChildProcess,
+  readMergedEditorConfig,
+  resolveLauncherPort,
+  classifyPortHolder,
+  formatForeignListenerError,
+  formatCrossProjectError,
+} = require("./utils");
 const { open } = require("./open");
 
-const SERVER_PORT = parseInt(process.env.CODEYAM_EDITOR_PORT || "14199", 10);
-const VITE_PORT = parseInt(process.env.PORT || "5173", 10);
-// The reverse proxy sits on VITE_PORT; the actual Vite dev server runs on
-// VITE_PORT + 1. We need to wait for the real Vite server, not the proxy.
-const VITE_INTERNAL_PORT = VITE_PORT + 1;
 const shouldRestart = process.argv.includes("--restart");
 
 function buildBinary() {
@@ -99,26 +105,23 @@ function sweepStaleArtifacts() {
 }
 
 async function main() {
-  // Sync ports to editor.json so the Rust backend uses them
-  const editorJsonPath = path.join(rootDir, ".codeyam", "editor.json");
-  if (fs.existsSync(editorJsonPath)) {
-    const editorJson = JSON.parse(fs.readFileSync(editorJsonPath, "utf8"));
-    editorJson.port = VITE_PORT;
-    editorJson.startCommand = `cd ui && npx vite --port ${VITE_PORT}`;
-    
-    const uiApp = editorJson.apps?.find(a => a.dir === "ui");
-    if (uiApp) {
-      uiApp.port = VITE_PORT;
-      uiApp.startCommand = `npx vite --port ${VITE_PORT}`;
-    }
-    
-    if (editorJson.proxy) {
-      editorJson.proxy.controlPort = SERVER_PORT;
-      editorJson.proxy.httpPort = SERVER_PORT - 99;
-      editorJson.proxy.dbPort = SERVER_PORT - 98;
-    }
-    fs.writeFileSync(editorJsonPath, JSON.stringify(editorJson, null, 2));
-  }
+  // Read ports from the merged editor config (editor.json + per-developer
+  // editor.local.json). The Rust backend reads the same merged config on
+  // its own — we resolve here so the launcher's log lines, `waitForPort`
+  // calls, and `--port` arg agree with what the binary will actually
+  // bind. Env vars still win for scripted/CI invocations
+  // (CODEYAM_EDITOR_PORT, PORT), then the merged config, then a hard
+  // fallback for fresh checkouts with no override file.
+  const merged = readMergedEditorConfig(rootDir);
+  const SERVER_PORT = resolveLauncherPort(
+    process.env.CODEYAM_EDITOR_PORT,
+    merged.proxy && merged.proxy.controlPort,
+    14199,
+  );
+  const VITE_PORT = resolveLauncherPort(process.env.PORT, merged.port, 5173);
+  // The reverse proxy sits on VITE_PORT; the actual Vite dev server runs on
+  // VITE_PORT + 1. We need to wait for the real Vite server, not the proxy.
+  const VITE_INTERNAL_PORT = VITE_PORT + 1;
 
   // Rebuild the Rust binary so code changes are picked up on restart.
   // This script is only invoked from a source checkout (via `npm run editor`),
@@ -145,11 +148,27 @@ async function main() {
 
   // Start the Rust backend — it serves ui/dist/ and launches the Vite dev
   // server (configured via startCommand in editor.json) for Live Preview HMR.
-  // On --restart: stop the existing server first, sweep stale artifacts while
-  // target/ is idle (no process holding files open), then start fresh.
-  if (shouldRestart && (await isPortInUse(SERVER_PORT))) {
-    console.error(`Stopping existing server on port ${SERVER_PORT}...`);
-    await stopServer(SERVER_PORT);
+  // On --restart: identity-check first, then stop the existing server,
+  // sweep stale artifacts while target/ is idle, then start fresh.
+  //
+  // Stopping someone else's editor server on `--restart` is the worst
+  // possible outcome of a port collision — only stop the listener if
+  // the identity probe confirms it's this project's server.
+  if (shouldRestart) {
+    const holder = await classifyPortHolder(SERVER_PORT);
+    if (holder.kind === "foreign") {
+      console.error(formatForeignListenerError(SERVER_PORT));
+      process.exit(1);
+    }
+    if (holder.kind === "cross-project") {
+      console.error(formatCrossProjectError(SERVER_PORT, holder, "restart"));
+      process.exit(1);
+    }
+    if (holder.kind === "same-project") {
+      console.error(`Stopping existing server on port ${SERVER_PORT}...`);
+      await stopServer(SERVER_PORT);
+    }
+    // holder.kind === "free": nothing to stop, fall through to ensureServer.
   }
   if (shouldRestart) {
     sweepStaleArtifacts();

package/npm/scenario-check.js

@@ -80,7 +80,10 @@ async function runScenarioCheck(config) {
   });
 
   page.on("requestfailed", (request) => {
-    pushIssue(issues, handleRequestFailed(request));
+    const issue = handleRequestFailed(request);
+    if (issue) {
+      pushIssue(issues, issue);
+    }
   });
 
   let loaded = false;

package/npm/scenario-handlers.js

@@ -56,11 +56,22 @@ function handlePageError(error) {
 }
 
 function handleRequestFailed(request) {
-  return createIssue(
-    "requestfailed",
-    request.failure()?.errorText || "Request failed",
-    { url: request.url() }
-  );
+  const errorText = request.failure()?.errorText || "Request failed";
+
+  // Filter benign request cancellations. `net::ERR_ABORTED` is what Playwright
+  // emits when a request is in-flight at the moment the page is closed (or the
+  // iframe is destroyed). For scenarios whose pages fetch large payloads (the
+  // editor's own EditorShell mounts a 2.2MB `/api/tests` fetch), the
+  // browser.close() at the end of capture races the fetch and produces this
+  // event AFTER the screenshot has already been taken — there is no real
+  // failure to surface. Genuine network failures arrive under different
+  // codes (net::ERR_CONNECTION_REFUSED, net::ERR_NAME_NOT_RESOLVED, etc.)
+  // and continue to be reported.
+  if (errorText.includes("net::ERR_ABORTED")) {
+    return null;
+  }
+
+  return createIssue("requestfailed", errorText, { url: request.url() });
 }
 
 module.exports = {

package/npm/utils.js

@@ -141,6 +141,122 @@ function uiDistDir() {
   return path.join(rootDir, "ui", "dist");
 }
 
+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;
+}
+
 /** Try to connect to a specific host:port. Returns true if something is listening. */
 function tryConnect(port, host) {
   return new Promise((resolve) => {
@@ -198,6 +314,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);
@@ -215,6 +335,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
@@ -306,19 +541,42 @@ 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);
@@ -347,10 +605,19 @@ module.exports = {
   readServerState,
   clearServerState,
   requestServerShutdown,
+  fetchServerIdentity,
+  canonicalisePath,
+  classifyPortHolder,
+  formatForeignListenerError,
+  formatCrossProjectError,
   tryKillPid,
   findListeningPids,
   stopServer,
   restartServer,
   ensureServer,
   killChildProcess,
+  deepMergeJson,
+  stripUnderscoreTopLevelKeys,
+  readMergedEditorConfig,
+  resolveLauncherPort,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codeyam-editor/codeyam-editor",
-  "version": "0.1.0-staging.27ed016",
+  "version": "0.1.0-staging.2b41530",
   "description": "Language-agnostic managed execution sandbox for scenario-driven development",
   "bin": {
     "codeyam-editor": "./npm/cli.js"
@@ -9,10 +9,10 @@
     "playwright": "^1.58.2"
   },
   "optionalDependencies": {
-    "@codeyam-editor/codeyam-editor-darwin-arm64": "0.1.0-staging.27ed016",
-    "@codeyam-editor/codeyam-editor-darwin-x64": "0.1.0-staging.27ed016",
-    "@codeyam-editor/codeyam-editor-linux-x64": "0.1.0-staging.27ed016",
-    "@codeyam-editor/codeyam-editor-win32-x64": "0.1.0-staging.27ed016"
+    "@codeyam-editor/codeyam-editor-darwin-arm64": "0.1.0-staging.2b41530",
+    "@codeyam-editor/codeyam-editor-darwin-x64": "0.1.0-staging.2b41530",
+    "@codeyam-editor/codeyam-editor-linux-x64": "0.1.0-staging.2b41530",
+    "@codeyam-editor/codeyam-editor-win32-x64": "0.1.0-staging.2b41530"
   },
   "keywords": [
     "codeyam",