@nathapp/nax 0.18.1

package/examples/plugins/console-reporter/index.test.ts

@@ -0,0 +1,207 @@
+/**
+ * Console Reporter Plugin Tests
+ */
+
+import { describe, test, expect, beforeEach, afterEach } from "bun:test";
+import type {
+  RunStartEvent,
+  StoryCompleteEvent,
+  RunEndEvent,
+} from "../../../src/plugins/types";
+import { validatePlugin } from "../../../src/plugins/validator";
+import consoleReporterPlugin from "./index";
+
+describe("Console Reporter Plugin", () => {
+  let consoleOutput: string[] = [];
+  const originalLog = console.log;
+
+  beforeEach(() => {
+    consoleOutput = [];
+    console.log = (...args: unknown[]) => {
+      consoleOutput.push(args.map(String).join(" "));
+    };
+  });
+
+  afterEach(() => {
+    console.log = originalLog;
+  });
+
+  test("plugin structure passes validation", () => {
+    const validated = validatePlugin(consoleReporterPlugin);
+    expect(validated).not.toBeNull();
+    expect(validated?.name).toBe("console-reporter");
+    expect(validated?.version).toBe("1.0.0");
+    expect(validated?.provides).toEqual(["reporter"]);
+  });
+
+  test("plugin has required fields", () => {
+    expect(consoleReporterPlugin.name).toBe("console-reporter");
+    expect(consoleReporterPlugin.version).toBe("1.0.0");
+    expect(consoleReporterPlugin.provides).toContain("reporter");
+    expect(consoleReporterPlugin.setup).toBeDefined();
+    expect(consoleReporterPlugin.teardown).toBeDefined();
+    expect(consoleReporterPlugin.extensions.reporter).toBeDefined();
+  });
+
+  test("setup() reads config.verbose", async () => {
+    await consoleReporterPlugin.setup?.({ verbose: true });
+    expect(consoleOutput.some(line => line.includes("verbose mode enabled"))).toBe(true);
+
+    consoleOutput = [];
+    await consoleReporterPlugin.setup?.({ verbose: false });
+    expect(consoleOutput.some(line => line.includes("verbose mode enabled"))).toBe(false);
+  });
+
+  test("setup() defaults verbose to false", async () => {
+    await consoleReporterPlugin.setup?.({});
+    expect(consoleOutput.some(line => line.includes("verbose mode enabled"))).toBe(false);
+  });
+
+  test("onRunStart prints banner with run details", async () => {
+    const event: RunStartEvent = {
+      runId: "run-123",
+      feature: "test-feature",
+      totalStories: 5,
+      startTime: "2026-02-27T10:00:00Z",
+    };
+
+    const reporter = consoleReporterPlugin.extensions.reporter;
+    await reporter?.onRunStart?.(event);
+
+    const output = consoleOutput.join("\n");
+    expect(output).toContain("Starting Run: test-feature");
+    expect(output).toContain("Run ID: run-123");
+    expect(output).toContain("Total Stories: 5");
+    expect(output).toContain("Start Time: 2026-02-27T10:00:00Z");
+    expect(output).toContain("=".repeat(60));
+  });
+
+  test("onStoryComplete prints status line with ✓ for completed", async () => {
+    const event: StoryCompleteEvent = {
+      runId: "run-123",
+      storyId: "US-001",
+      status: "completed",
+      durationMs: 1500,
+      cost: 0.0123,
+      tier: "balanced",
+      testStrategy: "three-session-tdd",
+    };
+
+    const reporter = consoleReporterPlugin.extensions.reporter;
+    await reporter?.onStoryComplete?.(event);
+
+    const output = consoleOutput.join("\n");
+    expect(output).toContain("✓");
+    expect(output).toContain("US-001");
+    expect(output).toContain("Tier: balanced");
+    expect(output).toContain("Strategy: three-session-tdd");
+    expect(output).toContain("Duration: 1500ms");
+    expect(output).toContain("Cost: $0.0123");
+  });
+
+  test("onStoryComplete prints status line with ✗ for failed", async () => {
+    const event: StoryCompleteEvent = {
+      runId: "run-123",
+      storyId: "US-002",
+      status: "failed",
+      durationMs: 2500,
+      cost: 0.0456,
+      tier: "powerful",
+      testStrategy: "three-session-tdd-lite",
+    };
+
+    const reporter = consoleReporterPlugin.extensions.reporter;
+    await reporter?.onStoryComplete?.(event);
+
+    const output = consoleOutput.join("\n");
+    expect(output).toContain("✗");
+    expect(output).toContain("US-002");
+    expect(output).toContain("Tier: powerful");
+    expect(output).toContain("Strategy: three-session-tdd-lite");
+  });
+
+  test("onRunEnd prints summary table", async () => {
+    const event: RunEndEvent = {
+      runId: "run-123",
+      totalDurationMs: 5000,
+      totalCost: 0.0789,
+      storySummary: {
+        completed: 3,
+        failed: 1,
+        skipped: 0,
+        paused: 1,
+      },
+    };
+
+    const reporter = consoleReporterPlugin.extensions.reporter;
+    await reporter?.onRunEnd?.(event);
+
+    const output = consoleOutput.join("\n");
+    expect(output).toContain("Run Summary");
+    expect(output).toContain("Run ID: run-123");
+    expect(output).toContain("Completed: 3/5");
+    expect(output).toContain("Failed:    1/5");
+    expect(output).toContain("Skipped:   0/5");
+    expect(output).toContain("Paused:    1/5");
+    expect(output).toContain("Total Duration: 5.00s");
+    expect(output).toContain("Total Cost:     $0.0789");
+  });
+
+  test("verbose mode adds extra output in onStoryComplete", async () => {
+    await consoleReporterPlugin.setup?.({ verbose: true });
+    consoleOutput = [];
+
+    const event: StoryCompleteEvent = {
+      runId: "run-123",
+      storyId: "US-001",
+      status: "completed",
+      durationMs: 1500,
+      cost: 0.0123,
+      tier: "balanced",
+      testStrategy: "three-session-tdd",
+    };
+
+    const reporter = consoleReporterPlugin.extensions.reporter;
+    await reporter?.onStoryComplete?.(event);
+
+    const output = consoleOutput.join("\n");
+    expect(output).toContain("[verbose]");
+    expect(output).toContain("Run ID: run-123");
+    expect(output).toContain("Status: completed");
+  });
+
+  test("verbose mode adds extra output in onRunEnd", async () => {
+    await consoleReporterPlugin.setup?.({ verbose: true });
+    consoleOutput = [];
+
+    const event: RunEndEvent = {
+      runId: "run-123",
+      totalDurationMs: 5000,
+      totalCost: 0.0789,
+      storySummary: {
+        completed: 3,
+        failed: 1,
+        skipped: 0,
+        paused: 1,
+      },
+    };
+
+    const reporter = consoleReporterPlugin.extensions.reporter;
+    await reporter?.onRunEnd?.(event);
+
+    const output = consoleOutput.join("\n");
+    expect(output).toContain("Run completed in verbose mode");
+  });
+
+  test("reporter has required methods", () => {
+    const reporter = consoleReporterPlugin.extensions.reporter;
+    expect(reporter?.name).toBe("console-reporter");
+    expect(typeof reporter?.onRunStart).toBe("function");
+    expect(typeof reporter?.onStoryComplete).toBe("function");
+    expect(typeof reporter?.onRunEnd).toBe("function");
+  });
+
+  test("teardown completes without errors", async () => {
+    await expect(consoleReporterPlugin.teardown?.()).resolves.toBeUndefined();
+  });
+});

package/examples/plugins/console-reporter/index.ts

@@ -0,0 +1,110 @@
+/**
+ * Console Reporter Plugin
+ *
+ * Sample reporter plugin that demonstrates the plugin API.
+ * Prints formatted output to the console for run lifecycle events.
+ */
+
+import type {
+  NaxPlugin,
+  IReporter,
+  RunStartEvent,
+  StoryCompleteEvent,
+  RunEndEvent,
+} from "../../../src/plugins/types";
+
+interface ConsoleReporterConfig {
+  verbose?: boolean;
+}
+
+let verboseMode = false;
+
+/**
+ * Console reporter implementation.
+ */
+const reporter: IReporter = {
+  name: "console-reporter",
+
+  async onRunStart(event: RunStartEvent): Promise<void> {
+    console.log("\n" + "=".repeat(60));
+    console.log(`🚀 Starting Run: ${event.feature}`);
+    console.log(`   Run ID: ${event.runId}`);
+    console.log(`   Total Stories: ${event.totalStories}`);
+    console.log(`   Start Time: ${event.startTime}`);
+    console.log("=".repeat(60) + "\n");
+
+    if (verboseMode) {
+      console.log("[console-reporter] Verbose mode enabled");
+    }
+  },
+
+  async onStoryComplete(event: StoryCompleteEvent): Promise<void> {
+    const statusIcon = event.status === "completed" ? "✓" : "✗";
+    const statusColor = event.status === "completed" ? "\x1b[32m" : "\x1b[31m";
+    const resetColor = "\x1b[0m";
+
+    console.log(
+      `${statusColor}${statusIcon}${resetColor} ${event.storyId} | ` +
+      `Tier: ${event.tier} | ` +
+      `Strategy: ${event.testStrategy} | ` +
+      `Duration: ${event.durationMs}ms | ` +
+      `Cost: $${event.cost.toFixed(4)}`
+    );
+
+    if (verboseMode) {
+      console.log(`   [verbose] Run ID: ${event.runId}, Status: ${event.status}`);
+    }
+  },
+
+  async onRunEnd(event: RunEndEvent): Promise<void> {
+    console.log("\n" + "=".repeat(60));
+    console.log("📊 Run Summary");
+    console.log("=".repeat(60));
+
+    const { storySummary } = event;
+    const total = storySummary.completed + storySummary.failed + storySummary.skipped + storySummary.paused;
+
+    console.log(`Run ID: ${event.runId}`);
+    console.log(`\nStory Results:`);
+    console.log(`  ✓ Completed: ${storySummary.completed}/${total}`);
+    console.log(`  ✗ Failed:    ${storySummary.failed}/${total}`);
+    console.log(`  ⊘ Skipped:   ${storySummary.skipped}/${total}`);
+    console.log(`  ⏸ Paused:    ${storySummary.paused}/${total}`);
+    console.log(`\nMetrics:`);
+    console.log(`  Total Duration: ${(event.totalDurationMs / 1000).toFixed(2)}s`);
+    console.log(`  Total Cost:     $${event.totalCost.toFixed(4)}`);
+    console.log("=".repeat(60) + "\n");
+
+    if (verboseMode) {
+      console.log("[console-reporter] Run completed in verbose mode");
+    }
+  },
+};
+
+/**
+ * Console reporter plugin export.
+ */
+const consoleReporterPlugin: NaxPlugin = {
+  name: "console-reporter",
+  version: "1.0.0",
+  provides: ["reporter"],
+
+  async setup(config: Record<string, unknown>): Promise<void> {
+    const reporterConfig = config as ConsoleReporterConfig;
+    verboseMode = reporterConfig.verbose ?? false;
+
+    if (verboseMode) {
+      console.log("[console-reporter] Plugin initialized with verbose mode enabled");
+    }
+  },
+
+  async teardown(): Promise<void> {
+    // No cleanup needed for console output
+  },
+
+  extensions: {
+    reporter,
+  },
+};
+
+export default consoleReporterPlugin;

package/nax/config.json

@@ -0,0 +1,147 @@
+{
+  "version": 1,
+  "models": {
+    "fast": {
+      "provider": "anthropic",
+      "model": "haiku"
+    },
+    "balanced": {
+      "provider": "anthropic",
+      "model": "sonnet"
+    },
+    "powerful": {
+      "provider": "anthropic",
+      "model": "sonnet"
+    }
+  },
+  "autoMode": {
+    "enabled": true,
+    "defaultAgent": "claude",
+    "fallbackOrder": [
+      "claude"
+    ],
+    "complexityRouting": {
+      "simple": "fast",
+      "medium": "balanced",
+      "complex": "balanced",
+      "expert": "powerful"
+    },
+    "escalation": {
+      "enabled": true,
+      "tierOrder": [
+        {
+          "tier": "fast",
+          "attempts": 3
+        },
+        {
+          "tier": "balanced",
+          "attempts": 2
+        },
+        {
+          "tier": "powerful",
+          "attempts": 1
+        }
+      ],
+      "escalateEntireBatch": false
+    }
+  },
+  "routing": {
+    "strategy": "llm",
+    "llm": {
+      "model": "fast",
+      "fallbackToKeywords": true,
+      "cacheDecisions": true,
+      "mode": "hybrid",
+      "timeoutMs": 15000
+    }
+  },
+  "execution": {
+    "maxIterations": 6,
+    "iterationDelayMs": 2000,
+    "costLimit": 8.0,
+    "sessionTimeoutSeconds": 600,
+    "verificationTimeoutSeconds": 300,
+    "maxStoriesPerFeature": 15,
+    "rectification": {
+      "enabled": true,
+      "maxRetries": 2,
+      "fullSuiteTimeoutSeconds": 120,
+      "maxFailureSummaryChars": 2000,
+      "abortOnIncreasingFailures": true
+    }
+  },
+  "quality": {
+    "requireTypecheck": false,
+    "requireLint": true,
+    "requireTests": true,
+    "commands": {
+      "test": "bun test --no-coverage",
+      "typecheck": "bun x tsc --noEmit",
+      "lint": "bun x biome check src/ bin/"
+    },
+    "forceExit": false,
+    "detectOpenHandles": true,
+    "detectOpenHandlesRetries": 1,
+    "gracePeriodMs": 5000,
+    "drainTimeoutMs": 2000,
+    "shell": "/bin/sh",
+    "stripEnvVars": [
+      "CLAUDECODE",
+      "REPL_ID",
+      "AGENT"
+    ],
+    "environmentalEscalationDivisor": 2
+  },
+  "tdd": {
+    "maxRetries": 2,
+    "autoVerifyIsolation": true,
+    "autoApproveVerifier": true,
+    "strategy": "lite",
+    "sessionTiers": {
+      "testWriter": "balanced",
+      "verifier": "fast"
+    }
+  },
+  "constitution": {
+    "enabled": true,
+    "path": "constitution.md",
+    "maxTokens": 2000
+  },
+  "analyze": {
+    "llmEnhanced": false,
+    "model": "balanced",
+    "fallbackToKeywords": true,
+    "maxCodebaseSummaryTokens": 5000
+  },
+  "review": {
+    "enabled": true,
+    "checks": [
+      "test",
+      "lint"
+    ],
+    "commands": {
+      "test": "bun test --no-coverage",
+      "typecheck": "bun x tsc --noEmit",
+      "lint": "bun x biome check src/ bin/"
+    }
+  },
+  "plan": {
+    "model": "balanced",
+    "outputPath": "spec.md"
+  },
+  "acceptance": {
+    "enabled": false,
+    "maxRetries": 2,
+    "generateTests": false,
+    "testPath": "acceptance.test.ts"
+  },
+  "context": {
+    "testCoverage": {
+      "enabled": true,
+      "detail": "names-and-counts",
+      "maxTokens": 500,
+      "testPattern": "**/*.test.{ts,js}",
+      "scopeToStory": true
+    }
+  }
+}

package/nax/features/bugfix-v0171/prd.json

@@ -0,0 +1,52 @@
+{
+  "project": "nax",
+  "branchName": "feat/v0.17.x-bugfixes",
+  "feature": "bugfix-v0171",
+  "userStories": [
+    {
+      "id": "BF-001",
+      "title": "Emit run.complete on SIGTERM shutdown (BUG-017)",
+      "description": "When nax receives SIGTERM, the crash-recovery handler shuts down cleanly but never emits the final run.complete JSONL event. This means the run log has no aggregate cost/duration summary when nax is killed externally.\n\nFind where SIGTERM is caught in src/execution/ and ensure a run.complete event is emitted before exit with: totalCost (sum of agent.complete costs), totalIterations, exitReason='sigterm', duration.\n\nAcceptance criteria:\n1. When nax is killed with SIGTERM mid-run, JSONL ends with run.complete event containing totalCost, totalIterations, exitReason='sigterm', duration\n2. Existing tests pass\n3. Add a unit test simulating SIGTERM that verifies run.complete is written",
+      "complexity": "simple",
+      "status": "pending",
+      "attempts": 0,
+      "priorErrors": [
+        "Attempt 1 failed with model tier: fast"
+      ],
+      "escalations": [],
+      "dependencies": [],
+      "tags": [],
+      "acceptanceCriteria": [],
+      "storyPoints": 1,
+      "routing": {
+        "complexity": "simple",
+        "modelTier": "balanced",
+        "testStrategy": "three-session-tdd-lite",
+        "reasoning": "three-session-tdd-lite: public-api, strategy:lite"
+      }
+    },
+    {
+      "id": "BF-002",
+      "title": "Add storyId to all JSONL events (BUG-020)",
+      "description": "Many JSONL events have empty or missing storyId. Audit and fix these event emitters to include storyId when a story is active:\n- src/pipeline/stages/verify.ts (verify info/debug events)\n- src/pipeline/stages/execution.ts (execution events)\n- src/tdd/orchestrator.ts (tdd session events)\n- src/execution/pipeline-result-handler.ts (escalation events)\n\nAcceptance criteria:\n1. Events at stages agent.start, agent.complete, verify, tdd, execution, escalation include storyId in data when a story is active\n2. Existing tests pass\n3. Add tests verifying storyId presence on key events",
+      "complexity": "simple",
+      "status": "pending",
+      "attempts": 0,
+      "priorErrors": [
+        "Attempt 1 failed with model tier: fast"
+      ],
+      "escalations": [],
+      "dependencies": [],
+      "tags": [],
+      "acceptanceCriteria": [],
+      "storyPoints": 1,
+      "routing": {
+        "complexity": "simple",
+        "modelTier": "balanced",
+        "testStrategy": "three-session-tdd-lite",
+        "reasoning": "three-session-tdd-lite: strategy:lite"
+      }
+    }
+  ],
+  "updatedAt": "2026-03-02T08:59:51.238Z"
+}

package/nax/features/config-management/prd.json

@@ -0,0 +1,108 @@
+{
+  "project": "nax",
+  "branchName": "feat/v0.17.0-config-management",
+  "feature": "config-management",
+  "userStories": [
+    {
+      "id": "CM-001",
+      "title": "nax config --explain",
+      "description": "Add `nax config` CLI command with `--explain` flag that dumps the effective merged config with inline comments. Resolution order: defaults \u2192 global (~/.nax/config.json) \u2192 project (nax/config.json) \u2192 CLI overrides. Each field gets a one-line human-readable description of what it does. Fields overridden by project config are annotated with '(project override)' vs '(global)' vs '(default)'. Output format: YAML-like with # comments. Must cover all sections: models, routing, execution, tdd, quality, review, context, constitution, analyze, plan, acceptance, interaction, autoMode. Implementation: add `src/cli/config.ts` with `configCommand()`. Read merged config from loader, annotate each field using a static descriptions map (Record<string, string>). Register in `src/cli/index.ts`.",
+      "complexity": "medium",
+      "status": "passed",
+      "attempts": 1,
+      "escalations": [],
+      "dependencies": [],
+      "tags": [
+        "cli",
+        "config",
+        "dx"
+      ],
+      "acceptanceCriteria": [
+        "Running `nax config --explain` outputs all config fields with descriptions",
+        "Each field shows its source: (default), (global), or (project override)",
+        "Output is human-readable, not raw JSON",
+        "Works from any directory (uses existing config loader)"
+      ],
+      "storyPoints": 1,
+      "priorErrors": [
+        "Attempt 1 failed with model tier: fast",
+        "Attempt 1 failed with model tier: balanced"
+      ],
+      "passes": true,
+      "routing": {
+        "complexity": "simple",
+        "modelTier": "powerful",
+        "testStrategy": "three-session-tdd-lite",
+        "reasoning": "three-session-tdd-lite: strategy:lite"
+      }
+    },
+    {
+      "id": "CM-002",
+      "title": "nax config --diff",
+      "description": "Add `--diff` flag to `nax config` that shows only fields where project config overrides the global config. Output format: table or structured list showing field path, project value, and global value. Skip fields that are identical or only set at one layer. If no project config exists, print 'No project config found \u2014 using global defaults'. Implementation: in `src/cli/config.ts`, load global and project configs separately (extend loader to expose both), deep-diff them, format as table. Use the same descriptions map from CM-001 to add context.",
+      "complexity": "medium",
+      "status": "passed",
+      "attempts": 1,
+      "escalations": [],
+      "dependencies": [
+        "CM-001"
+      ],
+      "tags": [
+        "cli",
+        "config",
+        "dx"
+      ],
+      "acceptanceCriteria": [
+        "Running `nax config --diff` shows only fields where project differs from global",
+        "Each differing field shows: field path, project value, global value",
+        "Shows 'No project config found' when no nax/config.json exists",
+        "Works alongside --explain (mutually exclusive flags)"
+      ],
+      "storyPoints": 1,
+      "priorErrors": [
+        "Attempt 1 failed with model tier: fast",
+        "Attempt 1 failed with model tier: balanced"
+      ],
+      "passes": false,
+      "routing": {
+        "complexity": "simple",
+        "modelTier": "powerful",
+        "testStrategy": "three-session-tdd-lite",
+        "reasoning": "three-session-tdd-lite: strategy:lite"
+      }
+    },
+    {
+      "id": "CM-003",
+      "title": "nax config (default view)",
+      "description": "When `nax config` is run without flags, print the effective merged config as formatted JSON with a header showing the config sources found (global path, project path if exists). This is the quick 'what am I actually running with?' view. Implementation: default action in `src/cli/config.ts`. Load merged config, pretty-print with JSON.stringify(config, null, 2). Add header lines showing which config files were found and loaded.",
+      "complexity": "simple",
+      "status": "passed",
+      "attempts": 1,
+      "escalations": [],
+      "dependencies": [],
+      "tags": [
+        "cli",
+        "config",
+        "dx"
+      ],
+      "acceptanceCriteria": [
+        "Running `nax config` prints the effective merged config as formatted JSON",
+        "Header shows paths of config files found (global, project)",
+        "Missing config files noted in header"
+      ],
+      "storyPoints": 1,
+      "priorErrors": [
+        "Attempt 1 failed with model tier: fast",
+        "Attempt 1 failed with model tier: balanced"
+      ],
+      "passes": true,
+      "routing": {
+        "complexity": "simple",
+        "modelTier": "powerful",
+        "testStrategy": "three-session-tdd-lite",
+        "reasoning": "three-session-tdd-lite: strategy:lite"
+      }
+    }
+  ],
+  "updatedAt": "2026-03-02T07:38:25.351Z"
+}

package/nax/features/config-management/progress.txt

@@ -0,0 +1,5 @@
+[2026-03-02T06:07:47.434Z] CM-001 — FAILED — nax config --explain — Execution failed
+[2026-03-02T08:15:00.000Z] CM-002 — PASSED — nax config --diff — All acceptance criteria met
+[2026-03-02T07:12:34.595Z] CM-002 — FAILED — nax config --diff — Execution failed
+[2026-03-02T09:30:00.000Z] CM-003 — PASSED — nax config (default view) — All acceptance criteria met
+[2026-03-02T07:20:20.866Z] CM-003 — FAILED — nax config (default view) — Execution failed