@nathapp/nax 0.41.0 → 0.42.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nathapp/nax",
-  "version": "0.41.0",
+  "version": "0.42.0",
   "description": "AI Coding Agent Orchestrator \u2014 loops until done",
   "type": "module",
   "bin": {
@@ -12,11 +12,12 @@
     "build": "bun build bin/nax.ts --outdir dist --target bun --define \"GIT_COMMIT=\\\"$(git rev-parse --short HEAD)\\\"\"",
     "typecheck": "bun x tsc --noEmit",
     "lint": "bun x biome check src/ bin/",
-    "test": "NAX_SKIP_PRECHECK=1 bun test test/ --timeout=60000",
-    "test:watch": "bun test --watch",
-    "test:unit": "bun test ./test/unit/ --timeout=60000",
-    "test:integration": "bun test ./test/integration/ --timeout=60000",
-    "test:ui": "bun test ./test/ui/ --timeout=60000",
+    "test": "CI=1 NAX_SKIP_PRECHECK=1 bun test test/ --timeout=60000",
+    "test:watch": "CI=1 bun test --watch",
+    "test:unit": "CI=1 NAX_SKIP_PRECHECK=1 bun test ./test/unit/ --timeout=60000",
+    "test:integration": "CI=1 NAX_SKIP_PRECHECK=1 bun test ./test/integration/ --timeout=60000",
+    "test:ui": "CI=1 bun test ./test/ui/ --timeout=60000",
+    "test:real": "NAX_SKIP_PRECHECK=1 bun test test/ --timeout=60000",
     "check-test-overlap": "bun run scripts/check-test-overlap.ts",
     "check-dead-tests": "bun run scripts/check-dead-tests.ts",
     "check:test-sizes": "bun run scripts/check-test-sizes.ts",

package/src/agents/acp/adapter.ts

@@ -505,7 +505,9 @@ export class AcpAgentAdapter implements AgentAdapter {
         }
       }
 
-      if (turnCount >= MAX_TURNS) {
+      // Only warn if we exhausted turns while still receiving questions (interactive mode).
+      // In non-interactive mode (MAX_TURNS=1) the loop always completes in 1 turn — not a warning.
+      if (turnCount >= MAX_TURNS && options.interactionBridge) {
         getSafeLogger()?.warn("acp-adapter", "Reached max turns limit", { sessionName, maxTurns: MAX_TURNS });
       }
     } finally {
@@ -586,10 +588,6 @@ export class AcpAgentAdapter implements AgentAdapter {
   }
 
   async plan(options: PlanOptions): Promise<PlanResult> {
-    if (options.interactive) {
-      throw new Error("[acp-adapter] plan() interactive mode is not yet supported via ACP");
-    }
-
     const modelDef = options.modelDef ?? { provider: "anthropic", model: "default" };
     // Timeout: from options, or config, or fallback to 600s
     const timeoutSeconds =

package/src/agents/claude.ts

@@ -56,6 +56,16 @@ export const _decomposeDeps = {
 // Re-export deps for testing
 export { _runOnceDeps, _completeDeps };
 
+/**
+ * Injectable dependencies for ClaudeCodeAdapter retry loop.
+ * Exported so tests can replace sleep with a no-op spy.
+ *
+ * @internal
+ */
+export const _claudeAdapterDeps = {
+  sleep: (ms: number): Promise<void> => Bun.sleep(ms),
+};
+
 /**
  * Claude Code agent adapter implementation.
  *
@@ -120,7 +130,7 @@ export class ClaudeCodeAdapter implements AgentAdapter {
             const backoffMs = 2 ** attempt * 1000;
             const logger = getLogger();
             logger.warn("agent", "Rate limited, retrying", { backoffSeconds: backoffMs / 1000, attempt, maxRetries });
-            await Bun.sleep(backoffMs);
+            await _claudeAdapterDeps.sleep(backoffMs);
             continue;
           }
 
@@ -138,7 +148,7 @@ export class ClaudeCodeAdapter implements AgentAdapter {
               attempt,
               maxRetries,
             });
-            await Bun.sleep(backoffMs);
+            await _claudeAdapterDeps.sleep(backoffMs);
             continue;
           }
 

package/src/analyze/scanner.ts

@@ -4,7 +4,7 @@
  * Scans the project directory to generate a summary for LLM classification.
  */
 
-import { existsSync } from "node:fs";
+import { existsSync, readdirSync } from "node:fs";
 import { join } from "node:path";
 import type { CodebaseScan } from "./types";
 
@@ -75,38 +75,34 @@ async function generateFileTree(dir: string, maxDepth: number, currentDepth = 0,
   const entries: string[] = [];
 
   try {
-    const dirEntries = Array.from(
-      new Bun.Glob("*").scanSync({
-        cwd: dir,
-        onlyFiles: false,
-      }),
-    );
+    // readdirSync with withFileTypes avoids a separate stat() call per entry —
+    // directory info comes from the single readdir syscall (much faster on large trees).
+    const dirEntries = readdirSync(dir, { withFileTypes: true });
 
     // Sort: directories first, then files
     dirEntries.sort((a, b) => {
-      const aIsDir = !a.includes(".");
-      const bIsDir = !b.includes(".");
-      if (aIsDir && !bIsDir) return -1;
-      if (!aIsDir && bIsDir) return 1;
-      return a.localeCompare(b);
+      if (a.isDirectory() && !b.isDirectory()) return -1;
+      if (!a.isDirectory() && b.isDirectory()) return 1;
+      return a.name.localeCompare(b.name);
     });
 
     for (let i = 0; i < dirEntries.length; i++) {
-      const entry = dirEntries[i];
-      const fullPath = join(dir, entry);
+      const dirent = dirEntries[i];
       const isLast = i === dirEntries.length - 1;
       const connector = isLast ? "└── " : "├── ";
       const childPrefix = isLast ? "    " : "│   ";
+      const isDir = dirent.isDirectory();
 
-      // Check if directory
-      const stat = await Bun.file(fullPath).stat();
-      const isDir = stat.isDirectory();
-
-      entries.push(`${prefix}${connector}${entry}${isDir ? "/" : ""}`);
+      entries.push(`${prefix}${connector}${dirent.name}${isDir ? "/" : ""}`);
 
       // Recurse into directories
       if (isDir) {
-        const subtree = await generateFileTree(fullPath, maxDepth, currentDepth + 1, prefix + childPrefix);
+        const subtree = await generateFileTree(
+          join(dir, dirent.name),
+          maxDepth,
+          currentDepth + 1,
+          prefix + childPrefix,
+        );
         if (subtree) {
           entries.push(subtree);
         }

package/src/cli/plan.ts

@@ -1,178 +1,204 @@
 /**
- * Plan Command — Interactive planning via agent plan mode
+ * Plan Command — Generate prd.json from a spec file via LLM one-shot call
  *
- * Spawns a coding agent in plan mode to gather requirements,
- * ask clarifying questions, and generate a structured specification.
+ * Reads a spec file (--from), builds a planning prompt with codebase context,
+ * calls adapter.complete(), validates the JSON response, and writes prd.json.
+ *
+ * Interactive mode is not yet implemented (PLN-002).
  */
 
 import { existsSync } from "node:fs";
 import { join } from "node:path";
-import { createInterface } from "node:readline";
-import { ClaudeCodeAdapter } from "../agents/claude";
-import type { PlanOptions } from "../agents/types";
+import { getAgent } from "../agents/registry";
+import type { AgentAdapter } from "../agents/types";
 import { scanCodebase } from "../analyze/scanner";
+import type { CodebaseScan } from "../analyze/types";
 import type { NaxConfig } from "../config";
-import { resolveModel } from "../config/schema";
 import { getLogger } from "../logger";
+import { validatePlanOutput } from "../prd/schema";
 
 // ─────────────────────────────────────────────────────────────────────────────
-// Question detection helpers for ACP interaction bridge
+// Dependency injection (_deps) — override in tests
 // ─────────────────────────────────────────────────────────────────────────────
 
-const QUESTION_PATTERNS = [/\?[\s]*$/, /\bwhich\b/i, /\bshould i\b/i, /\bdo you want\b/i, /\bwould you like\b/i];
+export const _deps = {
+  readFile: (path: string): Promise<string> => Bun.file(path).text(),
+  writeFile: (path: string, content: string): Promise<void> => Bun.write(path, content).then(() => {}),
+  scanCodebase: (workdir: string): Promise<CodebaseScan> => scanCodebase(workdir),
+  getAgent: (name: string): AgentAdapter | undefined => getAgent(name),
+  readPackageJson: (workdir: string): Promise<Record<string, unknown> | null> =>
+    Bun.file(join(workdir, "package.json"))
+      .json()
+      .catch(() => null),
+  spawnSync: (cmd: string[], opts?: { cwd?: string }): { stdout: Buffer; exitCode: number | null } => {
+    const result = Bun.spawnSync(cmd, opts ? { cwd: opts.cwd } : {});
+    return { stdout: result.stdout as Buffer, exitCode: result.exitCode };
+  },
+  mkdirp: (path: string): Promise<void> => Bun.spawn(["mkdir", "-p", path]).exited.then(() => {}),
+};
 
-async function detectQuestion(text: string): Promise<boolean> {
-  return QUESTION_PATTERNS.some((p) => p.test(text.trim()));
-}
+// ─────────────────────────────────────────────────────────────────────────────
+// Plan options
+// ─────────────────────────────────────────────────────────────────────────────
 
-async function askHuman(question: string): Promise<string> {
-  const rl = createInterface({ input: process.stdin, output: process.stdout });
-  return new Promise((resolve) => {
-    rl.question(`\n[Agent asks]: ${question}\nYour answer: `, (answer) => {
-      rl.close();
-      resolve(answer.trim());
-    });
-  });
+export interface PlanCommandOptions {
+  /** Path to spec file (--from) — required */
+  from: string;
+  /** Feature name (-f) — required */
+  feature: string;
+  /** Run in auto (one-shot LLM) mode */
+  auto?: boolean;
+  /** Override default branch name (-b) */
+  branch?: string;
 }
 
-/**
- * Template for structured specification output.
- *
- * This template guides the agent to produce a consistent spec format
- * that can be parsed by the analyze command.
- */
-const SPEC_TEMPLATE = `# Feature: [title]
-
-## Problem
-Why this is needed.
-
-## Requirements
-- REQ-1: ...
-- REQ-2: ...
-
-## Acceptance Criteria
-- AC-1: ...
-
-## Technical Notes
-Architecture hints, constraints, dependencies.
-
-## Out of Scope
-What this does NOT include.
-`;
+// ─────────────────────────────────────────────────────────────────────────────
+// Public API
+// ─────────────────────────────────────────────────────────────────────────────
 
 /**
- * Run the plan command to generate a feature specification.
+ * Run the plan command: read spec, call LLM, write prd.json.
  *
- * @param prompt - The feature description or task
  * @param workdir - Project root directory
- * @param config - Ngent configuration
- * @param options - Command options (interactive, from)
- * @returns Path to the generated spec file
+ * @param config  - Nax configuration
+ * @param options - Command options
+ * @returns Path to generated prd.json
  */
-export async function planCommand(
-  prompt: string,
-  workdir: string,
-  config: NaxConfig,
-  options: {
-    interactive?: boolean;
-    from?: string;
-  } = {},
-): Promise<string> {
-  const interactive = options.interactive !== false; // Default to true
-  const ngentDir = join(workdir, "nax");
-  const outputPath = join(ngentDir, config.plan.outputPath);
-
-  // Ensure nax directory exists
-  if (!existsSync(ngentDir)) {
+export async function planCommand(workdir: string, config: NaxConfig, options: PlanCommandOptions): Promise<string> {
+  const naxDir = join(workdir, "nax");
+
+  if (!existsSync(naxDir)) {
     throw new Error(`nax directory not found. Run 'nax init' first in ${workdir}`);
   }
 
-  // Scan codebase for context
   const logger = getLogger();
-  logger.info("cli", "Scanning codebase...");
-  const scan = await scanCodebase(workdir);
 
-  // Build codebase context markdown
+  // Read spec from --from path
+  logger?.info("plan", "Reading spec", { from: options.from });
+  const specContent = await _deps.readFile(options.from);
+
+  // Scan codebase for context
+  logger?.info("plan", "Scanning codebase...");
+  const scan = await _deps.scanCodebase(workdir);
   const codebaseContext = buildCodebaseContext(scan);
 
-  // Resolve model for planning
-  const modelTier = config.plan.model;
-  const modelEntry = config.models[modelTier];
-  const modelDef = resolveModel(modelEntry);
-
-  // Build full prompt with template
-  const fullPrompt = buildPlanPrompt(prompt, SPEC_TEMPLATE);
-
-  // Prepare plan options
-  const planOptions: PlanOptions = {
-    prompt: fullPrompt,
-    workdir,
-    interactive,
-    codebaseContext,
-    inputFile: options.from,
-    modelTier,
-    modelDef,
-    config,
-    // Wire ACP interaction bridge for mid-session Q&A (only in interactive mode)
-    interactionBridge: interactive ? { detectQuestion, onQuestionDetected: askHuman } : undefined,
-  };
+  // Auto-detect project name
+  const pkg = await _deps.readPackageJson(workdir);
+  const projectName = detectProjectName(workdir, pkg);
 
-  // Run agent in plan mode
-  const adapter = new ClaudeCodeAdapter();
-
-  logger.info("cli", interactive ? "Starting interactive planning session..." : `Reading from ${options.from}...`, {
-    interactive,
-    from: options.from,
-  });
-
-  const result = await adapter.plan(planOptions);
-
-  // Write spec to output file
-  if (interactive) {
-    // In interactive mode, the agent may have written directly
-    // But we also capture and write to ensure consistency
-    if (result.specContent) {
-      await Bun.write(outputPath, result.specContent);
-    } else {
-      // If agent wrote directly, verify it exists
-      if (!existsSync(outputPath)) {
-        throw new Error(`Interactive planning completed but spec not found at ${outputPath}`);
-      }
-    }
+  // Build prompt
+  const branchName = options.branch ?? `feat/${options.feature}`;
+  const prompt = buildPlanningPrompt(specContent, codebaseContext);
+
+  // Get agent adapter
+  const agentName = config?.autoMode?.defaultAgent ?? "claude";
+  const adapter = _deps.getAgent(agentName);
+  if (!adapter) {
+    throw new Error(`[plan] No agent adapter found for '${agentName}'`);
+  }
+
+  // Timeout: from config, or default to 600 seconds (10 min)
+  const timeoutSeconds = config?.execution?.sessionTimeoutSeconds ?? 600;
+
+  // Route to auto (one-shot) or interactive (multi-turn) mode
+  let rawResponse: string;
+  if (options.auto) {
+    rawResponse = await adapter.complete(prompt, { jsonMode: true });
   } else {
-    // In non-interactive mode, we have the spec in result
-    if (!result.specContent) {
-      throw new Error("Agent did not produce specification content");
+    const interactionBridge = createCliInteractionBridge();
+    logger?.info("plan", "Starting interactive planning session...", { agent: agentName });
+    try {
+      const result = await adapter.plan({
+        prompt,
+        workdir,
+        interactive: true,
+        timeoutSeconds,
+        interactionBridge,
+      });
+      rawResponse = result.specContent;
+    } finally {
+      logger?.info("plan", "Interactive session ended");
     }
-    await Bun.write(outputPath, result.specContent);
   }
 
-  logger.info("cli", "✓ Specification written to output", { outputPath });
+  // Validate and normalize: handles markdown extraction, trailing commas, LLM quirks,
+  // complexity normalization, dependency cross-ref, and forces status → pending.
+  const finalPrd = validatePlanOutput(rawResponse, options.feature, branchName);
+
+  // Override project with auto-detected name (validatePlanOutput fills feature/branchName already)
+  finalPrd.project = projectName;
+
+  // Write output
+  const outputDir = join(naxDir, "features", options.feature);
+  const outputPath = join(outputDir, "prd.json");
+  await _deps.mkdirp(outputDir);
+  await _deps.writeFile(outputPath, JSON.stringify(finalPrd, null, 2));
+
+  logger?.info("plan", "[OK] PRD written", { outputPath });
 
   return outputPath;
 }
 
+// ─────────────────────────────────────────────────────────────────────────────
+// Interaction and extraction helpers
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Create a CLI interaction bridge for stdin-based human interaction.
+ * This bridge accepts questions from the agent and prompts the user via stdin.
+ */
+function createCliInteractionBridge(): {
+  detectQuestion: (text: string) => Promise<boolean>;
+  onQuestionDetected: (text: string) => Promise<string>;
+} {
+  return {
+    async detectQuestion(text: string): Promise<boolean> {
+      // Simple heuristic: detect if text contains a question mark
+      return text.includes("?");
+    },
+
+    async onQuestionDetected(text: string): Promise<string> {
+      // For now, return the question text as-is to be used as follow-up prompt
+      // In a real CLI, this would read from stdin
+      // TODO: Implement stdin reading for actual CLI interaction
+      return text;
+    },
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Private helpers
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Detect project name from package.json or git remote.
+ */
+function detectProjectName(workdir: string, pkg: Record<string, unknown> | null): string {
+  if (pkg?.name && typeof pkg.name === "string") {
+    return pkg.name;
+  }
+
+  const result = _deps.spawnSync(["git", "remote", "get-url", "origin"], { cwd: workdir });
+  if (result.exitCode === 0) {
+    const url = result.stdout.toString().trim();
+    const match = url.match(/\/([^/]+?)(?:\.git)?$/);
+    if (match?.[1]) return match[1];
+  }
+
+  return "unknown";
+}
+
 /**
  * Build codebase context markdown from scan results.
- *
- * @param scan - Codebase scan result
- * @returns Formatted context string
  */
-function buildCodebaseContext(scan: {
-  fileTree: string;
-  dependencies: Record<string, string>;
-  devDependencies: Record<string, string>;
-  testPatterns: string[];
-}): string {
+function buildCodebaseContext(scan: CodebaseScan): string {
   const sections: string[] = [];
 
-  // File tree
   sections.push("## Codebase Structure\n");
   sections.push("```");
   sections.push(scan.fileTree);
   sections.push("```\n");
 
-  // Dependencies
   const allDeps = { ...scan.dependencies, ...scan.devDependencies };
   const depList = Object.entries(allDeps)
     .map(([name, version]) => `- ${name}@${version}`)
@@ -184,7 +210,6 @@ function buildCodebaseContext(scan: {
     sections.push("");
   }
 
-  // Test patterns
   if (scan.testPatterns.length > 0) {
     sections.push("## Test Setup\n");
     sections.push(scan.testPatterns.map((p) => `- ${p}`).join("\n"));
@@ -195,28 +220,69 @@ function buildCodebaseContext(scan: {
 }
 
 /**
- * Build the full planning prompt with template.
+ * Build the full planning prompt sent to the LLM.
  *
- * @param userPrompt - User's task description
- * @param template - Spec template
- * @returns Full prompt with instructions
+ * Includes:
+ * - Spec content
+ * - Codebase context
+ * - Output schema (exact prd.json JSON structure)
+ * - Complexity classification guide
+ * - Test strategy guide
  */
-function buildPlanPrompt(userPrompt: string, template: string): string {
-  return `You are helping plan a new feature for this codebase.
+function buildPlanningPrompt(specContent: string, codebaseContext: string): string {
+  return `You are a senior software architect generating a product requirements document (PRD) as JSON.
+
+## Spec
+
+${specContent}
+
+## Codebase Context
+
+${codebaseContext}
+
+## Output Schema
+
+Generate a JSON object with this exact structure (no markdown, no explanation — JSON only):
+
+{
+  "project": "string — project name",
+  "feature": "string — feature name",
+  "branchName": "string — git branch (e.g. feat/my-feature)",
+  "createdAt": "ISO 8601 timestamp",
+  "updatedAt": "ISO 8601 timestamp",
+  "userStories": [
+    {
+      "id": "string — e.g. US-001",
+      "title": "string — concise story title",
+      "description": "string — detailed description of the story",
+      "acceptanceCriteria": ["string — each AC line"],
+      "tags": ["string — routing tags, e.g. feature, security, api"],
+      "dependencies": ["string — story IDs this story depends on"],
+      "status": "pending",
+      "passes": false,
+      "routing": {
+        "complexity": "simple | medium | complex | expert",
+        "testStrategy": "test-after | tdd-lite | three-session-tdd",
+        "reasoning": "string — brief classification rationale"
+      },
+      "escalations": [],
+      "attempts": 0
+    }
+  ]
+}
 
-Task: ${userPrompt}
+## Complexity Classification Guide
 
-Please gather requirements and produce a structured specification following this template:
+- simple: ≤50 LOC, single-file change, purely additive, no new dependencies → test-after
+- medium: 50–200 LOC, 2–5 files, standard patterns, clear requirements → tdd-lite
+- complex: 200–500 LOC, multiple modules, new abstractions or integrations → three-session-tdd
+- expert: 500+ LOC, architectural changes, cross-cutting concerns, high risk → three-session-tdd
 
-${template}
+## Test Strategy Guide
 
-Ask clarifying questions as needed to ensure the spec is complete and unambiguous.
-Focus on understanding:
-- The problem being solved
-- Specific requirements and constraints
-- Acceptance criteria for success
-- Technical approach and architecture
-- What is explicitly out of scope
+- test-after: Simple changes with well-understood behavior. Write tests after implementation.
+- tdd-lite: Medium complexity. Write key tests first, implement, then fill coverage.
+- three-session-tdd: Complex/expert. Full TDD cycle with separate sessions for tests and implementation.
 
-When done, output the complete specification in markdown format.`;
+Output ONLY the JSON object. Do not wrap in markdown code blocks.`;
 }

package/src/commands/precheck.ts

@@ -66,7 +66,7 @@ export async function precheckCommand(options: PrecheckOptions): Promise<void> {
   // Validate prd.json exists
   if (!existsSync(prdPath)) {
     console.error(chalk.red(`Missing prd.json for feature: ${featureName}`));
-    console.error(chalk.dim(`Run: nax analyze -f ${featureName}`));
+    console.error(chalk.dim(`Run: nax plan -f ${featureName} --from spec.md --auto`));
     process.exit(EXIT_CODES.INVALID_PRD);
   }
 

package/src/interaction/plugins/webhook.ts

@@ -10,6 +10,15 @@ import type { Server } from "node:http";
 import { z } from "zod";
 import type { InteractionPlugin, InteractionRequest, InteractionResponse } from "../types";
 
+/**
+ * Injectable sleep for WebhookInteractionPlugin.receive() polling loop.
+ * Replace in tests to avoid real backoff delays.
+ * @internal
+ */
+export const _webhookPluginDeps = {
+  sleep: (ms: number): Promise<void> => Bun.sleep(ms),
+};
+
 /** Webhook plugin configuration */
 interface WebhookConfig {
   /** Webhook URL to POST requests to */
@@ -119,7 +128,7 @@ export class WebhookInteractionPlugin implements InteractionPlugin {
         this.pendingResponses.delete(requestId);
         return response;
       }
-      await Bun.sleep(backoffMs);
+      await _webhookPluginDeps.sleep(backoffMs);
       // Exponential backoff: double interval up to max
       backoffMs = Math.min(backoffMs * 2, maxBackoffMs);
     }