@nathapp/nax 0.23.0 → 0.24.0

package/src/pipeline/subscribers/registry.ts

@@ -0,0 +1,73 @@
+/**
+ * Registry Writer Subscriber
+ *
+ * Creates ~/.nax/runs/<project>-<feature>-<runId>/meta.json on run:started.
+ * Provides a persistent record of each run with paths for status and events.
+ *
+ * Design:
+ * - Best-effort: all writes wrapped in try/catch; never throws or blocks
+ * - Directory created on first write via mkdir recursive
+ * - Written once on run:started, never updated
+ * - Returns UnsubscribeFn matching wireHooks/wireEventsWriter pattern
+ */
+
+import { mkdir, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { basename, join } from "node:path";
+import { getSafeLogger } from "../../logger";
+import type { PipelineEventBus } from "../event-bus";
+import type { UnsubscribeFn } from "./hooks";
+
+export interface MetaJson {
+  runId: string;
+  project: string;
+  feature: string;
+  workdir: string;
+  statusPath: string;
+  eventsDir: string;
+  registeredAt: string;
+}
+
+/**
+ * Wire registry writer to the pipeline event bus.
+ *
+ * Listens to run:started and writes meta.json to
+ * ~/.nax/runs/<project>-<feature>-<runId>/meta.json.
+ *
+ * @param bus     - The pipeline event bus
+ * @param feature - Feature name
+ * @param runId   - Current run ID
+ * @param workdir - Working directory (project name derived via basename)
+ * @returns Unsubscribe function
+ */
+export function wireRegistry(bus: PipelineEventBus, feature: string, runId: string, workdir: string): UnsubscribeFn {
+  const logger = getSafeLogger();
+  const project = basename(workdir);
+  const runDir = join(homedir(), ".nax", "runs", `${project}-${feature}-${runId}`);
+  const metaFile = join(runDir, "meta.json");
+
+  const unsub = bus.on("run:started", (_ev) => {
+    (async () => {
+      try {
+        await mkdir(runDir, { recursive: true });
+        const meta: MetaJson = {
+          runId,
+          project,
+          feature,
+          workdir,
+          statusPath: join(workdir, "nax", "features", feature, "status.json"),
+          eventsDir: join(workdir, "nax", "features", feature, "runs"),
+          registeredAt: new Date().toISOString(),
+        };
+        await writeFile(metaFile, JSON.stringify(meta, null, 2));
+      } catch (err) {
+        logger?.warn("registry-writer", "Failed to write meta.json (non-fatal)", {
+          path: metaFile,
+          error: String(err),
+        });
+      }
+    })();
+  });
+
+  return unsub;
+}

package/test/integration/cli/cli-logs.test.ts

@@ -16,6 +16,7 @@ import { join } from "node:path";
 
 const TEST_WORKSPACE = join(import.meta.dir, "../../..", "tmp", "cli-logs-test");
 const NAX_BIN = join(import.meta.dir, "..", "..", "..", "bin", "nax.ts");
+const REGISTRY_DIR = join(TEST_WORKSPACE, "registry");
 
 function setupTestProject(featureName: string): string {
   const projectDir = join(TEST_WORKSPACE, `project-${Date.now()}`);
@@ -24,6 +25,7 @@ function setupTestProject(featureName: string): string {
   const runsDir = join(featureDir, "runs");
 
   mkdirSync(runsDir, { recursive: true });
+  mkdirSync(REGISTRY_DIR, { recursive: true });
 
   writeFileSync(join(naxDir, "config.json"), JSON.stringify({ feature: featureName }));
 
@@ -62,7 +64,24 @@ function setupTestProject(featureName: string): string {
     },
   ];
 
-  writeFileSync(join(runsDir, "2026-02-27T12-00-00.jsonl"), logs.map((l) => JSON.stringify(l)).join("\n"));
+  const runId = "2026-02-27T12-00-00";
+  writeFileSync(join(runsDir, `${runId}.jsonl`), logs.map((l) => JSON.stringify(l)).join("\n"));
+
+  // Create matching registry entry so --run <runId> resolves via registry
+  const entryDir = join(REGISTRY_DIR, `testproject-${featureName}-${runId}`);
+  mkdirSync(entryDir, { recursive: true });
+  writeFileSync(
+    join(entryDir, "meta.json"),
+    JSON.stringify({
+      runId,
+      project: "testproject",
+      feature: featureName,
+      workdir: projectDir,
+      statusPath: join(projectDir, "nax", "features", featureName, "status.json"),
+      eventsDir: runsDir,
+      registeredAt: "2026-02-27T12:00:00.000Z",
+    }),
+  );
 
   return projectDir;
 }
@@ -75,11 +94,15 @@ function cleanup(dir: string) {
 
 const CMD_TIMEOUT_MS = 15_000; // 15s per command — fast-fail instead of waiting full 60s
 
-function runNaxCommand(args: string[], cwd?: string): Promise<{ stdout: string; stderr: string; exitCode: number }> {
+function runNaxCommand(
+  args: string[],
+  cwd?: string,
+  extraEnv?: Record<string, string>,
+): Promise<{ stdout: string; stderr: string; exitCode: number }> {
   return new Promise((resolve, reject) => {
     const proc = spawn("bun", ["run", NAX_BIN, ...args], {
       cwd: cwd || process.cwd(),
-      env: process.env,
+      env: { ...process.env, ...extraEnv },
     });
 
     let stdout = "";
@@ -156,22 +179,24 @@ describe("nax logs CLI integration", () => {
   });
 
   describe("--run flag", () => {
-    test("nax logs --run <timestamp> selects specific run", async () => {
-      const result = await runNaxCommand(["logs", "--run", "2026-02-27T12-00-00", "-d", projectDir]);
+    const registryEnv = { NAX_RUNS_DIR: REGISTRY_DIR };
+
+    test("nax logs --run <runId> displays logs from matching registry entry", async () => {
+      const result = await runNaxCommand(["logs", "--run", "2026-02-27T12-00-00"], undefined, registryEnv);
 
       expect(result.exitCode).toBe(0);
       expect(result.stdout).toContain("run-001");
     });
 
     test("nax logs -r is shorthand for --run", async () => {
-      const result = await runNaxCommand(["logs", "-r", "2026-02-27T12-00-00", "-d", projectDir]);
+      const result = await runNaxCommand(["logs", "-r", "2026-02-27T12-00-00"], undefined, registryEnv);
 
       expect(result.exitCode).toBe(0);
       expect(result.stdout).toContain("run-001");
     });
 
-    test("nax logs --run fails when run not found", async () => {
-      const result = await runNaxCommand(["logs", "--run", "2026-01-01T00-00-00", "-d", projectDir]);
+    test("nax logs --run fails when run not found in registry", async () => {
+      const result = await runNaxCommand(["logs", "--run", "2026-01-01T00-00-00"], undefined, registryEnv);
 
       expect(result.exitCode).not.toBe(0);
       expect(result.stderr).toContain("not found");
@@ -256,6 +281,7 @@ describe("nax logs CLI integration", () => {
       // We verify the process starts and produces stdout output.
       const proc = spawn("bun", ["run", NAX_BIN, "logs", "--follow", "-d", projectDir], {
         cwd: process.cwd(),
+        env: process.env,
       });
 
       let started = false;
@@ -275,6 +301,7 @@ describe("nax logs CLI integration", () => {
     test("nax logs -f is shorthand for --follow", async () => {
       const proc = spawn("bun", ["run", NAX_BIN, "logs", "-f", "-d", projectDir], {
         cwd: process.cwd(),
+        env: process.env,
       });
 
       let started = false;
@@ -306,15 +333,11 @@ describe("nax logs CLI integration", () => {
     });
 
     test("--run + --story", async () => {
-      const result = await runNaxCommand([
-        "logs",
-        "--run",
-        "2026-02-27T12-00-00",
-        "--story",
-        "US-001",
-        "-d",
-        projectDir,
-      ]);
+      const result = await runNaxCommand(
+        ["logs", "--run", "2026-02-27T12-00-00", "--story", "US-001"],
+        undefined,
+        { NAX_RUNS_DIR: REGISTRY_DIR },
+      );
 
       expect(result.exitCode).toBe(0);
       expect(result.stdout).toContain("US-001");

package/test/unit/commands/logs.test.ts

@@ -16,7 +16,7 @@
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
 import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
-import { type LogsOptions, logsCommand } from "../../../src/commands/logs";
+import { type LogsOptions, _deps, logsCommand } from "../../../src/commands/logs";
 
 const TEST_WORKSPACE = join(import.meta.dir, "..", "..", "tmp", "logs-test");
 
@@ -110,13 +110,43 @@ function cleanup(projectDir: string) {
 
 describe("logsCommand", () => {
   let projectDir: string;
+  let registryDir: string;
+  let originalGetRunsDir: () => string;
 
   beforeEach(() => {
     projectDir = setupTestProject("test-feature");
+
+    // Set up a temp registry dir and override _deps
+    registryDir = join(TEST_WORKSPACE, `registry-${Date.now()}`);
+    mkdirSync(registryDir, { recursive: true });
+    originalGetRunsDir = _deps.getRunsDir;
+    _deps.getRunsDir = () => registryDir;
+
+    // Create registry entries pointing to the test runs
+    const runsDir = join(projectDir, "nax", "features", "test-feature", "runs");
+
+    for (const runId of ["2026-02-27T10-00-00", "2026-02-26T09-00-00"]) {
+      const entryDir = join(registryDir, `testproject-test-feature-${runId}`);
+      mkdirSync(entryDir, { recursive: true });
+      writeFileSync(
+        join(entryDir, "meta.json"),
+        JSON.stringify({
+          runId,
+          project: "testproject",
+          feature: "test-feature",
+          workdir: projectDir,
+          statusPath: join(projectDir, "nax", "features", "test-feature", "status.json"),
+          eventsDir: runsDir,
+          registeredAt: "2026-02-27T10:00:00.000Z",
+        }),
+      );
+    }
   });
 
   afterEach(() => {
+    _deps.getRunsDir = originalGetRunsDir;
     cleanup(projectDir);
+    cleanup(registryDir);
   });
 
   describe("default behavior (latest run formatted)", () => {
@@ -259,33 +289,46 @@ describe("logsCommand", () => {
     });
   });
 
-  describe("--run (specific run selection)", () => {
-    test("displays specific run by timestamp", async () => {
-      const options: LogsOptions = {
-        dir: projectDir,
-        run: "2026-02-26T09-00-00",
-      };
+  describe("--run (registry-based run selection)", () => {
+    test("displays run resolved from central registry by exact runId", async () => {
+      const options: LogsOptions = { run: "2026-02-26T09-00-00" };
 
-      // Should display the older run
       await expect(logsCommand(options)).resolves.toBeUndefined();
     });
 
-    test("throws when specified run does not exist", async () => {
-      const options: LogsOptions = {
-        dir: projectDir,
-        run: "2026-01-01T00-00-00",
-      };
+    test("displays run resolved from central registry by prefix match", async () => {
+      const options: LogsOptions = { run: "2026-02-26" };
 
-      await expect(logsCommand(options)).rejects.toThrow(/run not found/i);
+      // Should match "2026-02-26T09-00-00"
+      await expect(logsCommand(options)).resolves.toBeUndefined();
     });
 
-    test("works with partial timestamp matching", async () => {
-      const options: LogsOptions = {
-        dir: projectDir,
-        run: "2026-02-26",
-      };
+    test("throws with clear error when runId not found in registry", async () => {
+      const options: LogsOptions = { run: "2026-01-01T00-00-00" };
 
-      // Should match "2026-02-26T09-00-00"
+      await expect(logsCommand(options)).rejects.toThrow(/run not found in registry/i);
+    });
+
+    test("shows unavailable message when eventsDir does not exist", async () => {
+      // Add a registry entry pointing to a non-existent eventsDir
+      const entryDir = join(registryDir, "proj-feat-ghost-run");
+      mkdirSync(entryDir, { recursive: true });
+      writeFileSync(
+        join(entryDir, "meta.json"),
+        JSON.stringify({
+          runId: "ghost-run",
+          project: "proj",
+          feature: "feat",
+          workdir: "/nonexistent",
+          statusPath: "/nonexistent/nax/features/feat/status.json",
+          eventsDir: "/nonexistent/nax/features/feat/runs",
+          registeredAt: "2026-01-01T00:00:00.000Z",
+        }),
+      );
+
+      const options: LogsOptions = { run: "ghost-run" };
+
+      // Should resolve without throwing — prints unavailable message
       await expect(logsCommand(options)).resolves.toBeUndefined();
     });
   });
@@ -350,7 +393,6 @@ describe("logsCommand", () => {
 
     test("--run + --story + --level", async () => {
       const options: LogsOptions = {
-        dir: projectDir,
         run: "2026-02-27T10-00-00",
         story: "US-001",
         level: "info",
@@ -361,7 +403,6 @@ describe("logsCommand", () => {
 
     test("all filters combined", async () => {
       const options: LogsOptions = {
-        dir: projectDir,
         run: "2026-02-27T10-00-00",
         story: "US-001",
         level: "info",

package/test/unit/commands/runs.test.ts

@@ -0,0 +1,303 @@
+/**
+ * Unit tests for src/commands/runs.ts — runsCommand
+ *
+ * Tests all acceptance criteria:
+ * - Displays table sorted newest-first
+ * - --project filter
+ * - --last limit
+ * - --status filter
+ * - Missing statusPath shows '[unavailable]'
+ * - Empty registry shows 'No runs found'
+ */
+
+import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { _deps, runsCommand } from "../../../src/commands/runs";
+import type { MetaJson } from "../../../src/pipeline/subscribers/registry";
+import type { NaxStatusFile } from "../../../src/execution/status-file";
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+function makeTmpRunsDir(): string {
+  return mkdtempSync(join(tmpdir(), "nax-runs-test-"));
+}
+
+function makeStatusFile(overrides: Partial<NaxStatusFile["run"]> = {}): NaxStatusFile {
+  return {
+    version: 1,
+    run: {
+      id: "run-2026-01-01T00-00-00",
+      feature: "feat",
+      startedAt: "2026-01-01T00:00:00.000Z",
+      status: "completed",
+      dryRun: false,
+      pid: 1234,
+      ...overrides,
+    },
+    progress: { total: 4, passed: 3, failed: 1, paused: 0, blocked: 0, pending: 0 },
+    cost: { spent: 0.12, limit: null },
+    current: null,
+    iterations: 5,
+    updatedAt: "2026-01-01T00:10:00.000Z",
+    durationMs: 600000,
+  };
+}
+
+function writeRun(
+  runsDir: string,
+  opts: {
+    runId: string;
+    project: string;
+    feature: string;
+    registeredAt: string;
+    statusFile?: NaxStatusFile | null;
+  },
+): { metaPath: string; statusPath: string } {
+  const runDir = join(runsDir, `${opts.project}-${opts.feature}-${opts.runId}`);
+  mkdirSync(runDir, { recursive: true });
+
+  const statusPath = join(runDir, "status.json");
+
+  const meta: MetaJson = {
+    runId: opts.runId,
+    project: opts.project,
+    feature: opts.feature,
+    workdir: "/tmp/fake-workdir",
+    statusPath,
+    eventsDir: "/tmp/fake-workdir/nax/features/feat/runs",
+    registeredAt: opts.registeredAt,
+  };
+
+  writeFileSync(join(runDir, "meta.json"), JSON.stringify(meta, null, 2));
+
+  if (opts.statusFile !== null) {
+    const sf = opts.statusFile ?? makeStatusFile();
+    writeFileSync(statusPath, JSON.stringify(sf, null, 2));
+  }
+
+  return { metaPath: join(runDir, "meta.json"), statusPath };
+}
+
+// ─── Test state ───────────────────────────────────────────────────────────────
+
+let tmpDir: string;
+let capturedOutput: string[];
+const originalLog = console.log;
+const originalGetRunsDir = _deps.getRunsDir;
+
+beforeEach(() => {
+  tmpDir = makeTmpRunsDir();
+  capturedOutput = [];
+  console.log = (...args: unknown[]) => {
+    capturedOutput.push(args.map(String).join(" "));
+  };
+  _deps.getRunsDir = () => tmpDir;
+});
+
+afterEach(() => {
+  console.log = originalLog;
+  _deps.getRunsDir = originalGetRunsDir;
+  rmSync(tmpDir, { recursive: true, force: true });
+});
+
+// ─── Tests ────────────────────────────────────────────────────────────────────
+
+describe("runsCommand", () => {
+  describe("empty registry", () => {
+    test("shows 'No runs found' when registry dir does not exist", async () => {
+      _deps.getRunsDir = () => join(tmpDir, "nonexistent");
+      await runsCommand();
+      expect(capturedOutput.join("\n")).toContain("No runs found");
+    });
+
+    test("shows 'No runs found' when registry dir is empty", async () => {
+      await runsCommand();
+      expect(capturedOutput.join("\n")).toContain("No runs found");
+    });
+  });
+
+  describe("table display", () => {
+    test("displays runs sorted newest-first", async () => {
+      writeRun(tmpDir, {
+        runId: "run-A",
+        project: "proj",
+        feature: "feat",
+        registeredAt: "2026-01-01T10:00:00.000Z",
+        statusFile: makeStatusFile({ status: "completed" }),
+      });
+      writeRun(tmpDir, {
+        runId: "run-B",
+        project: "proj",
+        feature: "feat",
+        registeredAt: "2026-01-02T10:00:00.000Z",
+        statusFile: makeStatusFile({ status: "completed" }),
+      });
+
+      await runsCommand();
+
+      const output = capturedOutput.join("\n");
+      const posA = output.indexOf("run-A");
+      const posB = output.indexOf("run-B");
+      expect(posB).toBeLessThan(posA); // run-B (newer) should appear before run-A
+    });
+
+    test("shows RUN ID, PROJECT, FEATURE, STATUS, STORIES, DURATION, DATE columns", async () => {
+      writeRun(tmpDir, {
+        runId: "run-X",
+        project: "myproj",
+        feature: "my-feat",
+        registeredAt: "2026-01-01T00:00:00.000Z",
+        statusFile: makeStatusFile(),
+      });
+
+      await runsCommand();
+
+      const output = capturedOutput.join("\n");
+      expect(output).toContain("RUN ID");
+      expect(output).toContain("PROJECT");
+      expect(output).toContain("FEATURE");
+      expect(output).toContain("STATUS");
+      expect(output).toContain("STORIES");
+      expect(output).toContain("DURATION");
+      expect(output).toContain("DATE");
+    });
+
+    test("shows run data in table row", async () => {
+      writeRun(tmpDir, {
+        runId: "run-X",
+        project: "myproj",
+        feature: "my-feat",
+        registeredAt: "2026-01-01T00:00:00.000Z",
+        statusFile: makeStatusFile({ status: "completed" }),
+      });
+
+      await runsCommand();
+
+      const output = capturedOutput.join("\n");
+      expect(output).toContain("run-X");
+      expect(output).toContain("myproj");
+      expect(output).toContain("my-feat");
+      expect(output).toContain("3/4");
+    });
+  });
+
+  describe("--project filter", () => {
+    test("filters runs by project name", async () => {
+      writeRun(tmpDir, {
+        runId: "run-alpha",
+        project: "alpha",
+        feature: "feat",
+        registeredAt: "2026-01-01T00:00:00.000Z",
+        statusFile: makeStatusFile(),
+      });
+      writeRun(tmpDir, {
+        runId: "run-beta",
+        project: "beta",
+        feature: "feat",
+        registeredAt: "2026-01-01T00:00:00.000Z",
+        statusFile: makeStatusFile(),
+      });
+
+      await runsCommand({ project: "alpha" });
+
+      const output = capturedOutput.join("\n");
+      expect(output).toContain("run-alpha");
+      expect(output).not.toContain("run-beta");
+    });
+
+    test("shows 'No runs found' when project has no runs", async () => {
+      writeRun(tmpDir, {
+        runId: "run-alpha",
+        project: "alpha",
+        feature: "feat",
+        registeredAt: "2026-01-01T00:00:00.000Z",
+        statusFile: makeStatusFile(),
+      });
+
+      await runsCommand({ project: "nonexistent" });
+
+      expect(capturedOutput.join("\n")).toContain("No runs found");
+    });
+  });
+
+  describe("--last limit", () => {
+    test("limits output to N most recent runs", async () => {
+      for (let i = 1; i <= 5; i++) {
+        writeRun(tmpDir, {
+          runId: `run-${String(i).padStart(3, "0")}`,
+          project: "proj",
+          feature: "feat",
+          registeredAt: `2026-01-0${i}T00:00:00.000Z`,
+          statusFile: makeStatusFile(),
+        });
+      }
+
+      await runsCommand({ last: 2 });
+
+      const output = capturedOutput.join("\n");
+      // Only the 2 newest should appear
+      expect(output).toContain("run-005");
+      expect(output).toContain("run-004");
+      expect(output).not.toContain("run-001");
+      expect(output).not.toContain("run-002");
+      expect(output).not.toContain("run-003");
+    });
+  });
+
+  describe("--status filter", () => {
+    test("filters runs by status", async () => {
+      writeRun(tmpDir, {
+        runId: "run-done",
+        project: "proj",
+        feature: "feat",
+        registeredAt: "2026-01-01T00:00:00.000Z",
+        statusFile: makeStatusFile({ status: "completed" }),
+      });
+      writeRun(tmpDir, {
+        runId: "run-fail",
+        project: "proj",
+        feature: "feat",
+        registeredAt: "2026-01-02T00:00:00.000Z",
+        statusFile: makeStatusFile({ status: "failed" }),
+      });
+
+      await runsCommand({ status: "failed" });
+
+      const output = capturedOutput.join("\n");
+      expect(output).toContain("run-fail");
+      expect(output).not.toContain("run-done");
+    });
+  });
+
+  describe("missing statusPath", () => {
+    test("shows [unavailable] when status file does not exist", async () => {
+      writeRun(tmpDir, {
+        runId: "run-nostat",
+        project: "proj",
+        feature: "feat",
+        registeredAt: "2026-01-01T00:00:00.000Z",
+        statusFile: null, // no status file written
+      });
+
+      await runsCommand();
+
+      const output = capturedOutput.join("\n");
+      expect(output).toContain("[unavailable]");
+      expect(output).toContain("run-nostat");
+    });
+
+    test("does not throw when status file is missing", async () => {
+      writeRun(tmpDir, {
+        runId: "run-nostat",
+        project: "proj",
+        feature: "feat",
+        registeredAt: "2026-01-01T00:00:00.000Z",
+        statusFile: null,
+      });
+
+      await expect(runsCommand()).resolves.toBeUndefined();
+    });
+  });
+});