@codeyam-editor/codeyam-editor 0.1.0-staging.0f231be

package/npm/utils.js

@@ -0,0 +1,623 @@
+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 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.
+ * Accepts an explicit platform so the helper is testable across platforms.
+ */
+function binaryName(platform = process.platform) {
+  return platform === "win32" ? "codeyam-editor.exe" : "codeyam-editor";
+}
+
+/** 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 devCandidates = [
+    path.join(rootDir, "target", "debug", name),
+    path.join(rootDir, "target", "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);
+  }
+  return binary;
+}
+
+/** Resolve the UI dist directory for the binary to serve. */
+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) => {
+    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 ready = await waitForPort(port);
+  if (!ready) {
+    console.error("Server failed to start within 10 seconds");
+    child.kill();
+    process.exit(1);
+  }
+
+  return child;
+}
+
+module.exports = {
+  rootDir,
+  serverStatePath,
+  binaryName,
+  platformPackageInfo,
+  PLATFORM_PACKAGES,
+  findBinary,
+  ensureBinary,
+  uiDistDir,
+  tryConnect,
+  isPortInUse,
+  waitForPort,
+  waitForPortToClose,
+  readServerState,
+  clearServerState,
+  requestServerShutdown,
+  fetchServerIdentity,
+  canonicalisePath,
+  classifyPortHolder,
+  formatForeignListenerError,
+  formatCrossProjectError,
+  tryKillPid,
+  findListeningPids,
+  stopServer,
+  restartServer,
+  ensureServer,
+  killChildProcess,
+  deepMergeJson,
+  stripUnderscoreTopLevelKeys,
+  readMergedEditorConfig,
+  resolveLauncherPort,
+};

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@codeyam-editor/codeyam-editor",
+  "version": "0.1.0-staging.0f231be",
+  "description": "Language-agnostic managed execution sandbox for scenario-driven development",
+  "bin": {
+    "codeyam-editor": "./npm/cli.js"
+  },
+  "dependencies": {
+    "playwright": "^1.58.2"
+  },
+  "optionalDependencies": {
+    "@codeyam-editor/codeyam-editor-darwin-arm64": "0.1.0-staging.0f231be",
+    "@codeyam-editor/codeyam-editor-darwin-x64": "0.1.0-staging.0f231be",
+    "@codeyam-editor/codeyam-editor-linux-x64": "0.1.0-staging.0f231be",
+    "@codeyam-editor/codeyam-editor-win32-x64": "0.1.0-staging.0f231be"
+  },
+  "keywords": [
+    "codeyam",
+    "editor",
+    "development",
+    "scenarios"
+  ],
+  "homepage": "https://codeyam.com/",
+  "license": "MIT",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "files": [
+    "npm/",
+    "ui/"
+  ]
+}