@codeyam-editor/codeyam-editor 0.1.1 → 0.1.3

package/npm/container.js

@@ -8,12 +8,31 @@ 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;
-
+/**
+ * npm wrapper entry point for the container binary: ensures the Rust
+ * editor server is running and opens the container monitoring UI in
+ * a browser.
+ */
 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

@@ -14,17 +14,47 @@
  *   Rust binary, then forwards args to it.
  *     codeyam-editor-dev editor step 1
  *     codeyam-editor-dev editor advance
+ *
+ * The wrapper is symlinked twice by scripts/bootstrap.sh:
+ *   codeyam-editor-dev → this file (preserves the -dev branding;
+ *     scaffolded content emits "codeyam-editor-dev").
+ *   codeyam-editor     → this file (shadows the canonical name on PATH
+ *     so hooks and skills that emit `codeyam-editor` still get the
+ *     auto-rebuild behavior on local dev; scaffolded content emits the
+ *     canonical "codeyam-editor").
+ * The invocation name is read from `process.argv[1]` to decide which
+ * branding the Rust binary should use via `CODEYAM_CLI`.
  */
 
-const { execSync, spawn } = require("child_process");
+const { execSync, spawn, spawnSync } = 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,
+  staleBinaryBanner,
+  enforceFreshBinary,
+} = require("./utils");
 const { open } = require("./open");
+const { classifyProject } = require("./preflight-guidance");
+const { isEmptyProjectDir } = require("./empty-project-dir");
 
-// Tell the Rust binary to emit "codeyam-editor-dev" in all instructions,
-// permissions, and installed files instead of "codeyam-editor".
-process.env.CODEYAM_CLI = "codeyam-editor-dev";
+// When invoked through the `codeyam-editor-dev` symlink, tell the Rust
+// binary to emit "codeyam-editor-dev" in all scaffolded commands,
+// permissions, and installed files. When invoked through the
+// `codeyam-editor` symlink, leave CODEYAM_CLI unset so the binary
+// emits the canonical "codeyam-editor" — matching the cloud install
+// path and the new hook/skill convention. The runtime cost of the
+// rebuild-on-passthrough behavior is identical for both names.
+const invokedAs = path.basename(process.argv[1] || "");
+if (invokedAs === "codeyam-editor-dev") {
+  process.env.CODEYAM_CLI = "codeyam-editor-dev";
+}
 
 const args = process.argv.slice(2);
 const KNOWN_SUBCOMMANDS = ["start", "init", "editor"];
@@ -42,85 +72,386 @@ function hasSubcommand(argv = args) {
   return false;
 }
 
-/** Build the Rust binary from the editor repo. */
+/**
+ * Build the Rust binary from the editor repo. Returns true on success,
+ * false if `cargo build` failed. This function only reports the outcome —
+ * the caller decides whether a failed build is fatal (see staleBinaryBanner).
+ */
 function buildBinary() {
   console.error("Building Rust binary...");
   try {
     execSync("cargo build", { stdio: "inherit", cwd: rootDir });
+    return true;
   } catch {
-    console.error("Failed to build Rust binary. Continuing with existing build (if any)...");
+    return false;
+  }
+}
+
+/**
+ * Decide whether the dev wrapper should rebuild the Rust binary (and the UI,
+ * for the launcher path) before forwarding to it. The answer is always yes:
+ * `codeyam-editor-dev` ALWAYS rebuilds before running. Running fresh source is
+ * the entire purpose of the dev wrapper — if a developer wants a frozen tool
+ * that never rebuilds, the cargo-installed `codeyam-editor` binary is exactly
+ * that.
+ *
+ * `cargo build` is idempotent: a sub-second no-op that does not relink when
+ * nothing changed. So always-building costs nothing for a developer who only
+ * uses the editor as a tool against their own app (the binary never changes →
+ * the server-side stale-binary watcher never fires → zero mid-session
+ * restarts), and produces a rebuild+restart only when editor source actually
+ * changed — which is exactly when the developer wants the new code live.
+ *
+ * The injected cwd / repoRoot / env are retained so the contract — "rebuild
+ * regardless of where you run it or what env is set" — is demonstrable in a
+ * unit test across the dimensions that used to gate the decision (self-host
+ * vs. external project, `CODEYAM_DEV_REBUILD` set or not). They no longer
+ * influence the result.
+ */
+function shouldRebuildOnPassthrough() {
+  return true;
+}
+
+/**
+ * Returns true when the merged project config has a non-empty start
+ * command — either at `apps[0].startCommand` (per-app, preferred) or at
+ * the top-level `startCommand` (legacy default). Mirrors the Rust
+ * `resolve_start_command` precedence in
+ * `crates/codeyam-editor/src/commands/start.rs`.
+ *
+ * When neither slot has a non-empty string, the editor server runs in
+ * "editor UI only" mode and the launcher must skip the dev-server port
+ * wait — otherwise the user stares at "Waiting for dev server on port
+ * N..." for the full 15s timeout.
+ */
+function hasStartCommand(mergedConfig) {
+  if (mergedConfig == null || typeof mergedConfig !== "object") return false;
+  const apps = Array.isArray(mergedConfig.apps) ? mergedConfig.apps : null;
+  if (apps && apps.length > 0) {
+    const cmd = apps[0] && apps[0].startCommand;
+    if (typeof cmd === "string" && cmd.trim() !== "") return true;
+  }
+  const topLevel = mergedConfig.startCommand;
+  return typeof topLevel === "string" && topLevel.trim() !== "";
+}
+
+/**
+ * Decide what the launcher should do given a `classifyProject` result.
+ * Pure — no fs, no spawn, no process.exit — so `launcherMain`'s branching
+ * is unit-testable without building a binary or spawning a server (the same
+ * policy/classification split as `classifyPortHolder` in utils.js).
+ *
+ *   modern → { action: "proceed" }                 launch as-is
+ *   none   → { action: "init" }                     greenfield: init, then launch
+ *   legacy → { action: "bail", guidance, code: 2 }  print guidance and exit
+ *
+ * Greenfield auto-inits because the dev launcher is a one-shot "build
+ * everything, run the editor against this project" tool — running it in a
+ * fresh dir should just work. Legacy bails instead: `cmd_init`'s legacy
+ * branch deliberately skips `editor.json` creation so `/codeyam-onboard`
+ * can migrate from the preserved classification, so auto-running init would
+ * strand them. The Rust-side `start_preflight` stays the safety net for
+ * direct `codeyam-editor start` calls; this launcher composes init + start.
+ *
+ * Intentional divergence (improve39): this launcher auto-inits ALL `none`
+ * projects (empty or existing-source); the Rust `start_preflight` now
+ * auto-inits only the EMPTY case and still bails (exit 2) on existing-source.
+ * That gap is pre-existing and deliberate — the dev launcher is a local
+ * convenience, not the direct-`start` contract.
+ */
+function planPreflightAction(classification) {
+  if (classification.kind === "legacy") {
+    return { action: "bail", guidance: classification.guidance, code: 2 };
+  }
+  if (classification.kind === "none") {
+    return { action: "init" };
+  }
+  return { action: "proceed" };
+}
+
+/**
+ * Pick the launcher's post-launch tail banner — printed right next to the
+ * `Editor UI: http://…` line where the user is actually looking, after the
+ * editor server is up. Pure (no fs, no spawn) so the three-arm decision is
+ * unit-testable without spawning a binary, mirroring `planPreflightAction`.
+ *
+ * Skill assumption: /codeyam-editor scaffolds a project from scratch;
+ * /codeyam-onboard migrates an existing source tree. Empty greenfield
+ * (no non-hidden entries before init) must route to the scaffold path;
+ * existing greenfield routes to the migration path. Mirrors the same
+ * split in `cmd_init` (init.rs:10-24) — keep both in sync. Do NOT
+ * "simplify" by collapsing the branches; the skill each path names is the
+ * whole point.
+ *
+ *   action !== "init"          → null   (modern: proceed, no banner;
+ *                                         legacy already bailed earlier)
+ *   action "init", wasEmpty    → greenfield message. /codeyam-editor is driven
+ *                                from inside the browser UI, never hand-invoked,
+ *                                so the wording follows `browserOpened`: if the
+ *                                launcher actually opened a tab, promise it; if
+ *                                not (e.g. --restart attach), point at the URL
+ *                                so the user still has a path forward. The
+ *                                banner must never promise a tab that didn't
+ *                                appear.
+ *   action "init", !wasEmpty   → /codeyam-onboard migrate-existing
+ */
+function postLaunchInitBanner({ preflightAction, wasEmpty, browserOpened, url }) {
+  if (preflightAction !== "init") return null;
+  if (wasEmpty) {
+    return browserOpened
+      ? "\nA browser window is opening where you can begin your project."
+      : `\nOpen ${url} in your browser to begin your project.`;
   }
+  return (
+    "\nInitialized .codeyam/ in this directory. To populate scenarios, " +
+    "open Claude Code here and run `/codeyam-onboard`."
+  );
+}
+
+/**
+ * Decide whether the launcher should open a browser tab to the editor UI.
+ * Pure (no fs, no spawn) so the gating is unit-testable without a binary,
+ * mirroring `planPreflightAction` / `postLaunchInitBanner`.
+ *
+ * The browser open belongs ONLY on a genuine cold start — bringing the
+ * editor server up fresh against a not-yet-running port. Two cases must
+ * NOT re-pop a tab, because one is presumably already open:
+ *
+ *   shouldRestart → false   `--restart` (rebuild-self, restart-server routed
+ *                            through this wrapper, a manual --restart) tears
+ *                            down and respawns a server the user is already
+ *                            looking at. Re-opening spams tabs — the reported
+ *                            symptom. Mirrors the Rust `--no-open` restart
+ *                            spawn in restart_server.rs.
+ *   wasRunning   → false     `ensureServer` attached to an already-running
+ *                            same-project server (returned null) — no fresh
+ *                            process, so no new tab.
+ *
+ * Only a fresh spawn on a cold start (neither restart nor attach) opens the
+ * UI, matching the Rust `no_open`-gated `open_url` in start.rs.
+ *
+ *   freshInit    → true      A brand-new empty project that was just init'd
+ *                            this run. The entire greenfield onboarding flow
+ *                            is driven from inside the editor UI, and a
+ *                            project that didn't exist a moment ago has no
+ *                            pre-existing tab for the --restart tab-spam guard
+ *                            to protect. So a fresh init opens regardless of
+ *                            `shouldRestart` — UNLESS we merely attached to an
+ *                            already-running server (`wasRunning`), which
+ *                            implies a tab is already up.
+ */
+function shouldOpenBrowser({ shouldRestart, wasRunning, freshInit }) {
+  if (freshInit) return !wasRunning;
+  return !shouldRestart && !wasRunning;
 }
 
-module.exports = { hasSubcommand, buildBinary };
+module.exports = {
+  hasSubcommand,
+  buildBinary,
+  shouldRebuildOnPassthrough,
+  staleBinaryBanner,
+  hasStartCommand,
+  planPreflightAction,
+  postLaunchInitBanner,
+  shouldOpenBrowser,
+};
 
 if (require.main === module) {
   // --- Passthrough mode: build binary, then forward to it ---
   if (hasSubcommand()) {
-    buildBinary();
+    // Always rebuild before forwarding — running fresh source is the whole
+    // point of the dev wrapper. `cargo build` is a sub-second no-op when
+    // nothing changed (no relink → the server-side stale-binary watcher never
+    // fires), and relinks only when editor source actually changed, which is
+    // exactly when the developer wants the new code live. `ensureBinary()`
+    // still builds once if no binary exists at all.
+    if (shouldRebuildOnPassthrough()) {
+      enforceFreshBinary(buildBinary(), { action: "run editor commands" });
+    }
     const binary = ensureBinary();
     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}`);
 
-      buildBinary();
+      // Greenfield projects are auto-initialized here so the dev launcher
+      // stays a one-shot "build everything, run the editor against this
+      // project" tool. Legacy projects bail with guidance; modern projects
+      // skip init. See `planPreflightAction` for the rationale on each
+      // branch. Subcommand pass-through (handled above) is unaffected — the
+      // binary classifies its own subcommands.
+      const preflight = planPreflightAction(classifyProject(projectDir));
+      // Capture emptiness BEFORE init runs — the spawn below creates
+      // .codeyam/ (and install_editor_files writes .claude/ etc.), which
+      // would make every project look non-empty by the time the
+      // post-launch banner prints. Same constraint as the Rust comment in
+      // `init_greenfield_branch` (init.rs:82-85). Computed as a sibling
+      // local (not folded into `preflight`) because emptiness is
+      // orthogonal to the preflight kind.
+      const wasEmpty = isEmptyProjectDir(projectDir);
+      if (preflight.action === "bail") {
+        console.error(preflight.guidance);
+        process.exit(preflight.code);
+      }
+      if (preflight.action === "init") {
+        // Run init from projectDir before the config reads below so the
+        // freshly-written .codeyam/editor.json feeds port resolution.
+        // ensureBinary builds the binary first if this is a fresh checkout.
+        console.error(`Initializing codeyam-editor in ${projectDir}...`);
+        const initBinary = ensureBinary();
+        const initResult = spawnSync(initBinary, ["init"], {
+          cwd: projectDir,
+          stdio: "inherit",
+          env: process.env,
+        });
+        if (initResult.status !== 0) {
+          console.error(
+            `codeyam-editor init exited ${initResult.status ?? "by signal"}; aborting launch.`,
+          );
+          process.exit(1);
+        }
+      }
+
+      // 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,
+      );
 
-      // Build the UI from the editor repo
-      console.error("Building UI...");
-      try {
-        execSync("npx vite build", { stdio: "inherit", cwd: path.join(rootDir, "ui") });
-      } catch {
-        console.error("Failed to build UI. Continuing with existing build (if any)...");
+      // 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);
+
+      // Always rebuild the Rust binary + UI before launching — same contract
+      // as the passthrough path. The build runs BEFORE the server (re)starts
+      // below, so the new server records its start time after the relink and
+      // the stale-binary watcher reads it as fresh (no immediate SIGUSR1). A
+      // no-op `cargo build` (nothing changed) doesn't relink, so an external
+      // client-project launch is never disrupted. `ensureBinary()` still
+      // builds once if no binary exists.
+      if (shouldRebuildOnPassthrough()) {
+        enforceFreshBinary(buildBinary(), {
+          action: "run editor commands",
+          continueVerb: "launching with",
+        });
+
+        // Build the UI from the editor repo
+        console.error("Building UI...");
+        try {
+          execSync("npx vite build", { stdio: "inherit", cwd: path.join(rootDir, "ui") });
+        } catch {
+          console.error("Failed to build UI. Continuing with existing build (if any)...");
+        }
       }
 
       const serverChild = shouldRestart
         ? 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);
-      if (!viteReady) {
-        console.error(`Warning: Dev server not ready on port ${viteInternalPort}. Live Preview may not work initially.`);
+      // Re-read the (possibly just-initialized) project config to decide
+      // whether to wait on a dev server at all. On a project where init
+      // couldn't detect a framework (or a user-configured "editor UI
+      // only" setup), `startCommand` is empty — the editor server itself
+      // prints "No startCommand configured. Running editor UI only." and
+      // never spawns a dev server, so waiting 15s for `appPort + 1` is a
+      // pure UX hang. The launcher silently skips the wait; the server's
+      // own log line is the canonical signal to the user.
+      const postInitMerged = readMergedEditorConfig(projectDir);
+      const hasCommand = hasStartCommand(postInitMerged);
+      if (hasCommand) {
+        const viteInternalPort = appPort + 1;
+        console.error(`Waiting for dev server on port ${viteInternalPort}...`);
+        const viteReady = await waitForPort(viteInternalPort, 15000, 300);
+        if (!viteReady) {
+          console.error(`Warning: Dev server not ready on port ${viteInternalPort}. Live Preview may not work initially.`);
+        }
       }
 
       const url = `http://localhost:${SERVER_PORT}`;
       console.error(`Editor UI: ${url}`);
-      console.error(`Live Preview: http://localhost:${appPort}`);
+      if (hasCommand) {
+        console.error(`Live Preview: http://localhost:${appPort}`);
+      }
       console.error(`Project: ${projectDir}`);
-      open(url);
+      // Open the browser only on a genuine cold start. On the --restart path
+      // (rebuild-self, restart-server, manual --restart) and when we attached
+      // to an already-running server, a tab is presumably already open — the
+      // `Editor UI: <url>` line above is the signal. `ensureServer` returns
+      // null when it attached rather than spawning, so that is `wasRunning`.
+      // Exception: a fresh greenfield init (`freshInit`) opens regardless of
+      // --restart, because a project that didn't exist a moment ago has no
+      // pre-existing tab to protect and the onboarding flow lives in the UI.
+      // Compute the open decision once and feed the SAME boolean into the
+      // banner so it can never promise a tab that didn't appear.
+      const freshInit = preflight.action === "init" && wasEmpty;
+      const openedBrowser = shouldOpenBrowser({
+        shouldRestart,
+        wasRunning: serverChild === null,
+        freshInit,
+      });
+      if (openedBrowser) {
+        open(url);
+      }
+      const banner = postLaunchInitBanner({
+        preflightAction: preflight.action,
+        wasEmpty,
+        browserOpened: openedBrowser,
+        url,
+      });
+      if (banner) {
+        console.error(banner);
+      }
       const keepAlive = setInterval(() => {}, 60_000);
 
+      // Track launcher-initiated teardown so the unexpected-exit handler below
+      // can tell "we killed it on SIGINT" from "the server died on its own".
+      let tearingDown = false;
+
       process.on("SIGINT", () => {
+        tearingDown = true;
         clearInterval(keepAlive);
         killChildProcess(serverChild);
         process.exit(0);
       });
+
+      // Defense-in-depth against orphaned launchers: if the spawned server
+      // child exits and we did NOT initiate it (SIGINT), clear keepAlive and
+      // exit rather than lingering as a node process holding a dead child
+      // handle. We deliberately do NOT respawn — an exited server should let
+      // the launcher exit cleanly so stale supervisors can't accumulate across
+      // repeated launches. The in-place SIGUSR1 re-exec keeps the SAME pid, so
+      // it does NOT emit an "exit" here and does not trip this path; only a
+      // genuinely dead server does. `serverChild` is null when we attached to
+      // an already-running server (nothing of ours to watch).
+      if (serverChild) {
+        serverChild.on("exit", (code) => {
+          if (tearingDown) {
+            return;
+          }
+          clearInterval(keepAlive);
+          process.exit(code ?? 1);
+        });
+      }
     };
 
     launcherMain();