catherd-cli 0.2.1 → 1.0.0

package/src/entry/prompt.ts

@@ -0,0 +1,103 @@
+import { createInterface, type Interface } from "node:readline/promises";
+import { EXIT } from "./cli-kit.ts";
+
+/** Plain questions on stdin; `secret` does not echo what is typed. */
+export interface Prompter {
+  ask(question: string): Promise<string>;
+  secret(question: string): Promise<string>;
+  /** A question this machine does not need asked: piped, its line is still consumed, so answers keep their place */
+  skip?(): void;
+  close(): void;
+}
+
+/** A terminal's hidden input, one character at a time; Ctrl-C exits 130 (spec §8). */
+function readSecret(question: string): Promise<string> {
+  process.stdout.write(question);
+  const stdin = process.stdin;
+  return new Promise((resolve) => {
+    let value = "";
+    const done = () => {
+      stdin.off("data", onData);
+      stdin.setRawMode(false);
+      stdin.pause();
+      process.stdout.write("\n");
+      resolve(value.trim());
+    };
+    const onData = (chunk: Buffer) => {
+      for (const ch of chunk.toString("utf8")) {
+        if (ch === "\r" || ch === "\n") return done();
+        if (ch === "\u0003") {
+          stdin.setRawMode(false);
+          process.exit(EXIT.interrupted);
+        }
+        if (ch === "\u007f") {
+          if (value) process.stdout.write("\b \b");
+          value = value.slice(0, -1);
+        } else {
+          value += ch;
+          process.stdout.write("*");
+        }
+      }
+    };
+    stdin.setRawMode(true);
+    stdin.resume();
+    stdin.on("data", onData);
+  });
+}
+
+/** What `terminalAsk` needs of a readline interface. */
+interface Line {
+  question(q: string): Promise<string>;
+  on(event: "SIGINT", listener: () => void): unknown;
+}
+const isAbort = (e: unknown) =>
+  e instanceof Error && (e.name === "AbortError" || (e as { code?: string }).code === "ABORT_ERR");
+
+/**
+ * A terminal question on `rl`, trimmed. Ctrl-C exits 130 (spec §8), as the secret prompt does: readline
+ * emits SIGINT, or the pending question rejects with an AbortError, depending on the runtime.
+ */
+export function terminalAsk(
+  rl: Line,
+  exit: (code: number) => never = (code) => process.exit(code),
+): (q: string) => Promise<string> {
+  rl.on("SIGINT", () => exit(EXIT.interrupted));
+  return async (q) => {
+    try {
+      return (await rl.question(q)).trim();
+    } catch (e) {
+      if (isAbort(e)) exit(EXIT.interrupted);
+      throw e;
+    }
+  };
+}
+
+/**
+ * Questions for `catherd init`. On a terminal they are asked one by one; piped, stdin is read once and each
+ * question takes its own line (an empty or missing line takes the default), whether or not this machine
+ * asks it, so a script's answers never shift onto another question.
+ */
+export async function prompter(): Promise<Prompter> {
+  if (!process.stdin.isTTY) {
+    const lines = (await Bun.stdin.text()).split("\n");
+    const next = async (q: string) => {
+      const answer = (lines.shift() ?? "").trim();
+      process.stdout.write(`${q}\n`);
+      return answer;
+    };
+    return { ask: next, secret: next, skip: () => void lines.shift(), close() {} };
+  }
+  let rl: Interface | null = null;
+  let ask: ((q: string) => Promise<string>) | null = null;
+  return {
+    ask(q) {
+      rl ??= createInterface({ input: process.stdin, output: process.stdout });
+      ask ??= terminalAsk(rl);
+      return ask(q);
+    },
+    secret: (q) => readSecret(q),
+    close() {
+      rl?.close();
+    },
+  };
+}

package/src/entry/runs-command.ts

@@ -0,0 +1,217 @@
+import { resolve } from "node:path";
+import { defineCommand } from "citty";
+import { formatBudget } from "../domain/budget.ts";
+import { CatherdError } from "../domain/errors.ts";
+import { gitToplevel } from "../infra/git.ts";
+import { redact } from "../infra/log.ts";
+import { cancel } from "../services/dispatch-service.ts";
+import { registerSavedSecrets } from "../services/jev-service.ts";
+import { runDebug } from "../services/run-debug.ts";
+import { findRun, listRuns, readRecords } from "../services/run-store.ts";
+import { type RunSummary, status, summarizeRun } from "../services/summary.ts";
+import { JSON_ARG, mark, printJson } from "./cli-kit.ts";
+import { defaultDeps } from "./deps.ts";
+
+const json = JSON_ARG;
+const n = (x: number) => x.toLocaleString("en-US");
+
+/** One run at a glance: what is live, what finished, spend against the budget, landed milestones. */
+export function formatRun(s: RunSummary, now: number = Date.now()): string[] {
+  const t = s.totals;
+  const lines = [
+    `run ${s.id}  ${s.title}`,
+    `  repo ${s.repo} · started ${s.createdAt} · ${Math.round((now - Date.parse(s.createdAt)) / 60_000)} min`,
+  ];
+  for (const l of s.live) lines.push(`  live ${l.name}  ${l.rung}  ${l.state} ${l.secs}s`);
+  lines.push(
+    `  done ${t.runs} role run(s), ${t.ok} ok${t.notOk.length ? `; not ok: ${t.notOk.join(", ")}` : ""}`,
+    `  tokens ${n(t.tokens.input)} in (${n(t.tokens.cached)} cached) · ${n(t.tokens.output)} out · $${t.costUsd.toFixed(2)}` +
+      (s.agents.runs
+        ? ` · native agents ${s.agents.runs} run(s), ${n(s.agents.totalTokens)} tokens (reported)`
+        : ""),
+  );
+  if (s.harness.length)
+    lines.push(
+      `  harness ${s.harness.map((h) => `${h.backend} ${h.native} native, ${h.isolated} isolated`).join(" · ")}`,
+    );
+  if (s.budget) lines.push(`  budget ${formatBudget(s.budget)}`);
+  if (s.jev.decisions) lines.push(`  jev ${s.jev.decisions} decision(s), ${s.jev.fallbacks} fallback(s)`);
+  for (const m of s.milestones) lines.push(`  landed ${m}`);
+  for (const l of s.stateTail) lines.push(`  | ${l}`);
+  for (const w of s.warnings) lines.push(`  ${mark("warn")} ${w}`);
+  return lines;
+}
+
+function printStatus(runId: string | undefined, asJson: boolean): void {
+  // redacted as `runs show` is: the state.md tail can quote a secret, and status goes to shared terminals
+  registerSavedSecrets();
+  const r = redact(status(defaultDeps(), runId));
+  if (asJson) return printJson(r);
+  if (r.runs.length === 0) console.log("no runs yet");
+  for (const s of r.runs) for (const l of formatRun(s)) console.log(l);
+  for (const w of r.warnings) console.log(`${mark("warn")} ${w}`);
+}
+
+/** Spec §8 `catherd status [run] [--json]`: that run, else every run with a live role, else the newest. */
+export const statusCommand = defineCommand({
+  meta: {
+    name: "status",
+    description: "A run at a glance (default: runs with a live role, else the newest)",
+  },
+  args: { run: { type: "positional", required: false, description: "run id" }, ...json },
+  run({ args }) {
+    printStatus(args.run, args.json === true);
+  },
+});
+
+/** `watch --interval <secs>` in ms: 2 s when absent, never under 1 s (so 0 means 1 s); not a number is refused. */
+export function redrawMs(interval: string | undefined): number {
+  if (interval === undefined) return 2000;
+  const secs = interval.trim() === "" ? Number.NaN : Number(interval);
+  if (!Number.isFinite(secs) || secs < 0)
+    throw new CatherdError("E_INPUT_INVALID", `--interval takes a number of seconds, not "${interval}"`, {
+      fix: "catherd watch --interval <seconds>",
+    });
+  return Math.max(1, secs) * 1000;
+}
+
+/** Spec §8 `catherd watch [--once]`: the TUI's Runs tab on a terminal, else a plain redraw. */
+export const watchCommand = defineCommand({
+  meta: {
+    name: "watch",
+    description:
+      "The live runs: the dashboard's Runs tab on a terminal, else redrawn as text (--once: print once)",
+  },
+  args: {
+    once: { type: "boolean", description: "print one snapshot and exit" },
+    interval: { type: "string", description: "seconds between text redraws when piped (default 2)" },
+    plain: {
+      type: "boolean",
+      description: "the dashboard in ASCII without colour (NO_COLOR also drops colour)",
+    },
+    "reduced-motion": { type: "boolean", description: "the dashboard without animation" },
+    ...json,
+  },
+  async run({ args }) {
+    const every = redrawMs(args.interval);
+    if (args.once || args.json) return printStatus(undefined, args.json === true);
+    // on a terminal, watch is the dashboard's Runs tab (plan 6 Ruling 10); piped output keeps the plain view
+    if (process.stdin.isTTY && process.stdout.isTTY) {
+      const { openTui } = await import("./tui/run.tsx");
+      const rawArgs = [
+        ...(args.plain ? ["--plain"] : []),
+        ...(args["reduced-motion"] ? ["--reduced-motion"] : []),
+      ];
+      process.exitCode = await openTui({ rawArgs, tab: "runs", tty: true });
+      return;
+    }
+    for (;;) {
+      if (process.stdout.isTTY) process.stdout.write("\x1b[2J\x1b[H");
+      printStatus(undefined, false);
+      console.log(`updated ${new Date().toLocaleTimeString()} · Ctrl-C to stop`);
+      await Bun.sleep(every);
+    }
+  },
+});
+
+const list = defineCommand({
+  meta: { name: "list", description: "Every run, newest first" },
+  args: { repo: { type: "string", description: "only the runs of the git repo at this path" }, ...json },
+  async run({ args }) {
+    const top = args.repo ? await gitToplevel(resolve(args.repo)) : null;
+    if (args.repo && !top)
+      throw new CatherdError("E_INPUT_INVALID", `${resolve(args.repo)} is not inside a git repository`, {
+        fix: "pass a path inside the repo, or leave out --repo",
+      });
+    const { runs, corrupt } = listRuns();
+    const rows = runs
+      .filter((r) => !args.repo || r.meta.repo === top)
+      .map((r) => {
+        const s = summarizeRun(defaultDeps(), r);
+        return {
+          id: r.id,
+          title: r.meta.title,
+          repo: r.meta.repo,
+          createdAt: r.meta.createdAt,
+          live: s.live.length,
+          roleRuns: s.totals.runs,
+        };
+      });
+    if (args.json) return printJson({ runs: rows, corrupt });
+    if (rows.length === 0) console.log("no runs yet");
+    for (const r of rows)
+      console.log(
+        `${r.id}  ${r.live ? `${r.live} live` : "idle"}  ${r.roleRuns} role run(s)  ${r.title}  ${r.repo}`,
+      );
+    for (const c of corrupt) console.log(`${mark("warn")} skipped run ${c.id}: ${c.reason}`);
+  },
+});
+
+const show = defineCommand({
+  meta: {
+    name: "show",
+    description: "One run and its role runs; --debug adds exit.json and the stderr and event tails",
+  },
+  args: {
+    id: { type: "positional", required: true, description: "run id" },
+    debug: {
+      type: "boolean",
+      description: "per dispatch: the record, exit.json, and the stderr, event and supervisor tails",
+    },
+    name: { type: "string", description: "with --debug: only this role name" },
+    ...json,
+  },
+  run({ args }) {
+    const run = findRun(args.id);
+    // every part redacted, not only the dispatches: state.md and a record's reply can quote a secret too;
+    // the saved Jev key is a secret even in a process that never called Jev
+    registerSavedSecrets();
+    const { summary, records } = redact({
+      summary: summarizeRun(defaultDeps(), run),
+      records: readRecords(run).records,
+    });
+    const debug = args.debug ? runDebug(run, args.name) : undefined;
+    if (args.json) return printJson({ summary, records, ...(debug ? { dispatches: debug } : {}) });
+    for (const l of formatRun(summary)) console.log(l);
+    for (const r of records)
+      console.log(
+        `  ${r.name}  ${r.rung}  ${r.status}${r.replyStatus ? `/${r.replyStatus}` : ""}  ${r.secs}s  ${n(r.tokens.input + r.tokens.output)} tokens`,
+      );
+    for (const d of debug ?? []) {
+      console.log(`\n--- ${d.name} ${d.dispatchId} (${d.rung}, admitted ${d.admittedAt})`);
+      console.log(`record: ${d.record ? JSON.stringify(d.record) : "none yet"}`);
+      console.log(`exit.json: ${d.exit ? JSON.stringify(d.exit) : "none yet"}`);
+      for (const [label, lines] of [
+        ["stderr", d.stderrTail],
+        ["events", d.eventsTail],
+        ["supervisor.log", d.supervisorTail],
+      ] as const) {
+        console.log(`${label} (last ${lines.length} lines):`);
+        for (const l of lines) console.log(`  ${l}`);
+      }
+    }
+  },
+});
+
+const cancelCmd = defineCommand({
+  meta: {
+    name: "cancel",
+    description: "Stop a live role (interrupt, SIGTERM, SIGKILL) and record it cancelled",
+  },
+  args: {
+    id: { type: "positional", required: true, description: "run id" },
+    name: { type: "positional", required: true, description: "the role's name, as status lists it" },
+  },
+  async run({ args }) {
+    const r = await cancel(defaultDeps(), args.id, args.name);
+    console.log(`${mark("ok")} ${r.record.name} ${r.record.status}`);
+    for (const h of r.hints) console.log(`  ${h}`);
+  },
+});
+
+/** Spec §8 `catherd runs list|show [--debug]|cancel`; a bare `catherd runs` lists them, as `status` needs no run. */
+export const runsCommand = defineCommand({
+  meta: { name: "runs", description: "Runs: list them (the default), show one, cancel a live role" },
+  subCommands: { list, show, cancel: cancelCmd },
+  default: "list",
+});

package/src/entry/supervise-bin.ts

@@ -0,0 +1,18 @@
+#!/usr/bin/env bun
+// The detached supervisor's entry: it imports only what supervising needs, never src/cli.ts and its TUI.
+import { errorMessage } from "../domain/errors.ts";
+import { runSupervise } from "./supervise-command.ts";
+
+const spec = process.argv[2];
+if (!spec) {
+  console.error("usage: supervise-bin.ts <spec.json>");
+  process.exit(2);
+}
+try {
+  await runSupervise(spec);
+} catch (e) {
+  console.error(`catherd supervisor: ${errorMessage(e)}`);
+  process.exit(1);
+}
+// exit.json is written: a hook's call the supervisor cut off (a hung `opencode api`) must not keep it alive.
+process.exit(0);

package/src/entry/supervise-command.ts

@@ -0,0 +1,37 @@
+import { defineCommand } from "citty";
+import { adapterFor } from "../adapters/registry.ts";
+import { workerEnv } from "../infra/env.ts";
+import { readVersioned } from "../infra/store.ts";
+import { SuperviseSpecSchema, supervise } from "../infra/supervisor.ts";
+import "../adapters/all.ts";
+
+/**
+ * Supervises the worker a spec file describes, with its backend's hooks, until exit.json is written.
+ * spec.json holds only the adapter's env overrides; the worker's env is built here, from this process's
+ * own inherited env (already without catherd's secrets), so no credential is ever on disk (spec §10.4).
+ */
+export async function runSupervise(specPath: string): Promise<void> {
+  const read = readVersioned(specPath, SuperviseSpecSchema, 1);
+  const spec = { ...read, env: workerEnv(process.env, read.env, read.cwd) };
+  const a = adapterFor(spec.backend);
+  const busy = a?.isBusy?.bind(a);
+  const stop = a?.interrupt?.bind(a);
+  await supervise(spec, {
+    onLine: (line) => {
+      const d = a?.parse(line) ?? {};
+      return { final: d.final, thread: d.thread, item: d.item };
+    },
+    isBusy: busy
+      ? (thread, sinceMs) => (thread ? busy(thread, spec.cwd, sinceMs) : Promise.resolve(false))
+      : undefined,
+    interrupt: stop ? (thread) => (thread ? stop(thread, spec.cwd) : Promise.resolve()) : undefined,
+  });
+}
+
+export const superviseCommand = defineCommand({
+  meta: { name: "_supervise", description: "internal: supervise one worker process", hidden: true },
+  args: { spec: { type: "positional", required: true } },
+  async run({ args }) {
+    await runSupervise(args.spec);
+  },
+});