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

package/npm/container.js

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+
+const path = require("path");
+/**
+ * Start the container monitoring UI.
+ *
+ * Starts the Rust backend (if not already running) and opens the
+ * inline monitoring UI at http://localhost:14199.
+ */
+
+const {
+  ensureServer,
+  rootDir,
+  killChildProcess,
+  readMergedEditorConfig,
+  resolveLauncherPort,
+} = require("./utils");
+const { open } = require("./open");
+
+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}`);
+  console.error(`Logs: ${path.join(rootDir, ".codeyam", "logs")}`);
+  open(url);
+  const keepAlive = setInterval(() => {}, 60_000);
+
+  process.on("SIGINT", () => {
+    clearInterval(keepAlive);
+    killChildProcess(serverChild);
+    process.exit(0);
+  });
+}
+
+module.exports = { main };
+
+if (require.main === module) {
+  main();
+}

package/npm/editor-dev.js

@@ -0,0 +1,142 @@
+#!/usr/bin/env node
+
+/**
+ * Development CLI for running the codeyam-editor against any project.
+ *
+ * Two modes:
+ *
+ *   Launcher — no subcommand (or --restart): builds the Rust binary and UI
+ *   from the editor repo, starts the server, waits for readiness, opens browser.
+ *     codeyam-editor-dev
+ *     codeyam-editor-dev --restart
+ *
+ *   Passthrough — any subcommand (start, init, editor, ...): rebuilds the
+ *   Rust binary, then forwards args to it.
+ *     codeyam-editor-dev editor step 1
+ *     codeyam-editor-dev editor advance
+ */
+
+const { execSync, spawn } = require("child_process");
+const path = require("path");
+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,
+// permissions, and installed files instead of "codeyam-editor".
+process.env.CODEYAM_CLI = "codeyam-editor-dev";
+
+const args = process.argv.slice(2);
+const KNOWN_SUBCOMMANDS = ["start", "init", "editor"];
+
+/**
+ * Check if the first non-flag argument is a known subcommand.
+ * Accepts an explicit argv array so the helper is testable without mutating
+ * process.argv (the module-level `args` const is the production default).
+ */
+function hasSubcommand(argv = args) {
+  for (const arg of argv) {
+    if (arg.startsWith("-")) continue;
+    return KNOWN_SUBCOMMANDS.includes(arg);
+  }
+  return false;
+}
+
+/** Build the Rust binary from the editor repo. */
+function buildBinary() {
+  console.error("Building Rust binary...");
+  try {
+    execSync("cargo build", { stdio: "inherit", cwd: rootDir });
+  } catch {
+    console.error("Failed to build Rust binary. Continuing with existing build (if any)...");
+  }
+}
+
+module.exports = { hasSubcommand, buildBinary };
+
+if (require.main === module) {
+  // --- Passthrough mode: build binary, then forward to it ---
+  if (hasSubcommand()) {
+    buildBinary();
+    const binary = ensureBinary();
+    const child = spawn(binary, args, {
+      stdio: "inherit",
+      cwd: process.cwd(),
+      env: process.env,
+    });
+    child.on("exit", (code) => {
+      process.exit(code ?? 1);
+    });
+  } else {
+    // --- Launcher mode: build everything, start server, open browser ---
+    const shouldRestart = args.includes("--restart");
+
+    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
+      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 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}`);
+      console.error(`Project: ${projectDir}`);
+      open(url);
+      const keepAlive = setInterval(() => {}, 60_000);
+
+      process.on("SIGINT", () => {
+        clearInterval(keepAlive);
+        killChildProcess(serverChild);
+        process.exit(0);
+      });
+    };
+
+    launcherMain();
+  }
+}

package/npm/editor.js

@@ -0,0 +1,210 @@
+#!/usr/bin/env node
+
+/**
+ * Start the editor.
+ *
+ * 1. Builds the React UI into ui/dist/ (stable outer shell, no HMR)
+ * 2. Starts the Rust backend which:
+ *    - Serves ui/dist/ as static files on port 14199
+ *    - Launches the Vite dev server (startCommand) on port 5173 for Live Preview HMR
+ *    - Provides the API, WebSocket, and screenshot endpoints
+ * 3. Waits for the Vite dev server to be ready (so the Live Preview iframe works)
+ * 4. Opens http://localhost:14199 in the browser
+ */
+
+const { execSync } = require("child_process");
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const {
+  ensureServer,
+  stopServer,
+  waitForPort,
+  rootDir,
+  killChildProcess,
+  readMergedEditorConfig,
+  resolveLauncherPort,
+  classifyPortHolder,
+  formatForeignListenerError,
+  formatCrossProjectError,
+} = require("./utils");
+const { open } = require("./open");
+
+const shouldRestart = process.argv.includes("--restart");
+
+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;
+  }
+}
+
+// Resolve <CARGO_HOME>/bin (falling back to $HOME/.cargo/bin). Mirrors
+// `installed_binary_path()` in crates/control-api/src/pty_broker_startup.rs
+// — the Rust broker auto-spawn execs the binary at this path, so we MUST
+// keep it in sync with the freshly-built debug binary or `npm run editor`
+// will start a server whose PTY-broker auto-spawn execs a stale install.
+function cargoBinDir() {
+  if (process.env.CARGO_HOME) return path.join(process.env.CARGO_HOME, "bin");
+  return path.join(os.homedir(), ".cargo", "bin");
+}
+
+// Install target/debug/codeyam-editor to <cargo_bin>/codeyam-editor
+// atomically (write to tmp in same dir, then rename), and refresh the
+// codeyam-editor-pty-broker hardlink so it points at the new inode.
+//
+// The PTY broker auto-spawn (control-api/src/pty_broker_startup.rs) always
+// resolves the *installed* path, NOT current_exe() — that was a deliberate
+// fix to prevent a fork-bomb where test binaries spawned themselves. So a
+// fresh `target/debug/codeyam-editor` is not enough; the install path must
+// be refreshed too. Without this, build tabs hang on "Reconnecting..."
+// because the broker daemon errors out (`unrecognized subcommand`) before
+// the UDS socket opens.
+function installBinary() {
+  const srcPath = path.join(rootDir, "target", "debug", "codeyam-editor");
+  if (!fs.existsSync(srcPath)) {
+    console.error(`Skipping install: ${srcPath} not found.`);
+    return;
+  }
+  const binDir = cargoBinDir();
+  const dstPath = path.join(binDir, "codeyam-editor");
+  const linkPath = path.join(binDir, "codeyam-editor-pty-broker");
+  const tmpPath = path.join(binDir, `.codeyam-editor.tmp.${process.pid}`);
+  console.error(`Installing fresh binary to ${dstPath}...`);
+  try {
+    fs.mkdirSync(binDir, { recursive: true });
+    fs.copyFileSync(srcPath, tmpPath);
+    fs.chmodSync(tmpPath, 0o755);
+    fs.renameSync(tmpPath, dstPath);
+    try {
+      fs.unlinkSync(linkPath);
+    } catch (e) {
+      if (e.code !== "ENOENT") throw e;
+    }
+    fs.linkSync(dstPath, linkPath);
+  } catch (err) {
+    console.error(`Failed to install binary: ${err.message}`);
+    try { fs.unlinkSync(tmpPath); } catch {}
+  }
+}
+
+// Evict Rust build artifacts not touched in the last day so target/ doesn't
+// grow unboundedly. Must run after the old server is stopped (it holds files
+// in target/debug/ open) and before the new server starts. Non-fatal.
+function sweepStaleArtifacts() {
+  console.error("Sweeping stale Rust build artifacts (idle >1 day)...");
+  try {
+    execSync("cargo sweep --time 1", { stdio: "inherit", cwd: rootDir });
+  } catch {
+    console.error("cargo-sweep failed (install with `cargo install cargo-sweep`). Continuing.");
+  }
+}
+
+async function main() {
+  // 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`),
+  // so Cargo.toml and the crates tree are always present.
+  const buildOk = buildBinary();
+  // Refresh <cargo_bin>/codeyam-editor (and the pty-broker hardlink) so
+  // the broker auto-spawn execs a binary that knows the `pty-broker
+  // daemon` subcommand. Skip if the build failed — installing a stale
+  // debug binary over a working install is worse than leaving it.
+  if (buildOk) {
+    installBinary();
+  }
+
+  // Build the UI so the backend can serve it as static files
+  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)...");
+  }
+
+  // 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: 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();
+  }
+  const serverChild = await ensureServer(SERVER_PORT);
+
+  // Wait for the actual Vite dev server on the internal port (not the reverse
+  // proxy on VITE_PORT, which starts immediately with the Rust binary).
+  console.error("Waiting for Vite dev server...");
+  const viteReady = await waitForPort(VITE_INTERNAL_PORT, 15000, 300);
+  if (!viteReady) {
+    console.error(`Warning: Vite dev server not ready on port ${VITE_INTERNAL_PORT}. Live Preview may not work initially.`);
+  }
+
+  const url = `http://localhost:${SERVER_PORT}`;
+  console.error(`Editor UI: ${url}`);
+  console.error(`Live Preview: http://localhost:${VITE_PORT}`);
+  console.error(`Logs: ${path.join(rootDir, ".codeyam", "logs")}`);
+  open(url);
+  const keepAlive = setInterval(() => {}, 60_000);
+
+  process.on("SIGINT", () => {
+    clearInterval(keepAlive);
+    killChildProcess(serverChild);
+    process.exit(0);
+  });
+}
+
+module.exports = {
+  buildBinary,
+  cargoBinDir,
+  installBinary,
+  main,
+  sweepStaleArtifacts,
+};
+
+if (require.main === module) {
+  main();
+}

package/npm/open.js

@@ -0,0 +1,15 @@
+const { spawn } = require("child_process");
+
+/** Open a URL in the default browser. */
+function open(url) {
+  const cmd =
+    process.platform === "darwin"
+      ? "open"
+      : process.platform === "win32"
+        ? "start"
+        : "xdg-open";
+
+  spawn(cmd, [url], { stdio: "ignore", detached: true }).unref();
+}
+
+module.exports = { open };

package/npm/scenario-check.js

@@ -0,0 +1,218 @@
+#!/usr/bin/env node
+
+// Render environment (colorScheme, deviceScaleFactor, userAgent, locale,
+// timezoneId, reduceMotion, forcedColors) is read from config when present
+// and passed to browser.newContext(). This is what makes screenshots match
+// the Live Preview iframe's host browser — see docs/rendering.md.
+//
+// iframeBackground is forwarded to buildIframeHarness so the capture paints
+// the user's editor-shell background (or whatever the UI detected) behind
+// the iframe instead of a hardcoded white.
+
+const fs = require("fs");
+const path = require("path");
+const { chromium } = require("playwright");
+
+const {
+  findErrorPattern,
+  buildErrorContextSnippet,
+  hasRenderableContent,
+  describeBlankReason,
+} = require("./scenario-metrics");
+
+const {
+  createIssue,
+  pushIssue,
+  buildResult,
+} = require("./scenario-issues");
+
+const {
+  attachHttpMocks,
+} = require("./scenario-mocks");
+
+const {
+  loadScenarioInIframe,
+  waitForStablePage,
+  collectContentState,
+} = require("./scenario-playwright");
+
+const {
+  getInitScript,
+  handleConsoleMessage,
+  handlePageError,
+  handleRequestFailed,
+} = require("./scenario-handlers");
+
+const BLANK_RETRY_DELAY_MS = 500;
+
+async function runScenarioCheck(config) {
+  const { url, outputPath, width, height, httpMocks = {} } = config;
+  const issues = [];
+  const browser = await chromium.launch();
+  const contextOptions = {
+    viewport: { width: width || 1440, height: height || 900 },
+  };
+  if (config.colorScheme) contextOptions.colorScheme = config.colorScheme;
+  if (config.deviceScaleFactor)
+    contextOptions.deviceScaleFactor = config.deviceScaleFactor;
+  if (config.userAgent) contextOptions.userAgent = config.userAgent;
+  if (config.locale) contextOptions.locale = config.locale;
+  if (config.timezoneId) contextOptions.timezoneId = config.timezoneId;
+  if (config.reduceMotion) contextOptions.reducedMotion = config.reduceMotion;
+  if (config.forcedColors) contextOptions.forcedColors = config.forcedColors;
+  const context = await browser.newContext(contextOptions);
+
+  // Context-level init script runs in ALL frames (including cross-origin iframes)
+  await context.addInitScript(getInitScript());
+
+  const page = await context.newPage();
+  await attachHttpMocks(page, httpMocks);
+
+  page.on("pageerror", (error) => {
+    pushIssue(issues, handlePageError(error));
+  });
+
+  page.on("console", (message) => {
+    const issue = handleConsoleMessage(message);
+    if (issue) {
+      pushIssue(issues, issue);
+    }
+  });
+
+  page.on("requestfailed", (request) => {
+    const issue = handleRequestFailed(request);
+    if (issue) {
+      pushIssue(issues, issue);
+    }
+  });
+
+  let loaded = false;
+
+  try {
+    const { frame, response } = await loadScenarioInIframe(page, url, {
+      background: config.iframeBackground,
+    });
+    loaded = true;
+
+    if (response && response.status() >= 400) {
+      pushIssue(
+        issues,
+        createIssue("navigation", `Navigation returned HTTP ${response.status()}`, {
+          url: response.url(),
+          status: response.status(),
+        }),
+      );
+    }
+
+    await waitForStablePage(page, frame);
+
+    const rejectionMessages = await frame.evaluate(
+      () => window.__codeyamUnhandledRejections || [],
+    );
+    for (const message of rejectionMessages) {
+      pushIssue(
+        issues,
+        createIssue("unhandledrejection", message, {
+          url: page.url() || url,
+        }),
+      );
+    }
+
+    // Cold-start retry: a single re-collect after a short pause covers
+    // the React.lazy / Suspense-fallback race that flagged 4-of-59
+    // scenarios as blank against a cold Vite dev server on 2026-04-30.
+    // One retry is enough — the Suspense window is sub-second in
+    // practice, longer waits just slow down genuine blank-render bugs.
+    let contentState = await collectContentState(frame);
+    let hasContent = hasRenderableContent(contentState);
+    if (!hasContent) {
+      await new Promise((r) => setTimeout(r, BLANK_RETRY_DELAY_MS));
+      contentState = await collectContentState(frame);
+      hasContent = hasRenderableContent(contentState);
+    }
+
+    if (!hasContent) {
+      pushIssue(
+        issues,
+        createIssue(
+          "blank",
+          `Page rendered no visible content (${describeBlankReason(contentState)})`,
+          { url: page.url() || url },
+        ),
+      );
+    }
+
+    // Check for known error states in the rendered content
+    const bodyText = await frame.evaluate(() => document.body.innerText || "");
+    const matchedPattern = findErrorPattern(bodyText);
+    if (matchedPattern) {
+      const contextSnippet = buildErrorContextSnippet(bodyText, matchedPattern);
+      pushIssue(
+        issues,
+        createIssue(
+          "error-state",
+          `Page contains error content (matched "${matchedPattern}"): ${contextSnippet ?? bodyText.slice(0, 200)}`,
+          {
+            url: page.url() || url,
+            matchedPattern,
+            contextSnippet,
+          },
+        ),
+      );
+    }
+
+    if (outputPath && loaded) {
+      fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+      await page.screenshot({ path: outputPath, fullPage: false });
+    }
+
+    return buildResult({
+      loaded,
+      hasContent,
+      issues,
+      outputPath,
+      url: frame.url() || url,
+    });
+  } catch (error) {
+    pushIssue(
+      issues,
+      createIssue("navigation", error.message || String(error), { url }),
+    );
+
+    return buildResult({
+      loaded,
+      hasContent: false,
+      issues,
+      outputPath,
+      url,
+    });
+  } finally {
+    await browser.close();
+  }
+}
+
+async function main() {
+  const config = JSON.parse(process.argv[2] || "{}");
+
+  if (!config.url) {
+    console.error(
+      "Usage: node scenario-check.js '{\"url\":\"...\",\"outputPath\":\"...\",\"width\":1440,\"height\":900}'",
+    );
+    process.exit(1);
+  }
+
+  const result = await runScenarioCheck(config);
+  console.log(JSON.stringify(result));
+}
+
+module.exports = {
+  runScenarioCheck,
+  main,
+};
+
+if (require.main === module) {
+  main().catch((error) => {
+    console.error(error.message || String(error));
+    process.exit(1);
+  });
+}