@codeyam-editor/codeyam-editor 0.1.3 → 0.1.4

package/npm/utils.js

@@ -620,6 +620,114 @@ function tryKillPid(pid) {
   }
 }
 
+/**
+ * True when the launcher is attached to an interactive terminal — i.e. a human
+ * could have typed Ctrl+C. Headless / agent-driven launchers (cloud containers,
+ * `npm run editor` under a supervisor) have no tty here. Used to decide whether a
+ * received SIGINT is a deliberate "stop the editor" (forward it) or a stray
+ * group / spurious signal that must NOT reap the now-detached server.
+ */
+function isInteractiveLauncher(stream = process.stdout) {
+  return Boolean(stream && stream.isTTY);
+}
+
+/**
+ * Spawn options for the editor server child. The server is spawned `detached:
+ * true` so it leads its OWN session + process group (setsid), decoupling its
+ * lifetime from the launcher's controlling terminal and process group — a stray
+ * tty Ctrl+C or a group-wide `kill(-pgid, SIGINT)` can no longer reach it. stdio
+ * is detached from the terminal for the same reason (an inherited tty can still
+ * deliver tty signals to a detached child): stdout/stderr go to `logFd` when one
+ * is supplied, else are ignored — the Rust server writes its own
+ * `.codeyam/logs/editor-server.log` regardless.
+ */
+function buildServerSpawnOptions({ cwd, env, logFd = null }) {
+  return {
+    stdio: logFd === null ? "ignore" : ["ignore", logFd, logFd],
+    cwd,
+    detached: true,
+    env,
+  };
+}
+
+/**
+ * Open (creating dirs as needed) the launcher-managed server stdout/stderr log
+ * in append mode and return its fd, or null if it can't be opened. Kept separate
+ * from the Rust server's own structured `editor-server.log` so the two streams
+ * never interleave. Best-effort: a failure here just means the detached server's
+ * stdio is ignored, never that the launch itself fails.
+ */
+function openServerOutputLog(cwd) {
+  try {
+    const dir = path.join(cwd, ".codeyam", "logs");
+    fs.mkdirSync(dir, { recursive: true });
+    return fs.openSync(path.join(dir, "editor-server.out.log"), "a");
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Format one launcher-teardown-signal record for
+ * `.codeyam/logs/launcher-signals.log`. Pure: every input is passed in, so the
+ * formatting is unit-testable without a real signal or `ps`. Captures the
+ * launcher's own pid/ppid/pgid, whether it was interactive (a tty Ctrl+C) vs
+ * headless (a stray/spurious signal), the decision taken (forwarded teardown vs
+ * kept the server alive), and a best-effort `ps` group snapshot so the SENDER of
+ * a spurious `kill()` can be identified on the next repro.
+ */
+function formatLauncherSignalRecord({ signal, pid, ppid, pgid, interactive, forwarded, ps, timestamp }) {
+  const lines = [
+    `[${timestamp}] launcher-signal signal=${signal} pid=${pid} ppid=${ppid} pgid=${pgid} ` +
+      `interactive=${interactive} action=${forwarded ? "forwarded-teardown" : "ignored-kept-server-alive"}`,
+  ];
+  if (ps && ps.trim() !== "") {
+    lines.push(ps.trimEnd());
+  }
+  return lines.join("\n") + "\n";
+}
+
+/**
+ * Append a launcher-teardown-signal forensic record. Called from each launcher's
+ * SIGINT handler BEFORE it decides whether to forward, so a server reaped by a
+ * stray group SIGINT (or a spurious `kill()` to a headless launcher) always
+ * leaves a trail naming the launcher's process group. Best-effort: never throws,
+ * so a logging failure can never block the teardown decision.
+ */
+function logLauncherTeardownSignal(signal, projectDir, { interactive, forwarded }) {
+  try {
+    const pid = process.pid;
+    const ppid = typeof process.ppid === "number" ? process.ppid : -1;
+    let pgid = -1;
+    let ps = "";
+    if (process.platform !== "win32") {
+      const pgidOut = spawnSync("ps", ["-o", "pgid=", "-p", String(pid)], { encoding: "utf8" });
+      if (!pgidOut.error) {
+        pgid = parseInt(pgidOut.stdout.trim(), 10);
+      }
+      if (Number.isInteger(pgid) && pgid > 0) {
+        const grp = spawnSync("ps", ["-o", "pid,ppid,pgid,tpgid,comm", "-g", String(pgid)], { encoding: "utf8" });
+        if (!grp.error) ps = grp.stdout;
+      }
+    }
+    const dir = path.join(projectDir, ".codeyam", "logs");
+    fs.mkdirSync(dir, { recursive: true });
+    const record = formatLauncherSignalRecord({
+      signal,
+      pid,
+      ppid,
+      pgid,
+      interactive: Boolean(interactive),
+      forwarded: Boolean(forwarded),
+      ps,
+      timestamp: new Date().toISOString(),
+    });
+    fs.appendFileSync(path.join(dir, "launcher-signals.log"), record);
+  } catch {
+    /* best-effort forensics — never block teardown on a logging failure */
+  }
+}
+
 /**
  * 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 —
@@ -726,12 +834,29 @@ async function ensureServer(port = 14199) {
   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,
-  });
+  //
+  // The server is spawned into its OWN session/process group (detached: true)
+  // with stdio detached from the launcher's controlling terminal, so a stray
+  // tty Ctrl+C or a group-wide SIGINT can no longer reap it — its lifetime is
+  // governed only by the launcher's deliberate teardown forward and the
+  // pidfile / API-shutdown paths. stdout/stderr are appended to
+  // `.codeyam/logs/editor-server.out.log` (the Rust server also writes its own
+  // editor-server.log). `unref()` keeps the detached child from pinning the
+  // launcher's event loop alive on its own.
+  const logFd = openServerOutputLog(process.cwd());
+  const child = spawn(
+    binary,
+    ["start", "--no-open", "--port", String(port)],
+    buildServerSpawnOptions({ cwd: process.cwd(), env: process.env, logFd }),
+  );
+  if (logFd !== null) {
+    try {
+      fs.closeSync(logFd);
+    } catch {
+      /* child holds its own dup of the fd; the launcher's copy is no longer needed */
+    }
+  }
+  child.unref();
 
   const { outcome, exitedBeforeBind } = await awaitServerReadyOrChildExit(child, port);
 
@@ -740,7 +865,8 @@ async function ensureServer(port = 14199) {
     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.",
+        "Likely a preflight bail; see .codeyam/logs/editor-server.out.log " +
+        "and .codeyam/logs/editor-server.log.",
     );
     // Always propagate as a real failure — even on code 0 the caller
     // needs to know the server isn't running.
@@ -814,6 +940,11 @@ module.exports = {
   restartServer,
   ensureServer,
   awaitServerReadyOrChildExit,
+  isInteractiveLauncher,
+  buildServerSpawnOptions,
+  openServerOutputLog,
+  formatLauncherSignalRecord,
+  logLauncherTeardownSignal,
   killChildProcess,
   deepMergeJson,
   stripUnderscoreTopLevelKeys,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codeyam-editor/codeyam-editor",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "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.3",
-    "@codeyam-editor/codeyam-editor-darwin-x64": "0.1.3",
-    "@codeyam-editor/codeyam-editor-linux-x64": "0.1.3",
-    "@codeyam-editor/codeyam-editor-win32-x64": "0.1.3"
+    "@codeyam-editor/codeyam-editor-darwin-arm64": "0.1.4",
+    "@codeyam-editor/codeyam-editor-darwin-x64": "0.1.4",
+    "@codeyam-editor/codeyam-editor-linux-x64": "0.1.4",
+    "@codeyam-editor/codeyam-editor-win32-x64": "0.1.4"
   },
   "keywords": [
     "codeyam",