@opsee/cli 0.11.9

package/src/commands/foreman-views.ts

@@ -0,0 +1,398 @@
+/**
+ * The three read-only views (OPS-280): `opsee foreman status`, `logs <task>` and `review
+ * [<initiativeId>]`. Read-only by design — every control the human has is in foreman-control.ts,
+ * and nothing here marks a row, stops a process or writes to the Run Record.
+ *
+ * Where each reads from follows ADR-0009's split. `status` and `logs` are about what is running on
+ * *this machine*, so they read the Process Table and the transcripts directory and never the
+ * backend: they answer while the network is down, and they answer for a daemon this process has no
+ * other channel to. `review` is about what *happened*, which Opsee owns, so it reads the Run
+ * Record and the Initiative's memory through the Tracker Adapter.
+ *
+ * "Within one tick of a change" is why nothing here caches: the Process Table is SQLite on disk
+ * that the Run writes as it goes, so each invocation opens it, reads it and is done. `--watch` is
+ * the same read on a timer, not a subscription.
+ *
+ * Everything these commands print goes through core/views.ts, which flattens and strips every
+ * string that came off a row, an Account, a Task or an event before it reaches the terminal; see
+ * that file's header for why a Task title and a Gate's name are as hostile as an assistant's
+ * output.
+ */
+import { existsSync, openSync, readdirSync, readSync, closeSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { StringDecoder } from "node:string_decoder";
+import type { AccountStore } from "../foreman/account-store.js";
+import { ForemanError } from "../foreman/core/run.js";
+import { formatReview, formatStatus, formatTranscriptLine, transcriptHeader, type NamedTask, type TranscriptTarget } from "../foreman/core/views.js";
+import type { TrackerAdapter } from "../foreman/tracker-adapter.js";
+import type { ForemanLocal } from "./foreman.js";
+
+/** How often `--watch` and a followed transcript re-read. Short enough to feel live, long enough
+ * that a terminal left open all night is not a busy loop on a SQLite file. */
+export const DEFAULT_WATCH_MS = 2_000;
+
+/** How many lines of a finished Worker's transcript are printed by default. */
+export const DEFAULT_TAIL_LINES = 200;
+
+/** How much of a transcript file is read to find its last `n` lines: enough for a long turn's tail,
+ * bounded so a multi-megabyte transcript is not pulled into memory to print a screenful. */
+const TAIL_BYTES = 512 * 1024;
+
+// --- status ---------------------------------------------------------------------------------
+
+export interface ForemanStatusDeps {
+  store: AccountStore;
+  local: ForemanLocal;
+  out: (line: string) => void;
+  now?: () => number;
+  sleep?: (ms: number) => Promise<void>;
+  /** Seam for the pid check behind `USED` and the `STATE` column; the real one by default. */
+  isAlive?: (pid: number | undefined) => boolean;
+  /** Called for a promise that resolves when a watch should stop (Ctrl-C, or a test's own signal).
+   * A function rather than a promise because the real one installs `SIGINT`/`SIGTERM` handlers,
+   * and installing those for a one-shot `status` that never awaits it turns Ctrl-C into a no-op on
+   * a command that should just die. It is called only on the path that actually waits. */
+  untilStop?: () => Promise<void>;
+}
+
+export interface ForemanStatusArgs {
+  /** Repaint every `watchMs` until stopped, rather than printing once. */
+  watch: boolean;
+  watchMs?: number;
+}
+
+/** One reading of the Process Table and the Accounts file. Both are re-read per call, never held:
+ * that is the whole of "reflects the Process Table within one tick of a change". */
+function statusOnce(deps: ForemanStatusDeps): string[] {
+  const { local } = deps;
+  return formatStatus({
+    accounts: deps.store.load(),
+    rows: local.table.liveWorkers(),
+    paused: local.table.pausedInitiatives(),
+    tablePath: local.table.path,
+    now: (deps.now ?? Date.now)(),
+    isAlive: deps.isAlive,
+  });
+}
+
+/** `opsee foreman status`: per-Account Slots, the live Workers and every Paused state. Exit 0
+ * whatever it finds — it reports, it does not judge. */
+export async function runForemanStatus(deps: ForemanStatusDeps, args: ForemanStatusArgs = { watch: false }): Promise<number> {
+  if (!args.watch) {
+    for (const line of statusOnce(deps)) deps.out(line);
+    return 0;
+  }
+  // Deliberately dumb: re-read and print the whole view again, with a rule and a timestamp between
+  // readings. No cursor addressing and no diffing, so the output is the same whether it goes to a
+  // terminal, a pipe or a file, and one repaint can never be left half-drawn.
+  const sleep = deps.sleep ?? ((ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms)));
+  const every = args.watchMs ?? DEFAULT_WATCH_MS;
+  let stopping = false;
+  // Only here: the one-shot above returned before this line, so it never armed a handler.
+  const untilStop = deps.untilStop?.();
+  void untilStop?.then(() => {
+    stopping = true;
+  });
+  while (!stopping) {
+    deps.out(`--- ${new Date((deps.now ?? Date.now)()).toISOString()} · every ${Math.round(every / 1000)}s · Ctrl-C to stop ---`);
+    for (const line of statusOnce(deps)) deps.out(line);
+    if (stopping) break;
+    await (untilStop ? Promise.race([sleep(every), untilStop]) : sleep(every));
+  }
+  return 0;
+}
+
+// --- logs -----------------------------------------------------------------------------------
+
+export interface ForemanLogsDeps {
+  local: ForemanLocal;
+  out: (line: string) => void;
+  /** Used only to turn a numeric Task id into its identifier when the Process Table has no row for
+   * it (a turn that is over). Absent, such a Task is refused with the identifier form to retry with. */
+  tracker?: TrackerAdapter;
+  sleep?: (ms: number) => Promise<void>;
+  /** Called only once the command has decided it is going to follow; see `ForemanStatusDeps`. */
+  untilStop?: () => Promise<void>;
+}
+
+export interface ForemanLogsArgs {
+  /** `OPS-280` or `1447`: whichever the human has in front of them. */
+  task: string;
+  /** Lines of the stored tail; also how much of the file is printed before a live follow starts. */
+  lines?: number;
+  /** Do not follow a running Worker; print what is there and return. */
+  noFollow?: boolean;
+  pollMs?: number;
+}
+
+/** `OPS-280-2.jsonl`, asked for as `ops-280` -> attempt 2, identifier `OPS-280`. The store names
+ * every file `<identifier>-<attempt>.jsonl` (core/transcripts.ts) and an identifier may itself
+ * contain a dash, so the attempt is the trailing run of digits and nothing else. Matched without
+ * regard to case, because a human types `ops-280` as readily as `OPS-280`, and the identifier as
+ * the file spells it is what comes back, so the header names the Task the way the Tracker does. */
+function transcriptOf(file: string, identifier: string): { identifier: string; attempt: number } | undefined {
+  const match = new RegExp(`^(${identifier.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")})-(\\d+)\\.jsonl$`, "i").exec(file);
+  return match ? { identifier: match[1], attempt: Number(match[2]) } : undefined;
+}
+
+/** Every transcript the store has for an identifier, newest attempt first. Scans the Initiative
+ * directories rather than asking for one, so a Task whose Initiative the caller does not know
+ * (which is every finished Worker: its row is gone) is still found. */
+function transcriptsFor(root: string, identifier: string): Array<{ path: string; identifier: string; initiativeId: number; attempt: number; mtimeMs: number }> {
+  if (!existsSync(root)) return [];
+  const found: Array<{ path: string; identifier: string; initiativeId: number; attempt: number; mtimeMs: number }> = [];
+  for (const dir of readdirSync(root, { withFileTypes: true })) {
+    if (!dir.isDirectory()) continue;
+    const initiativeId = Number(dir.name);
+    if (!Number.isInteger(initiativeId)) continue;
+    const dirPath = join(root, dir.name);
+    for (const file of readdirSync(dirPath)) {
+      const match = transcriptOf(file, identifier);
+      if (!match) continue;
+      const path = join(dirPath, file);
+      found.push({ path, identifier: match.identifier, initiativeId, attempt: match.attempt, mtimeMs: statSync(path).mtimeMs });
+    }
+  }
+  // Newest attempt first, and the newest file where two Initiatives somehow hold the same
+  // identifier: the turn the human just watched is the one they mean.
+  return found.sort((a, b) => b.attempt - a.attempt || b.mtimeMs - a.mtimeMs);
+}
+
+/** The Worker row for a Task reference, when one exists: by id for a number, by identifier
+ * otherwise (case-insensitively, since a human types `ops-280` as readily as `OPS-280`). */
+function rowFor(deps: ForemanLogsDeps, task: string) {
+  const rows = deps.local.table.liveWorkers();
+  if (/^\d+$/.test(task)) return deps.local.table.worker(Number(task));
+  const wanted = task.toLowerCase();
+  return rows.find((r) => r.identifier.toLowerCase() === wanted);
+}
+
+/** Which transcript `logs` is about, and whether its Worker is still writing to it.
+ *
+ * A running Worker has a row, and the row names its Initiative and attempt exactly. A finished one
+ * has none — the Run removes the row when the turn settles — so the file is found by identifier
+ * instead, which is why a bare numeric id for a finished Task has to be turned into an identifier
+ * through the Tracker first.
+ */
+export async function resolveTranscript(deps: ForemanLogsDeps, task: string): Promise<TranscriptTarget> {
+  const root = deps.local.transcripts.root;
+  const row = rowFor(deps, task);
+  if (row) {
+    const path = deps.local.transcripts.pathFor(row.initiativeId, row.identifier, row.attempt);
+    if (existsSync(path)) return { path, identifier: row.identifier, initiativeId: row.initiativeId, attempt: row.attempt, row };
+    // The row exists but nothing has been written yet: the dispatch is committed and the adapter
+    // has not produced its first event. Say that rather than "no such Task".
+    throw new ForemanError(
+      `Worker ${row.identifier} is on Task ${row.taskId} (Account ${row.account}, attempt ${row.attempt}) but has written nothing yet: ${path} does not exist. Its first output creates it; try again in a moment.`,
+    );
+  }
+
+  let identifier = task;
+  if (/^\d+$/.test(task)) {
+    if (!deps.tracker) {
+      throw new ForemanError(
+        `No Worker on Task ${task} in the Process Table ${deps.local.table.path}, and this command has no Tracker to look its identifier up with. Pass the Task's identifier instead: opsee foreman logs OPS-123`,
+      );
+    }
+    try {
+      identifier = (await deps.tracker.getTask(Number(task))).task.identifier;
+    } catch (error) {
+      throw new ForemanError(
+        `No Worker on Task ${task} in the Process Table ${deps.local.table.path}, and the Tracker could not say what its identifier is (${error instanceof Error ? error.message : String(error)}). Pass the identifier instead: opsee foreman logs OPS-123`,
+      );
+    }
+  }
+
+  const [newest] = transcriptsFor(root, identifier);
+  if (!newest) {
+    throw new ForemanError(
+      `Nothing to show for ${identifier}: the Process Table ${deps.local.table.path} has no Worker on it, and ${root} holds no transcript for it. A Task the Foreman has never dispatched on this machine has neither.`,
+    );
+  }
+  return { path: newest.path, identifier: newest.identifier, initiativeId: newest.initiativeId, attempt: newest.attempt };
+}
+
+/** The last `lines` lines of a file, and the byte offset the file was read to, so a follow can
+ * carry on from exactly there without reprinting what it just showed. */
+export function tailOf(path: string, lines: number): { lines: string[]; offset: number } {
+  const size = statSync(path).size;
+  const from = Math.max(0, size - TAIL_BYTES);
+  const fd = openSync(path, "r");
+  let text: string;
+  try {
+    const buffer = Buffer.alloc(size - from);
+    readSync(fd, buffer, 0, buffer.length, from);
+    text = buffer.toString("utf8");
+  } finally {
+    closeSync(fd);
+  }
+  // A read that started mid-file almost certainly started mid-line; that partial first line is
+  // dropped rather than printed as a broken event.
+  const all = (from > 0 ? text.slice(text.indexOf("\n") + 1) : text).split("\n").filter((l) => l.trim() !== "");
+  return { lines: all.slice(-lines), offset: size };
+}
+
+/**
+ * `opsee foreman logs <task>`: one Worker's stream.
+ *
+ * Live while the Worker is running — the file is polled from where the tail left off and each new
+ * line printed as it lands — and the stored tail once the turn is over. The header says which of
+ * the two it is, because past the first screenful they read identically.
+ */
+export async function runForemanLogs(deps: ForemanLogsDeps, args: ForemanLogsArgs): Promise<number> {
+  const target = await resolveTranscript(deps, args.task);
+  const tail = args.lines ?? DEFAULT_TAIL_LINES;
+  const live = target.row !== undefined && !args.noFollow;
+  for (const line of transcriptHeader(target, { live, tail })) deps.out(line);
+
+  const start = tailOf(target.path, tail);
+  for (const raw of start.lines) for (const line of formatTranscriptLine(raw)) deps.out(line);
+  if (!live) return 0;
+
+  const sleep = deps.sleep ?? ((ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms)));
+  const every = args.pollMs ?? DEFAULT_WATCH_MS;
+  let stopping = false;
+  // Only on the following path: a `--no-follow` or a finished Worker returned above without ever
+  // asking for this, so neither arms a SIGINT handler it would not then wait on.
+  const untilStop = deps.untilStop?.();
+  void untilStop?.then(() => {
+    stopping = true;
+  });
+  let offset = start.offset;
+  let carry = "";
+  // Bytes, not characters: a read that ends mid-codepoint would become a replacement character if
+  // each chunk were decoded on its own, and `carry` only preserves a partial *line*. The decoder
+  // holds the partial bytes back until the rest of the sequence arrives on a later poll.
+  const decoder = new StringDecoder("utf8");
+  while (!stopping) {
+    await (untilStop ? Promise.race([sleep(every), untilStop]) : sleep(every));
+    if (stopping) break;
+    // The row going away is the turn settling: read whatever was appended in the meantime, then
+    // stop, so a follow never misses the Completion Report it was waiting for. A row that is still
+    // there but on a *later attempt* is not this turn: the Run removes the row when a turn settles
+    // and the next dispatch upserts a new one for the same Task, and at a 2s poll the gap between
+    // the two is usually missed entirely. Comparing the task id alone would have the follow decide
+    // attempt 2 was still running and go on tailing attempt 1's file, which nothing will ever
+    // append to again, under a header still saying it is streaming.
+    const current = deps.local.table.worker(target.row!.taskId);
+    const sameTurn = current !== undefined && current.attempt === target.attempt && current.identifier === target.identifier;
+    if (existsSync(target.path)) {
+      const size = statSync(target.path).size;
+      // Truncated or replaced under us (a rotation, a Worker rewriting its own file): the offset is
+      // past the end and every later poll would read nothing while the header still claims a live
+      // stream. Start again from the top rather than going quietly silent.
+      if (size < offset) {
+        deps.out("");
+        deps.out(`${target.path} is shorter than it was: it has been truncated or replaced, so the follow starts again from the beginning of the file.`);
+        offset = 0;
+        carry = "";
+      }
+      if (size > offset) {
+        // Bounded per poll. A Worker that dumps a large chunk between two polls would otherwise be
+        // allocated whole; the remainder is picked up by the next poll, which is 2s away.
+        const to = Math.min(size, offset + TAIL_BYTES);
+        const fd = openSync(target.path, "r");
+        try {
+          const buffer = Buffer.alloc(to - offset);
+          const read = readSync(fd, buffer, 0, buffer.length, offset);
+          carry += decoder.write(buffer.subarray(0, read));
+          offset += read;
+        } finally {
+          closeSync(fd);
+        }
+        const parts = carry.split("\n");
+        // The last piece has no newline yet: an append still in flight, kept for the next poll.
+        carry = parts.pop() ?? "";
+        for (const raw of parts) for (const line of formatTranscriptLine(raw)) deps.out(line);
+      }
+    }
+    if (!sameTurn) {
+      deps.out("");
+      if (current) {
+        deps.out(
+          `The Worker on ${target.identifier} is now on attempt ${current.attempt}: this turn settled and the Run dispatched again. This file is attempt ${target.attempt} and nothing more will be appended to it; follow the new one with: opsee foreman logs ${target.identifier}`,
+        );
+      } else {
+        deps.out(`The Worker on ${target.identifier} is gone from the Process Table: its turn settled. What the Run made of it is on the Task and the Run Record (opsee foreman review).`);
+      }
+      break;
+    }
+  }
+  return 0;
+}
+
+// --- review ---------------------------------------------------------------------------------
+
+export interface ForemanReviewDeps {
+  tracker: TrackerAdapter;
+  local: ForemanLocal;
+  out: (line: string) => void;
+}
+
+export interface ForemanReviewArgs {
+  /** Omitted when this machine has exactly one Initiative to be about. */
+  initiativeId?: number;
+}
+
+/** The Initiative `review` is about: the one asked for, or the only one this machine has a Worker
+ * row or a Run request for. Several, and it asks rather than guessing which night is meant. */
+export function chooseInitiative(local: ForemanLocal, asked: number | undefined): number {
+  if (asked !== undefined) return asked;
+  const known = local.table.knownInitiatives();
+  if (known.length === 1) return known[0];
+  if (known.length === 0) {
+    throw new ForemanError("Which Initiative? This machine's Process Table has no Worker and no Run request to name one: opsee foreman review <initiativeId>");
+  }
+  throw new ForemanError(`Which Initiative? This machine has Runs on ${known.join(", ")}: opsee foreman review <initiativeId>`);
+}
+
+/**
+ * `opsee foreman review [<initiativeId>]`: the morning summary of a Run.
+ *
+ * Three reads, all of them the backend's: the Run Record for what the night did, the Initiative
+ * context for the Tasks (so every id in the output is a title a human recognises), and the memory
+ * log for the Proposed Learnings, which live there rather than on the Run Record because they come
+ * out of Completion Reports (core/learnings.ts).
+ *
+ * The Initiative context is the one read that may fail on its own — an Initiative the Tracker does
+ * not know, a backend that refuses it — and it is not what the Run Record is about, so a failure
+ * there leaves the Run's own facts on screen with the Tasks named by id and says why.
+ */
+export async function runForemanReview(deps: ForemanReviewDeps, args: ForemanReviewArgs = {}): Promise<number> {
+  const initiativeId = chooseInitiative(deps.local, args.initiativeId);
+  const record = await deps.tracker.readRunRecord(initiativeId);
+
+  const tasks = new Map<number, NamedTask>();
+  let initiative: { title: string; status: string } | undefined;
+  let contextError: string | undefined;
+  let learnings: Array<{ body: string; sourceTaskId?: number; isAgent: boolean }> = [];
+  let learningsError: string | undefined;
+  try {
+    const context = await deps.tracker.getInitiativeContext(initiativeId);
+    initiative = { title: context.initiative.title, status: context.initiative.status };
+    for (const t of context.tasks) tasks.set(t.id, t);
+    // The context read has already walked the whole memory log — `getInitiativeContext` pages it
+    // through `listMemory` itself rather than taking the windowed copy off the response — and the
+    // Proposed Learnings are in what came back. Asking for them again would page a long-lived
+    // Initiative's log a second time for a list this already holds.
+    learnings = context.memory.filter((m) => m.kind === "learning" && !m.isSystem);
+  } catch (error) {
+    contextError = error instanceof Error ? error.message : String(error);
+    // The context read is the only one that may fail on its own, and it is not what the Run Record
+    // is about. Its Learnings go with it, so they are fetched on their own here: a Tracker that
+    // will not describe the Initiative may still serve its memory log.
+    try {
+      learnings = (await deps.tracker.listMemory(initiativeId, { kinds: ["learning"] })).filter((l) => !l.isSystem);
+    } catch (memoryError) {
+      learningsError = memoryError instanceof Error ? memoryError.message : String(memoryError);
+    }
+  }
+
+  // `tasksUnavailable` rather than an empty map doing the talking: the Blocked section is read off
+  // the Status Label, which lives on the Task, so a task list that could not be read is "not known"
+  // and never "nothing is blocked".
+  for (const line of formatReview({ initiativeId, initiative, run: record.run, events: record.events, tasks, learnings, tasksUnavailable: contextError !== undefined })) deps.out(line);
+  if (contextError) deps.out(`\nTasks are named by id above: the Initiative's task list could not be read (${contextError}).`);
+  if (learningsError) deps.out(`\nProposed Learnings could not be read (${learningsError}); the Run Record's own sections above are unaffected.`);
+  return 0;
+}