@nathapp/nax 0.23.0 → 0.25.0

package/src/commands/logs.ts

@@ -6,13 +6,23 @@
  */
 
 import { existsSync, readdirSync } from "node:fs";
+import { readdir } from "node:fs/promises";
+import { homedir } from "node:os";
 import { join } from "node:path";
 import chalk from "chalk";
 import type { LogEntry, LogLevel } from "../logger/types";
 import { type FormattedEntry, formatLogEntry, formatRunSummary } from "../logging/formatter";
 import type { RunSummary, VerbosityMode } from "../logging/types";
+import type { MetaJson } from "../pipeline/subscribers/registry";
 import { type ResolveProjectOptions, resolveProject } from "./common";
 
+/**
+ * Swappable dependencies for testing (project convention: _deps over mock.module).
+ */
+export const _deps = {
+  getRunsDir: () => process.env.NAX_RUNS_DIR ?? join(homedir(), ".nax", "runs"),
+};
+
 /**
  * Options for logs command
  */
@@ -43,12 +53,84 @@ const LOG_LEVEL_PRIORITY: Record<LogLevel, number> = {
   error: 3,
 };
 
+/**
+ * Resolve log file path for a runId from the central registry (~/.nax/runs/).
+ *
+ * Scans all ~/.nax/runs/*\/meta.json entries for an exact or prefix match on runId.
+ * Returns the path to the matching run's JSONL file, or null if eventsDir/file is unavailable.
+ * Throws if the runId is not found in the registry at all.
+ *
+ * @param runId - Full or prefix run ID to look up
+ * @returns Absolute path to the JSONL log file, or null if unavailable
+ */
+async function resolveRunFileFromRegistry(runId: string): Promise<string | null> {
+  const runsDir = _deps.getRunsDir();
+
+  let entries: string[];
+  try {
+    entries = await readdir(runsDir);
+  } catch {
+    throw new Error(`Run not found in registry: ${runId}`);
+  }
+
+  let matched: MetaJson | null = null;
+  for (const entry of entries) {
+    const metaPath = join(runsDir, entry, "meta.json");
+    try {
+      const meta: MetaJson = await Bun.file(metaPath).json();
+      if (meta.runId === runId || meta.runId.startsWith(runId)) {
+        matched = meta;
+        break;
+      }
+    } catch {
+      // skip unreadable meta.json entries
+    }
+  }
+
+  if (!matched) {
+    throw new Error(`Run not found in registry: ${runId}`);
+  }
+
+  if (!existsSync(matched.eventsDir)) {
+    console.log(`Log directory unavailable for run: ${runId}`);
+    return null;
+  }
+
+  const files = readdirSync(matched.eventsDir)
+    .filter((f) => f.endsWith(".jsonl") && f !== "latest.jsonl")
+    .sort()
+    .reverse();
+
+  if (files.length === 0) {
+    console.log(`No log files found for run: ${runId}`);
+    return null;
+  }
+
+  // Look for the specific run file by runId, fall back to newest
+  const specificFile = files.find((f) => f === `${matched.runId}.jsonl`);
+  return join(matched.eventsDir, specificFile ?? files[0]);
+}
+
 /**
  * Display logs with filtering and formatting
  *
  * @param options - Command options
  */
 export async function logsCommand(options: LogsOptions): Promise<void> {
+  // When --run <runId> is provided, resolve via central registry
+  if (options.run) {
+    const runFile = await resolveRunFileFromRegistry(options.run);
+    if (!runFile) {
+      return;
+    }
+    if (options.follow) {
+      await followLogs(runFile, options);
+    } else {
+      await displayLogs(runFile, options);
+    }
+    return;
+  }
+
   // Resolve project directory
   const resolved = resolveProject({ dir: options.dir });
   const naxDir = join(resolved.projectDir, "nax");
@@ -77,8 +159,8 @@ export async function logsCommand(options: LogsOptions): Promise<void> {
     return;
   }
 
-  // Determine which run to display
-  const runFile = await selectRunFile(runsDir, options.run);
+  // Determine which run to display (latest by default — --run handled above via registry)
+  const runFile = await selectRunFile(runsDir);
 
   if (!runFile) {
     throw new Error("No runs found for this feature");
@@ -95,9 +177,9 @@ export async function logsCommand(options: LogsOptions): Promise<void> {
 }
 
 /**
- * Select which run file to display
+ * Select which run file to display (always returns the latest run)
  */
-async function selectRunFile(runsDir: string, runTimestamp?: string): Promise<string | null> {
+async function selectRunFile(runsDir: string): Promise<string | null> {
   const files = readdirSync(runsDir)
     .filter((f) => f.endsWith(".jsonl") && f !== "latest.jsonl")
     .sort()
@@ -107,19 +189,7 @@ async function selectRunFile(runsDir: string, runTimestamp?: string): Promise<st
     return null;
   }
 
-  // If no specific run requested, use latest
-  if (!runTimestamp) {
-    return join(runsDir, files[0]);
-  }
-
-  // Find matching run by partial timestamp
-  const matchingFile = files.find((f) => f.startsWith(runTimestamp));
-
-  if (!matchingFile) {
-    throw new Error(`Run not found: ${runTimestamp}`);
-  }
-
-  return join(runsDir, matchingFile);
+  return join(runsDir, files[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/types.ts

@@ -309,7 +309,9 @@ export interface InteractionConfig {
     fallback: "continue" | "skip" | "escalate" | "abort";
   };
   /** Enable/disable built-in triggers */
-  triggers: Partial<Record<string, boolean | { enabled: boolean; fallback?: string; timeout?: number }>>;
+  triggers: Partial<
+    Record<string, boolean | { enabled: boolean; fallback?: string; timeout?: number; threshold?: number }>
+  >;
 }
 
 /** Test coverage context config */

package/src/execution/crash-recovery.ts

@@ -32,6 +32,8 @@ export interface CrashRecoveryContext {
   getStartTime?: () => number;
   getTotalStories?: () => number;
   getStoriesCompleted?: () => number;
+  /** Optional callback to emit run:errored event (fire-and-forget) */
+  emitError?: (reason: string) => void;
 }
 
 /**
@@ -171,6 +173,9 @@ export function installCrashHandlers(ctx: CrashRecoveryContext): () => void {
       await ctx.pidRegistry.killAll();
     }
 
+    // Emit run:errored event (fire-and-forget)
+    ctx.emitError?.(signal.toLowerCase());
+
     // Write fatal log
     await writeFatalLog(ctx.jsonlFilePath, signal);
 
@@ -209,6 +214,9 @@ export function installCrashHandlers(ctx: CrashRecoveryContext): () => void {
       await ctx.pidRegistry.killAll();
     }
 
+    // Emit run:errored event (fire-and-forget)
+    ctx.emitError?.("uncaughtException");
+
     // Write fatal log with stack trace
     await writeFatalLog(ctx.jsonlFilePath, "uncaughtException", error);
 
@@ -242,6 +250,9 @@ export function installCrashHandlers(ctx: CrashRecoveryContext): () => void {
       await ctx.pidRegistry.killAll();
     }
 
+    // Emit run:errored event (fire-and-forget)
+    ctx.emitError?.("unhandledRejection");
+
     // Write fatal log
     await writeFatalLog(ctx.jsonlFilePath, "unhandledRejection", error);
 

package/src/execution/executor-types.ts

@@ -40,7 +40,7 @@ export interface SequentialExecutionResult {
   storiesCompleted: number;
   totalCost: number;
   allStoryMetrics: StoryMetrics[];
-  exitReason: "completed" | "cost-limit" | "max-iterations" | "stalled" | "no-stories";
+  exitReason: "completed" | "cost-limit" | "max-iterations" | "stalled" | "no-stories" | "pre-merge-aborted";
 }
 
 /**

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

@@ -21,6 +21,7 @@ import { fireHook } from "../../hooks";
 import type { InteractionChain } from "../../interaction";
 import { initInteractionChain } from "../../interaction";
 import { getSafeLogger } from "../../logger";
+import { pipelineEventBus } from "../../pipeline/event-bus";
 import { loadPlugins } from "../../plugins/loader";
 import type { PluginRegistry } from "../../plugins/registry";
 import type { PRD } from "../../prd";
@@ -123,6 +124,9 @@ export async function setupRun(options: RunSetupOptions): Promise<RunSetupResult
     getStartTime: () => options.startTime,
     getTotalStories: options.getTotalStories,
     getStoriesCompleted: options.getStoriesCompleted,
+    emitError: (reason: string) => {
+      pipelineEventBus.emit({ type: "run:errored", reason, feature: options.feature });
+    },
   });
 
   // Load PRD (before try block so it's accessible in finally for onRunEnd)

package/src/execution/sequential-executor.ts

@@ -1,12 +1,15 @@
 /** Sequential Story Executor (ADR-005, Phase 4) — main execution loop. */
 
+import { checkCostExceeded, checkCostWarning, checkPreMerge, isTriggerEnabled } from "../interaction/triggers";
 import { getSafeLogger } from "../logger";
 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";
@@ -33,11 +36,14 @@ export async function executeSequential(
     0,
   ];
   const allStoryMetrics: StoryMetrics[] = [];
+  let warningSent = false;
 
   pipelineEventBus.clear();
   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,
@@ -65,6 +71,17 @@ export async function executeSequential(
         prdDirty = false;
       }
       if (isComplete(prd)) {
+        // pre-merge trigger: prompt before completing the run
+        if (ctx.interactionChain && isTriggerEnabled("pre-merge", ctx.config)) {
+          const shouldProceed = await checkPreMerge(
+            { featureName: ctx.feature, totalStories: prd.userStories.length, cost: totalCost },
+            ctx.config,
+            ctx.interactionChain,
+          );
+          if (!shouldProceed) {
+            return buildResult("pre-merge-aborted");
+          }
+        }
         pipelineEventBus.emit({
           type: "run:completed",
           totalStories: 0,
@@ -87,13 +104,24 @@ export async function executeSequential(
       if (!ctx.useBatch) lastStoryId = selection.story.id;
 
       if (totalCost >= ctx.config.execution.costLimit) {
-        pipelineEventBus.emit({
-          type: "run:paused",
-          reason: `Cost limit reached: $${totalCost.toFixed(2)}`,
-          storyId: selection.story.id,
-          cost: totalCost,
-        });
-        return buildResult("cost-limit");
+        const shouldProceed =
+          ctx.interactionChain && isTriggerEnabled("cost-exceeded", ctx.config)
+            ? await checkCostExceeded(
+                { featureName: ctx.feature, cost: totalCost, limit: ctx.config.execution.costLimit },
+                ctx.config,
+                ctx.interactionChain,
+              )
+            : false;
+        if (!shouldProceed) {
+          pipelineEventBus.emit({
+            type: "run:paused",
+            reason: `Cost limit reached: $${totalCost.toFixed(2)}`,
+            storyId: selection.story.id,
+            cost: totalCost,
+          });
+          return buildResult("cost-limit");
+        }
+        pipelineEventBus.emit({ type: "run:resumed", feature: ctx.feature });
       }
 
       pipelineEventBus.emit({
@@ -114,6 +142,20 @@ export async function executeSequential(
         iter.prdDirty,
       ];
 
+      if (ctx.interactionChain && isTriggerEnabled("cost-warning", ctx.config) && !warningSent) {
+        const costLimit = ctx.config.execution.costLimit;
+        const triggerCfg = ctx.config.interaction?.triggers?.["cost-warning"];
+        const threshold = typeof triggerCfg === "object" ? (triggerCfg.threshold ?? 0.8) : 0.8;
+        if (totalCost >= costLimit * threshold) {
+          await checkCostWarning(
+            { featureName: ctx.feature, cost: totalCost, limit: costLimit },
+            ctx.config,
+            ctx.interactionChain,
+          );
+          warningSent = true;
+        }
+      }
+
       if (iter.prdDirty) {
         prd = await loadPRD(ctx.prdPath);
         prdDirty = false;

package/src/interaction/plugins/auto.ts

@@ -38,6 +38,14 @@ interface DecisionResponse {
   reasoning: string;
 }
 
+/**
+ * Module-level deps for testability (_deps pattern).
+ * Override callLlm in tests to avoid spawning the claude CLI.
+ */
+export const _deps = {
+  callLlm: null as ((request: InteractionRequest) => Promise<DecisionResponse>) | null,
+};
+
 /**
  * Auto plugin for AI-powered interaction responses
  */
@@ -80,7 +88,8 @@ export class AutoInteractionPlugin implements InteractionPlugin {
     }
 
     try {
-      const decision = await this.callLlm(request);
+      const callFn = _deps.callLlm ?? this.callLlm.bind(this);
+      const decision = await callFn(request);
 
       // Check confidence threshold
       if (decision.confidence < (this.config.confidenceThreshold ?? 0.7)) {

package/src/pipeline/event-bus.ts

@@ -135,6 +135,17 @@ export interface StoryPausedEvent {
   cost: number;
 }
 
+export interface RunResumedEvent {
+  type: "run:resumed";
+  feature: string;
+}
+
+export interface RunErroredEvent {
+  type: "run:errored";
+  reason: string;
+  feature?: string;
+}
+
 /** Discriminated union of all pipeline events. */
 export type PipelineEvent =
   | StoryStartedEvent
@@ -150,7 +161,9 @@ export type PipelineEvent =
   | HumanReviewRequestedEvent
   | RunStartedEvent
   | RunPausedEvent
-  | StoryPausedEvent;
+  | StoryPausedEvent
+  | RunResumedEvent
+  | RunErroredEvent;
 
 export type PipelineEventType = PipelineEvent["type"];
 

package/src/pipeline/stages/completion.ts

@@ -13,6 +13,7 @@
  */
 
 import { appendProgress } from "../../execution/progress";
+import { checkReviewGate, isTriggerEnabled } from "../../interaction/triggers";
 import { getLogger } from "../../logger";
 import { collectBatchMetrics, collectStoryMetrics } from "../../metrics";
 import { countStories, markStoryPassed, savePRD } from "../../prd";
@@ -72,6 +73,18 @@ export const completionStage: PipelineStage = {
         modelTier: ctx.routing?.modelTier,
         testStrategy: ctx.routing?.testStrategy,
       });
+
+      // review-gate trigger: check if story needs re-review after passing
+      if (ctx.interaction && isTriggerEnabled("review-gate", ctx.config)) {
+        const shouldContinue = await _completionDeps.checkReviewGate(
+          { featureName: ctx.prd.feature, storyId: completedStory.id },
+          ctx.config,
+          ctx.interaction,
+        );
+        if (!shouldContinue) {
+          logger.warn("completion", "Story marked for re-review", { storyId: completedStory.id });
+        }
+      }
     }
 
     // Save PRD
@@ -89,3 +102,10 @@ export const completionStage: PipelineStage = {
     return { action: "continue" };
   },
 };
+
+/**
+ * Swappable dependencies for testing (avoids mock.module() which leaks in Bun 1.x).
+ */
+export const _completionDeps = {
+  checkReviewGate,
+};