codetrellis 0.0.0-stage → 0.2.0

package/src/cli/desktop.js

@@ -0,0 +1,91 @@
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var desktop_exports = {};
+__export(desktop_exports, {
+  DESKTOP_PLATFORMS: () => DESKTOP_PLATFORMS,
+  DesktopUsageError: () => DesktopUsageError,
+  desktop: () => desktop
+});
+module.exports = __toCommonJS(desktop_exports);
+var import_node_fs = __toESM(require("node:fs"));
+var import_node_path = __toESM(require("node:path"));
+var import_args = require("./args");
+class DesktopUsageError extends Error {
+}
+const DESKTOP_PLATFORMS = ["darwin-arm64", "darwin-x64", "win32-x64", "win32-arm64", "linux-x64", "linux-arm64"];
+async function desktop(p, deps) {
+  const sub = p.rest[0];
+  if (sub !== "install" && sub !== "url") {
+    throw new DesktopUsageError("desktop needs install or url: codetrellis desktop install [--version <v>] [--platform <p>] [--dir <d>] [--no-open]");
+  }
+  const platform = (0, import_args.flag)(p, "platform") ?? deps.platform;
+  if (!DESKTOP_PLATFORMS.includes(platform)) {
+    throw new DesktopUsageError(`--platform must be one of ${DESKTOP_PLATFORMS.join(", ")}${(0, import_args.flag)(p, "platform") ? "" : ` (this computer is ${platform})`}`);
+  }
+  const json = p.flags.json === true;
+  const release = await deps.findRelease(platform, (0, import_args.flag)(p, "version"));
+  const asset = release.download;
+  if (!asset) {
+    const says = `CodeTrellis ${release.version} has no installer for ${platform}.`;
+    return { out: json ? JSON.stringify({ version: release.version, platform, error: says }) : says, code: 1 };
+  }
+  if (sub === "url") {
+    return {
+      out: json ? JSON.stringify({ version: release.version, platform, filename: asset.filename, url: asset.url, size: asset.size ?? null }) : asset.url,
+      code: 0
+    };
+  }
+  const dir = import_node_path.default.resolve((0, import_args.flag)(p, "dir") ?? deps.downloadsDir);
+  import_node_fs.default.mkdirSync(dir, { recursive: true });
+  const state = await deps.download(release.version, asset);
+  if (state.phase !== "ready") {
+    const says = `CodeTrellis ${release.version} was not downloaded: ${state.error ?? "the download did not finish"}`;
+    return { out: json ? JSON.stringify({ version: release.version, platform, error: says }) : says, code: 1 };
+  }
+  const saved = await deps.saveCopy(import_node_path.default.join(dir, import_node_path.default.basename(state.filename ?? asset.filename)));
+  const appImage = /\.AppImage$/i.test(saved);
+  if (appImage) import_node_fs.default.chmodSync(saved, 493);
+  const open = p.flags["no-open"] !== true && platform === deps.platform && !appImage;
+  if (open) deps.open(saved);
+  if (json) {
+    return { out: JSON.stringify({ version: release.version, platform, path: saved, sha256: state.sha256, opened: open }), code: 0 };
+  }
+  const lines = [
+    `Downloaded CodeTrellis ${release.version} for ${platform}, checked against the release's signed checksums:`,
+    `  ${saved}`
+  ];
+  if (open) lines.push(platform.startsWith("darwin") ? "Opened it: drag CodeTrellis to Applications." : "Opened the installer.");
+  else if (appImage && platform === deps.platform) lines.push(`Run it with: ${saved}`);
+  return { out: lines.join("\n"), code: 0 };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DESKTOP_PLATFORMS,
+  DesktopUsageError,
+  desktop
+});

package/src/cli/main.js

@@ -0,0 +1,409 @@
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var import_node_child_process = require("node:child_process");
+var import_node_fs = __toESM(require("node:fs"));
+var import_node_os = __toESM(require("node:os"));
+var import_node_path = __toESM(require("node:path"));
+var import_args = require("./args");
+var import_verbs = require("./verbs");
+var import_plan_verbs = require("./plan-verbs");
+var import_package = require("../../package.json");
+const out = (s) => process.stdout.write(s.endsWith("\n") ? s : `${s}
+`);
+const fail = (s, code = 2) => {
+  process.stderr.write(`codetrellis: ${s}
+`);
+  process.exit(code);
+};
+async function shareTaskState(project) {
+  const { setSharedTaskState, startRecordWatcher } = await Promise.resolve().then(() => __toESM(require("../backend/services/task-records/shared-state")));
+  setSharedTaskState(project, true, "the command line (--share-task-state)");
+  await startRecordWatcher(project);
+}
+function backendLogToStderr() {
+  const toErr = (...args) => console.error(...args);
+  console.log = toErr;
+  console.info = toErr;
+  console.debug = toErr;
+}
+function projectOf(p) {
+  const dir = import_node_path.default.resolve((0, import_args.flag)(p, "project") ?? process.cwd());
+  let st;
+  try {
+    st = import_node_fs.default.statSync(dir);
+  } catch {
+    return fail(`no such folder: ${dir}`);
+  }
+  if (!st.isDirectory()) fail(`not a folder: ${dir}`);
+  return import_node_fs.default.realpathSync(dir);
+}
+function portOf(p, name) {
+  const v = (0, import_args.flag)(p, name);
+  if (v === void 0) return void 0;
+  const n = Number(v);
+  if (!Number.isInteger(n) || n < 0 || n > 65535) fail(`--${name} must be a port number`);
+  return String(n);
+}
+async function boot(p, project, dataDir) {
+  if (p.flags["share-task-state"]) {
+    const { defaultDataDir } = await Promise.resolve().then(() => __toESM(require("../backend/mcp/connector/files")));
+    if (import_node_path.default.resolve(dataDir) === import_node_path.default.resolve(defaultDataDir({}))) {
+      fail("--share-task-state is for a headless backend; in the app, turn it on in Settings \u2192 Shared task state.", 2);
+    }
+  }
+  process.env.CODETRELLIS_DATA_DIR = dataDir;
+  process.env.CODETRELLIS_HEADLESS = "1";
+  const port = portOf(p, "port");
+  const mcpPort = portOf(p, "mcp-port");
+  if (port !== void 0) process.env.CODETRELLIS_BACKEND_PORT = port;
+  if (mcpPort !== void 0) process.env.CODETRELLIS_MCP_PORT = mcpPort;
+  import_node_fs.default.mkdirSync(dataDir, { recursive: true });
+  backendLogToStderr();
+  const { startServer, getBoundBackendPort } = await Promise.resolve().then(() => __toESM(require("../backend/server")));
+  const { installProcessHandlers } = await Promise.resolve().then(() => __toESM(require("../backend/lifecycle")));
+  const { getCapabilityToken } = await Promise.resolve().then(() => __toESM(require("../backend/services/capability-token")));
+  installProcessHandlers();
+  await startServer(void 0, "127.0.0.1");
+  const base = `http://127.0.0.1:${getBoundBackendPort()}`;
+  const res = await fetch(`${base}/api/project/scan`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json", "x-codetrellis-token": getCapabilityToken() },
+    body: JSON.stringify({ projectPath: project })
+  });
+  const scan = await res.json().catch(() => ({}));
+  if (!res.ok) fail(`could not open ${project}: ${scan.error ?? res.status}`, 1);
+  if (p.flags["share-task-state"]) await shareTaskState(project);
+  const { readConnectTarget } = await Promise.resolve().then(() => __toESM(require("../backend/mcp/connector/files")));
+  const target = readConnectTarget(dataDir);
+  return { base, scan, mcp: target.ok ? target.url : null };
+}
+function counts(scan) {
+  const a = scan.astStats ?? {};
+  return {
+    files: scan.fileCount ?? 0,
+    parsed: a.fileCount ?? 0,
+    symbols: a.symbolCount ?? 0,
+    imports: a.importCount ?? 0,
+    resolvedImports: a.resolvedImports ?? 0
+  };
+}
+async function serve(p) {
+  const project = projectOf(p);
+  const dataDir = import_node_path.default.resolve((0, import_args.flag)(p, "data-dir") ?? (0, import_args.headlessDataDir)(project, process.env, import_node_os.default.homedir()));
+  const { base, scan, mcp: mcp2 } = await boot(p, project, dataDir);
+  const line = (0, import_args.connectorLine)(process.execPath, binPath(), dataDir);
+  const c = counts(scan);
+  markReady(dataDir, project);
+  if (p.flags.json) {
+    out(JSON.stringify({ project, dataDir, api: base, mcp: mcp2, connector: { command: line.command, args: line.args }, counts: c }));
+    return;
+  }
+  out([
+    `CodeTrellis is serving ${project}`,
+    `  headless, on loopback only; every request needs the token in ${import_node_path.default.join(dataDir, "capability-token")}`,
+    `  ${c.files} files, ${c.symbols} symbols, ${c.resolvedImports} of ${c.imports} imports resolved`,
+    `  data: ${dataDir}`,
+    "",
+    "Connect an agent (the token is read on every connect, so this survives a restart):",
+    `  ${line.claude}`,
+    `  ${line.json}`,
+    "",
+    "Stop with Ctrl-C."
+  ].join("\n"));
+}
+async function scanOnce(p) {
+  const project = projectOf(p);
+  const dataDir = import_node_path.default.resolve((0, import_args.flag)(p, "data-dir") ?? (0, import_args.headlessDataDir)(project, process.env, import_node_os.default.homedir()));
+  const { scan } = await boot(p, project, dataDir);
+  const c = counts(scan);
+  if (p.flags.json) out(JSON.stringify({ project, ...c }));
+  else out(`${project}: ${c.files} files (${c.parsed} parsed), ${c.symbols} symbols, ${c.resolvedImports} of ${c.imports} imports resolved`);
+  const { gracefulShutdown } = await Promise.resolve().then(() => __toESM(require("../backend/lifecycle")));
+  await gracefulShutdown("scan finished");
+}
+async function mcp(p) {
+  if (!(0, import_args.flag)(p, "data-dir")) {
+    const here = (0, import_args.headlessDataDir)(process.cwd(), process.env, import_node_os.default.homedir());
+    if (import_node_fs.default.existsSync(import_node_path.default.join(here, "mcp-endpoint.json"))) process.argv.push("--data-dir", here);
+  }
+  await Promise.resolve().then(() => __toESM(require("../backend/mcp/connector/main")));
+}
+const READY_FILE = "serve-ready.json";
+function markReady(dataDir, project) {
+  const file = import_node_path.default.join(dataDir, READY_FILE);
+  import_node_fs.default.writeFileSync(file, JSON.stringify({ pid: process.pid, project }), { mode: 384 });
+  process.on("exit", () => {
+    try {
+      if (JSON.parse(import_node_fs.default.readFileSync(file, "utf8")).pid === process.pid) import_node_fs.default.unlinkSync(file);
+    } catch {
+    }
+  });
+}
+async function runningIn(dataDir) {
+  const { readConnectTarget, readEndpoint } = await Promise.resolve().then(() => __toESM(require("../backend/mcp/connector/files")));
+  const endpoint = readEndpoint(dataDir);
+  const target = readConnectTarget(dataDir);
+  if (!endpoint || !target.ok) return null;
+  try {
+    process.kill(endpoint.pid, 0);
+  } catch {
+    return null;
+  }
+  try {
+    if (JSON.parse(import_node_fs.default.readFileSync(import_node_path.default.join(dataDir, READY_FILE), "utf8")).pid !== endpoint.pid) return null;
+  } catch {
+    return null;
+  }
+  return { pid: endpoint.pid, url: target.url };
+}
+async function start(p) {
+  const project = projectOf(p);
+  const dataDir = import_node_path.default.resolve((0, import_args.flag)(p, "data-dir") ?? (0, import_args.headlessDataDir)(project, process.env, import_node_os.default.homedir()));
+  const line = (0, import_args.connectorLine)(process.execPath, binPath(), dataDir);
+  const say = (state, pid) => {
+    if (p.flags.quiet) return;
+    if (p.flags.json) out(JSON.stringify({ state, pid, project, dataDir, connector: { command: line.command, args: line.args } }));
+    else out(`CodeTrellis ${state === "running" ? "is already running" : "started"} for ${project} (pid ${pid}).
+Connect an agent with:
+  ${line.claude}`);
+  };
+  const up = await runningIn(dataDir);
+  if (up) return say("running", up.pid);
+  import_node_fs.default.mkdirSync(dataDir, { recursive: true });
+  const log = import_node_fs.default.openSync(import_node_path.default.join(dataDir, "serve.log"), "a");
+  const args = [binPath(), "serve", "--project", project, "--data-dir", dataDir];
+  for (const k of ["port", "mcp-port"]) {
+    const v = portOf(p, k);
+    if (v !== void 0) args.push(`--${k}`, v);
+  }
+  if (p.flags["share-task-state"]) args.push("--share-task-state");
+  const child = (0, import_node_child_process.spawn)(process.execPath, args, { detached: true, stdio: ["ignore", log, log], cwd: project, env: process.env });
+  child.unref();
+  import_node_fs.default.closeSync(log);
+  let exited = null;
+  child.on("exit", (code) => {
+    exited = code ?? 1;
+  });
+  const limit = Number((0, import_args.flag)(p, "timeout") ?? 120) * 1e3;
+  const until = Date.now() + (Number.isFinite(limit) && limit > 0 ? limit : 12e4);
+  while (Date.now() < until) {
+    const now = await runningIn(dataDir);
+    if (now) return say("started", now.pid);
+    if (exited !== null) fail(`codetrellis serve stopped (exit ${exited}); see ${import_node_path.default.join(dataDir, "serve.log")}`, 1);
+    await new Promise((r) => setTimeout(r, 250));
+  }
+  fail(`codetrellis serve did not come up in time; see ${import_node_path.default.join(dataDir, "serve.log")}`, 1);
+}
+async function stop(p) {
+  const project = projectOf(p);
+  const dataDir = import_node_path.default.resolve((0, import_args.flag)(p, "data-dir") ?? (0, import_args.headlessDataDir)(project, process.env, import_node_os.default.homedir()));
+  const up = await runningIn(dataDir);
+  if (!up) {
+    out(`CodeTrellis is not running for ${project}.`);
+    return;
+  }
+  process.kill(up.pid, "SIGTERM");
+  const until = Date.now() + 15e3;
+  while (Date.now() < until) {
+    try {
+      process.kill(up.pid, 0);
+    } catch {
+      out(`Stopped CodeTrellis for ${project}.`);
+      return;
+    }
+    await new Promise((r) => setTimeout(r, 200));
+  }
+  fail(`CodeTrellis (pid ${up.pid}) did not stop within 15 s`, 1);
+}
+async function verb(name, p) {
+  const { agentName, connectAgent, dataDirFor, NotRunningError } = await Promise.resolve().then(() => __toESM(require("./agent")));
+  const { runVerb, UsageError } = await Promise.resolve().then(() => __toESM(require("./verbs")));
+  const cwd = process.cwd();
+  let agent;
+  try {
+    agent = await connectAgent({ dataDir: dataDirFor((0, import_args.flag)(p, "data-dir"), cwd, process.env), name: agentName((0, import_args.flag)(p, "as"), process.env), cwd });
+  } catch (err) {
+    if (err instanceof NotRunningError) fail(err.message, 1);
+    throw err;
+  }
+  try {
+    const { runPlanVerb } = await Promise.resolve().then(() => __toESM(require("./plan-verbs")));
+    const { out: text, code } = import_plan_verbs.PLAN_VERBS.has(name) ? await runPlanVerb(name, agent, p, cwd) : await runVerb(name, agent, p, cwd);
+    if (text) out(text);
+    process.exitCode = code;
+  } catch (err) {
+    if (err instanceof UsageError) {
+      process.stderr.write(`codetrellis: ${err.message}
+`);
+      process.exitCode = 2;
+    } else throw err;
+  } finally {
+    await agent.close();
+  }
+}
+async function reviewCmd(p) {
+  if (p.rest[0] === "verify" || p.rest[0] === "publish") {
+    const { verifyCmd, publishCmd, VerifyUsageError } = await Promise.resolve().then(() => __toESM(require("./review-verify")));
+    try {
+      const r = p.rest[0] === "verify" ? verifyCmd(p, process.cwd(), process.env, import_package.version) : publishCmd(p, process.cwd());
+      out(r.out);
+      process.exitCode = r.code;
+    } catch (err) {
+      if (err instanceof VerifyUsageError) fail(err.message);
+      throw err;
+    }
+    return;
+  }
+  const { agentName, connectAgent, dataDirFor, NotRunningError } = await Promise.resolve().then(() => __toESM(require("./agent")));
+  const { review, reviewOptions, ReviewUsageError } = await Promise.resolve().then(() => __toESM(require("./review")));
+  const cwd = process.cwd();
+  let opts;
+  try {
+    opts = reviewOptions(p, cwd, process.env);
+  } catch (err) {
+    if (err instanceof ReviewUsageError) fail(err.message);
+    throw err;
+  }
+  let agent;
+  try {
+    agent = await connectAgent({ dataDir: dataDirFor((0, import_args.flag)(p, "data-dir"), cwd, process.env), name: agentName((0, import_args.flag)(p, "as"), process.env), cwd });
+  } catch (err) {
+    if (err instanceof NotRunningError) fail(err.message, 1);
+    throw err;
+  }
+  try {
+    const sinkFor = (dir) => ({ command: process.execPath, args: [binPath(), "review-sink", "--pass", dir] });
+    const post = opts.post ? await reviewPoster(opts.post, cwd) : void 0;
+    const { out: text, code, note } = await review(agent, opts, cwd, process.env, sinkFor, { post, version: import_package.version });
+    out(text);
+    if (note) process.stderr.write(`codetrellis review: ${note}
+`);
+    process.exitCode = code;
+  } finally {
+    await agent.close();
+  }
+}
+async function reviewPoster(post, cwd) {
+  const { detectProjectHost } = await Promise.resolve().then(() => __toESM(require("../backend/services/review-host/detect")));
+  const { DEFAULT_TOKEN, postComment, pullNumber } = await Promise.resolve().then(() => __toESM(require("./review-post")));
+  const host = detectProjectHost(cwd);
+  const pr = post.pr ?? pullNumber(process.env);
+  return async (markdown) => {
+    if (!host?.kind) return { ok: false, says: "origin is not on GitHub, GitLab or Bitbucket; the review was not posted" };
+    if (!pr) return { ok: false, says: "no pull request to post to (not a pull request job; --pr names one)" };
+    const tokenVar = post.tokenVar ?? DEFAULT_TOKEN[host.kind];
+    const token = process.env[tokenVar];
+    if (!token) return { ok: false, says: `${tokenVar} is not set; the review was not posted` };
+    return postComment(host, pr, token, markdown);
+  };
+}
+async function reviewSink(p) {
+  const dir = (0, import_args.flag)(p, "pass");
+  if (!dir) fail("review-sink needs --pass <dir>");
+  backendLogToStderr();
+  const { runReviewSink } = await Promise.resolve().then(() => __toESM(require("./review-sink")));
+  await runReviewSink(dir);
+}
+async function desktopCmd(p) {
+  const { desktop, DesktopUsageError } = await Promise.resolve().then(() => __toESM(require("./desktop")));
+  const work = import_node_fs.default.mkdtempSync(import_node_path.default.join(import_node_os.default.tmpdir(), "codetrellis-desktop-"));
+  process.env.CODETRELLIS_DATA_DIR = work;
+  const { findDesktopRelease, detectPlatform } = await Promise.resolve().then(() => __toESM(require("../backend/services/update-service")));
+  const { startUpdateDownload, saveVerifiedUpdateCopy, getUpdateDownloadState } = await Promise.resolve().then(() => __toESM(require("../backend/services/update-download-service")));
+  const downloads = import_node_path.default.join(import_node_os.default.homedir(), "Downloads");
+  const tty = process.stderr.isTTY && p.flags.json !== true;
+  let ticker;
+  let error;
+  try {
+    const r = await desktop(p, {
+      platform: detectPlatform(),
+      findRelease: findDesktopRelease,
+      download: (version, info) => {
+        if (tty) {
+          ticker = setInterval(() => {
+            const s = getUpdateDownloadState();
+            const pct = s.totalBytes ? Math.floor(s.bytesDownloaded / s.totalBytes * 100) : null;
+            process.stderr.write(`\r${s.phase === "preparing" ? "Checking the signed checksums\u2026" : `Downloading ${s.filename ?? ""} ${pct === null ? "" : `${pct}%`}`}   `);
+          }, 500);
+        }
+        return startUpdateDownload(version, info).finally(() => {
+          if (ticker) {
+            clearInterval(ticker);
+            process.stderr.write("\r\x1B[K");
+          }
+        });
+      },
+      saveCopy: saveVerifiedUpdateCopy,
+      // A DMG mounts; a Windows installer is itself the program to start.
+      open: (file) => {
+        const child = process.platform === "darwin" ? (0, import_node_child_process.spawn)("open", [file], { detached: true, stdio: "ignore" }) : process.platform === "win32" ? (0, import_node_child_process.spawn)(file, [], { detached: true, stdio: "ignore" }) : (0, import_node_child_process.spawn)("xdg-open", [file], { detached: true, stdio: "ignore" });
+        child.unref();
+      },
+      downloadsDir: import_node_fs.default.existsSync(downloads) ? downloads : process.cwd()
+    });
+    out(r.out);
+    process.exitCode = r.code;
+  } catch (err) {
+    error = err;
+  } finally {
+    import_node_fs.default.rmSync(work, { recursive: true, force: true });
+  }
+  if (error instanceof DesktopUsageError) fail(error.message);
+  if (error) fail(error instanceof Error ? error.message : String(error), 1);
+}
+function binPath() {
+  return import_node_path.default.resolve(__dirname, "..", "..", "bin", "codetrellis.mjs");
+}
+async function main() {
+  const p = (0, import_args.parseArgs)(process.argv.slice(2));
+  if (p.flags.version === true && !p.command) {
+    out(import_package.version);
+    return;
+  }
+  if (p.flags.help || !p.command || p.command === "help") {
+    out(import_args.USAGE);
+    return;
+  }
+  switch (p.command) {
+    case "serve":
+      return serve(p);
+    case "scan":
+      return scanOnce(p);
+    case "mcp":
+      return mcp(p);
+    case "start":
+      return start(p);
+    case "stop":
+      return stop(p);
+    case "review":
+      return reviewCmd(p);
+    case "review-sink":
+      return reviewSink(p);
+    case "desktop":
+      return desktopCmd(p);
+    default:
+      if (import_verbs.VERBS.has(p.command) || import_plan_verbs.PLAN_VERBS.has(p.command)) return verb(p.command, p);
+      fail(`unknown command "${p.command}". Run codetrellis --help.`);
+  }
+}
+main().catch((err) => fail(err instanceof Error ? err.message : String(err), 1));

package/src/cli/pipeline.js

@@ -0,0 +1,109 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var pipeline_exports = {};
+__export(pipeline_exports, {
+  pipelineWords: () => pipelineWords,
+  runPipeline: () => runPipeline
+});
+module.exports = __toCommonJS(pipeline_exports);
+var import_pipeline = require("../backend/services/pipeline");
+var import_check_words = require("../shared/lib/check-words");
+const agentOnly = (s) => !!s.rules.engine && s.rules.engine.every((e) => e === "agent");
+const wantsReview = (s) => !!s.rules.engine?.includes("agent");
+function gateFindings(stage, g) {
+  return g.rules.map((r) => ({
+    stage,
+    path: r.path,
+    says: `${r.path} ${(0, import_check_words.reachWords)(r.imports)}, which ${r.words ?? r.rule} forbids`,
+    rule: r.rule,
+    ...r.strength ? { strength: r.strength } : {}
+  }));
+}
+async function runPipeline(p, run, only) {
+  const notes = [];
+  const results = /* @__PURE__ */ new Map();
+  let first = true;
+  const chosen = only ? p.stages.filter((s) => s.id === only) : null;
+  if (only && !chosen.length) return { ok: false, stages: [], notes: [`The pipeline has no stage ${only}: its stages are ${p.stages.map((s) => s.id).join(", ")}.`] };
+  const one = async (s, judgesPipeline) => {
+    const base = { id: s.id, words: (0, import_pipeline.stageWords)(s), advisory: !!s.advisory, findings: [] };
+    if (s.when && !only) {
+      const unmet = Object.entries(s.when).filter(([id, want]) => {
+        const r = results.get(id);
+        return !r || !r.ran || (want === "passed" ? !r.ok : r.ok);
+      });
+      if (unmet.length) return { ...base, ran: false, ok: true, skipped: `it runs when ${unmet.map(([id, want]) => `${id} ${want}`).join(" and ")}, and ${unmet.length === 1 ? "that" : "those"} did not happen` };
+    }
+    const scope = { ...(0, import_pipeline.stageScope)(s), stage: s.id };
+    let ok = true;
+    const out = { ...base, ran: true, ok: true };
+    if (!agentOnly(s) || judgesPipeline) {
+      const g = await run.gate({ ...scope, ...judgesPipeline ? { pipeline: true } : {} });
+      out.gate = g;
+      if ("error" in g) ok = false;
+      else {
+        ok = g.ok;
+        out.findings.push(...gateFindings(s.id, g));
+      }
+    }
+    if (wantsReview(s)) {
+      if (!run.review) {
+        if (agentOnly(s) && !judgesPipeline) return { ...base, ran: false, ok: true, skipped: "no reviewer was given (--agent), so its agent rules are guides" };
+        notes.push(`The stage ${s.id}'s agent rules were not reviewed: no reviewer was given (--agent).`);
+      } else {
+        const grounding = only ? [] : (s.grounding ?? []).flatMap((id) => results.get(id)?.findings ?? []);
+        const r = await run.review(s, { ...scope, engine: "agent" }, grounding);
+        out.review = r;
+        if ("error" in r) ok = false;
+        else {
+          ok = ok && r.ok;
+          out.findings.push(...r.findings);
+        }
+      }
+    }
+    out.ok = ok;
+    return out;
+  };
+  for (const wave of (0, import_pipeline.waves)(p)) {
+    const stages2 = chosen ? wave.filter((s) => chosen.includes(s)) : wave;
+    if (!stages2.length) continue;
+    const done = await Promise.all(stages2.map((s, i) => one(s, first && i === 0)));
+    first = false;
+    for (const r of done) results.set(r.id, r);
+  }
+  const stages = [...results.values()];
+  return { ok: stages.every((s) => s.ok || s.advisory), stages, notes };
+}
+function pipelineWords(r, render) {
+  const lines = [];
+  for (const s of r.stages) {
+    const mark = !s.ran ? "\xB7" : s.ok ? "\u2713" : s.advisory ? "\u26A0" : "\u2717";
+    lines.push(`${mark} stage ${s.words}${s.skipped ? ` \u2014 skipped: ${s.skipped}` : ""}`);
+    if (s.gate) lines.push("error" in s.gate ? `  ${s.gate.error}` : render(s.gate).split("\n").map((l) => l ? `  ${l}` : l).join("\n"));
+    if (s.review) lines.push("error" in s.review ? `  review: ${s.review.error}` : s.review.out.split("\n").map((l) => l ? `  ${l}` : l).join("\n"));
+  }
+  for (const n of r.notes) lines.push(`\u26A0 ${n}`);
+  const failing = r.stages.filter((s) => !s.ok && !s.advisory).map((s) => s.id);
+  lines.push(r.ok ? `\u2713 The pipeline passes (${r.stages.filter((s) => s.ran).length} of ${r.stages.length} stages ran).` : `\u2717 The pipeline fails: ${failing.join(", ")}.`);
+  return lines.join("\n");
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  pipelineWords,
+  runPipeline
+});