@intentius/chant 0.124.26 → 0.124.28

package/src/run-event-store.ts

@@ -0,0 +1,213 @@
+/**
+ * Where a run's events are kept on this host, and how to read them back
+ * (#4042). `chant run events <run>` replays a run from here and `--follow`
+ * tails it.
+ *
+ * Each run gets one file, `<git-common-dir>/chant/run-events/<run id>.jsonl`,
+ * holding the lines the one writer (`./run-event.ts`) produced, byte for byte
+ * as `--events-json` prints them. It sits beside the in-flight records
+ * (`./op/run-live.ts`), outside the working tree and off `chant/lifecycle`:
+ * the run ledger's growth is #4036's concern and these files add none to it.
+ * Unlike the in-flight record they are kept after the run settles. They are
+ * never pruned here; retention is #4036's.
+ *
+ * Every write is best-effort. A run whose events cannot be kept still runs.
+ */
+
+import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { gitCommonDir } from "./op/run-live";
+import type { RunEvent } from "./run-event";
+
+/** The directory name under `<git-common-dir>/chant/` that holds the files. */
+export const RUN_EVENTS_DIR = "run-events";
+
+/** The file name a run id is kept under: anything that is not a plain file-name character becomes `_`. */
+export function runEventFileName(runId: string): string {
+  return `${runId.replace(/[^A-Za-z0-9._@-]/g, "_")}.jsonl`;
+}
+
+/**
+ * The environment variable that names the directory run events are kept in,
+ * in place of the checkout's. The test suite sets it to a per-run temp
+ * directory, so no test writes to the real repository's store (worktrees
+ * share one git directory).
+ */
+export const RUN_EVENTS_DIR_ENV = "CHANT_RUN_EVENTS_DIR";
+
+/** The directory the checkout at `cwd` keeps run events in (`CHANT_RUN_EVENTS_DIR` when set), or null outside a checkout. */
+export async function runEventsDir(cwd: string): Promise<string | null> {
+  const override = process.env[RUN_EVENTS_DIR_ENV];
+  if (override) return override;
+  const common = await gitCommonDir(cwd);
+  return common ? join(common, "chant", RUN_EVENTS_DIR) : null;
+}
+
+/** An open file a run's lines are appended to. */
+export interface RunEventStore {
+  readonly path: string;
+  /** Append one line (it already ends with a newline). Never throws. */
+  write(line: string): void;
+}
+
+/** Open the file for `runId`, or undefined outside a checkout or where it cannot be created. */
+export async function openRunEventStore(cwd: string, runId: string): Promise<RunEventStore | undefined> {
+  let dir: string | null;
+  try {
+    dir = await runEventsDir(cwd);
+  } catch {
+    return undefined;
+  }
+  if (!dir) return undefined;
+  const path = join(dir, runEventFileName(runId));
+  try {
+    mkdirSync(dir, { recursive: true });
+    // A run id used again (a re-run of the same CI run) replaces the earlier stream.
+    writeFileSync(path, "");
+  } catch {
+    return undefined;
+  }
+  return {
+    path,
+    write(line) {
+      try {
+        appendFileSync(path, line);
+      } catch {
+        // The directory is gone or unwritable: the line is dropped.
+      }
+    },
+  };
+}
+
+/** A write function that hands each line to every function given, or undefined when none is. */
+export function teeLines(...writes: Array<((line: string) => void) | undefined>): ((line: string) => void) | undefined {
+  const live = writes.filter((w): w is (line: string) => void => w !== undefined);
+  if (live.length === 0) return undefined;
+  if (live.length === 1) return live[0];
+  return (line) => {
+    for (const w of live) w(line);
+  };
+}
+
+/** The events in `text`, one per whole line. Returns what is left of an unfinished last line. */
+export function parseRunEventLines(text: string): { events: RunEvent[]; rest: string } {
+  const events: RunEvent[] = [];
+  const parts = text.split("\n");
+  const rest = parts.pop() ?? "";
+  for (const part of parts) {
+    if (part.trim() === "") continue;
+    try {
+      events.push(JSON.parse(part) as RunEvent);
+    } catch {
+      // A line that is not JSON is not an event: skipped.
+    }
+  }
+  return { events, rest };
+}
+
+/** A stored run, as far as its first line says. */
+export interface StoredRun {
+  runId: string;
+  name: string;
+  file: string;
+  /** The file's last write, in ms. */
+  mtimeMs: number;
+}
+
+/** The runs stored for the checkout at `cwd`, newest first. */
+export async function listStoredRuns(cwd: string): Promise<StoredRun[]> {
+  const dir = await runEventsDir(cwd);
+  if (!dir || !existsSync(dir)) return [];
+  const runs: StoredRun[] = [];
+  for (const entry of readdirSync(dir)) {
+    if (!entry.endsWith(".jsonl")) continue;
+    const file = join(dir, entry);
+    try {
+      const first = readFileSync(file, "utf8").split("\n", 1)[0] ?? "";
+      if (first === "") continue;
+      const head = JSON.parse(first) as Partial<RunEvent>;
+      if (typeof head.runId !== "string") continue;
+      runs.push({ runId: head.runId, name: String(head.name ?? ""), file, mtimeMs: statSync(file).mtimeMs });
+    } catch {
+      // Unreadable or not an event file: not listed.
+    }
+  }
+  return runs.sort((a, b) => b.mtimeMs - a.mtimeMs);
+}
+
+/**
+ * The file for `ref`: a run id, else the name of an Op or a component
+ * selection, for which the newest stored run of that name stands. Null when
+ * nothing matches (a run that has not written its first line yet included).
+ */
+export async function findStoredRun(cwd: string, ref: string): Promise<StoredRun | null> {
+  const dir = await runEventsDir(cwd);
+  if (!dir) return null;
+  const direct = join(dir, runEventFileName(ref));
+  if (existsSync(direct)) {
+    const byId = (await listStoredRuns(cwd)).find((r) => r.file === direct);
+    return byId ?? { runId: ref, name: "", file: direct, mtimeMs: statSync(direct).mtimeMs };
+  }
+  return (await listStoredRuns(cwd)).find((r) => r.name === ref) ?? null;
+}
+
+/** Whether `event` ends a stream. */
+export const isRunSettle = (event: RunEvent): boolean => event.type === "run-settle";
+
+/**
+ * Read `file` from the start and hand each event to `onEvent` (with its raw
+ * line). Without `follow` it stops at the end of the file. With it, it keeps
+ * reading what is appended, by polling every `pollMs`, until `run-settle` is
+ * read, `signal` aborts, or `idleMs` passes with nothing new (when given).
+ * Resolves with the `run-settle` event, or undefined when the stream had
+ * none (a replay of a run still going, or a follow that was cut short).
+ */
+export async function readRunEvents(
+  file: string,
+  onEvent: (event: RunEvent, line: string) => void,
+  opts: { follow?: boolean; pollMs?: number; idleMs?: number; signal?: AbortSignal } = {},
+): Promise<RunEvent | undefined> {
+  const pollMs = opts.pollMs ?? 100;
+  let offset = 0;
+  let rest = "";
+  let lastGrowth = Date.now();
+  for (;;) {
+    let size = 0;
+    try {
+      size = statSync(file).size;
+    } catch {
+      // Not there yet (a follow started before the run opened its file).
+    }
+    if (size > offset) {
+      const buf = readFileSync(file);
+      const chunk = buf.subarray(offset, size).toString("utf8");
+      offset = size;
+      lastGrowth = Date.now();
+      const text = rest + chunk;
+      const parts = text.split("\n");
+      rest = parts.pop() ?? "";
+      for (const part of parts) {
+        if (part.trim() === "") continue;
+        let event: RunEvent;
+        try {
+          event = JSON.parse(part) as RunEvent;
+        } catch {
+          continue;
+        }
+        onEvent(event, `${part}\n`);
+        if (isRunSettle(event)) return event;
+      }
+    } else if (!opts.follow) {
+      return undefined;
+    } else if (opts.signal?.aborted) {
+      return undefined;
+    } else if (opts.idleMs !== undefined && Date.now() - lastGrowth > opts.idleMs) {
+      return undefined;
+    } else {
+      await new Promise<void>((resolve) => {
+        const timer = setTimeout(resolve, pollMs);
+        opts.signal?.addEventListener("abort", () => { clearTimeout(timer); resolve(); }, { once: true });
+      });
+    }
+  }
+}

package/src/run-event-stream.test.ts

@@ -0,0 +1,175 @@
+/**
+ * #4041: the emitters' side of the run-event contract. The stream holds a
+ * run to the shape the schema promises, the older `--progress-json` lines
+ * come back unchanged from the bodies the driver now emits, and a run is
+ * named by the commit and CI run #4020 resolves.
+ */
+
+import { describe, expect, test } from "vitest";
+import type { RunProgressEvent } from "./components/run-progress";
+import { memoryGateLedgerPort, type GateCheck } from "./op/gate";
+import type { RunEventBody, RunEventRun } from "./run-event";
+import {
+  emitGateStep,
+  gateEventsOf,
+  joinRunEventSinks,
+  openRunEventStream,
+  progressOfRunEvent,
+  progressSinkOf,
+  resolveRunEventRun,
+  runEventRunOf,
+} from "./run-event-stream";
+import { checkRunEventLines } from "./workspace/__fixtures__/run-event-check";
+
+const SHA = "0123456789abcdef0123456789abcdef01234567";
+const RUN: RunEventRun = { runId: "local-1", kind: "component", name: "api", gitSha: SHA, runtime: "local", runOrigin: { forge: "local" } };
+
+function capture(run: RunEventRun = RUN) {
+  const lines: string[] = [];
+  let t = Date.parse("2026-10-16T12:00:00.000Z");
+  const stream = openRunEventStream(run, (l) => lines.push(l), { now: () => new Date((t += 1000)), chant: "0.124.28" });
+  return { stream, lines };
+}
+
+describe("openRunEventStream", () => {
+  test("opens with run-start, drops a second one, times run-settle, and writes nothing after it", () => {
+    const { stream, lines } = capture();
+    stream.emit({ type: "run-start", waves: [["api"]] });
+    stream.emit({ type: "run-start", waves: [["other"]] });
+    stream.emit({ type: "phase-start", component: "api", phase: "Apply" });
+    stream.emit({ type: "phase-settle", component: "api", phase: "Apply", status: "ok" });
+    stream.emit({ type: "run-settle", status: "ok", durationMs: null });
+    stream.emit({ type: "phase-start", component: "api", phase: "late" });
+    stream.settle("failed", "too late");
+    const events = checkRunEventLines(lines);
+    expect(events.map((e) => e.type)).toEqual(["run-start", "phase-start", "phase-settle", "run-settle"]);
+    expect(events[0]).toMatchObject({ waves: [["api"]] });
+    // Untimed by the emitter, so the stream timed it from run-start.
+    expect(events.at(-1)).toMatchObject({ status: "ok", durationMs: expect.any(Number) });
+    expect((events.at(-1) as { durationMs: number }).durationMs).toBeGreaterThan(0);
+    expect(stream.settled).toBe(true);
+  });
+
+  test("a stream whose emitter never said run-start still opens with one, and settle ends it with the error", () => {
+    const { stream, lines } = capture();
+    stream.emit({ type: "step-start", component: null, phase: "Build", step: "make", index: 0 });
+    stream.emit({ type: "step-settle", component: null, phase: "Build", step: "make", index: 0, status: "failed", durationMs: 5, error: "boom" });
+    stream.settle("failed", "boom");
+    const events = checkRunEventLines(lines);
+    expect(events[0]).toMatchObject({ type: "run-start", waves: null });
+    expect(events.at(-1)).toMatchObject({ type: "run-settle", status: "failed", error: "boom" });
+  });
+
+  test("nested drops the inner run's framing, so the outer run settles it", () => {
+    const { stream, lines } = capture();
+    stream.emit({ type: "run-start", waves: [["a"]] });
+    stream.nested({ type: "run-start", waves: [["a"]] });
+    stream.nested({ type: "wave-start", wave: 1, components: ["a"] });
+    stream.nested({ type: "wave-settle", wave: 1, status: "ok" });
+    stream.nested({ type: "run-settle", status: "ok", durationMs: null });
+    expect(stream.settled).toBe(false);
+    stream.settle("gated");
+    expect(checkRunEventLines(lines).map((e) => e.type)).toEqual(["run-start", "wave-start", "wave-settle", "run-settle"]);
+  });
+});
+
+describe("progressOfRunEvent: --progress-json keeps its shape", () => {
+  test("each body the driver emits maps back to the RunProgressEvent it replaced, key order and all", () => {
+    const pairs: Array<[RunEventBody, RunProgressEvent]> = [
+      [{ type: "run-start", waves: [["a"]] }, { type: "run-start", waves: [["a"]] }],
+      [{ type: "wave-start", wave: 1, components: ["a"] }, { type: "wave-start", wave: 1, components: ["a"] }],
+      [{ type: "component-start", wave: 1, component: "a" }, { type: "component-start", wave: 1, component: "a" }],
+      [{ type: "phase-start", component: "a", phase: "Apply" }, { type: "phase-start", component: "a", phase: "Apply" }],
+      [{ type: "step-start", component: "a", phase: "Apply", step: "apply", index: 0 }, { type: "step", component: "a", phase: "Apply", step: "apply", status: "running" }],
+      [
+        { type: "step-settle", component: "a", phase: "Apply", step: "apply", index: 0, status: "failed", durationMs: 4, error: "no" },
+        { type: "step", component: "a", phase: "Apply", step: "apply", status: "failed", error: "no" },
+      ],
+      [{ type: "phase-settle", component: "a", phase: "Apply", status: "gated" }, { type: "phase-done", component: "a", phase: "Apply", status: "gated" }],
+      [{ type: "component-settle", wave: 1, component: "a", status: "failed" }, { type: "component-done", wave: 1, component: "a", status: "failed" }],
+      [{ type: "wave-settle", wave: 1, status: "ok" }, { type: "wave-done", wave: 1, status: "ok" }],
+      [{ type: "run-settle", status: "ok", durationMs: 12 }, { type: "run-done", status: "ok" }],
+    ];
+    for (const [body, old] of pairs) expect(JSON.stringify(progressOfRunEvent(body))).toBe(JSON.stringify(old));
+  });
+
+  test("what the older stream never printed maps to nothing: gate steps, skipped steps, gate decisions, phases outside a component", () => {
+    const none: RunEventBody[] = [
+      { type: "step-start", component: "a", phase: "Apply", step: "gate:prod", index: 0 },
+      { type: "step-settle", component: "a", phase: "Apply", step: "gate:prod", index: 0, status: "gated", durationMs: 1 },
+      { type: "step-settle", component: "a", phase: "Apply", step: "apply", index: 1, status: "skipped", skip: "not-run", durationMs: null },
+      { type: "gate-waiting", component: "a", phase: "Apply", step: "gate:prod", op: "a", gate: "prod", point: null },
+      { type: "phase-start", component: null, phase: "gate" },
+      { type: "phase-settle", component: null, phase: "gate", status: "ok" },
+    ];
+    for (const body of none) expect(progressOfRunEvent(body)).toBeUndefined();
+  });
+
+  test("progressSinkOf and joinRunEventSinks hand each body to every sink, and to none when none is given", () => {
+    const old: RunProgressEvent[] = [];
+    const bodies: RunEventBody[] = [];
+    const sink = joinRunEventSinks((b) => bodies.push(b), progressSinkOf((e) => old.push(e)), undefined)!;
+    sink({ type: "run-start", waves: [] });
+    sink({ type: "gate-waiting", component: null, phase: "gate", step: "gate:g", op: "fan-out", gate: "g", point: null });
+    expect(bodies).toHaveLength(2);
+    expect(old).toEqual([{ type: "run-start", waves: [] }]);
+    expect(joinRunEventSinks(undefined, progressSinkOf(undefined))).toBeUndefined();
+  });
+});
+
+describe("a gate's decision as events", () => {
+  const at = { component: null, phase: "gate", step: "gate:pr-apply", op: "pr-12", gate: "pr-apply" };
+
+  test("approved: gate-resolved and an ok settle; not approved: gate-waiting and a gated settle", () => {
+    const approved: GateCheck = {
+      satisfied: true,
+      resolution: { version: 1, kind: "resolution", op: "pr-12", gate: "pr-apply", resolvedBy: "github:alice", timestamp: "2026-10-16T11:00:00.000Z" },
+    } as GateCheck;
+    expect(gateEventsOf(approved, at, { durationMs: 3 })).toEqual([
+      { type: "gate-resolved", component: null, phase: "gate", step: "gate:pr-apply", op: "pr-12", gate: "pr-apply", resolvedBy: "github:alice", resolvedAt: "2026-10-16T11:00:00.000Z", via: null },
+      { type: "step-settle", component: null, phase: "gate", step: "gate:pr-apply", status: "ok", durationMs: 3 },
+    ]);
+  });
+
+  test("emitGateStep frames the decision as a gate phase, schema-valid, start before settle", async () => {
+    const { stream, lines } = capture();
+    const port = memoryGateLedgerPort();
+    const check = await emitGateStep(stream.emit, { op: "fan-out", gate: "ship" }, () =>
+      import("./op/gate").then((g) => g.evaluateGate(port, { op: "fan-out", gate: "ship", now: "2026-10-16T12:00:00.000Z" })),
+    );
+    expect(check.satisfied).toBe(false);
+    stream.settle("gated");
+    const events = checkRunEventLines(lines);
+    expect(events.map((e) => e.type)).toEqual(["run-start", "phase-start", "step-start", "gate-waiting", "step-settle", "phase-settle", "run-settle"]);
+    expect(events[4]).toMatchObject({ status: "gated", step: "gate:ship" });
+  });
+});
+
+describe("a run's identity (#4020's sources)", () => {
+  test("outside CI: a local id, the local origin and the local runtime", async () => {
+    const run = await resolveRunEventRun({ kind: "component", name: "api", cwd: "/nonexistent", env: {} });
+    expect(run).toMatchObject({ kind: "component", name: "api", gitSha: null, runtime: "local", runOrigin: { forge: "local" } });
+    expect(run.runId).toMatch(/^local-\d+$/);
+  });
+
+  test("in a GitHub job: the CI run's id and origin, the commit the job is for, and the ci runtime", async () => {
+    const env = { GITHUB_RUN_ID: "77", GITHUB_REPOSITORY: "acme/app", GITHUB_SERVER_URL: "https://github.com", GITHUB_SHA: SHA };
+    const run = await resolveRunEventRun({ kind: "component", name: "api", cwd: "/nonexistent", env });
+    expect(run).toEqual({
+      runId: "77",
+      kind: "component",
+      name: "api",
+      gitSha: SHA,
+      runtime: "ci",
+      runOrigin: { forge: "github", repo: "acme/app", url: "https://github.com/acme/app/actions/runs/77" },
+    });
+    // An id of the caller's own, not the CI run's, lives in no CI id space.
+    expect((await resolveRunEventRun({ kind: "component", name: "api", runId: "run-9", cwd: "/nonexistent", env })).runOrigin).toEqual({ forge: "local" });
+  });
+
+  test("a steward's run is the op id space on the steward runtime", () => {
+    expect(runEventRunOf({ kind: "op", name: "deploy", runId: "conv-1", steward: true })).toEqual({
+      runId: "conv-1", kind: "op", name: "deploy", gitSha: null, runtime: "steward", runOrigin: { forge: "op" },
+    });
+  });
+});