catherd-cli 1.4.0 → 2.0.0-beta.20261022113309

package/src/services/run-events-store.ts

@@ -0,0 +1,174 @@
+import { closeSync, existsSync, fstatSync, ftruncateSync, openSync, readFileSync, readSync } from "node:fs";
+import { join } from "node:path";
+import { CatherdError, UPGRADE } from "../domain/errors.ts";
+import { EVENTS_SCHEMA, RunEventSchema, type RunEvent, type RunEventInput } from "../domain/run-events.ts";
+import { type RunState, replay } from "../domain/run-state.ts";
+import { withFileLock } from "../infra/filelock.ts";
+import { log } from "../infra/log.ts";
+import { appendJsonlBatch } from "../infra/store.ts";
+import type { Run } from "./run-store.ts";
+
+/** `<run>/events.jsonl`: one fact per line, dense `seq`, the only state a 2.0 run keeps. */
+export const eventsFile = (run: Run): string => join(run.dir, "events.jsonl");
+
+/** A 2.0 run has an events.jsonl; a run without one is a 1.5 run, and the daemon never drives it. */
+export const isDaemonRun = (run: Run): boolean => existsSync(eventsFile(run));
+
+const corrupt = (run: Run, after: number, why: string): CatherdError =>
+  new CatherdError("E_RUN_CORRUPT", `${eventsFile(run)} is corrupt after seq ${after}: ${why}`, {
+    fix: `restore events.jsonl from a backup, or finish run ${run.id} with catherd 1.x`,
+  });
+
+const tooOld = (run: Run, v: unknown): CatherdError =>
+  new CatherdError(
+    "E_RUNTIME_TOO_OLD",
+    `${eventsFile(run)} holds events of version ${String(v)}, newer than this catherd (${EVENTS_SCHEMA})`,
+    { fix: `upgrade catherd: ${UPGRADE}` },
+  );
+
+/** One line as an event: a newer `v` is too old a catherd, anything else invalid is corrupt (null here). */
+function decode(run: Run, line: string): RunEvent | null {
+  let raw: unknown;
+  try {
+    raw = JSON.parse(line);
+  } catch {
+    return null;
+  }
+  const v = (raw as { v?: unknown } | null)?.v;
+  if (typeof v === "number" && v > EVENTS_SCHEMA) throw tooOld(run, v);
+  const r = RunEventSchema.safeParse(raw);
+  return r.success ? r.data : null;
+}
+
+/**
+ * The run's events from `fromSeq` (1 reads them all and checks every line). A last line without its newline
+ * that does not parse is a torn append: skipped and logged. Any other line that does not parse, or a seq that
+ * is not the line's number, refuses the read (E_RUN_CORRUPT, naming the seq before it); a newer `v`, too.
+ * Lines before `fromSeq` are skipped unread: the caller replayed them already.
+ */
+export function readEvents(run: Run, fromSeq = 1): RunEvent[] {
+  let text: string;
+  try {
+    text = readFileSync(eventsFile(run), "utf8");
+  } catch {
+    return [];
+  }
+  const lines = text.split("\n");
+  const tail = lines.pop() ?? "";
+  if (tail) lines.push(tail);
+  const out: RunEvent[] = [];
+  for (const [i, line] of lines.entries()) {
+    if (i + 1 < fromSeq || !line.trim()) continue;
+    const e = decode(run, line);
+    if (e === null) {
+      if (i === lines.length - 1 && line === tail) {
+        log("warn", "events", { run: run.id, torn: i + 1 });
+        break;
+      }
+      throw corrupt(run, i, "a line is not an event");
+    }
+    if (e.seq !== i + 1) throw corrupt(run, i, `seq ${e.seq} stands where ${i + 1} belongs`);
+    out.push(e);
+  }
+  return out;
+}
+
+export const replayRun = (run: Run): RunState => replay(readEvents(run), run.id);
+
+/** The last seq of the file; a torn tail is cut off first, so the next line starts clean. Under the file's lock. */
+function lastSeq(run: Run): number {
+  const file = eventsFile(run);
+  if (!existsSync(file)) return 0;
+  const fd = openSync(file, "r+");
+  try {
+    const size = fstatSync(fd).size;
+    let chunk = 64 * 1024;
+    for (;;) {
+      const start = Math.max(0, size - chunk);
+      const buf = Buffer.alloc(size - start);
+      readSync(fd, buf, 0, buf.length, start);
+      const text = buf.toString("utf8");
+      const cut = text.lastIndexOf("\n");
+      const tail = text.slice(cut + 1);
+      const body = text.slice(0, cut + 1).trimEnd();
+      // the whole last complete line is in the chunk, or the chunk is the whole file
+      if (start > 0 && !body.includes("\n")) {
+        chunk *= 4;
+        continue;
+      }
+      if (tail && decode(run, tail) === null) {
+        // a torn append: not an event, never will be one
+        ftruncateSync(fd, size - Buffer.byteLength(tail));
+        log("warn", "events", { run: run.id, tornTail: Buffer.byteLength(tail) });
+      }
+      const line = tail && decode(run, tail) !== null ? tail : body.slice(body.lastIndexOf("\n") + 1);
+      if (!line) return 0;
+      const last = decode(run, line);
+      if (!last) throw corrupt(run, 0, "its last line is not an event");
+      return last.seq;
+    }
+  } finally {
+    closeSync(fd);
+  }
+}
+
+/** Runs `fn` under the events file's lock, handing it an append that does not take the lock again. */
+export function withEventsLock<T>(
+  run: Run,
+  fn: (add: (e: RunEventInput, now?: Date) => RunEvent) => T | Promise<T>,
+): Promise<T> {
+  return withFileLock(eventsFile(run), () => fn((e, now) => writeEvents(run, [e], now)[0] as RunEvent));
+}
+
+/** The events with the next dense seqs, validated all before the one write that appends them. */
+function writeEvents(run: Run, es: RunEventInput[], now: Date = new Date()): RunEvent[] {
+  const first = lastSeq(run) + 1;
+  const out = es.map((e, i) =>
+    RunEventSchema.parse({ v: EVENTS_SCHEMA, seq: first + i, at: now.toISOString(), ...e }),
+  );
+  appendJsonlBatch(eventsFile(run), out);
+  return out;
+}
+
+/** Appends one event under the file's lock, with the next dense `seq`, and returns it as written. */
+export async function appendEvent(run: Run, e: RunEventInput, now: Date = new Date()): Promise<RunEvent> {
+  return withEventsLock(run, (add) => add(e, now));
+}
+
+/** Appends events that belong together in one write under the file's lock: all of them or, on a crash, a torn tail. */
+export function appendEvents(run: Run, es: RunEventInput[], now: Date = new Date()): Promise<RunEvent[]> {
+  return withFileLock(eventsFile(run), () => writeEvents(run, es, now));
+}
+
+/**
+ * Calls `onEvent` with each event after `fromSeq - 1`, in order, as they are appended, until the returned stop
+ * is called. A poll that finds the file unreadable waits for the next one.
+ */
+export function tailEvents(
+  run: Run,
+  fromSeq: number,
+  onEvent: (e: RunEvent) => void,
+  o: { pollMs?: number } = {},
+): () => void {
+  let next = fromSeq;
+  let stopped = false;
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  const poll = (): void => {
+    if (stopped) return;
+    try {
+      for (const e of readEvents(run, next)) {
+        if (stopped) return;
+        next = e.seq + 1;
+        onEvent(e);
+      }
+    } catch (err) {
+      log("warn", "events", { run: run.id, tail: err instanceof Error ? err.message : String(err) });
+    }
+    if (!stopped) timer = setTimeout(poll, o.pollMs ?? 500);
+  };
+  poll();
+  return () => {
+    stopped = true;
+    if (timer) clearTimeout(timer);
+  };
+}

package/src/services/run-evidence.ts

@@ -17,7 +17,7 @@ export interface Evidence {
   fails: number;
 }
 
-/** `<canonical rung>|<kind or *>` → its evidence. Shown by route, catalog list and the TUI; never routes. */
+/** `<canonical rung>|<kind or *>` → its evidence. Shown by route and catalog list; never routes. */
 export type EvidenceTable = Record<string, Evidence>;
 
 const VERDICT_FAIL = /^VERDICT: FAIL\b/;

package/src/services/run-pin.ts

@@ -0,0 +1,125 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { z } from "zod";
+import { errorMessage } from "../domain/errors.ts";
+import { ACCESS } from "../domain/record.ts";
+import { ROLES } from "../domain/roles.ts";
+import { readVersioned, writeJsonAtomic } from "../infra/store.ts";
+import type { Deps, ProfileView } from "./ports.ts";
+import { findRun, type Run } from "./run-store.ts";
+import { refreshState } from "./state.ts";
+
+// Spec 1.5 "Pinned per run": run_start records the profile the run started on, each role's access and each
+// backend's isolation. A later change (another active profile, a toggled isolation, a version that changed a
+// default) is logged in state.md and status, and dispatch keeps the pinned values until the owner re-pins.
+
+const PinSchema = z.looseObject({
+  schema: z.literal(1),
+  at: z.string(),
+  profile: z.string(),
+  access: z.partialRecord(z.enum(ROLES), z.enum(ACCESS)),
+  isolated: z.record(z.string(), z.boolean()),
+});
+export type Pin = z.infer<typeof PinSchema>;
+
+export const pinFile = (run: Run): string => join(run.dir, "pin.json");
+
+/** The run's pin, or null: a run from before 1.5, or a pin that cannot be read (the profile then rules). */
+export function readPin(run: Run): Pin | null {
+  if (!existsSync(pinFile(run))) return null;
+  try {
+    return readVersioned(pinFile(run), PinSchema, 1);
+  } catch {
+    return null;
+  }
+}
+
+const pinOf = (view: ProfileView, at: string): Pin => ({
+  schema: 1,
+  at,
+  profile: view.name,
+  access: Object.fromEntries(
+    Object.entries(view.roles).flatMap(([role, rc]) => (rc ? [[role, rc.access]] : [])),
+  ),
+  isolated: Object.fromEntries(Object.entries(view.isolated).map(([k, v]) => [k, v === true])),
+});
+
+/** Records what the run runs on now: the profile its repo runs on, each role's access, each backend's isolation. */
+export function writePin(deps: Deps, run: Run): Pin {
+  const pin = pinOf(deps.profiles.forRepo(run.meta.repo), new Date(deps.now()).toISOString());
+  writeJsonAtomic(pinFile(run), pin);
+  return pin;
+}
+
+/** The pinned profile's view, or null with why when it can no longer be read (deleted, invalid). */
+function pinnedView(deps: Deps, run: Run, pin: Pin): { view: ProfileView | null; why: string | null } {
+  const current = deps.profiles.forRepo(run.meta.repo);
+  if (current.name === pin.profile) return { view: current, why: null };
+  try {
+    return { view: deps.profiles.get(pin.profile, run.meta.repo).profile, why: null };
+  } catch (e) {
+    return { view: null, why: errorMessage(e) };
+  }
+}
+
+/**
+ * The profile a run's dispatch, routing and failover read: its pinned profile, with its pinned access and
+ * isolation laid over it. A run with no pin, or whose pinned profile is gone, reads its repo's profile.
+ */
+export function runProfile(deps: Deps, run: Run): ProfileView {
+  const pin = readPin(run);
+  if (!pin) return deps.profiles.forRepo(run.meta.repo);
+  const view = pinnedView(deps, run, pin).view ?? deps.profiles.forRepo(run.meta.repo);
+  const roles: ProfileView["roles"] = {};
+  for (const [role, rc] of Object.entries(view.roles) as [
+    keyof ProfileView["roles"],
+    NonNullable<ProfileView["roles"][keyof ProfileView["roles"]]>,
+  ][])
+    roles[role] = { ...rc, access: pin.access[role] ?? rc.access };
+  // a backend the pin does not name ran with no isolation when the run started
+  const backends = new Set([...Object.keys(view.isolated), ...Object.keys(pin.isolated)]);
+  const isolated = Object.fromEntries([...backends].map((k) => [k, pin.isolated[k] === true]));
+  return { ...view, roles, isolated };
+}
+
+/** What changed since the pin, one line each, in words; none while the run's repo still runs as pinned. */
+export function pinChanges(deps: Deps, run: Run): string[] {
+  const pin = readPin(run);
+  if (!pin) return [];
+  let now: ProfileView;
+  try {
+    now = deps.profiles.forRepo(run.meta.repo);
+  } catch {
+    // a profile that cannot be read is doctor's and profile validate's to report, not a pin change
+    return [];
+  }
+  const out: string[] = [];
+  if (now.name !== pin.profile) {
+    const { why } = pinnedView(deps, run, pin);
+    out.push(
+      `profile: pinned ${pin.profile}, the repo now runs on ${now.name}${why ? ` (${pin.profile} cannot be read: ${why}; dispatch reads ${now.name})` : ""}`,
+    );
+  }
+  for (const [role, access] of Object.entries(pin.access)) {
+    const was = now.roles[role as keyof ProfileView["roles"]]?.access;
+    if (was !== undefined && was !== access) out.push(`${role} access: pinned ${access}, now ${was}`);
+  }
+  for (const backend of new Set([...Object.keys(pin.isolated), ...Object.keys(now.isolated)])) {
+    const isolated = pin.isolated[backend] === true;
+    const was = now.isolated[backend] === true;
+    if (was !== isolated) out.push(`${backend} isolated: pinned ${isolated}, now ${was}`);
+  }
+  return out;
+}
+
+/** `run_pin`: the owner re-pins the run to what its repo runs on now. Returns the new pin and what it changed. */
+export async function repin(
+  deps: Deps,
+  i: { run: string },
+): Promise<{ pin: Pin; changed: string[]; hints?: string[] }> {
+  const run = findRun(i.run);
+  const changed = pinChanges(deps, run);
+  const pin = writePin(deps, run);
+  const { hints } = await refreshState(run, { pinChanges: [] });
+  return { pin, changed, ...(hints.length ? { hints } : {}) };
+}

package/src/services/run-read.ts

@@ -0,0 +1,221 @@
+import { z } from "zod";
+import { errorMessage } from "../domain/errors.ts";
+import { PARK_REASONS, describeEvent } from "../domain/run-events.ts";
+import { type RunState, liveDispatches } from "../domain/run-state.ts";
+import { log } from "../infra/log.ts";
+import { daemonAlive, ensureDaemon, readHeartbeat } from "./daemon.ts";
+import { liveDispatches as liveDispatchesOf } from "./dispatches.ts";
+import { landedMilestones } from "./milestones.ts";
+import type { Deps } from "./ports.ts";
+import { openQuestions } from "./questions.ts";
+import { isDaemonRun, readEvents, replayRun, tailEvents } from "./run-events-store.ts";
+import { findRun, listRuns, type Run } from "./run-store.ts";
+
+/**
+ * The read side of a run, for the panel (plan 31) and the session's `status`: each shape has a zod
+ * schema, which is its contract. A 1.5 run reads as `engine: "1.5"`, with what its folder says.
+ */
+export const ParkedViewSchema = z.object({
+  run: z.string(),
+  runTitle: z.string(),
+  unit: z.string(),
+  question: z.string(),
+  reason: z.enum(PARK_REASONS),
+  at: z.string(),
+  /** the command that answers it */
+  command: z.string(),
+});
+export type ParkedView = z.infer<typeof ParkedViewSchema>;
+
+export const TimelineEntrySchema = z.object({
+  seq: z.number().int(),
+  at: z.string(),
+  type: z.string(),
+  text: z.string(),
+});
+export type TimelineEntry = z.infer<typeof TimelineEntrySchema>;
+
+export const RunViewSchema = z.object({
+  id: z.string(),
+  title: z.string(),
+  repo: z.string(),
+  engine: z.enum(["2.0", "1.5"]),
+  phase: z.enum(["planning", "approval", "running", "ended"]).nullable(),
+  outcome: z.enum(["done", "cancelled", "failed"]).nullable(),
+  daemon: z.object({
+    alive: z.boolean(),
+    pid: z.number().int().nullable(),
+    beatAgeSec: z.number().nullable(),
+  }),
+  milestones: z.array(
+    z.object({
+      id: z.string(),
+      title: z.string(),
+      status: z.string(),
+      round: z.number().int(),
+      commit: z.string().nullable(),
+    }),
+  ),
+  live: z.array(
+    z.object({ name: z.string(), role: z.string(), rung: z.string(), unit: z.string(), since: z.string() }),
+  ),
+  parked: z.array(ParkedViewSchema),
+  holds: z.array(z.object({ quota: z.string(), until: z.string() })),
+  /** the latest event, in one line */
+  last: z.string().nullable(),
+  startedAt: z.string(),
+  updatedAt: z.string(),
+});
+export type RunView = z.infer<typeof RunViewSchema>;
+
+export { tailEvents };
+
+const answerCommand = (run: string, unit: string): string => `catherd answer ${run} ${unit} "<answer>"`;
+
+function parkedOf(run: Run, s: RunState): ParkedView[] {
+  return Object.values(s.questions).map((q) => ({
+    run: run.id,
+    runTitle: run.meta.title,
+    unit: q.unit,
+    question: q.question,
+    reason: q.reason,
+    at: q.at,
+    command: answerCommand(run.id, q.unit),
+  }));
+}
+
+/** A daemon of an unfinished 2.0 run is started again when it is dead; a failure to start never fails a read. */
+function revive(run: Run): void {
+  try {
+    ensureDaemon(run);
+  } catch (e) {
+    log("warn", "daemon", { run: run.id, revive: errorMessage(e) });
+  }
+}
+
+function view15(deps: Deps, run: Run): RunView {
+  const now = deps.now();
+  return {
+    id: run.id,
+    title: run.meta.title,
+    repo: run.meta.repo,
+    engine: "1.5",
+    phase: null,
+    outcome: null,
+    daemon: { alive: false, pid: null, beatAgeSec: null },
+    milestones: landedMilestones(run).map((id) => ({
+      id,
+      title: id,
+      status: "landed",
+      round: 0,
+      commit: null,
+    })),
+    live: liveDispatchesOf(run, now).map((d) => ({
+      name: d.admit.name,
+      role: d.admit.role,
+      rung: d.admit.rung,
+      unit: d.admit.lane ?? d.admit.name,
+      since: d.admit.admittedAt,
+    })),
+    parked: openQuestions(run).map((q) => ({
+      run: run.id,
+      runTitle: run.meta.title,
+      unit: q.milestone,
+      question: q.question,
+      reason: "needs_user" as const,
+      at: q.at,
+      command: `answer(run: "${run.id}", milestone: "${q.milestone}", answer: "<answer>")`,
+    })),
+    holds: [],
+    last: null,
+    startedAt: run.meta.createdAt,
+    updatedAt: run.meta.createdAt,
+  };
+}
+
+/** One run at a glance. Reading an unfinished 2.0 run starts its daemon again if it died. */
+export function runView(deps: Deps, runId: string): RunView {
+  const run = findRun(runId);
+  if (!isDaemonRun(run)) return view15(deps, run);
+  revive(run);
+  const s = replayRun(run);
+  const beat = readHeartbeat(run);
+  const events = readEvents(run);
+  const last = events.at(-1);
+  return {
+    id: run.id,
+    title: run.meta.title,
+    repo: run.meta.repo,
+    engine: "2.0",
+    phase: s.phase,
+    outcome: s.outcome,
+    daemon: {
+      alive: daemonAlive(run),
+      pid: beat?.pid ?? null,
+      beatAgeSec: beat ? Math.max(0, Math.round((deps.now() - Date.parse(beat.beatAt)) / 1000)) : null,
+    },
+    milestones: s.milestones.map((m) => ({
+      id: m.id,
+      title: m.title,
+      status: m.status,
+      round: m.round,
+      commit: m.commit,
+    })),
+    live: liveDispatches(s).map((d) => ({
+      name: d.name,
+      role: d.role,
+      rung: d.rung,
+      unit: d.unit,
+      since: d.startedAt,
+    })),
+    parked: parkedOf(run, s),
+    holds: Object.entries(s.holds).map(([quota, until]) => ({ quota, until })),
+    last: last ? describeEvent(last, (id) => s.dispatches[id]?.rung) : null,
+    startedAt: run.meta.createdAt,
+    updatedAt: last?.at ?? run.meta.createdAt,
+  };
+}
+
+/** Every run, newest first (one repo's with `repo`), at most `limit` (default 50). */
+export function listRunViews(deps: Deps, o: { repo?: string; limit?: number } = {}): RunView[] {
+  const runs = listRuns(o.repo ? [o.repo] : undefined).runs.slice(0, o.limit ?? 50);
+  const out: RunView[] = [];
+  for (const r of runs) {
+    try {
+      out.push(runView(deps, r.id));
+    } catch (e) {
+      log("warn", "read", { run: r.id, error: errorMessage(e) });
+    }
+  }
+  return out;
+}
+
+/** The run's events from `fromSeq`, one line each (never a reply's body), at most `limit` (default 200). */
+export function runTimeline(runId: string, fromSeq = 1, limit = 200): TimelineEntry[] {
+  const run = findRun(runId);
+  if (!isDaemonRun(run)) return [];
+  const s = replayRun(run);
+  return readEvents(run, fromSeq)
+    .slice(0, limit)
+    .map((e) => ({
+      seq: e.seq,
+      at: e.at,
+      type: e.type,
+      text: describeEvent(e, (id) => s.dispatches[id]?.rung),
+    }));
+}
+
+/** Every unfinished 2.0 run's open questions (one run's with `run`), each with the command that answers it. */
+export function parkedQuestions(o: { run?: string } = {}): ParkedView[] {
+  const runs = o.run ? [findRun(o.run)] : listRuns().runs;
+  return runs.flatMap((run) => {
+    try {
+      if (!isDaemonRun(run)) return [];
+      const s = replayRun(run);
+      return s.phase === "ended" ? [] : parkedOf(run, s);
+    } catch (e) {
+      log("warn", "read", { run: run.id, error: errorMessage(e) });
+      return [];
+    }
+  });
+}