@nathapp/nax 0.18.1

package/src/acceptance/generator.ts

@@ -0,0 +1,282 @@
+/**
+ * Acceptance Test Generator
+ *
+ * Parses spec.md acceptance criteria (AC-N lines) and generates acceptance.test.ts
+ * via LLM call to the agent adapter.
+ */
+
+import type { AgentAdapter } from "../agents/types";
+import { getLogger } from "../logger";
+import type { AcceptanceCriterion, AcceptanceTestResult, GenerateAcceptanceTestsOptions } from "./types";
+
+/**
+ * Parse acceptance criteria from spec.md content.
+ *
+ * Extracts lines matching "AC-N: description" or "- AC-N: description" patterns.
+ *
+ * @param specContent - Full spec.md markdown content
+ * @returns Array of extracted acceptance criteria
+ *
+ * @example
+ * ```ts
+ * const spec = `
+ * ## Acceptance Criteria
+ * - AC-1: System should handle empty input
+ * - AC-2: set(key, value, ttl) expires after ttl milliseconds
+ * `;
+ * const criteria = parseAcceptanceCriteria(spec);
+ * // Returns: [
+ * //   { id: "AC-1", text: "System should handle empty input", lineNumber: 3 },
+ * //   { id: "AC-2", text: "set(key, value, ttl) expires after ttl", lineNumber: 4 },
+ * // ]
+ * ```
+ */
+export function parseAcceptanceCriteria(specContent: string): AcceptanceCriterion[] {
+  const criteria: AcceptanceCriterion[] = [];
+  const lines = specContent.split("\n");
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const lineNumber = i + 1;
+
+    // Match patterns:
+    // - AC-1: description
+    // - [ ] AC-1: description
+    // AC-1: description
+    const acMatch = line.match(/^\s*-?\s*(?:\[.\])?\s*(AC-\d+):\s*(.+)$/i);
+
+    if (acMatch) {
+      const id = acMatch[1].toUpperCase(); // Normalize to uppercase
+      const text = acMatch[2].trim();
+
+      criteria.push({
+        id,
+        text,
+        lineNumber,
+      });
+    }
+  }
+
+  return criteria;
+}
+
+/**
+ * Build LLM prompt for generating acceptance tests.
+ *
+ * Combines acceptance criteria, codebase context, and test generation instructions.
+ *
+ * @param criteria - Extracted acceptance criteria
+ * @param featureName - Feature name for context
+ * @param codebaseContext - File tree, dependencies, test patterns
+ * @returns Formatted prompt string
+ *
+ * @example
+ * ```ts
+ * const prompt = buildAcceptanceTestPrompt(
+ *   [{ id: "AC-1", text: "handles empty input", lineNumber: 5 }],
+ *   "url-shortener",
+ *   "File tree:\nsrc/\n  index.ts\n"
+ * );
+ * ```
+ */
+export function buildAcceptanceTestPrompt(
+  criteria: AcceptanceCriterion[],
+  featureName: string,
+  codebaseContext: string,
+): string {
+  const criteriaList = criteria.map((ac) => `${ac.id}: ${ac.text}`).join("\n");
+
+  return `You are a test engineer. Generate acceptance tests for the "${featureName}" feature based on the acceptance criteria below.
+
+CODEBASE CONTEXT:
+${codebaseContext}
+
+ACCEPTANCE CRITERIA:
+${criteriaList}
+
+Generate a complete acceptance.test.ts file using bun:test framework. Follow these rules:
+
+1. **One test per AC**: Each acceptance criterion maps to exactly one test
+2. **Test observable behavior only**: No implementation details, only user-facing behavior
+3. **Independent tests**: No shared state between tests
+4. **Integration-level**: Tests should be runnable without mocking (use real implementations)
+5. **Clear test names**: Use format "AC-N: <description>" for test names
+6. **Async where needed**: Use async/await for operations that may be asynchronous
+
+Use this structure:
+
+\`\`\`typescript
+import { describe, test, expect } from "bun:test";
+
+describe("${featureName} - Acceptance Tests", () => {
+  test("AC-1: <description>", async () => {
+    // Test implementation
+  });
+
+  test("AC-2: <description>", async () => {
+    // Test implementation
+  });
+});
+\`\`\`
+
+**Important**:
+- Import the feature code being tested
+- Set up any necessary test fixtures
+- Use expect() assertions to verify behavior
+- Clean up resources if needed (close connections, delete temp files)
+
+Respond with ONLY the TypeScript test code (no markdown code fences, no explanation).`;
+}
+
+/**
+ * Generate acceptance tests from spec.md acceptance criteria.
+ *
+ * Parses AC lines from spec, builds LLM prompt, calls agent adapter,
+ * and returns generated test code. Falls back to skeleton tests if LLM fails.
+ *
+ * @param adapter - Agent adapter to use for test generation
+ * @param options - Generation options with spec content, context, and model
+ * @returns Generated test code and processed criteria
+ * @throws Error if AC parsing fails or agent call fails critically
+ *
+ * @example
+ * ```ts
+ * const adapter = new ClaudeCodeAdapter();
+ * const result = await generateAcceptanceTests(adapter, {
+ *   specContent: await Bun.file("spec.md").text(),
+ *   featureName: "url-shortener",
+ *   workdir: "/project",
+ *   codebaseContext: "File tree:\nsrc/\n",
+ *   modelTier: "balanced",
+ *   modelDef: { provider: "anthropic", model: "claude-sonnet-4-5" },
+ * });
+ *
+ * await Bun.write("acceptance.test.ts", result.testCode);
+ * ```
+ */
+export async function generateAcceptanceTests(
+  adapter: AgentAdapter,
+  options: GenerateAcceptanceTestsOptions,
+): Promise<AcceptanceTestResult> {
+  // Parse acceptance criteria from spec
+  const logger = getLogger();
+  const criteria = parseAcceptanceCriteria(options.specContent);
+
+  if (criteria.length === 0) {
+    // No AC found — generate empty skeleton
+    logger.warn("acceptance", "⚠ No acceptance criteria found in spec.md");
+    return {
+      testCode: generateSkeletonTests(options.featureName, []),
+      criteria: [],
+    };
+  }
+
+  logger.info("acceptance", "Found acceptance criteria", { count: criteria.length });
+
+  // Build prompt
+  const prompt = buildAcceptanceTestPrompt(criteria, options.featureName, options.codebaseContext);
+
+  try {
+    // Call agent to generate tests (using decompose as pattern)
+    const cmd = [adapter.binary, "--model", options.modelDef.model, "--dangerously-skip-permissions", "-p", prompt];
+
+    const proc = Bun.spawn(cmd, {
+      cwd: options.workdir,
+      stdout: "pipe",
+      stderr: "pipe",
+      env: {
+        ...process.env,
+        ...(options.modelDef.env || {}),
+      },
+    });
+
+    const exitCode = await proc.exited;
+    const stdout = await new Response(proc.stdout).text();
+    const stderr = await new Response(proc.stderr).text();
+
+    if (exitCode !== 0) {
+      logger.warn("acceptance", "⚠ Agent test generation failed", { stderr });
+      // Fall back to skeleton
+      return {
+        testCode: generateSkeletonTests(options.featureName, criteria),
+        criteria,
+      };
+    }
+
+    // Extract test code from output
+    const testCode = extractTestCode(stdout);
+
+    return {
+      testCode,
+      criteria,
+    };
+  } catch (error) {
+    logger.warn("acceptance", "⚠ Agent test generation error", { error: (error as Error).message });
+    // Fall back to skeleton
+    return {
+      testCode: generateSkeletonTests(options.featureName, criteria),
+      criteria,
+    };
+  }
+}
+
+/**
+ * Extract TypeScript test code from agent output.
+ *
+ * Handles markdown code fences and extracts clean test code.
+ *
+ * @param output - Agent stdout
+ * @returns Extracted test code
+ */
+function extractTestCode(output: string): string {
+  // Try to extract from markdown code fence
+  const fenceMatch = output.match(/```(?:typescript|ts)?\s*([\s\S]*?)\s*```/);
+  if (fenceMatch) {
+    return fenceMatch[1].trim();
+  }
+
+  // If no fence, try to find import statement and take everything from there
+  const importMatch = output.match(/import\s+{[\s\S]+/);
+  if (importMatch) {
+    return importMatch[0].trim();
+  }
+
+  // Fall back to full output
+  return output.trim();
+}
+
+/**
+ * Generate skeleton acceptance tests with TODO placeholders.
+ *
+ * Used as fallback when LLM test generation fails.
+ *
+ * @param featureName - Feature name
+ * @param criteria - Acceptance criteria to generate skeletons for
+ * @returns TypeScript test code with TODO placeholders
+ *
+ * @example
+ * ```ts
+ * const skeleton = generateSkeletonTests("auth", [
+ *   { id: "AC-1", text: "login succeeds", lineNumber: 5 },
+ * ]);
+ * // Generates test with TODO comment
+ * ```
+ */
+export function generateSkeletonTests(featureName: string, criteria: AcceptanceCriterion[]): string {
+  const tests = criteria
+    .map((ac) => {
+      return `  test("${ac.id}: ${ac.text}", async () => {
+    // TODO: Implement acceptance test for ${ac.id}
+    // ${ac.text}
+    expect(true).toBe(false); // Replace with actual test
+  });`;
+    })
+    .join("\n\n");
+
+  return `import { describe, test, expect } from "bun:test";
+
+describe("${featureName} - Acceptance Tests", () => {
+${tests || "  // No acceptance criteria found"}
+});
+`;
+}

package/src/acceptance/index.ts

@@ -0,0 +1,30 @@
+/**
+ * Acceptance Test Generation Module
+ *
+ * Barrel exports for acceptance test generation functionality.
+ */
+
+export type {
+  AcceptanceCriterion,
+  GenerateAcceptanceTestsOptions,
+  AcceptanceTestResult,
+} from "./types";
+
+export {
+  parseAcceptanceCriteria,
+  buildAcceptanceTestPrompt,
+  generateAcceptanceTests,
+  generateSkeletonTests,
+} from "./generator";
+
+export type {
+  FixStory,
+  GenerateFixStoriesOptions,
+} from "./fix-generator";
+
+export {
+  generateFixStories,
+  findRelatedStories,
+  parseACTextFromSpec,
+  convertFixStoryToUserStory,
+} from "./fix-generator";

package/src/acceptance/types.ts

@@ -0,0 +1,79 @@
+/**
+ * Acceptance Test Generation Types
+ *
+ * Types for generating acceptance tests from spec.md acceptance criteria.
+ */
+
+import type { ModelDef, ModelTier } from "../config/schema";
+
+/**
+ * A single acceptance criterion extracted from spec.md.
+ *
+ * @example
+ * ```ts
+ * const ac: AcceptanceCriterion = {
+ *   id: "AC-2",
+ *   text: "set(key, value, ttl) expires after ttl milliseconds",
+ *   lineNumber: 42,
+ * };
+ * ```
+ */
+export interface AcceptanceCriterion {
+  /** AC identifier (e.g., "AC-1", "AC-2") */
+  id: string;
+  /** Full criterion text */
+  text: string;
+  /** Line number in spec.md for reference */
+  lineNumber: number;
+}
+
+/**
+ * Options for generating acceptance tests.
+ *
+ * @example
+ * ```ts
+ * const options: GenerateAcceptanceTestsOptions = {
+ *   specContent: "# Feature\n\n## Acceptance Criteria\n- AC-1: ...",
+ *   featureName: "url-shortener",
+ *   workdir: "/home/user/project",
+ *   codebaseContext: "File tree:\nsrc/\n  index.ts\n",
+ *   modelTier: "balanced",
+ *   modelDef: { provider: "anthropic", model: "claude-sonnet-4-5" },
+ * };
+ * ```
+ */
+export interface GenerateAcceptanceTestsOptions {
+  /** Full spec.md content */
+  specContent: string;
+  /** Feature name for context */
+  featureName: string;
+  /** Working directory for context scanning */
+  workdir: string;
+  /** Codebase context (file tree, dependencies, test patterns) */
+  codebaseContext: string;
+  /** Model tier to use for test generation */
+  modelTier: ModelTier;
+  /** Resolved model definition */
+  modelDef: ModelDef;
+}
+
+/**
+ * Result from acceptance test generation.
+ *
+ * @example
+ * ```ts
+ * const result: AcceptanceTestResult = {
+ *   testCode: 'import { describe, test, expect } from "bun:test";\n\n...',
+ *   criteria: [
+ *     { id: "AC-1", text: "TTL expires", lineNumber: 12 },
+ *     { id: "AC-2", text: "set(key, value, ttl) expires after ttl", lineNumber: 13 },
+ *   ],
+ * };
+ * ```
+ */
+export interface AcceptanceTestResult {
+  /** Generated test code */
+  testCode: string;
+  /** Acceptance criteria that were processed */
+  criteria: AcceptanceCriterion[];
+}

package/src/agents/claude-decompose.ts

@@ -0,0 +1,169 @@
+/**
+ * Claude Code Decompose Logic
+ *
+ * Extracted from claude.ts: decompose(), buildDecomposePrompt(),
+ * parseDecomposeOutput(), validateComplexity()
+ */
+
+import type { DecomposeOptions, DecomposeResult, DecomposedStory } from "./types";
+
+/**
+ * Build the decompose prompt combining spec content and codebase context.
+ */
+export function buildDecomposePrompt(options: DecomposeOptions): string {
+  return `You are a requirements analyst. Break down the following feature specification into user stories and classify each story's complexity.
+
+CODEBASE CONTEXT:
+${options.codebaseContext}
+
+FEATURE SPECIFICATION:
+${options.specContent}
+
+Decompose this spec into user stories. For each story, provide:
+1. id: Story ID (e.g., "US-001")
+2. title: Concise story title
+3. description: What needs to be implemented
+4. acceptanceCriteria: Array of testable criteria
+5. tags: Array of routing tags (e.g., ["security", "api"])
+6. dependencies: Array of story IDs this depends on (e.g., ["US-001"])
+7. complexity: "simple" | "medium" | "complex" | "expert"
+8. contextFiles: Array of file paths to inject into agent prompt before execution
+9. reasoning: Why this complexity level
+10. estimatedLOC: Estimated lines of code to change
+11. risks: Array of implementation risks
+12. testStrategy: "three-session-tdd" | "test-after"
+
+testStrategy rules:
+- "three-session-tdd": ONLY for complex/expert tasks that are security-critical (auth, encryption, tokens, credentials) or define public API contracts consumers depend on
+- "test-after": for all other tasks including simple/medium complexity
+- A "simple" complexity task should almost never be "three-session-tdd"
+
+Complexity classification rules:
+- simple: 1-3 files, <100 LOC, straightforward implementation, existing patterns
+- medium: 3-6 files, 100-300 LOC, moderate logic, some new patterns
+- complex: 6+ files, 300-800 LOC, architectural changes, cross-cutting concerns
+- expert: Security/crypto/real-time/distributed systems, >800 LOC, new infrastructure
+
+Grouping Guidelines:
+- Combine small, related tasks (e.g., multiple utility functions, interfaces) into a single "simple" or "medium" story.
+- Do NOT create separate stories for every single file or function unless complex.
+- Aim for coherent units of value (e.g., "Implement User Authentication" vs "Create User Interface", "Create Login Service").
+- Maximum recommended stories: 10-15 per feature. Group aggressively if list grows too long.
+
+Consider:
+1. Does infrastructure exist? (e.g., "add caching" when no cache layer exists = complex)
+2. How many files will be touched?
+3. Are there cross-cutting concerns (auth, validation, error handling)?
+4. Does it require new dependencies or architectural decisions?
+
+Respond with ONLY a JSON array (no markdown code fences):
+[{
+  "id": "US-001",
+  "title": "Story title",
+  "description": "Story description",
+  "acceptanceCriteria": ["Criterion 1", "Criterion 2"],
+  "tags": ["tag1"],
+  "dependencies": [],
+  "complexity": "medium",
+  "contextFiles": ["src/path/to/file.ts"],
+  "reasoning": "Why this complexity level",
+  "estimatedLOC": 150,
+  "risks": ["Risk 1"],
+  "testStrategy": "test-after"
+}]`;
+}
+
+/**
+ * Parse decompose output from agent stdout.
+ *
+ * Extracts JSON array from output, handles markdown code fences,
+ * and validates structure.
+ */
+export function parseDecomposeOutput(output: string): DecomposedStory[] {
+  // Extract JSON from output (handles markdown code fences)
+  const jsonMatch = output.match(/```(?:json)?\s*(\[[\s\S]*?\])\s*```/);
+  let jsonText = jsonMatch ? jsonMatch[1] : output;
+
+  // Try to find JSON array directly if no code fence
+  if (!jsonMatch) {
+    const arrayMatch = output.match(/\[[\s\S]*\]/);
+    if (arrayMatch) {
+      jsonText = arrayMatch[0];
+    }
+  }
+
+  // Parse JSON
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(jsonText.trim());
+  } catch (error) {
+    throw new Error(
+      `Failed to parse decompose output as JSON: ${(error as Error).message}\n\nOutput:\n${output.slice(0, 500)}`,
+    );
+  }
+
+  // Validate structure
+  if (!Array.isArray(parsed)) {
+    throw new Error("Decompose output is not an array");
+  }
+
+  // Map to DecomposedStory[] with validation
+  const stories: DecomposedStory[] = parsed.map((item: unknown, index: number) => {
+    // Type guard: ensure item is an object
+    if (typeof item !== "object" || item === null) {
+      throw new Error(`Story at index ${index} is not an object`);
+    }
+    const record = item as Record<string, unknown>;
+    if (!record.id || typeof record.id !== "string") {
+      throw new Error(`Story at index ${index} missing valid 'id' field`);
+    }
+    if (!record.title || typeof record.title !== "string") {
+      throw new Error(`Story ${record.id} missing valid 'title' field`);
+    }
+
+    return {
+      id: record.id,
+      title: record.title,
+      description: String(record.description || record.title),
+      acceptanceCriteria: Array.isArray(record.acceptanceCriteria)
+        ? record.acceptanceCriteria
+        : ["Implementation complete"],
+      tags: Array.isArray(record.tags) ? record.tags : [],
+      dependencies: Array.isArray(record.dependencies) ? record.dependencies : [],
+      complexity: validateComplexity(record.complexity),
+      // contextFiles: prefer the new field; fall back to legacy relevantFiles from older LLM responses
+      contextFiles: Array.isArray(record.contextFiles)
+        ? record.contextFiles
+        : Array.isArray(record.relevantFiles)
+          ? record.relevantFiles
+          : [],
+      relevantFiles: Array.isArray(record.relevantFiles) ? record.relevantFiles : [],
+      reasoning: String(record.reasoning || "No reasoning provided"),
+      estimatedLOC: Number(record.estimatedLOC) || 0,
+      risks: Array.isArray(record.risks) ? record.risks : [],
+      testStrategy:
+        record.testStrategy === "three-session-tdd"
+          ? "three-session-tdd"
+          : record.testStrategy === "test-after"
+            ? "test-after"
+            : undefined,
+    };
+  });
+
+  if (stories.length === 0) {
+    throw new Error("Decompose returned empty story array");
+  }
+
+  return stories;
+}
+
+/**
+ * Validate complexity value from decompose output.
+ */
+export function validateComplexity(value: unknown): "simple" | "medium" | "complex" | "expert" {
+  if (value === "simple" || value === "medium" || value === "complex" || value === "expert") {
+    return value;
+  }
+  // Default to medium if invalid
+  return "medium";
+}

package/src/agents/claude-plan.ts

@@ -0,0 +1,139 @@
+/**
+ * Claude Code Plan Logic
+ *
+ * Extracted from claude.ts: plan(), buildPlanCommand()
+ */
+
+import type { PidRegistry } from "../execution/pid-registry";
+import { getLogger } from "../logger";
+import type { AgentRunOptions } from "./types";
+import type { PlanOptions, PlanResult } from "./types-extended";
+
+/**
+ * Build the CLI command for plan mode.
+ */
+export function buildPlanCommand(binary: string, options: PlanOptions): string[] {
+  const cmd = [binary, "--permission-mode", "plan"];
+
+  // Add model if specified
+  if (options.modelDef) {
+    cmd.push("--model", options.modelDef.model);
+  }
+
+  // Add dangerously-skip-permissions for automation
+  cmd.push("--dangerously-skip-permissions");
+
+  // Add prompt with codebase context and input file if available
+  let fullPrompt = options.prompt;
+  if (options.codebaseContext) {
+    fullPrompt = `${options.codebaseContext}\n\n${options.prompt}`;
+  }
+
+  // For non-interactive mode, include input file content in the prompt
+  if (options.inputFile) {
+    try {
+      const inputContent = require("node:fs").readFileSync(
+        require("node:path").resolve(options.workdir, options.inputFile),
+        "utf-8",
+      );
+      fullPrompt = `${fullPrompt}\n\n## Input Requirements\n\n${inputContent}`;
+    } catch (error) {
+      throw new Error(`Failed to read input file ${options.inputFile}: ${(error as Error).message}`);
+    }
+  }
+
+  if (!options.interactive) {
+    cmd.push("-p", fullPrompt);
+  } else {
+    // Interactive mode: pass prompt as initial message, agent will ask follow-ups
+    cmd.push("-p", fullPrompt);
+  }
+
+  return cmd;
+}
+
+/**
+ * Run Claude Code in plan mode to generate a feature specification.
+ */
+export async function runPlan(
+  binary: string,
+  options: PlanOptions,
+  pidRegistry: PidRegistry,
+  buildAllowedEnv: (options: AgentRunOptions) => Record<string, string | undefined>,
+): Promise<PlanResult> {
+  const cmd = buildPlanCommand(binary, options);
+
+  const envOptions: AgentRunOptions = {
+    workdir: options.workdir,
+    modelDef: options.modelDef || { provider: "anthropic", model: "claude-sonnet-4-5", env: {} },
+    prompt: "",
+    modelTier: "balanced",
+    timeoutSeconds: 600,
+  };
+
+  if (options.interactive) {
+    // Interactive mode: inherit stdio
+    const proc = Bun.spawn(cmd, {
+      cwd: options.workdir,
+      stdin: "inherit",
+      stdout: "inherit",
+      stderr: "inherit",
+      env: buildAllowedEnv(envOptions),
+    });
+
+    // Register PID
+    await pidRegistry.register(proc.pid);
+
+    const exitCode = await proc.exited;
+
+    // Unregister PID after exit
+    await pidRegistry.unregister(proc.pid);
+
+    if (exitCode !== 0) {
+      throw new Error(`Plan mode failed with exit code ${exitCode}`);
+    }
+    return { specContent: "", conversationLog: "" };
+  }
+
+  // Non-interactive: redirect stdout to temp file via Bun.file()
+  const { join } = require("node:path");
+  const { mkdtempSync, readFileSync, rmSync } = require("node:fs");
+  const { tmpdir } = require("node:os");
+  const tempDir = mkdtempSync(join(tmpdir(), "nax-plan-"));
+  const outFile = join(tempDir, "stdout.txt");
+  const errFile = join(tempDir, "stderr.txt");
+
+  try {
+    const proc = Bun.spawn(cmd, {
+      cwd: options.workdir,
+      stdin: "ignore",
+      stdout: Bun.file(outFile),
+      stderr: Bun.file(errFile),
+      env: buildAllowedEnv(envOptions),
+    });
+
+    // Register PID
+    await pidRegistry.register(proc.pid);
+
+    const exitCode = await proc.exited;
+
+    // Unregister PID after exit
+    await pidRegistry.unregister(proc.pid);
+
+    const specContent = readFileSync(outFile, "utf-8");
+    const conversationLog = readFileSync(errFile, "utf-8");
+
+    if (exitCode !== 0) {
+      throw new Error(`Plan mode failed with exit code ${exitCode}: ${conversationLog || "unknown error"}`);
+    }
+
+    return { specContent, conversationLog };
+  } finally {
+    try {
+      rmSync(tempDir, { recursive: true });
+    } catch (error) {
+      const logger = getLogger();
+      logger?.debug("agent", "Failed to clean up temp directory", { error, tempDir });
+    }
+  }
+}