@nathapp/nax 0.75.6 → 0.76.0

package/flows/nax-finish/steps/result.ts

@@ -1,23 +1,112 @@
-import { mkdir, writeFile } from "node:fs/promises";
-import { dirname } from "node:path";
-import type { FinishResult } from "../types";
+/**
+ * Finish-audit artifacts.
+ *
+ * These live under nax's global per-project output directory —
+ * `~/.nax/<project>/finish-audit/<feature>/` — alongside `prompt-audit/` and
+ * `review-audit/`, not in the user's repo. Two reasons the repo was the wrong
+ * home: the artifact describes a *run*, not the source tree, so committing it
+ * and gitignoring it are both wrong answers; and a per-feature, per-run path
+ * makes the history queryable across runs, which a single overwritten
+ * `.nax/nax-finish-result.json` never was.
+ *
+ * The plugin supplies `auditDir` because it owns nax's path SSOT
+ * (`src/runtime/paths.ts`), which this module may not import — `flows/` is
+ * loaded by acpx, outside nax's own process. Absent, we fall back to a
+ * repo-local directory so a hand-run `acpx flow run` still records something.
+ *
+ * Two files per run:
+ * - `<runId>.jsonl`       — one line per fix round, appended as it happens
+ * - `<runId>.result.json` — the terminal result the plugin reads back
+ */
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import type { FinishInput, FinishResult, FinishRound } from "../types";
 
-export function resultPath(repoRoot: string): string {
-  return `${repoRoot}/.nax/nax-finish-result.json`;
+/** Used when the plugin supplied no run id (e.g. a hand-run `acpx flow run`). */
+const FALLBACK_RUN_ID = "run";
+
+type AuditTarget = Pick<FinishInput, "auditDir" | "workdir" | "feature" | "runId">;
+
+export function resolveAuditDir(input: AuditTarget): string {
+  return input.auditDir ?? join(input.workdir, ".nax", "finish-audit", input.feature);
+}
+
+export function resultPath(input: AuditTarget): string {
+  return join(resolveAuditDir(input), `${input.runId || FALLBACK_RUN_ID}.result.json`);
 }
 
-export const _resultDeps: { writeText: (p: string, s: string) => Promise<void> } = {
+export function roundsPath(input: AuditTarget): string {
+  return join(resolveAuditDir(input), `${input.runId || FALLBACK_RUN_ID}.jsonl`);
+}
+
+export const _resultDeps: {
+  writeText: (p: string, s: string) => Promise<void>;
+  appendText: (p: string, s: string) => Promise<void>;
+  readText: (p: string) => Promise<string | null>;
+} = {
   // node:fs, not Bun.write — this module runs inside acpx's Node process, where
   // the `Bun` global does not exist (see the header of `../exec.ts`). The mkdir
   // is not redundant: Bun.write creates missing parent directories implicitly,
-  // writeFile does not, and this is the one artifact the plugin needs on disk to
-  // report an outcome at all.
+  // writeFile does not, and the audit directory now lives under `~/.nax/`,
+  // where for a project's first run nothing on the path exists yet.
   writeText: async (p, s) => {
     await mkdir(dirname(p), { recursive: true });
     await writeFile(p, s, "utf8");
   },
+  appendText: async (p, s) => {
+    await mkdir(dirname(p), { recursive: true });
+    await writeFile(p, s, { encoding: "utf8", flag: "a" });
+  },
+  readText: async (p) => {
+    try {
+      return await readFile(p, "utf8");
+    } catch {
+      return null;
+    }
+  },
 };
 
-export async function writeResult(repoRoot: string, result: FinishResult): Promise<void> {
-  await _resultDeps.writeText(resultPath(repoRoot), `${JSON.stringify(result, null, 2)}\n`);
+/**
+ * Append one fix round to the run's audit trail.
+ *
+ * Best-effort: an unwritable audit directory must not take the flow down
+ * mid-loop. The round is a record of work already done — losing the record is
+ * bad, losing the run that did the work is worse.
+ */
+export async function appendRound(input: AuditTarget, round: FinishRound): Promise<void> {
+  try {
+    await _resultDeps.appendText(roundsPath(input), `${JSON.stringify(round)}\n`);
+  } catch {
+    // Intentionally swallowed — see the doc comment above.
+  }
+}
+
+/** Read back every round recorded for this run, so a terminal result can embed them. */
+export async function readRounds(input: AuditTarget): Promise<FinishRound[]> {
+  const raw = await _resultDeps.readText(roundsPath(input));
+  if (!raw) return [];
+  const rounds: FinishRound[] = [];
+  for (const line of raw.split("\n")) {
+    if (!line.trim()) continue;
+    try {
+      rounds.push(JSON.parse(line) as FinishRound);
+    } catch {
+      // A torn final line (killed mid-write) must not lose the rounds before it.
+    }
+  }
+  return rounds;
+}
+
+/**
+ * Write the terminal result, embedding every round this run recorded.
+ *
+ * Rounds are attached on *every* status, not just `escalated`: a finish that
+ * succeeded after four rounds is precisely the case worth auditing — it says
+ * the run's own review gates missed four defects — and it was the one case
+ * that previously recorded nothing at all.
+ */
+export async function writeResult(input: AuditTarget, result: FinishResult): Promise<void> {
+  const rounds = await readRounds(input);
+  const withRounds: FinishResult = rounds.length > 0 ? { ...result, rounds } : result;
+  await _resultDeps.writeText(resultPath(input), `${JSON.stringify(withRounds, null, 2)}\n`);
 }

package/flows/nax-finish/types.ts

@@ -29,11 +29,46 @@ export interface FinishTimeouts {
   acceptanceMs?: number;
   gateMs?: number;
 }
+/** The four fix-and-reverify loops, in graph order. */
+export type FinishPhase = "acceptance" | "spec" | "quality" | "gate";
+
+/**
+ * One completed fix round, appended to the audit trail as it happens.
+ *
+ * Rounds are appended at `commit_<phase>` as they happen rather than
+ * reconstructed by a terminal node from `ctx.state.steps` (which does retain
+ * every step's output). Appending live is what makes the trail survive a flow
+ * that is killed or times out: no terminal node runs on those paths, and a
+ * finish that died mid-loop is exactly when the record of what it already
+ * changed on the branch matters most.
+ */
+export interface FinishRound {
+  ts: string;
+  phase: FinishPhase;
+  /** 1-based; the Nth time this phase's fix node has run. */
+  attempt: number;
+  /** True when the fix produced a commit; false when it changed nothing. */
+  committed: boolean;
+  /** Reviewer findings this round set out to fix (spec/quality phases). */
+  findings: Finding[];
+  /** Gate commands that were red this round (gate phase). */
+  failing?: string[];
+}
+
 export interface FinishInput {
   feature: string;
   workdir: string;
   branch: string;
   prdPath: string;
+  /**
+   * Directory for this feature's finish-audit artifacts, e.g.
+   * `~/.nax/<project>/finish-audit/<feature>`. Supplied by the plugin, which
+   * owns nax's path SSOT (`src/runtime/paths.ts`) that this module may not
+   * import. Absent → the flow falls back to a repo-local directory.
+   */
+  auditDir?: string;
+  /** Run id, used to name this run's audit files. Absent → "run". */
+  runId?: string;
   /**
    * True only when Telegram escalation is both enabled *and* credentialed, as
    * determined by the plugin. When true the flow skips the PR/MR comment
@@ -62,6 +97,13 @@ export interface FinishResult {
    * rather than lost.
    */
   deliveryError?: string;
+  /**
+   * Every fix round the flow ran, on *all* terminal statuses — not just
+   * escalations. A successful finish that took four rounds to get there is the
+   * case worth auditing (it says the run's own review gates missed four
+   * defects), and it was previously the one case that recorded nothing.
+   */
+  rounds?: FinishRound[];
 }
 export interface RunResult {
   exitCode: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nathapp/nax",
-  "version": "0.75.6",
+  "version": "0.76.0",
   "description": "AI Coding Agent Orchestrator — loops until done",
   "type": "module",
   "bin": {