@nathapp/nax 0.40.0 → 0.41.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nathapp/nax",
-  "version": "0.40.0",
-  "description": "AI Coding Agent Orchestrator — loops until done",
+  "version": "0.41.0",
+  "description": "AI Coding Agent Orchestrator \u2014 loops until done",
   "type": "module",
   "bin": {
     "nax": "./dist/nax.js"

package/src/acceptance/fix-generator.ts

@@ -199,7 +199,7 @@ export async function generateFixStories(
   adapter: AgentAdapter,
   options: GenerateFixStoriesOptions,
 ): Promise<FixStory[]> {
-  const { failedACs, testOutput, prd, specContent, workdir, modelDef } = options;
+  const { failedACs, testOutput, prd, specContent, modelDef } = options;
 
   const fixStories: FixStory[] = [];
 
@@ -225,42 +225,11 @@ export async function generateFixStories(
     const prompt = buildFixPrompt(failedAC, acText, testOutput, relatedStories, prd);
 
     try {
-      // Call agent to generate fix description
-      const skipPerms = options.config.quality?.dangerouslySkipPermissions ?? true;
-      const permArgs = skipPerms ? ["--dangerously-skip-permissions"] : [];
-      const cmd = [adapter.binary, "--model", modelDef.model, ...permArgs, "-p", prompt];
-
-      const proc = Bun.spawn(cmd, {
-        cwd: workdir,
-        stdout: "pipe",
-        stderr: "pipe",
-        env: {
-          ...process.env,
-          ...(modelDef.env || {}),
-        },
+      // Call adapter to generate fix description
+      const fixDescription = await adapter.complete(prompt, {
+        model: modelDef.model,
       });
 
-      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 fix generation failed", { failedAC, stderr });
-        // Use fallback description
-        fixStories.push({
-          id: `US-FIX-${String(i + 1).padStart(3, "0")}`,
-          title: `Fix: ${failedAC}`,
-          failedAC,
-          testOutput,
-          relatedStories,
-          description: `Fix the implementation to make ${failedAC} pass. Related stories: ${relatedStories.join(", ")}.`,
-        });
-        continue;
-      }
-
-      // Extract fix description
-      const fixDescription = stdout.trim();
-
       fixStories.push({
         id: `US-FIX-${String(i + 1).padStart(3, "0")}`,
         title: `Fix: ${failedAC} — ${acText.slice(0, 50)}`,

package/src/acceptance/generator.ts

@@ -82,6 +82,8 @@ export async function generateFromPRD(
 
   const criteriaList = refinedCriteria.map((c, i) => `AC-${i + 1}: ${c.refined}`).join("\n");
 
+  const strategyInstructions = buildStrategyInstructions(options.testStrategy, options.testFramework);
+
   const prompt = `You are a test engineer. Generate acceptance tests for the "${options.featureName}" feature based on the refined acceptance criteria below.
 
 CODEBASE CONTEXT:
@@ -90,7 +92,7 @@ ${options.codebaseContext}
 ACCEPTANCE CRITERIA (refined):
 ${criteriaList}
 
-Generate a complete acceptance.test.ts file using bun:test framework. Each AC maps to exactly one test named "AC-N: <description>".
+${strategyInstructions}Generate a complete acceptance.test.ts file using bun:test framework. Each AC maps to exactly one test named "AC-N: <description>".
 
 Use this structure:
 
@@ -127,6 +129,26 @@ Respond with ONLY the TypeScript test code (no markdown code fences, no explanat
   return { testCode, criteria };
 }
 
+function buildStrategyInstructions(strategy?: string, framework?: string): string {
+  switch (strategy) {
+    case "component": {
+      const fw = framework ?? "ink-testing-library";
+      if (fw === "react") {
+        return "TEST STRATEGY: component (react)\nImport render and screen from @testing-library/react. Render the component and use screen.getByText to assert on output.\n\n";
+      }
+      return "TEST STRATEGY: component (ink-testing-library)\nImport render from ink-testing-library. Render the component and use lastFrame() to assert on output.\n\n";
+    }
+    case "cli":
+      return "TEST STRATEGY: cli\nUse Bun.spawn to run the binary. Read stdout and assert on the text output.\n\n";
+    case "e2e":
+      return "TEST STRATEGY: e2e\nUse fetch() against http://localhost to call the running service. Assert on response body using response.text() or response.json().\n\n";
+    case "snapshot":
+      return "TEST STRATEGY: snapshot\nRender the component and use toMatchSnapshot() to capture and compare snapshots.\n\n";
+    default:
+      return "";
+  }
+}
+
 export function parseAcceptanceCriteria(specContent: string): AcceptanceCriterion[] {
   const criteria: AcceptanceCriterion[] = [];
   const lines = specContent.split("\n");
@@ -273,36 +295,13 @@ export async function generateAcceptanceTests(
   const prompt = buildAcceptanceTestPrompt(criteria, options.featureName, options.codebaseContext);
 
   try {
-    // Call agent to generate tests (using decompose as pattern)
-    const skipPerms = options.config.quality?.dangerouslySkipPermissions ?? true;
-    const permArgs = skipPerms ? ["--dangerously-skip-permissions"] : [];
-    const cmd = [adapter.binary, "--model", options.modelDef.model, ...permArgs, "-p", prompt];
-
-    const proc = Bun.spawn(cmd, {
-      cwd: options.workdir,
-      stdout: "pipe",
-      stderr: "pipe",
-      env: {
-        ...process.env,
-        ...(options.modelDef.env || {}),
-      },
+    // Call adapter to generate tests
+    const output = await adapter.complete(prompt, {
+      model: options.modelDef.model,
     });
 
-    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);
+    const testCode = extractTestCode(output);
 
     return {
       testCode,

package/src/acceptance/refinement.ts

@@ -22,21 +22,38 @@ export const _refineDeps = {
   adapter: new ClaudeCodeAdapter() as AgentAdapter,
 };
 
+/**
+ * Strategy-specific context for the refinement prompt.
+ */
+export interface RefinementPromptOptions {
+  /** Test strategy — controls strategy-specific prompt instructions */
+  testStrategy?: "unit" | "component" | "cli" | "e2e" | "snapshot";
+  /** Test framework — informs LLM which testing library syntax to use */
+  testFramework?: string;
+}
+
 /**
  * Build the LLM prompt for refining acceptance criteria.
  *
  * @param criteria - Raw AC strings from PRD
  * @param codebaseContext - File tree / dependency context
+ * @param options - Optional strategy/framework context
  * @returns Formatted prompt string
  */
-export function buildRefinementPrompt(criteria: string[], codebaseContext: string): string {
+export function buildRefinementPrompt(
+  criteria: string[],
+  codebaseContext: string,
+  options?: RefinementPromptOptions,
+): string {
   const criteriaList = criteria.map((c, i) => `${i + 1}. ${c}`).join("\n");
+  const strategySection = buildStrategySection(options);
+  const refinedExample = buildRefinedExample(options?.testStrategy);
 
   return `You are an acceptance criteria refinement assistant. Your task is to convert raw acceptance criteria into concrete, machine-verifiable assertions.
 
 CODEBASE CONTEXT:
 ${codebaseContext}
-
+${strategySection}
 ACCEPTANCE CRITERIA TO REFINE:
 ${criteriaList}
 
@@ -51,12 +68,62 @@ Respond with ONLY a JSON array (no markdown code fences):
 
 Rules:
 - "original" must match the input criterion text exactly
-- "refined" must be a concrete assertion (e.g., "Function returns array of length N", "HTTP status 200 returned")
+- "refined" must be a concrete assertion (e.g., ${refinedExample})
 - "testable" is false only if the criterion cannot be automatically verified (e.g., "UX feels responsive", "design looks good")
 - "storyId" leave as empty string — it will be assigned by the caller
 - Respond with ONLY the JSON array`;
 }
 
+/**
+ * Build strategy-specific instructions section for the prompt.
+ */
+function buildStrategySection(options?: RefinementPromptOptions): string {
+  if (!options?.testStrategy) {
+    return "";
+  }
+
+  const framework = options.testFramework ? ` Use ${options.testFramework} testing library syntax.` : "";
+
+  switch (options.testStrategy) {
+    case "component":
+      return `
+TEST STRATEGY: component
+Focus assertions on rendered output visible on screen — text content, visible elements, and screen state.
+Assert what the user sees rendered in the component, not what internal functions produce.${framework}
+`;
+    case "cli":
+      return `
+TEST STRATEGY: cli
+Focus assertions on stdout and stderr text output from the CLI command.
+Assert about terminal output content, exit codes, and standard output/standard error streams.${framework}
+`;
+    case "e2e":
+      return `
+TEST STRATEGY: e2e
+Focus assertions on HTTP response content — status codes, response bodies, and endpoint behavior.
+Assert about HTTP responses, status codes, and API endpoint output.${framework}
+`;
+    default:
+      return framework ? `\nTEST FRAMEWORK: ${options.testFramework}\n` : "";
+  }
+}
+
+/**
+ * Build the "refined" example string based on the test strategy.
+ */
+function buildRefinedExample(testStrategy?: RefinementPromptOptions["testStrategy"]): string {
+  switch (testStrategy) {
+    case "component":
+      return '"Text content visible on screen matches expected", "Rendered output contains expected element"';
+    case "cli":
+      return '"stdout contains expected text", "stderr is empty on success", "exit code is 0"';
+    case "e2e":
+      return '"HTTP status 200 returned", "Response body contains expected field", "Endpoint returns JSON"';
+    default:
+      return '"Array of length N returned", "HTTP status 200 returned"';
+  }
+}
+
 /**
  * Parse the LLM JSON response into RefinedCriterion[].
  *
@@ -105,7 +172,7 @@ export async function refineAcceptanceCriteria(
     return [];
   }
 
-  const { storyId, codebaseContext, config } = context;
+  const { storyId, codebaseContext, config, testStrategy, testFramework } = context;
   const logger = getLogger();
 
   const modelTier = config.acceptance?.model ?? "fast";
@@ -116,7 +183,7 @@ export async function refineAcceptanceCriteria(
   }
 
   const modelDef = resolveModel(modelEntry);
-  const prompt = buildRefinementPrompt(criteria, codebaseContext);
+  const prompt = buildRefinementPrompt(criteria, codebaseContext, { testStrategy, testFramework });
 
   let response: string;
 

package/src/acceptance/templates/cli.ts

@@ -0,0 +1,47 @@
+/**
+ * CLI test template builder
+ *
+ * Generates acceptance test structure for CLI testing strategy.
+ * Uses Bun.spawn to run the binary and asserts on stdout text.
+ */
+
+import type { AcceptanceCriterion } from "../types";
+
+export interface CliTemplateOptions {
+  featureName: string;
+  criteria: AcceptanceCriterion[];
+}
+
+/**
+ * Build CLI test template code for the given criteria.
+ *
+ * @param options - Feature name and criteria list
+ * @returns TypeScript test code string
+ */
+export function buildCliTemplate(options: CliTemplateOptions): string {
+  const { featureName, criteria } = options;
+
+  const tests = criteria
+    .map(
+      (ac) => `  test("${ac.id}: ${ac.text}", async () => {
+    const proc = Bun.spawn(["bun", "run", "src/${featureName}.ts"], {
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    const [exitCode, stdout] = await Promise.all([
+      proc.exited,
+      new Response(proc.stdout).text(),
+    ]);
+    expect(exitCode).toBe(0);
+    expect(stdout).toContain(""); // Replace with expected stdout text
+  });`,
+    )
+    .join("\n\n");
+
+  return `import { describe, expect, test } from "bun:test";
+
+describe("${featureName} - Acceptance Tests", () => {
+${tests}
+});
+`;
+}

package/src/acceptance/templates/component.ts

@@ -0,0 +1,78 @@
+/**
+ * Component test template builder
+ *
+ * Generates acceptance test structure for component testing strategy.
+ * Supports ink-testing-library (lastFrame) and react (screen.getByText).
+ */
+
+import type { AcceptanceCriterion } from "../types";
+
+export interface ComponentTemplateOptions {
+  featureName: string;
+  criteria: AcceptanceCriterion[];
+  /** Test framework: 'ink-testing-library' | 'react' */
+  testFramework?: string;
+}
+
+/**
+ * Build component test template code for the given criteria.
+ *
+ * @param options - Feature name, criteria, and test framework
+ * @returns TypeScript test code string
+ */
+export function buildComponentTemplate(options: ComponentTemplateOptions): string {
+  const { featureName, criteria, testFramework = "ink-testing-library" } = options;
+
+  if (testFramework === "react") {
+    return buildReactTemplate(featureName, criteria);
+  }
+
+  return buildInkTemplate(featureName, criteria);
+}
+
+function buildInkTemplate(featureName: string, criteria: AcceptanceCriterion[]): string {
+  const tests = criteria
+    .map(
+      (ac) => `  test("${ac.id}: ${ac.text}", () => {
+    const { lastFrame } = render(<${toPascalCase(featureName)} />);
+    expect(lastFrame()).toContain(""); // Replace with expected output
+  });`,
+    )
+    .join("\n\n");
+
+  return `import { describe, expect, test } from "bun:test";
+import { render } from "ink-testing-library";
+import { ${toPascalCase(featureName)} } from "../src/${featureName}";
+
+describe("${featureName} - Acceptance Tests", () => {
+${tests}
+});
+`;
+}
+
+function buildReactTemplate(featureName: string, criteria: AcceptanceCriterion[]): string {
+  const tests = criteria
+    .map(
+      (ac) => `  test("${ac.id}: ${ac.text}", () => {
+    render(<${toPascalCase(featureName)} />);
+    expect(screen.getByText("")).toBeTruthy(); // Replace with expected text
+  });`,
+    )
+    .join("\n\n");
+
+  return `import { describe, expect, test } from "bun:test";
+import { render, screen } from "@testing-library/react";
+import { ${toPascalCase(featureName)} } from "../src/${featureName}";
+
+describe("${featureName} - Acceptance Tests", () => {
+${tests}
+});
+`;
+}
+
+function toPascalCase(name: string): string {
+  return name
+    .split(/[-_\s]+/)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join("");
+}

package/src/acceptance/templates/e2e.ts

@@ -0,0 +1,43 @@
+/**
+ * E2E test template builder
+ *
+ * Generates acceptance test structure for end-to-end testing strategy.
+ * Uses fetch() against localhost and asserts on response body.
+ */
+
+import type { AcceptanceCriterion } from "../types";
+
+export interface E2eTemplateOptions {
+  featureName: string;
+  criteria: AcceptanceCriterion[];
+}
+
+const DEFAULT_PORT = 3000;
+
+/**
+ * Build E2E test template code for the given criteria.
+ *
+ * @param options - Feature name and criteria list
+ * @returns TypeScript test code string
+ */
+export function buildE2eTemplate(options: E2eTemplateOptions): string {
+  const { featureName, criteria } = options;
+
+  const tests = criteria
+    .map(
+      (ac) => `  test("${ac.id}: ${ac.text}", async () => {
+    const response = await fetch("http://localhost:${DEFAULT_PORT}/api/${featureName}");
+    expect(response.ok).toBe(true);
+    const body = await response.text();
+    expect(body).toContain(""); // Replace with expected response body
+  });`,
+    )
+    .join("\n\n");
+
+  return `import { describe, expect, test } from "bun:test";
+
+describe("${featureName} - Acceptance Tests", () => {
+${tests}
+});
+`;
+}

package/src/acceptance/templates/index.ts

@@ -0,0 +1,21 @@
+/**
+ * Acceptance Test Template Builders
+ *
+ * One builder per test strategy. The generator selects the appropriate
+ * builder based on the testStrategy option.
+ */
+
+export { buildUnitTemplate } from "./unit";
+export type { UnitTemplateOptions } from "./unit";
+
+export { buildComponentTemplate } from "./component";
+export type { ComponentTemplateOptions } from "./component";
+
+export { buildCliTemplate } from "./cli";
+export type { CliTemplateOptions } from "./cli";
+
+export { buildE2eTemplate } from "./e2e";
+export type { E2eTemplateOptions } from "./e2e";
+
+export { buildSnapshotTemplate } from "./snapshot";
+export type { SnapshotTemplateOptions } from "./snapshot";

package/src/acceptance/templates/snapshot.ts

@@ -0,0 +1,50 @@
+/**
+ * Snapshot test template builder
+ *
+ * Generates acceptance test structure for snapshot testing strategy.
+ * Renders the component and uses toMatchSnapshot() for assertions.
+ */
+
+import type { AcceptanceCriterion } from "../types";
+
+export interface SnapshotTemplateOptions {
+  featureName: string;
+  criteria: AcceptanceCriterion[];
+  /** Test framework: 'ink-testing-library' | 'react' */
+  testFramework?: string;
+}
+
+/**
+ * Build snapshot test template code for the given criteria.
+ *
+ * @param options - Feature name, criteria, and optional test framework
+ * @returns TypeScript test code string
+ */
+export function buildSnapshotTemplate(options: SnapshotTemplateOptions): string {
+  const { featureName, criteria } = options;
+
+  const tests = criteria
+    .map(
+      (ac) => `  test("${ac.id}: ${ac.text}", () => {
+    const { lastFrame } = render(<${toPascalCase(featureName)} />);
+    expect(lastFrame()).toMatchSnapshot();
+  });`,
+    )
+    .join("\n\n");
+
+  return `import { describe, expect, test } from "bun:test";
+import { render } from "ink-testing-library";
+import { ${toPascalCase(featureName)} } from "../src/${featureName}";
+
+describe("${featureName} - Acceptance Tests", () => {
+${tests}
+});
+`;
+}
+
+function toPascalCase(name: string): string {
+  return name
+    .split(/[-_\s]+/)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join("");
+}

package/src/acceptance/templates/unit.ts

@@ -0,0 +1,48 @@
+/**
+ * Unit test template builder
+ *
+ * Generates acceptance test structure for unit testing strategy:
+ * imports the function under test, calls it, and asserts on the return value.
+ */
+
+import type { AcceptanceCriterion } from "../types";
+
+export interface UnitTemplateOptions {
+  featureName: string;
+  criteria: AcceptanceCriterion[];
+}
+
+/**
+ * Build unit test template code for the given criteria.
+ *
+ * @param options - Feature name and criteria list
+ * @returns TypeScript test code string
+ */
+export function buildUnitTemplate(options: UnitTemplateOptions): string {
+  const { featureName, criteria } = options;
+
+  const tests = criteria
+    .map(
+      (ac) => `  test("${ac.id}: ${ac.text}", async () => {
+    // TODO: import and call the function under test
+    expect(true).toBe(true); // Replace with real assertion
+  });`,
+    )
+    .join("\n\n");
+
+  return `import { describe, expect, test } from "bun:test";
+import { ${toCamelCase(featureName)} } from "../src/${toKebabCase(featureName)}";
+
+describe("${featureName} - Acceptance Tests", () => {
+${tests}
+});
+`;
+}
+
+function toCamelCase(name: string): string {
+  return name.replace(/-([a-z])/g, (_, c: string) => c.toUpperCase());
+}
+
+function toKebabCase(name: string): string {
+  return name.toLowerCase().replace(/\s+/g, "-");
+}

package/src/acceptance/types.ts

@@ -4,7 +4,7 @@
  * Types for generating acceptance tests from spec.md acceptance criteria.
  */
 
-import type { ModelDef, ModelTier, NaxConfig } from "../config/schema";
+import type { AcceptanceTestStrategy, ModelDef, ModelTier, NaxConfig } from "../config/schema";
 
 /**
  * A single refined acceptance criterion produced by the refinement module.
@@ -30,6 +30,10 @@ export interface RefinementContext {
   codebaseContext: string;
   /** Global config — model tier resolved from config.acceptance.model */
   config: NaxConfig;
+  /** Test strategy — controls strategy-specific prompt instructions */
+  testStrategy?: AcceptanceTestStrategy;
+  /** Test framework — informs LLM which testing library syntax to use */
+  testFramework?: string;
 }
 
 /**
@@ -84,6 +88,10 @@ export interface GenerateFromPRDOptions {
   modelDef: ModelDef;
   /** Global config for quality settings */
   config: NaxConfig;
+  /** Test strategy to use for template selection (default: 'unit') */
+  testStrategy?: AcceptanceTestStrategy;
+  /** Test framework for component/snapshot strategies (e.g. 'ink-testing-library', 'react') */
+  testFramework?: string;
 }
 
 export interface GenerateAcceptanceTestsOptions {