codetrellis 0.0.0-stage → 0.3.0

package/src/backend/services/worktree-service.js

@@ -0,0 +1,235 @@
+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 worktree_service_exports = {};
+__export(worktree_service_exports, {
+  WorktreeError: () => WorktreeError,
+  belongsToRepo: () => belongsToRepo,
+  createWorktree: () => createWorktree,
+  describeWorktrees: () => describeWorktrees,
+  listWorktrees: () => listWorktrees,
+  listWorktreesAsync: () => listWorktreesAsync,
+  listWorktreesWithPlans: () => listWorktreesWithPlans,
+  parseWorktreePorcelain: () => parseWorktreePorcelain,
+  readWorktreePlans: () => readWorktreePlans,
+  worktreeWhere: () => worktreeWhere
+});
+module.exports = __toCommonJS(worktree_service_exports);
+var import_node_child_process = require("node:child_process");
+var fs = __toESM(require("node:fs"));
+var path = __toESM(require("node:path"));
+var import_yaml = require("yaml");
+var import_confined_fs = require("./confined-fs");
+var import_git_env = require("./git-env");
+function parseWorktreePorcelain(out, currentRoot) {
+  const current = safeCanonical(currentRoot);
+  const result = [];
+  for (const block of out.split(/\n\s*\n/)) {
+    const lines = block.split("\n").map((l) => l.trim()).filter(Boolean);
+    const first = lines.find((l) => l.startsWith("worktree "));
+    if (!first) continue;
+    const wtPath = first.slice("worktree ".length);
+    const branchLine = lines.find((l) => l.startsWith("branch "));
+    const headLine = lines.find((l) => l.startsWith("HEAD "));
+    result.push({
+      path: wtPath,
+      branch: branchLine ? branchLine.slice("branch ".length).replace(/^refs\/heads\//, "") : null,
+      head: headLine ? headLine.slice("HEAD ".length) : null,
+      isMain: result.length === 0,
+      isCurrent: safeCanonical(wtPath) === current,
+      bare: lines.includes("bare"),
+      prunable: lines.some((l) => l === "prunable" || l.startsWith("prunable "))
+    });
+  }
+  return result;
+}
+function safeCanonical(p) {
+  try {
+    return (0, import_confined_fs.canonicalRoot)(p);
+  } catch {
+    return path.resolve(p);
+  }
+}
+function git(projectRoot, args) {
+  return (0, import_node_child_process.execFileSync)("git", ["-C", projectRoot, ...args], {
+    encoding: "utf-8",
+    stdio: ["ignore", "pipe", "ignore"],
+    timeout: 5e3
+  });
+}
+function belongsToRepo(wt, commonDir) {
+  try {
+    const wtRoot = fs.realpathSync.native(wt.path);
+    const dotGit = path.join(wtRoot, ".git");
+    const st = fs.lstatSync(dotGit);
+    if (wt.isMain) {
+      return st.isDirectory() && fs.realpathSync.native(dotGit) === commonDir;
+    }
+    if (!st.isFile()) return false;
+    const m = /^gitdir:\s*(.+)\s*$/m.exec(fs.readFileSync(dotGit, "utf-8"));
+    if (!m) return false;
+    const target = fs.realpathSync.native(path.resolve(wtRoot, m[1].trim()));
+    return path.dirname(target) === path.join(commonDir, "worktrees");
+  } catch {
+    return false;
+  }
+}
+const WHERE_ORDER = { main: 0, inside: 1, beside: 2, home: 3, elsewhere: 4 };
+function under(child, parent) {
+  const rel = path.relative(parent, child);
+  if (!rel || rel.startsWith("..") || path.isAbsolute(rel)) return null;
+  return rel.split(path.sep).join("/");
+}
+function worktreeWhere(wtPath, isMain, mainRoot, home) {
+  const homeLabel = (p) => {
+    const rel = under(p, home);
+    return rel ? `~/${rel}` : p.split(path.sep).join("/");
+  };
+  if (isMain) return { where: "main", label: homeLabel(wtPath) };
+  const inside = under(wtPath, mainRoot);
+  if (inside) return { where: "inside", label: inside };
+  const beside = under(wtPath, path.dirname(mainRoot));
+  if (beside) return { where: "beside", label: `../${beside}` };
+  const label = homeLabel(wtPath);
+  return { where: label.startsWith("~/") ? "home" : "elsewhere", label };
+}
+function describeWorktrees(list, projectRoot, home) {
+  const main = list.find((w) => w.isMain && !w.bare);
+  const mainRoot = safeCanonical(main?.path ?? projectRoot);
+  const homeRoot = safeCanonical(home);
+  return list.filter((w) => !w.isCurrent && !w.bare).map((w) => ({
+    path: w.path,
+    branch: w.branch,
+    isMain: w.isMain,
+    prunable: w.prunable,
+    ...worktreeWhere(w.prunable ? path.resolve(w.path) : safeCanonical(w.path), w.isMain, mainRoot, homeRoot)
+  })).sort((a, b) => Number(a.prunable) - Number(b.prunable) || WHERE_ORDER[a.where] - WHERE_ORDER[b.where] || a.label.localeCompare(b.label));
+}
+function listWorktrees(projectRoot) {
+  let out;
+  let commonDir;
+  try {
+    out = git(projectRoot, ["worktree", "list", "--porcelain"]);
+    commonDir = fs.realpathSync.native(
+      path.resolve(projectRoot, git(projectRoot, ["rev-parse", "--git-common-dir"]).trim())
+    );
+  } catch {
+    return [];
+  }
+  return parseWorktreePorcelain(out, projectRoot).filter((w) => w.bare || w.prunable || belongsToRepo(w, commonDir));
+}
+async function listWorktreesAsync(projectRoot) {
+  let out;
+  let commonDir;
+  try {
+    out = await (0, import_git_env.gitAsync)(projectRoot, ["worktree", "list", "--porcelain"]);
+    commonDir = fs.realpathSync.native(
+      path.resolve(projectRoot, (await (0, import_git_env.gitAsync)(projectRoot, ["rev-parse", "--git-common-dir"])).trim())
+    );
+  } catch {
+    return [];
+  }
+  return parseWorktreePorcelain(out, projectRoot).filter((w) => w.bare || w.prunable || belongsToRepo(w, commonDir));
+}
+function readWorktreePlans(worktreeRoot) {
+  let plansDir;
+  try {
+    plansDir = (0, import_confined_fs.resolveWithin)(worktreeRoot, path.join(".codetrellis", "plans"), "plans dir");
+  } catch {
+    return [];
+  }
+  if (!fs.existsSync(plansDir)) return [];
+  const plans = [];
+  let entries = [];
+  try {
+    entries = fs.readdirSync(plansDir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    try {
+      const text = (0, import_confined_fs.readTextWithin)(worktreeRoot, path.join(".codetrellis", "plans", entry.name, "plan.yaml"), "plan.yaml");
+      const doc = (0, import_yaml.parse)(text);
+      if (!doc || typeof doc.uid !== "string") continue;
+      plans.push({
+        uid: doc.uid,
+        title: typeof doc.title === "string" ? doc.title : entry.name,
+        status: typeof doc.status === "string" ? doc.status : "draft"
+      });
+    } catch {
+    }
+  }
+  return plans;
+}
+function listWorktreesWithPlans(projectRoot) {
+  return listWorktrees(projectRoot).filter((w) => !w.bare && !w.prunable && fs.existsSync(w.path)).map((w) => ({ ...w, plans: readWorktreePlans(w.path) }));
+}
+class WorktreeError extends Error {
+  constructor(message, status = 400) {
+    super(message);
+    this.status = status;
+  }
+  status;
+}
+function createWorktree(projectRoot, opts) {
+  if (fs.existsSync(opts.dir)) throw new WorktreeError(`${opts.dir} already exists; choose another branch name`, 409);
+  let branchExists = true;
+  try {
+    git(projectRoot, ["rev-parse", "--verify", "--quiet", `refs/heads/${opts.branch}`]);
+  } catch {
+    branchExists = false;
+  }
+  if (branchExists) throw new WorktreeError(`A branch named ${opts.branch} already exists; choose another name`, 409);
+  if (opts.base) {
+    try {
+      git(projectRoot, ["rev-parse", "--verify", "--quiet", `${opts.base}^{commit}`]);
+    } catch {
+      throw new WorktreeError(`The plan's base, ${opts.base}, is not a branch or commit in this repository`, 400);
+    }
+  }
+  const args = ["-C", projectRoot, "worktree", "add", "-b", opts.branch, opts.dir, ...opts.base ? [opts.base] : []];
+  try {
+    (0, import_node_child_process.execFileSync)("git", args, { encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"], timeout: 3e4 });
+  } catch (err) {
+    const stderr = String(err.stderr ?? "").split("\n").find((l) => l.trim()) ?? "unknown error";
+    throw new WorktreeError(`git could not make the worktree: ${stderr.replace(/^fatal:\s*/, "")}`, 400);
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  WorktreeError,
+  belongsToRepo,
+  createWorktree,
+  describeWorktrees,
+  listWorktrees,
+  listWorktreesAsync,
+  listWorktreesWithPlans,
+  parseWorktreePorcelain,
+  readWorktreePlans,
+  worktreeWhere
+});

package/src/cli/agent.js

@@ -0,0 +1,100 @@
+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 agent_exports = {};
+__export(agent_exports, {
+  NotRunningError: () => NotRunningError,
+  agentName: () => agentName,
+  connectAgent: () => connectAgent,
+  dataDirFor: () => dataDirFor
+});
+module.exports = __toCommonJS(agent_exports);
+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_client = require("@modelcontextprotocol/sdk/client/index.js");
+var import_sse = require("@modelcontextprotocol/sdk/client/sse.js");
+var import_binding_headers = require("../backend/mcp/binding-headers");
+var import_files = require("../backend/mcp/connector/files");
+var import_args = require("./args");
+function agentName(asFlag, env) {
+  if (asFlag && asFlag.trim()) return asFlag.trim();
+  if (env.CODETRELLIS_AGENT && env.CODETRELLIS_AGENT.trim()) return env.CODETRELLIS_AGENT.trim();
+  if (env.CLAUDECODE === "1") return "claude-code";
+  return "codetrellis-cli";
+}
+function dataDirFor(given, cwd, env) {
+  if (given) return import_node_path.default.resolve(given);
+  const here = (0, import_args.headlessDataDir)(cwd, env, import_node_os.default.homedir());
+  if (import_node_fs.default.existsSync(import_node_path.default.join(here, "mcp-endpoint.json"))) return here;
+  return (0, import_files.defaultDataDir)(env);
+}
+class NotRunningError extends Error {
+}
+async function connectAgent(opts) {
+  const target = (0, import_files.readConnectTarget)(opts.dataDir);
+  if (!target.ok) {
+    throw new NotRunningError(`CodeTrellis is not running for this folder (${target.reason}). Start it with \`codetrellis serve\`, or open the app.`);
+  }
+  const url = new URL(target.url);
+  url.searchParams.set("ct_token", target.token);
+  const headers = (0, import_binding_headers.bindingHeaders)({ cwd: opts.cwd });
+  const transport = new import_sse.SSEClientTransport(url, {
+    eventSourceInit: {
+      fetch: (u, init) => fetch(u, { ...init, headers: { ...init?.headers, ...headers } })
+    },
+    requestInit: { headers }
+  });
+  const client = new import_client.Client({ name: opts.name, version: "cli" }, { capabilities: {} });
+  await client.connect(transport);
+  return {
+    name: opts.name,
+    async call(name, args) {
+      const res = await client.callTool({ name, arguments: args });
+      const text = (res.content ?? []).find((c) => c.type === "text" && typeof c.text === "string")?.text ?? "";
+      let json = null;
+      try {
+        json = JSON.parse(text);
+      } catch {
+      }
+      return { text, json, isError: res.isError === true };
+    },
+    async close() {
+      try {
+        await client.close();
+      } catch {
+      }
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  NotRunningError,
+  agentName,
+  connectAgent,
+  dataDirFor
+});

package/src/cli/args.js

@@ -0,0 +1,209 @@
+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 args_exports = {};
+__export(args_exports, {
+  USAGE: () => USAGE,
+  connectorLine: () => connectorLine,
+  flag: () => flag,
+  headlessCacheRoot: () => headlessCacheRoot,
+  headlessDataDir: () => headlessDataDir,
+  parseArgs: () => parseArgs,
+  selfCommand: () => selfCommand
+});
+module.exports = __toCommonJS(args_exports);
+var import_node_path = __toESM(require("node:path"));
+var import_node_crypto = __toESM(require("node:crypto"));
+const SWITCHES = /* @__PURE__ */ new Set(["json", "help", "no-wait", "quiet", "share-task-state", "top", "page", "strict", "no-color", "verify", "post", "pipeline", "require", "no-fetch", "no-open"]);
+function parseArgs(argv) {
+  const flags = {};
+  const rest = [];
+  let command = null;
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--") {
+      rest.push(...argv.slice(i + 1));
+      break;
+    }
+    if (a.startsWith("--")) {
+      const eq = a.indexOf("=");
+      const name = eq > 0 ? a.slice(2, eq) : a.slice(2);
+      if (eq > 0) flags[name] = a.slice(eq + 1);
+      else if (!SWITCHES.has(name) && i + 1 < argv.length && !argv[i + 1].startsWith("--")) flags[name] = argv[++i];
+      else flags[name] = true;
+      continue;
+    }
+    if (a === "-h") {
+      flags.help = true;
+      continue;
+    }
+    if (a === "-m" && i + 1 < argv.length) {
+      flags.m = argv[++i];
+      continue;
+    }
+    if (command === null) command = a;
+    else rest.push(a);
+  }
+  return { command, flags, rest };
+}
+function flag(p, name) {
+  const v = p.flags[name];
+  return typeof v === "string" ? v : void 0;
+}
+function headlessDataDir(projectRoot, env, home, platform = process.platform) {
+  const fromEnv = env.CODETRELLIS_DATA_DIR;
+  if (fromEnv && fromEnv.trim()) return fromEnv;
+  const resolved = import_node_path.default.resolve(projectRoot);
+  const id = import_node_crypto.default.createHash("sha256").update(resolved).digest("hex").slice(0, 10);
+  const name = import_node_path.default.basename(resolved).replace(/[^A-Za-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 40) || "project";
+  return import_node_path.default.join(headlessCacheRoot(env, home, platform), `${name}-${id}`);
+}
+function headlessCacheRoot(env, home, platform = process.platform) {
+  const cache = platform === "darwin" ? import_node_path.default.join(home, "Library", "Caches") : platform === "win32" ? env.LOCALAPPDATA || import_node_path.default.join(home, "AppData", "Local") : env.XDG_CACHE_HOME && import_node_path.default.isAbsolute(env.XDG_CACHE_HOME) ? env.XDG_CACHE_HOME : import_node_path.default.join(home, ".cache");
+  return import_node_path.default.join(cache, "codetrellis");
+}
+const quote = (s) => /^[A-Za-z0-9_./:=@-]+$/.test(s) ? s : `'${s.replace(/'/g, `'\\''`)}'`;
+function selfCommand(binDir, proc) {
+  if (proc.electron) return { command: proc.execPath, args: [import_node_path.default.join(binDir, "app.cjs")], env: { ELECTRON_RUN_AS_NODE: "1" } };
+  return { command: proc.execPath, args: [import_node_path.default.join(binDir, "codetrellis.mjs")], env: {} };
+}
+function connectorLine(self, dataDir) {
+  const args = [...self.args, "mcp", "--data-dir", dataDir];
+  const env = Object.keys(self.env).length ? self.env : void 0;
+  const envFlags = Object.entries(self.env).map(([k, v]) => `-e ${quote(`${k}=${v}`)} `).join("");
+  return {
+    command: self.command,
+    args,
+    claude: `claude mcp add codetrellis ${envFlags}-- ${[self.command, ...args].map(quote).join(" ")}`,
+    json: JSON.stringify({ mcpServers: { codetrellis: { command: self.command, args, ...env ? { env } : {} } } })
+  };
+}
+const USAGE = `codetrellis \u2014 CodeTrellis for agents, without the desktop app
+
+  codetrellis serve [--project <dir>] [--data-dir <dir>] [--port <n>] [--mcp-port <n>] [--share-task-state] [--json]
+      Run the backend headless for a project: loopback only, the capability
+      token on every transport, no discovery, peers or update check. Prints
+      the line an agent's MCP config needs. --share-task-state writes task
+      state and test runs to the project's files and reads teammates', as the
+      app's Settings switch does.
+
+  codetrellis scan [--project <dir>] [--data-dir <dir>] [--json]
+      Scan a project once and print what was found, then exit.
+
+  codetrellis start [--project <dir>] [--data-dir <dir>] [--timeout <s>] [--share-task-state] [--quiet | --json]
+      serve in the background, unless it already runs for this folder; for a
+      session-start hook or a CI step. Its log is serve.log in the data dir.
+
+  codetrellis stop [--project <dir>] [--data-dir <dir>]
+
+  codetrellis mcp [--data-dir <dir>]
+      The stdio MCP connector an agent's config launches. Finds the headless
+      backend for the folder it is started in, else the desktop app's.
+
+Keeping on track, as the agent running the command (--as <name> to say
+which; text, or --json):
+
+  codetrellis next [--plan <uid>]              the task to pick up
+  codetrellis claim <task>                     take it
+  codetrellis update <task> --progress N [--note <text>]
+  codetrellis stuck <task> <why\u2026>              blocked, and why
+  codetrellis done <task>                      refused while a criterion's check fails
+  codetrellis request <question\u2026> [--options a,b] [--item <task>] [--no-wait] [--timeout <s>]
+                                               ask the person; waits for their answer
+  codetrellis brief <task>                     what the task needs
+  codetrellis awareness                        what overlaps your work
+  codetrellis check <path>                     before an edit: overlaps, and whether a breakpoint holds it
+  codetrellis check [--base <ref>] [--strict]  does this work conform? exit 3 when a breakpoint holds a
+                                               changed file, its tests fail or are older than the code, a
+                                               done task fails its checks, a doc describing it is stale,
+                                               it adds an import a rule at block forbids, or it loosens a
+                                               rule; a rule at warn is said and passes (--strict: it fails)
+  codetrellis check --format sarif             the same, as SARIF 2.1.0 for any CI host (or text, json, markdown)
+  codetrellis check --no-color                 plain text in a terminal too (NO_COLOR does the same)
+  codetrellis check --suite <s> | --rule <id> | --path <p> | --tag <t>
+                                               only those rules (comma-separated): one suite's, named
+                                               rules, the rules about a path, or those with a tag
+  codetrellis check --pipeline [--stage <id>]  the base's .codetrellis/pipeline.yaml, stage by stage; agent
+                                               stages too with --agent and the review's flags
+  codetrellis rules baseline                   record each rule's breaches now; the check then fails on
+                                               any it does not list, and the file may only shrink
+  codetrellis report-tests <junit.xml>         tell CodeTrellis how the tests went
+  codetrellis review [--agent claude-code] [--model <m>] [--endpoint <url>] [--auth env:<VAR>]
+                     [--skills <dir>] [--suite <s> | --rule <id> | --path <p> | --tag <t>] [--base <ref>] [--task <uid>]
+                     [--max-turns <n>] [--timeout <s>] [--max-tool-calls <n>] [--fail-on block,error] [--verify]
+                     [--format text|markdown|sarif|json] [--sarif-out <f>] [--markdown-out <f>] [--post [--pr <n>]]
+                                               your own agent reviews the change, headless, with no shell,
+                                               files or web; each finding must cite the diff, and each pass
+                                               is kept as a check run. --verify: a second pass tries to refute
+                                               each finding. --auth oidc:bedrock|vertex|foundry signs in through
+                                               your cloud. --post comments on the pull request. Advisory: exit 3
+                                               only with --fail-on. A review of a commit is signed with this
+                                               device's key, as a git note on it
+  codetrellis review publish [--remote <r>]    push the signed reviews, for CI to read
+  codetrellis review verify --base <ref> [--head <ref>] [--require] [--format text|markdown|sarif|json]
+                                               the head's signed review, checked against the keys on the base:
+                                               verified, stale (of an earlier commit), refused, or none; no
+                                               app, no secret, no AI. --require: exit 3 unless verified
+
+The desktop app:
+
+  codetrellis desktop install [--version <v>] [--platform <p>] [--dir <d>] [--no-open] [--json]
+                                               download the app for this computer (or --platform:
+                                               darwin-arm64, darwin-x64, win32-x64, win32-arm64, linux-x64,
+                                               linux-arm64), check it against the release's signed
+                                               checksums, save it to --dir (default ~/Downloads) and open it
+  codetrellis desktop url [--version <v>] [--platform <p>] [--json]
+                                               the installer's download link, without downloading
+
+  codetrellis --version                        this CLI's version
+
+Changing and committing the plan:
+
+  codetrellis plan show [--plan <uid>]
+  codetrellis plan add <title\u2026> [--under <task>] [--page] [--body <text>]
+  codetrellis plan edit <task> [--title <text>] [--body <text>]
+  codetrellis plan move <task> (--under <task> | --top) [--position N]
+  codetrellis commit [-m <subject>]            commits only CodeTrellis's own files (.codetrellis/)
+  codetrellis status [--base <ref>] [--strict] plans, what is under way, blocked, and waiting on you,
+                                               and whether this work conforms (exit 3 when not)
+
+  <task> is a uid, or its first characters ("6cb8cf43", "task 6cb8cf43").
+  Exit codes: 0 done, 1 refused, 2 usage, 3 held, not answered yet, or not conforming.
+  This work is the branch since its base (--base, else the pull request's
+  base in GitHub Actions, else origin's default branch) and what is not
+  committed yet.
+`;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  USAGE,
+  connectorLine,
+  flag,
+  headlessCacheRoot,
+  headlessDataDir,
+  parseArgs,
+  selfCommand
+});

package/src/cli/conformity.js

@@ -0,0 +1,106 @@
+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 conformity_exports = {};
+__export(conformity_exports, {
+  baseRef: () => import_work_changes.baseRef,
+  changedFiles: () => import_work_changes.changedFiles,
+  gate: () => gate,
+  gateMarkdown: () => gateMarkdown,
+  gateWords: () => gateWords,
+  ranIn: () => ranIn,
+  wantsColor: () => wantsColor,
+  withPlaces: () => withPlaces
+});
+module.exports = __toCommonJS(conformity_exports);
+var import_check_words = require("../shared/lib/check-words");
+var import_import_line = require("../shared/lib/import-line");
+var import_work_changes = require("../backend/services/work-changes");
+function ranIn(env) {
+  const on = (k) => env[k] !== void 0 && env[k] !== "" && env[k] !== "false" && env[k] !== "0";
+  if (on("GITHUB_ACTIONS")) return "GitHub Actions";
+  if (on("GITLAB_CI")) return "GitLab CI";
+  if (on("BITBUCKET_BUILD_NUMBER")) return "Bitbucket Pipelines";
+  if (on("TF_BUILD")) return "Azure Pipelines";
+  if (on("JENKINS_URL")) return "Jenkins";
+  if (on("CIRCLECI")) return "CircleCI";
+  if (on("BUILDKITE")) return "Buildkite";
+  if (on("CI")) return "CI";
+  return "a terminal";
+}
+async function gate(agent, root, changed, strict = false, scope = {}) {
+  if (changed.files.length === 0 && !changed.rulebook) return { ok: true, says: [], files: 0, base: changed.base, breakpoints: [], tests: [], criteria: [], docs: [], rules: [], rulebook: [], notes: [] };
+  const { stage, ...selects } = scope;
+  const a = await agent.call("check_changes", {
+    paths: changed.files.slice(0, 500),
+    project_path: root,
+    ...changed.since ? { base: changed.since } : {},
+    ...strict ? { strict: true } : {},
+    ...selects,
+    // C7: the run is kept saying where it ran; B6: and which stage of the pipeline it was.
+    ran_in: stage ? `${ranIn(process.env)}, stage ${stage}` : ranIn(process.env)
+  });
+  if (a.isError) return { error: a.text };
+  const j = a.json ?? {};
+  const list = (k) => Array.isArray(j[k]) ? j[k] : [];
+  return {
+    ok: j.ok === true,
+    says: list("says"),
+    files: changed.files.length,
+    base: changed.base,
+    breakpoints: list("breakpoints"),
+    tests: list("tests"),
+    criteria: list("criteria"),
+    docs: list("docs"),
+    rules: list("rules"),
+    rulebook: list("rulebook"),
+    notes: list("notes").filter((n) => typeof n === "string"),
+    ...typeof j.rules_note === "string" ? { rulesNote: j.rules_note } : {},
+    ...typeof j.scope === "string" ? { scope: j.scope } : {},
+    ...Array.isArray(j.checked) ? { checked: j.checked } : {}
+  };
+}
+function gateWords(g, opts = {}) {
+  return (0, import_check_words.renderText)(withPlaces(g, opts.read), { color: opts.color });
+}
+function gateMarkdown(g, read) {
+  return (0, import_check_words.renderMarkdown)(withPlaces(g, read));
+}
+function withPlaces(g, read) {
+  const rules = g.rules.map((r) => {
+    const text = read ? read(r.path) : null;
+    const line = text === null ? null : (0, import_import_line.findingAt)(text, r.imports, r.line_found);
+    return { ...r, line, text: line ? text.split("\n")[line - 1] : null };
+  });
+  return { ...g, rules, rulebook: g.rulebook };
+}
+function wantsColor(stream, env, noColorFlag = false) {
+  if (noColorFlag || env.NO_COLOR !== void 0 && env.NO_COLOR !== "") return false;
+  if (env.FORCE_COLOR !== void 0 && env.FORCE_COLOR !== "" && env.FORCE_COLOR !== "0") return true;
+  return stream.isTTY === true && env.TERM !== "dumb";
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  baseRef,
+  changedFiles,
+  gate,
+  gateMarkdown,
+  gateWords,
+  ranIn,
+  wantsColor,
+  withPlaces
+});