@nathapp/nax 0.18.1

package/test/US-002-orchestrator.test.ts

@@ -0,0 +1,246 @@
+/**
+ * US-002: Precheck orchestrator with formatted output
+ *
+ * Acceptance criteria verification tests
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+
+// Skip in CI: AC2, AC5, AC6 call runPrecheck() which includes checkClaudeCLI as a
+// Tier 1 blocker. Without the claude binary installed, blockers.length > 0 always,
+// breaking assertions like expect(blockers.length).toBe(0). These ACs test correct
+// orchestration behaviour and pass reliably on Mac01/VPS where claude is installed.
+const skipInCI = process.env.CI ? test.skip : test;
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { NaxConfig } from "../src/config";
+import type { PRD } from "../src/prd/types";
+import { EXIT_CODES, runPrecheck } from "../src/precheck";
+
+// Helper to create a minimal valid git environment
+async function setupGitRepo(dir: string): Promise<void> {
+  mkdirSync(join(dir, ".git"));
+  await Bun.spawn(["git", "init"], { cwd: dir, stdout: "ignore", stderr: "ignore" }).exited;
+  await Bun.spawn(["git", "config", "user.name", "Test"], { cwd: dir, stdout: "ignore", stderr: "ignore" }).exited;
+  await Bun.spawn(["git", "config", "user.email", "test@test.com"], { cwd: dir, stdout: "ignore", stderr: "ignore" })
+    .exited;
+  writeFileSync(join(dir, "README.md"), "# Test");
+  await Bun.spawn(["git", "add", "."], { cwd: dir, stdout: "ignore", stderr: "ignore" }).exited;
+  await Bun.spawn(["git", "commit", "-m", "init"], { cwd: dir, stdout: "ignore", stderr: "ignore" }).exited;
+}
+
+const createConfig = (workdir: string): NaxConfig =>
+  ({
+    execution: {
+      maxIterations: 10,
+      iterationDelayMs: 1000,
+      maxCostUSD: 10,
+      testCommand: "echo test",
+      lintCommand: "echo lint",
+      typecheckCommand: "echo typecheck",
+      contextProviderTokenBudget: 2000,
+      requireExplicitContextFiles: false,
+      preflightExpectedFilesEnabled: false,
+      cwd: workdir,
+    },
+    autoMode: {
+      enabled: false,
+      defaultAgent: "test",
+      fallbackOrder: [],
+      complexityRouting: {},
+      escalation: { enabled: false, tierOrder: [] },
+    },
+    quality: { minTestCoverage: 80, requireTypecheck: true, requireLint: true },
+    tdd: { strategy: "auto", skipGeneratedVerificationTests: false },
+    models: {},
+    rectification: {
+      enabled: true,
+      maxRetries: 2,
+      fullSuiteTimeoutSeconds: 120,
+      maxFailureSummaryChars: 2000,
+      abortOnIncreasingFailures: true,
+    },
+  }) as NaxConfig;
+
+const createPRD = (): PRD => ({
+  project: "test",
+  feature: "test-feature",
+  branchName: "test",
+  createdAt: new Date().toISOString(),
+  updatedAt: new Date().toISOString(),
+  userStories: [
+    {
+      id: "US-001",
+      title: "Test",
+      description: "Test description",
+      acceptanceCriteria: [],
+      tags: [],
+      dependencies: [],
+      status: "pending",
+      passes: false,
+      escalations: [],
+      attempts: 0,
+    },
+  ],
+});
+
+describe("US-002: Precheck orchestrator acceptance criteria", () => {
+  let testDir: string;
+
+  beforeEach(() => {
+    testDir = mkdtempSync(join(tmpdir(), "nax-test-us002-"));
+  });
+
+  afterEach(() => {
+    rmSync(testDir, { recursive: true, force: true });
+  });
+
+  test("AC1: Runs Tier 1 checks first, stops on first failure", async () => {
+    // No .git directory - should fail on first check
+    const config = createConfig(testDir);
+    const prd = createPRD();
+
+    const { result } = await runPrecheck(config, prd, { workdir: testDir, format: "json" });
+
+    // Should have exactly 1 blocker (fail-fast)
+    expect(result.blockers.length).toBe(1);
+    expect(result.blockers[0].name).toBe("git-repo-exists");
+  });
+
+  skipInCI("AC2: Runs all Tier 2 checks even if some warn", async () => {
+    // Create valid Tier 1 environment
+    await setupGitRepo(testDir);
+    mkdirSync(join(testDir, "node_modules"));
+
+    const config = createConfig(testDir);
+    const prd = createPRD();
+
+    const { result } = await runPrecheck(config, prd, { workdir: testDir, format: "json" });
+
+    // No blockers
+    expect(result.blockers.length).toBe(0);
+
+    // All Tier 2 checks should run (5 total)
+    // At least 2 will fail (CLAUDE.md, .gitignore)
+    expect(result.warnings.length).toBeGreaterThanOrEqual(2);
+  });
+
+  test("AC3: Human output shows emoji per check result", async () => {
+    await setupGitRepo(testDir);
+    mkdirSync(join(testDir, "node_modules"));
+
+    const config = createConfig(testDir);
+    const prd = createPRD();
+
+    // Capture console output
+    const originalLog = console.log;
+    const logs: string[] = [];
+    console.log = (msg: string) => logs.push(msg);
+
+    try {
+      await runPrecheck(config, prd, { workdir: testDir, format: "human" });
+
+      // Should have emoji indicators
+      const hasCheckmark = logs.some((l) => l.includes("✓"));
+      const hasWarning = logs.some((l) => l.includes("⚠"));
+
+      expect(hasCheckmark || hasWarning).toBe(true);
+    } finally {
+      console.log = originalLog;
+    }
+  });
+
+  test("AC4: JSON output matches spec schema", async () => {
+    await setupGitRepo(testDir);
+    mkdirSync(join(testDir, "node_modules"));
+
+    const config = createConfig(testDir);
+    const prd = createPRD();
+
+    const originalLog = console.log;
+    let jsonOutput = "";
+    console.log = (msg: string) => {
+      jsonOutput += msg;
+    };
+
+    try {
+      await runPrecheck(config, prd, { workdir: testDir, format: "json" });
+
+      const output = JSON.parse(jsonOutput);
+
+      // Verify schema fields
+      expect(typeof output.passed).toBe("boolean");
+      expect(Array.isArray(output.blockers)).toBe(true);
+      expect(Array.isArray(output.warnings)).toBe(true);
+      expect(output.summary).toBeDefined();
+      expect(typeof output.summary.total).toBe("number");
+      expect(typeof output.summary.passed).toBe("number");
+      expect(typeof output.summary.failed).toBe("number");
+      expect(typeof output.summary.warnings).toBe("number");
+      expect(output.feature).toBe("test-feature");
+    } finally {
+      console.log = originalLog;
+    }
+  });
+
+  skipInCI("AC5: Exit code 0 for pass, 1 for blocker, 2 for invalid PRD", async () => {
+    // Test exit code 0 (pass)
+    await setupGitRepo(testDir);
+    mkdirSync(join(testDir, "node_modules"));
+    writeFileSync(join(testDir, "CLAUDE.md"), "# Test");
+    writeFileSync(join(testDir, ".gitignore"), "nax.lock\nruns/\ntest/tmp/");
+    await Bun.spawn(["git", "add", "."], { cwd: testDir, stdout: "ignore" }).exited;
+    await Bun.spawn(["git", "commit", "-m", "add"], { cwd: testDir, stdout: "ignore" }).exited;
+
+    let config = createConfig(testDir);
+    const prd = createPRD();
+    let result = await runPrecheck(config, prd, { workdir: testDir, format: "json" });
+    expect(result.exitCode).toBe(EXIT_CODES.SUCCESS);
+
+    // Test exit code 1 (blocker)
+    const testDir2 = mkdtempSync(join(tmpdir(), "nax-test-blocker-"));
+    config = createConfig(testDir2);
+    result = await runPrecheck(config, prd, { workdir: testDir2, format: "json" });
+    expect(result.exitCode).toBe(EXIT_CODES.BLOCKER);
+    rmSync(testDir2, { recursive: true, force: true });
+
+    // Test exit code 2 (invalid PRD)
+    const testDir3 = mkdtempSync(join(tmpdir(), "nax-test-invalid-prd-"));
+    await setupGitRepo(testDir3);
+    mkdirSync(join(testDir3, "node_modules"));
+    config = createConfig(testDir3);
+    const invalidPRD: PRD = {
+      ...prd,
+      userStories: [{ ...prd.userStories[0], id: "", title: "", description: "" }],
+    };
+    result = await runPrecheck(config, invalidPRD, { workdir: testDir3, format: "json" });
+    expect(result.exitCode).toBe(EXIT_CODES.INVALID_PRD);
+    rmSync(testDir3, { recursive: true, force: true });
+  });
+
+  test("AC6: Summary line shows total checks/passed/failed/warnings", async () => {
+    await setupGitRepo(testDir);
+    mkdirSync(join(testDir, "node_modules"));
+
+    const config = createConfig(testDir);
+    const prd = createPRD();
+
+    const originalLog = console.log;
+    const logs: string[] = [];
+    console.log = (msg: string) => logs.push(msg);
+
+    try {
+      await runPrecheck(config, prd, { workdir: testDir, format: "human" });
+
+      // Should have summary with counts
+      const hasSummary = logs.some(
+        (l) => l.includes("total") && l.includes("passed") && (l.includes("failed") || l.includes("warnings")),
+      );
+
+      expect(hasSummary).toBe(true);
+    } finally {
+      console.log = originalLog;
+    }
+  });
+});

package/test/acceptance/cm-003-default-view.test.ts

@@ -0,0 +1,194 @@
+/**
+ * Acceptance Tests for CM-003: nax config (default view)
+ *
+ * Tests the acceptance criteria for running `nax config` without flags.
+ *
+ * ACCEPTANCE CRITERIA:
+ * 1. Running `nax config` prints the effective merged config as formatted JSON
+ * 2. Header shows paths of config files found (global, project)
+ * 3. Missing config files noted in header
+ */
+
+import { describe, test, expect, beforeEach, afterEach } from "bun:test";
+import { mkdtempSync, rmSync, writeFileSync, mkdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+describe("CM-003: nax config (default view)", () => {
+  let tempDir: string;
+  let originalCwd: string;
+
+  beforeEach(() => {
+    tempDir = mkdtempSync(join(tmpdir(), "cm-003-test-"));
+    originalCwd = process.cwd();
+  });
+
+  afterEach(() => {
+    process.chdir(originalCwd);
+    rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  // AC1: Running `nax config` prints the effective merged config as formatted JSON
+  test("AC1: prints effective merged config as formatted JSON", async () => {
+    process.chdir(tempDir);
+
+    const proc = Bun.spawn(["bun", join(import.meta.dir, "../../bin/nax.ts"), "config"], {
+      cwd: tempDir,
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+
+    const output = await new Response(proc.stdout).text();
+    const exitCode = await proc.exited;
+
+    expect(exitCode).toBe(0);
+
+    // Should output valid JSON
+    const lines = output.split("\n");
+    const jsonStartIndex = lines.findIndex((line) => line.startsWith("{"));
+    expect(jsonStartIndex).toBeGreaterThanOrEqual(0);
+
+    const jsonOutput = lines.slice(jsonStartIndex).join("\n");
+    expect(() => JSON.parse(jsonOutput)).not.toThrow();
+
+    // Verify it's the merged config (contains version, models, etc.)
+    const parsed = JSON.parse(jsonOutput);
+    expect(parsed.version).toBe(1);
+    expect(parsed.models).toBeDefined();
+    expect(parsed.autoMode).toBeDefined();
+    expect(parsed.execution).toBeDefined();
+
+    // Verify it's formatted (pretty-printed with indentation)
+    expect(jsonOutput).toContain("  "); // Should have 2-space indentation
+  });
+
+  // AC2: Header shows paths of config files found (global, project)
+  test("AC2: header shows global config path", async () => {
+    process.chdir(tempDir);
+
+    const proc = Bun.spawn(["bun", join(import.meta.dir, "../../bin/nax.ts"), "config"], {
+      cwd: tempDir,
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+
+    const output = await new Response(proc.stdout).text();
+    const exitCode = await proc.exited;
+
+    expect(exitCode).toBe(0);
+
+    // Should show global config line
+    expect(output).toContain("// Global config:");
+  });
+
+  test("AC2: header shows project config path when present", async () => {
+    // Create project config
+    const naxDir = join(tempDir, "nax");
+    mkdirSync(naxDir, { recursive: true });
+    writeFileSync(
+      join(naxDir, "config.json"),
+      JSON.stringify({
+        execution: {
+          maxIterations: 42,
+        },
+      }),
+    );
+
+    process.chdir(tempDir);
+
+    const proc = Bun.spawn(["bun", join(import.meta.dir, "../../bin/nax.ts"), "config"], {
+      cwd: tempDir,
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+
+    const output = await new Response(proc.stdout).text();
+    const exitCode = await proc.exited;
+
+    expect(exitCode).toBe(0);
+
+    // Should show project config path
+    expect(output).toContain("// Project config:");
+    expect(output).toContain("config.json");
+
+    // Verify the merged config reflects project override
+    const lines = output.split("\n");
+    const jsonStartIndex = lines.findIndex((line) => line.startsWith("{"));
+    const jsonOutput = lines.slice(jsonStartIndex).join("\n");
+    const parsed = JSON.parse(jsonOutput);
+    expect(parsed.execution.maxIterations).toBe(42);
+  });
+
+  // AC3: Missing config files noted in header
+  test("AC3: notes missing project config in header", async () => {
+    // Use a directory without nax/config.json
+    const isolatedDir = join(tempDir, "isolated");
+    mkdirSync(isolatedDir, { recursive: true });
+    process.chdir(isolatedDir);
+
+    const proc = Bun.spawn(["bun", join(import.meta.dir, "../../bin/nax.ts"), "config"], {
+      cwd: isolatedDir,
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+
+    const output = await new Response(proc.stdout).text();
+    const exitCode = await proc.exited;
+
+    expect(exitCode).toBe(0);
+
+    // Should indicate project config is not found
+    expect(output).toContain("// Project config:");
+    expect(output).toContain("(not found)");
+  });
+
+  // Additional verification: header includes resolution order info
+  test("header includes resolution order information", async () => {
+    process.chdir(tempDir);
+
+    const proc = Bun.spawn(["bun", join(import.meta.dir, "../../bin/nax.ts"), "config"], {
+      cwd: tempDir,
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+
+    const output = await new Response(proc.stdout).text();
+    const exitCode = await proc.exited;
+
+    expect(exitCode).toBe(0);
+
+    // Should show resolution order
+    expect(output).toContain("// Resolution order:");
+    expect(output).toContain("defaults");
+    expect(output).toContain("global");
+    expect(output).toContain("project");
+  });
+
+  // Additional verification: header precedes JSON
+  test("header appears before JSON output with blank line separator", async () => {
+    process.chdir(tempDir);
+
+    const proc = Bun.spawn(["bun", join(import.meta.dir, "../../bin/nax.ts"), "config"], {
+      cwd: tempDir,
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+
+    const output = await new Response(proc.stdout).text();
+    const exitCode = await proc.exited;
+
+    expect(exitCode).toBe(0);
+
+    const lines = output.split("\n");
+
+    // Header should come before JSON
+    const headerIndex = lines.findIndex((line) => line.includes("// nax Configuration"));
+    const jsonIndex = lines.findIndex((line) => line.startsWith("{"));
+
+    expect(headerIndex).toBeGreaterThanOrEqual(0);
+    expect(jsonIndex).toBeGreaterThan(headerIndex);
+
+    // Should have blank line between header and JSON
+    expect(lines[jsonIndex - 1]).toBe("");
+  });
+});

package/test/execution/pid-registry.test.ts

@@ -0,0 +1,240 @@
+/**
+ * PID Registry Tests
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { existsSync, mkdirSync, rmSync } from "node:fs";
+import { PidRegistry } from "../../src/execution/pid-registry";
+
+const TEST_WORKDIR = "/tmp/nax-pid-registry-test";
+const PID_FILE = `${TEST_WORKDIR}/.nax-pids`;
+
+describe("PidRegistry", () => {
+  beforeEach(() => {
+    // Create test workdir
+    if (!existsSync(TEST_WORKDIR)) {
+      mkdirSync(TEST_WORKDIR, { recursive: true });
+    }
+
+    // Clean up any existing .nax-pids file
+    if (existsSync(PID_FILE)) {
+      rmSync(PID_FILE);
+    }
+  });
+
+  afterEach(() => {
+    // Cleanup test workdir
+    if (existsSync(TEST_WORKDIR)) {
+      rmSync(TEST_WORKDIR, { recursive: true });
+    }
+  });
+
+  test("register() adds PID to in-memory set and writes to file", async () => {
+    const registry = new PidRegistry(TEST_WORKDIR);
+
+    await registry.register(12345);
+
+    // Check in-memory state
+    expect(registry.getPids()).toEqual([12345]);
+
+    // Check file content
+    const content = await Bun.file(PID_FILE).text();
+    const lines = content.split("\n").filter((line) => line.trim());
+    expect(lines.length).toBe(1);
+
+    const entry = JSON.parse(lines[0]);
+    expect(entry.pid).toBe(12345);
+    expect(entry.workdir).toBe(TEST_WORKDIR);
+    expect(entry.spawnedAt).toBeDefined();
+  });
+
+  test("register() appends multiple PIDs to file", async () => {
+    const registry = new PidRegistry(TEST_WORKDIR);
+
+    await registry.register(12345);
+    await registry.register(67890);
+
+    // Check in-memory state
+    expect(registry.getPids()).toEqual([12345, 67890]);
+
+    // Check file content
+    const content = await Bun.file(PID_FILE).text();
+    const lines = content.split("\n").filter((line) => line.trim());
+    expect(lines.length).toBe(2);
+
+    const entry1 = JSON.parse(lines[0]);
+    expect(entry1.pid).toBe(12345);
+
+    const entry2 = JSON.parse(lines[1]);
+    expect(entry2.pid).toBe(67890);
+  });
+
+  test("unregister() removes PID from in-memory set and rewrites file", async () => {
+    const registry = new PidRegistry(TEST_WORKDIR);
+
+    await registry.register(12345);
+    await registry.register(67890);
+    await registry.unregister(12345);
+
+    // Check in-memory state
+    expect(registry.getPids()).toEqual([67890]);
+
+    // Check file content
+    const content = await Bun.file(PID_FILE).text();
+    const lines = content.split("\n").filter((line) => line.trim());
+    expect(lines.length).toBe(1);
+
+    const entry = JSON.parse(lines[0]);
+    expect(entry.pid).toBe(67890);
+  });
+
+  test("unregister() clears file when last PID is removed", async () => {
+    const registry = new PidRegistry(TEST_WORKDIR);
+
+    await registry.register(12345);
+    await registry.unregister(12345);
+
+    // Check in-memory state
+    expect(registry.getPids()).toEqual([]);
+
+    // Check file is empty
+    const content = await Bun.file(PID_FILE).text();
+    expect(content.trim()).toBe("");
+  });
+
+  test("killAll() clears in-memory PIDs and registry file", async () => {
+    const registry = new PidRegistry(TEST_WORKDIR);
+
+    // Register non-existent PIDs (will fail to kill but should clear registry)
+    await registry.register(99999);
+    await registry.register(88888);
+
+    await registry.killAll();
+
+    // Check in-memory state
+    expect(registry.getPids()).toEqual([]);
+
+    // Check file is empty
+    const content = await Bun.file(PID_FILE).text();
+    expect(content.trim()).toBe("");
+  });
+
+  test("killAll() handles empty registry gracefully", async () => {
+    const registry = new PidRegistry(TEST_WORKDIR);
+
+    // Should not throw
+    await registry.killAll();
+
+    expect(registry.getPids()).toEqual([]);
+  });
+
+  test("cleanupStale() reads and kills PIDs from previous run", async () => {
+    // Simulate a previous run that left PIDs in the file
+    const entry1 = JSON.stringify({
+      pid: 99999, // Non-existent PID
+      spawnedAt: new Date().toISOString(),
+      workdir: TEST_WORKDIR,
+    });
+    const entry2 = JSON.stringify({
+      pid: 88888, // Non-existent PID
+      spawnedAt: new Date().toISOString(),
+      workdir: TEST_WORKDIR,
+    });
+    await Bun.write(PID_FILE, `${entry1}\n${entry2}\n`);
+
+    // Create new registry and cleanup stale PIDs
+    const registry = new PidRegistry(TEST_WORKDIR);
+    await registry.cleanupStale();
+
+    // Check file is cleared
+    const content = await Bun.file(PID_FILE).text();
+    expect(content.trim()).toBe("");
+  });
+
+  test("cleanupStale() handles missing .nax-pids file", async () => {
+    const registry = new PidRegistry(TEST_WORKDIR);
+
+    // Should not throw
+    await registry.cleanupStale();
+
+    // File should not exist
+    expect(existsSync(PID_FILE)).toBe(false);
+  });
+
+  test("cleanupStale() handles empty .nax-pids file", async () => {
+    // Create empty file
+    await Bun.write(PID_FILE, "");
+
+    const registry = new PidRegistry(TEST_WORKDIR);
+    await registry.cleanupStale();
+
+    // File should be empty
+    const content = await Bun.file(PID_FILE).text();
+    expect(content.trim()).toBe("");
+  });
+
+  test("cleanupStale() handles malformed JSON lines gracefully", async () => {
+    // Write malformed JSON
+    await Bun.write(PID_FILE, 'not valid json\n{"pid":12345}\n');
+
+    const registry = new PidRegistry(TEST_WORKDIR);
+
+    // Should not throw
+    await registry.cleanupStale();
+
+    // File should be cleared
+    const content = await Bun.file(PID_FILE).text();
+    expect(content.trim()).toBe("");
+  });
+
+  test("platform-specific kill command: Linux uses process groups", async () => {
+    const registry = new PidRegistry(TEST_WORKDIR, "linux");
+
+    // Register a non-existent PID
+    await registry.register(99999);
+
+    // Should not throw (process doesn't exist, but kill command should be correct)
+    await registry.killAll();
+
+    expect(registry.getPids()).toEqual([]);
+  });
+
+  test("platform-specific kill command: macOS uses direct PID", async () => {
+    const registry = new PidRegistry(TEST_WORKDIR, "darwin");
+
+    // Register a non-existent PID
+    await registry.register(99999);
+
+    // Should not throw (process doesn't exist, but kill command should be correct)
+    await registry.killAll();
+
+    expect(registry.getPids()).toEqual([]);
+  });
+
+  test("multiple registries can coexist with different workdirs", async () => {
+    const workdir1 = `${TEST_WORKDIR}/workspace1`;
+    const workdir2 = `${TEST_WORKDIR}/workspace2`;
+
+    mkdirSync(workdir1, { recursive: true });
+    mkdirSync(workdir2, { recursive: true });
+
+    const registry1 = new PidRegistry(workdir1);
+    const registry2 = new PidRegistry(workdir2);
+
+    await registry1.register(11111);
+    await registry2.register(22222);
+
+    expect(registry1.getPids()).toEqual([11111]);
+    expect(registry2.getPids()).toEqual([22222]);
+
+    // Check separate files
+    const content1 = await Bun.file(`${workdir1}/.nax-pids`).text();
+    const content2 = await Bun.file(`${workdir2}/.nax-pids`).text();
+
+    const entry1 = JSON.parse(content1.trim());
+    const entry2 = JSON.parse(content2.trim());
+
+    expect(entry1.pid).toBe(11111);
+    expect(entry2.pid).toBe(22222);
+  });
+});