@nathapp/nax 0.43.1 → 0.45.0

package/src/precheck/index.ts

@@ -4,6 +4,10 @@
  * Runs all prechecks with formatted output. Stops on first Tier 1 blocker (fail-fast).
  * Collects all Tier 2 warnings. Formats human-readable output with emoji indicators.
  * Supports --json flag for machine-readable output.
+ *
+ * Check categories:
+ * - **Environment checks** — no PRD needed (git, deps, agent CLI, stale lock)
+ * - **Project checks** — require PRD (validation, story counts, story size gate)
  */
 
 import type { NaxConfig } from "../config";
@@ -80,8 +84,136 @@ export interface PrecheckResultWithCode {
   flaggedStories?: import("./story-size-gate").FlaggedStory[];
 }
 
+// ─────────────────────────────────────────────────────────────────────────────
+// Check list definitions — shared between runEnvironmentPrecheck and runPrecheck
+// ─────────────────────────────────────────────────────────────────────────────
+
+type CheckFn = () => Promise<Check | Check[]>;
+
+/**
+ * Early environment checks — git repo, clean tree, stale lock.
+ * Fast checks that run first in both runEnvironmentPrecheck and runPrecheck.
+ * In runPrecheck, PRD validation is inserted after these (original order preserved).
+ */
+function getEarlyEnvironmentBlockers(workdir: string): CheckFn[] {
+  return [() => checkGitRepoExists(workdir), () => checkWorkingTreeClean(workdir), () => checkStaleLock(workdir)];
+}
+
+/**
+ * Late environment checks — agent CLI, deps, commands, git user.
+ * Run after PRD validation in runPrecheck; all included in runEnvironmentPrecheck.
+ */
+function getLateEnvironmentBlockers(config: NaxConfig, workdir: string): CheckFn[] {
+  return [
+    () => checkAgentCLI(config),
+    () => checkDependenciesInstalled(workdir),
+    () => checkTestCommand(config),
+    () => checkLintCommand(config),
+    () => checkTypecheckCommand(config),
+    () => checkGitUserConfigured(workdir),
+  ];
+}
+
+/** All environment checks — no PRD needed. Used by runEnvironmentPrecheck. */
+function getEnvironmentBlockers(config: NaxConfig, workdir: string): CheckFn[] {
+  return [...getEarlyEnvironmentBlockers(workdir), ...getLateEnvironmentBlockers(config, workdir)];
+}
+
+/** Environment warnings — no PRD needed. */
+function getEnvironmentWarnings(config: NaxConfig, workdir: string): CheckFn[] {
+  return [
+    () => checkClaudeMdExists(workdir),
+    () => checkDiskSpace(),
+    () => checkOptionalCommands(config, workdir),
+    () => checkGitignoreCoversNax(workdir),
+    () => checkPromptOverrideFiles(config, workdir),
+    () => checkMultiAgentHealth(),
+  ];
+}
+
+/** Project checks — require PRD. */
+function getProjectBlockers(prd: PRD): CheckFn[] {
+  return [() => checkPRDValid(prd)];
+}
+
+/** Project warnings — require PRD. */
+function getProjectWarnings(prd: PRD): CheckFn[] {
+  return [() => checkPendingStories(prd)];
+}
+
+/** Normalize check result to array (some checks return Check[]) */
+function normalizeChecks(result: Check | Check[]): Check[] {
+  return Array.isArray(result) ? result : [result];
+}
+
+/** Result from environment-only precheck */
+export interface EnvironmentPrecheckResult {
+  /** Whether all environment checks passed (no blockers) */
+  passed: boolean;
+  /** Blocker check results */
+  blockers: Check[];
+  /** Warning check results */
+  warnings: Check[];
+}
+
+/**
+ * Run environment-only prechecks (no PRD needed).
+ *
+ * Use before plan phase to catch environment issues early,
+ * before expensive LLM calls are made.
+ */
+export async function runEnvironmentPrecheck(
+  config: NaxConfig,
+  workdir: string,
+  options?: { format?: "human" | "json"; silent?: boolean },
+): Promise<EnvironmentPrecheckResult> {
+  const format = options?.format ?? "human";
+  const silent = options?.silent ?? false;
+
+  const passed: Check[] = [];
+  const blockers: Check[] = [];
+  const warnings: Check[] = [];
+
+  // Environment blockers — fail-fast
+  for (const checkFn of getEnvironmentBlockers(config, workdir)) {
+    const checks = normalizeChecks(await checkFn());
+    let blocked = false;
+    for (const check of checks) {
+      if (!silent && format === "human") printCheckResult(check);
+      if (check.passed) {
+        passed.push(check);
+      } else {
+        blockers.push(check);
+        blocked = true;
+        break;
+      }
+    }
+    if (blocked) break;
+  }
+
+  // Environment warnings — only if no blockers
+  if (blockers.length === 0) {
+    for (const checkFn of getEnvironmentWarnings(config, workdir)) {
+      for (const check of normalizeChecks(await checkFn())) {
+        if (!silent && format === "human") printCheckResult(check);
+        if (check.passed) {
+          passed.push(check);
+        } else {
+          warnings.push(check);
+        }
+      }
+    }
+  }
+
+  if (!silent && format === "json") {
+    console.log(JSON.stringify({ passed: blockers.length === 0, blockers, warnings }, null, 2));
+  }
+
+  return { passed: blockers.length === 0, blockers, warnings };
+}
+
 /**
- * Run all precheck validations.
+ * Run all precheck validations (environment + project).
  * Returns result, exit code, and formatted output.
  */
 export async function runPrecheck(
@@ -98,67 +230,46 @@ export async function runPrecheck(
   const warnings: Check[] = [];
 
   // ─────────────────────────────────────────────────────────────────────────────
-  // Tier 1 Blockers - fail-fast on first failure
+  // Tier 1 Blockers — environment + project, fail-fast on first failure
   // ─────────────────────────────────────────────────────────────────────────────
 
+  // Original order preserved: early env → PRD valid → late env
+  // checkPRDValid at position 4 ensures test environments that lack agent CLI
+  // still get EXIT_CODES.INVALID_PRD (2) rather than a generic blocker (1)
   const tier1Checks = [
-    () => checkGitRepoExists(workdir),
-    () => checkWorkingTreeClean(workdir),
-    () => checkStaleLock(workdir),
-    () => checkPRDValid(prd),
-    () => checkAgentCLI(config),
-    () => checkDependenciesInstalled(workdir),
-    () => checkTestCommand(config),
-    () => checkLintCommand(config),
-    () => checkTypecheckCommand(config),
-    () => checkGitUserConfigured(workdir),
+    ...getEarlyEnvironmentBlockers(workdir),
+    ...getProjectBlockers(prd),
+    ...getLateEnvironmentBlockers(config, workdir),
   ];
 
+  let tier1Blocked = false;
   for (const checkFn of tier1Checks) {
-    const result = await checkFn();
-
-    if (format === "human") {
-      printCheckResult(result);
-    }
-
-    if (result.passed) {
-      passed.push(result);
-    } else {
-      blockers.push(result);
-      // Fail-fast: stop on first blocker
-      break;
+    for (const check of normalizeChecks(await checkFn())) {
+      if (format === "human") printCheckResult(check);
+      if (check.passed) {
+        passed.push(check);
+      } else {
+        blockers.push(check);
+        tier1Blocked = true;
+        break;
+      }
     }
+    if (tier1Blocked) break;
   }
 
   // ─────────────────────────────────────────────────────────────────────────────
-  // Tier 2 Warnings - run all regardless of failures
+  // Tier 2 Warnings — environment + project, run all regardless of failures
   // ─────────────────────────────────────────────────────────────────────────────
 
   let flaggedStories: import("./story-size-gate").FlaggedStory[] = [];
 
   // Only run Tier 2 if no blockers
   if (blockers.length === 0) {
-    const tier2Checks = [
-      () => checkClaudeMdExists(workdir),
-      () => checkDiskSpace(),
-      () => checkPendingStories(prd),
-      () => checkOptionalCommands(config, workdir),
-      () => checkGitignoreCoversNax(workdir),
-      () => checkPromptOverrideFiles(config, workdir),
-      () => checkMultiAgentHealth(),
-    ];
+    const tier2Checks = [...getEnvironmentWarnings(config, workdir), ...getProjectWarnings(prd)];
 
     for (const checkFn of tier2Checks) {
-      const result = await checkFn();
-
-      // Handle both single checks and arrays of checks
-      const checksToProcess = Array.isArray(result) ? result : [result];
-
-      for (const check of checksToProcess) {
-        if (format === "human") {
-          printCheckResult(check);
-        }
-
+      for (const check of normalizeChecks(await checkFn())) {
+        if (format === "human") printCheckResult(check);
         if (check.passed) {
           passed.push(check);
         } else {

package/src/verification/rectification-loop.ts

@@ -7,7 +7,7 @@
  * Used by: src/pipeline/stages/rectify.ts, src/execution/lifecycle/run-regression.ts
  */
 
-import { getAgent } from "../agents";
+import { getAgent as _getAgent } from "../agents";
 import type { NaxConfig } from "../config";
 import { resolveModel } from "../config";
 import { resolvePermissions } from "../config/permissions";
@@ -16,7 +16,7 @@ import { getSafeLogger } from "../logger";
 import type { UserStory } from "../prd";
 import { getExpectedFiles } from "../prd";
 import { type RectificationState, createRectificationPrompt, shouldRetryRectification } from "./rectification";
-import { fullSuite as runVerification } from "./runners";
+import { fullSuite as _fullSuite } from "./runners";
 
 export interface RectificationLoopOptions {
   config: NaxConfig;
@@ -26,11 +26,21 @@ export interface RectificationLoopOptions {
   timeoutSeconds: number;
   testOutput: string;
   promptPrefix?: string;
+  featureName?: string;
 }
 
+// ─────────────────────────────────────────────────────────────────────────────
+// Injectable dependencies
+// ─────────────────────────────────────────────────────────────────────────────
+
+export const _rectificationDeps = {
+  getAgent: _getAgent as (name: string) => import("../agents/types").AgentAdapter | undefined,
+  runVerification: _fullSuite as typeof _fullSuite,
+};
+
 /** Run the rectification retry loop. Returns true if all failures were fixed. */
 export async function runRectificationLoop(opts: RectificationLoopOptions): Promise<boolean> {
-  const { config, workdir, story, testCommand, timeoutSeconds, testOutput, promptPrefix } = opts;
+  const { config, workdir, story, testCommand, timeoutSeconds, testOutput, promptPrefix, featureName } = opts;
   const logger = getSafeLogger();
   const rectificationConfig = config.execution.rectification;
   const testSummary = parseBunTestOutput(testOutput);
@@ -59,7 +69,7 @@ export async function runRectificationLoop(opts: RectificationLoopOptions): Prom
     let rectificationPrompt = createRectificationPrompt(testSummary.failures, story, rectificationConfig);
     if (promptPrefix) rectificationPrompt = `${promptPrefix}\n\n${rectificationPrompt}`;
 
-    const agent = getAgent(config.autoMode.defaultAgent);
+    const agent = _rectificationDeps.getAgent(config.autoMode.defaultAgent);
     if (!agent) {
       logger?.error("rectification", "Agent not found, cannot retry");
       break;
@@ -78,6 +88,9 @@ export async function runRectificationLoop(opts: RectificationLoopOptions): Prom
       pipelineStage: "rectification",
       config,
       maxInteractionTurns: config.agent?.maxInteractionTurns,
+      featureName,
+      storyId: story.id,
+      sessionRole: "implementer",
     });
 
     if (agentResult.success) {
@@ -94,7 +107,7 @@ export async function runRectificationLoop(opts: RectificationLoopOptions): Prom
       });
     }
 
-    const retryVerification = await runVerification({
+    const retryVerification = await _rectificationDeps.runVerification({
       workdir,
       expectedFiles: getExpectedFiles(story),
       command: testCommand,