@nathapp/nax 0.22.4 → 0.24.0

package/src/commands/runs.ts

@@ -0,0 +1,220 @@
+/**
+ * Runs Command
+ *
+ * Reads all ~/.nax/runs/*\/meta.json entries and displays a table of runs
+ * sorted by registeredAt descending. Resolves each statusPath to read the
+ * live NaxStatusFile for current state. Falls back to '[unavailable]' if
+ * the status file is missing or unreadable.
+ *
+ * Usage:
+ *   nax runs [--project <name>] [--last <N>] [--status <status>]
+ */
+
+import { readdir } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import chalk from "chalk";
+import type { NaxStatusFile } from "../execution/status-file";
+import type { MetaJson } from "../pipeline/subscribers/registry";
+
+const DEFAULT_LIMIT = 20;
+
+/**
+ * Swappable dependencies for testing (project convention: _deps over mock.module).
+ */
+export const _deps = {
+  getRunsDir: () => join(homedir(), ".nax", "runs"),
+};
+
+export interface RunsOptions {
+  /** Filter by project name */
+  project?: string;
+  /** Limit number of runs displayed (default: 20) */
+  last?: number;
+  /** Filter by run status */
+  status?: "running" | "completed" | "failed" | "crashed";
+}
+
+interface RunRow {
+  runId: string;
+  project: string;
+  feature: string;
+  status: string;
+  passed: number;
+  total: number;
+  durationMs: number;
+  registeredAt: string;
+}
+
+/**
+ * Format duration in milliseconds to human-readable string.
+ */
+function formatDuration(ms: number): string {
+  if (ms <= 0) return "-";
+  const minutes = Math.floor(ms / 60000);
+  const seconds = Math.floor((ms % 60000) / 1000);
+  if (minutes === 0) return `${seconds}s`;
+  return `${minutes}m ${seconds}s`;
+}
+
+/**
+ * Format ISO date to short local date string.
+ */
+function formatDate(iso: string): string {
+  try {
+    const d = new Date(iso);
+    return d.toLocaleDateString(undefined, { month: "short", day: "numeric", year: "numeric" });
+  } catch {
+    return iso;
+  }
+}
+
+/**
+ * Color a status string for terminal output.
+ */
+function colorStatus(status: string): string {
+  switch (status) {
+    case "completed":
+      return chalk.green(status);
+    case "failed":
+      return chalk.red(status);
+    case "running":
+      return chalk.yellow(status);
+    case "[unavailable]":
+      return chalk.dim(status);
+    default:
+      return chalk.dim(status);
+  }
+}
+
+/** Regex that matches ANSI escape sequences. */
+const ANSI_RE = new RegExp(`${String.fromCharCode(27)}\\[[0-9;]*m`, "g");
+
+/** Strip ANSI escape codes to compute visible string length. */
+function visibleLength(str: string): number {
+  return str.replace(ANSI_RE, "").length;
+}
+
+/**
+ * Pad a string to a fixed width (left-aligned).
+ */
+function pad(str: string, width: number): string {
+  const padding = Math.max(0, width - visibleLength(str));
+  return str + " ".repeat(padding);
+}
+
+/**
+ * Display all registered runs from ~/.nax/runs/ as a table.
+ *
+ * @param options - Filter and limit options
+ */
+export async function runsCommand(options: RunsOptions = {}): Promise<void> {
+  const runsDir = _deps.getRunsDir();
+
+  let entries: string[];
+  try {
+    entries = await readdir(runsDir);
+  } catch {
+    console.log("No runs found.");
+    return;
+  }
+
+  const rows: RunRow[] = [];
+
+  for (const entry of entries) {
+    const metaPath = join(runsDir, entry, "meta.json");
+    let meta: MetaJson;
+    try {
+      meta = await Bun.file(metaPath).json();
+    } catch {
+      continue;
+    }
+
+    // Apply project filter early
+    if (options.project && meta.project !== options.project) continue;
+
+    // Read live status file
+    let statusData: NaxStatusFile | null = null;
+    try {
+      statusData = await Bun.file(meta.statusPath).json();
+    } catch {
+      // statusPath missing or unreadable — handled gracefully below
+    }
+
+    const runStatus = statusData ? statusData.run.status : "[unavailable]";
+
+    // Apply status filter
+    if (options.status && runStatus !== options.status) continue;
+
+    rows.push({
+      runId: meta.runId,
+      project: meta.project,
+      feature: meta.feature,
+      status: runStatus,
+      passed: statusData?.progress.passed ?? 0,
+      total: statusData?.progress.total ?? 0,
+      durationMs: statusData?.durationMs ?? 0,
+      registeredAt: meta.registeredAt,
+    });
+  }
+
+  // Sort newest first
+  rows.sort((a, b) => new Date(b.registeredAt).getTime() - new Date(a.registeredAt).getTime());
+
+  // Apply limit
+  const limit = options.last ?? DEFAULT_LIMIT;
+  const displayed = rows.slice(0, limit);
+
+  if (displayed.length === 0) {
+    console.log("No runs found.");
+    return;
+  }
+
+  // Column widths (minimum per header)
+  const COL = {
+    runId: Math.max(6, ...displayed.map((r) => r.runId.length)),
+    project: Math.max(7, ...displayed.map((r) => r.project.length)),
+    feature: Math.max(7, ...displayed.map((r) => r.feature.length)),
+    status: Math.max(6, ...displayed.map((r) => visibleLength(r.status))),
+    stories: 7,
+    duration: 8,
+    date: 11,
+  };
+
+  // Header
+  const header = [
+    pad(chalk.bold("RUN ID"), COL.runId),
+    pad(chalk.bold("PROJECT"), COL.project),
+    pad(chalk.bold("FEATURE"), COL.feature),
+    pad(chalk.bold("STATUS"), COL.status),
+    pad(chalk.bold("STORIES"), COL.stories),
+    pad(chalk.bold("DURATION"), COL.duration),
+    chalk.bold("DATE"),
+  ].join("  ");
+
+  console.log();
+  console.log(header);
+  console.log(
+    chalk.dim("-".repeat(COL.runId + COL.project + COL.feature + COL.status + COL.stories + COL.duration + 11 + 12)),
+  );
+
+  for (const row of displayed) {
+    const colored = colorStatus(row.status);
+    const line = [
+      pad(row.runId, COL.runId),
+      pad(row.project, COL.project),
+      pad(row.feature, COL.feature),
+      pad(colored, COL.status + (colored.length - visibleLength(colored))),
+      pad(`${row.passed}/${row.total}`, COL.stories),
+      pad(formatDuration(row.durationMs), COL.duration),
+      formatDate(row.registeredAt),
+    ].join("  ");
+    console.log(line);
+  }
+
+  console.log();
+  if (rows.length > limit) {
+    console.log(chalk.dim(`Showing ${limit} of ${rows.length} runs. Use --last <N> to see more.`));
+    console.log();
+  }
+}

package/src/config/schemas.ts

@@ -117,6 +117,9 @@ const QualityConfigSchema = z.object({
     typecheck: z.string().optional(),
     lint: z.string().optional(),
     test: z.string().optional(),
+    testScoped: z.string().optional(),
+    lintFix: z.string().optional(),
+    formatFix: z.string().optional(),
   }),
   forceExit: z.boolean().default(false),
   detectOpenHandles: z.boolean().default(true),

package/src/execution/crash-recovery.ts

@@ -27,6 +27,8 @@ export interface CrashRecoveryContext {
   // BUG-017: Additional context for run.complete event on SIGTERM
   runId?: string;
   feature?: string;
+  // SFC-002: Feature directory for writing feature-level status on crash
+  featureDir?: string;
   getStartTime?: () => number;
   getTotalStories?: () => number;
   getStoriesCompleted?: () => number;
@@ -115,13 +117,14 @@ async function writeRunComplete(ctx: CrashRecoveryContext, exitReason: string):
 }
 
 /**
- * Update status.json to "crashed" state
+ * Update status.json to "crashed" state (both project-level and feature-level)
  */
 async function updateStatusToCrashed(
   statusWriter: StatusWriter,
   totalCost: number,
   iterations: number,
   signal: string,
+  featureDir?: string,
 ): Promise<void> {
   try {
     statusWriter.setRunStatus("crashed");
@@ -129,6 +132,14 @@ async function updateStatusToCrashed(
       crashedAt: new Date().toISOString(),
       crashSignal: signal,
     });
+
+    // Write feature-level status (SFC-002)
+    if (featureDir) {
+      await statusWriter.writeFeatureStatus(featureDir, totalCost, iterations, {
+        crashedAt: new Date().toISOString(),
+        crashSignal: signal,
+      });
+    }
   } catch (err) {
     console.error("[crash-recovery] Failed to update status.json:", err);
   }
@@ -166,8 +177,8 @@ export function installCrashHandlers(ctx: CrashRecoveryContext): () => void {
     // Write run.complete event (BUG-017)
     await writeRunComplete(ctx, signal.toLowerCase());
 
-    // Update status.json to crashed
-    await updateStatusToCrashed(ctx.statusWriter, ctx.getTotalCost(), ctx.getIterations(), signal);
+    // Update status.json to crashed (SFC-002: include feature-level status)
+    await updateStatusToCrashed(ctx.statusWriter, ctx.getTotalCost(), ctx.getIterations(), signal, ctx.featureDir);
 
     // Stop heartbeat
     stopHeartbeat();
@@ -201,8 +212,14 @@ export function installCrashHandlers(ctx: CrashRecoveryContext): () => void {
     // Write fatal log with stack trace
     await writeFatalLog(ctx.jsonlFilePath, "uncaughtException", error);
 
-    // Update status.json to crashed
-    await updateStatusToCrashed(ctx.statusWriter, ctx.getTotalCost(), ctx.getIterations(), "uncaughtException");
+    // Update status.json to crashed (SFC-002: include feature-level status)
+    await updateStatusToCrashed(
+      ctx.statusWriter,
+      ctx.getTotalCost(),
+      ctx.getIterations(),
+      "uncaughtException",
+      ctx.featureDir,
+    );
 
     // Stop heartbeat
     stopHeartbeat();
@@ -228,8 +245,14 @@ export function installCrashHandlers(ctx: CrashRecoveryContext): () => void {
     // Write fatal log
     await writeFatalLog(ctx.jsonlFilePath, "unhandledRejection", error);
 
-    // Update status.json to crashed
-    await updateStatusToCrashed(ctx.statusWriter, ctx.getTotalCost(), ctx.getIterations(), "unhandledRejection");
+    // Update status.json to crashed (SFC-002: include feature-level status)
+    await updateStatusToCrashed(
+      ctx.statusWriter,
+      ctx.getTotalCost(),
+      ctx.getIterations(),
+      "unhandledRejection",
+      ctx.featureDir,
+    );
 
     // Stop heartbeat
     stopHeartbeat();

package/src/execution/lifecycle/run-setup.ts

@@ -25,6 +25,7 @@ import { loadPlugins } from "../../plugins/loader";
 import type { PluginRegistry } from "../../plugins/registry";
 import type { PRD } from "../../prd";
 import { loadPRD } from "../../prd";
+import { NAX_BUILD_INFO, NAX_COMMIT, NAX_VERSION } from "../../version";
 import { installCrashHandlers } from "../crash-recovery";
 import { acquireLock, hookCtx, releaseLock } from "../helpers";
 import { PidRegistry } from "../pid-registry";
@@ -36,6 +37,7 @@ export interface RunSetupOptions {
   config: NaxConfig;
   hooks: LoadedHooksConfig;
   feature: string;
+  featureDir?: string;
   dryRun: boolean;
   statusFile: string;
   logFilePath?: string;
@@ -117,6 +119,7 @@ export async function setupRun(options: RunSetupOptions): Promise<RunSetupResult
     // BUG-017: Pass context for run.complete event on SIGTERM
     runId: options.runId,
     feature: options.feature,
+    featureDir: options.featureDir,
     getStartTime: () => options.startTime,
     getTotalStories: options.getTotalStories,
     getStoriesCompleted: options.getStoriesCompleted,
@@ -173,12 +176,14 @@ export async function setupRun(options: RunSetupOptions): Promise<RunSetupResult
 
     // Log run start
     const routingMode = config.routing.llm?.mode ?? "hybrid";
-    logger?.info("run.start", `Starting feature: ${feature}`, {
+    logger?.info("run.start", `Starting feature: ${feature} [nax ${NAX_BUILD_INFO}]`, {
       runId,
       feature,
       workdir,
       dryRun,
       routingMode,
+      naxVersion: NAX_VERSION,
+      naxCommit: NAX_COMMIT,
     });
 
     // Fire on-start hook

package/src/execution/runner.ts

@@ -110,6 +110,7 @@ export async function run(options: RunOptions): Promise<RunResult> {
     config,
     hooks,
     feature,
+    featureDir,
     dryRun,
     statusFile,
     logFilePath,
@@ -307,6 +308,13 @@ export async function run(options: RunOptions): Promise<RunResult> {
 
     const { durationMs, runCompletedAt, finalCounts } = completionResult;
 
+    // ── Write feature-level status (SFC-002) ────────────────────────────────
+    if (featureDir) {
+      const finalStatus = isComplete(prd) ? "completed" : "failed";
+      statusWriter.setRunStatus(finalStatus);
+      await statusWriter.writeFeatureStatus(featureDir, totalCost, iterations);
+    }
+
     // ── Output run footer in headless mode ─────────────────────────────────
     if (headless && formatterMode !== "json") {
       const { outputRunFooter } = await import("./lifecycle/headless-formatter");

package/src/execution/sequential-executor.ts

@@ -5,8 +5,10 @@ import type { StoryMetrics } from "../metrics";
 import { pipelineEventBus } from "../pipeline/event-bus";
 import { runPipeline } from "../pipeline/runner";
 import { postRunPipeline } from "../pipeline/stages";
+import { wireEventsWriter } from "../pipeline/subscribers/events-writer";
 import { wireHooks } from "../pipeline/subscribers/hooks";
 import { wireInteraction } from "../pipeline/subscribers/interaction";
+import { wireRegistry } from "../pipeline/subscribers/registry";
 import { wireReporters } from "../pipeline/subscribers/reporters";
 import type { PipelineContext } from "../pipeline/types";
 import { generateHumanHaltSummary, isComplete, isStalled, loadPRD } from "../prd";
@@ -38,6 +40,8 @@ export async function executeSequential(
   wireHooks(pipelineEventBus, ctx.hooks, ctx.workdir, ctx.feature);
   wireReporters(pipelineEventBus, ctx.pluginRegistry, ctx.runId, ctx.startTime);
   wireInteraction(pipelineEventBus, ctx.interactionChain, ctx.config);
+  wireEventsWriter(pipelineEventBus, ctx.feature, ctx.runId, ctx.workdir);
+  wireRegistry(pipelineEventBus, ctx.feature, ctx.runId, ctx.workdir);
 
   const buildResult = (exitReason: SequentialExecutionResult["exitReason"]): SequentialExecutionResult => ({
     prd,

package/src/execution/status-writer.ts

@@ -6,6 +6,7 @@
  * write failure counter. Provides atomic status file writes via writeStatusFile.
  */
 
+import { join } from "node:path";
 import type { NaxConfig } from "../config";
 import { getSafeLogger } from "../logger";
 import type { PRD } from "../prd";
@@ -136,4 +137,45 @@ export class StatusWriter {
       });
     }
   }
+
+  /**
+   * Write the current status snapshot to feature-level status.json file.
+   *
+   * Called on run completion, failure, or crash to persist the final state
+   * to <featureDir>/status.json. Uses the same NaxStatusFile schema as
+   * the project-level status file.
+   *
+   * No-ops if _prd has not been set.
+   * On failure, logs a warning/error but does not throw (non-fatal).
+   *
+   * @param featureDir - Feature directory (e.g., nax/features/auth-system)
+   * @param totalCost - Accumulated cost at this write point
+   * @param iterations - Loop iteration count at this write point
+   * @param overrides  - Optional partial snapshot overrides (spread last)
+   */
+  async writeFeatureStatus(
+    featureDir: string,
+    totalCost: number,
+    iterations: number,
+    overrides: Partial<RunStateSnapshot> = {},
+  ): Promise<void> {
+    if (!this._prd) return;
+    const safeLogger = getSafeLogger();
+    const featureStatusPath = join(featureDir, "status.json");
+
+    try {
+      const base = this.getSnapshot(totalCost, iterations);
+      if (!base) {
+        throw new Error("Failed to get snapshot");
+      }
+      const state: RunStateSnapshot = { ...base, ...overrides };
+      await writeStatusFile(featureStatusPath, buildStatusSnapshot(state));
+      safeLogger?.debug("status-file", "Feature status written", { path: featureStatusPath });
+    } catch (err) {
+      safeLogger?.warn("status-file", "Failed to write feature status file (non-fatal)", {
+        path: featureStatusPath,
+        error: (err as Error).message,
+      });
+    }
+  }
 }

package/src/pipeline/subscribers/events-writer.ts

@@ -0,0 +1,121 @@
+/**
+ * Events Writer Subscriber
+ *
+ * Appends one JSON line per pipeline lifecycle event to
+ * ~/.nax/events/<project>/events.jsonl. Provides a machine-readable
+ * signal that nax exited gracefully (run:completed → event=on-complete),
+ * fixing watchdog false crash reports.
+ *
+ * Design:
+ * - Best-effort: all writes are wrapped in try/catch; never throws or blocks
+ * - Directory is created on first write via mkdir recursive
+ * - Returns UnsubscribeFn matching wireHooks/wireReporters pattern
+ */
+
+import { appendFile, mkdir } 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";
+
+interface EventLine {
+  ts: string;
+  event: string;
+  runId: string;
+  feature: string;
+  project: string;
+  storyId?: string;
+  data?: object;
+}
+
+/**
+ * Wire events file writer to the pipeline event bus.
+ *
+ * Listens to run:started, story:started, story:completed, story:failed,
+ * run:completed, run:paused and appends one JSONL entry per event.
+ *
+ * @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 wireEventsWriter(
+  bus: PipelineEventBus,
+  feature: string,
+  runId: string,
+  workdir: string,
+): UnsubscribeFn {
+  const logger = getSafeLogger();
+  const project = basename(workdir);
+  const eventsDir = join(homedir(), ".nax", "events", project);
+  const eventsFile = join(eventsDir, "events.jsonl");
+  let dirReady = false;
+
+  const write = (line: EventLine): void => {
+    (async () => {
+      try {
+        if (!dirReady) {
+          await mkdir(eventsDir, { recursive: true });
+          dirReady = true;
+        }
+        await appendFile(eventsFile, `${JSON.stringify(line)}\n`);
+      } catch (err) {
+        logger?.warn("events-writer", "Failed to write event line (non-fatal)", {
+          event: line.event,
+          error: String(err),
+        });
+      }
+    })();
+  };
+
+  const unsubs: UnsubscribeFn[] = [];
+
+  unsubs.push(
+    bus.on("run:started", (_ev) => {
+      write({ ts: new Date().toISOString(), event: "run:started", runId, feature, project });
+    }),
+  );
+
+  unsubs.push(
+    bus.on("story:started", (ev) => {
+      write({ ts: new Date().toISOString(), event: "story:started", runId, feature, project, storyId: ev.storyId });
+    }),
+  );
+
+  unsubs.push(
+    bus.on("story:completed", (ev) => {
+      write({ ts: new Date().toISOString(), event: "story:completed", runId, feature, project, storyId: ev.storyId });
+    }),
+  );
+
+  unsubs.push(
+    bus.on("story:failed", (ev) => {
+      write({ ts: new Date().toISOString(), event: "story:failed", runId, feature, project, storyId: ev.storyId });
+    }),
+  );
+
+  unsubs.push(
+    bus.on("run:completed", (_ev) => {
+      write({ ts: new Date().toISOString(), event: "on-complete", runId, feature, project });
+    }),
+  );
+
+  unsubs.push(
+    bus.on("run:paused", (ev) => {
+      write({
+        ts: new Date().toISOString(),
+        event: "run:paused",
+        runId,
+        feature,
+        project,
+        ...(ev.storyId !== undefined && { storyId: ev.storyId }),
+      });
+    }),
+  );
+
+  return () => {
+    for (const u of unsubs) u();
+  };
+}

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/src/version.ts

@@ -0,0 +1,23 @@
+/**
+ * Version and build info for nax.
+ *
+ * GIT_COMMIT is injected at build time via --define in the bun build script.
+ * When running from source (bun run dev), it falls back to "dev".
+ */
+
+import pkg from "../package.json";
+
+declare const GIT_COMMIT: string;
+
+export const NAX_VERSION: string = pkg.version;
+
+/** Short git commit hash, injected at build time. Falls back to "dev" from source. */
+export const NAX_COMMIT: string = (() => {
+  try {
+    return GIT_COMMIT ?? "dev";
+  } catch {
+    return "dev";
+  }
+})();
+
+export const NAX_BUILD_INFO = `v${NAX_VERSION} (${NAX_COMMIT})`;