@nathapp/nax 0.50.3 → 0.51.2

package/src/execution/lifecycle/acceptance-loop.ts

@@ -1,309 +0,0 @@
-/**
- * Acceptance Retry Loop
- *
- * Handles the acceptance testing retry loop after main execution completes:
- * 1. Runs acceptance validation
- * 2. Generates fix stories for failed acceptance criteria
- * 3. Executes fix stories through pipeline
- * 4. Retries until max retries or all tests pass
- */
-
-import path from "node:path";
-import { type FixStory, convertFixStoryToUserStory, generateFixStories } from "../../acceptance";
-import type { NaxConfig } from "../../config";
-import { resolveModel } from "../../config/schema";
-import { type LoadedHooksConfig, fireHook } from "../../hooks";
-import { getSafeLogger } from "../../logger";
-import type { StoryMetrics } from "../../metrics";
-import type { PipelineEventEmitter } from "../../pipeline/events";
-import { runPipeline } from "../../pipeline/runner";
-import { defaultPipeline } from "../../pipeline/stages";
-import type { AgentGetFn } from "../../pipeline/types";
-import type { PipelineContext, RoutingResult } from "../../pipeline/types";
-import type { PluginRegistry } from "../../plugins";
-import { loadPRD, savePRD } from "../../prd";
-import type { PRD, UserStory } from "../../prd/types";
-import { routeTask } from "../../routing";
-import { hookCtx } from "../helpers";
-import type { StatusWriter } from "../status-writer";
-
-export interface AcceptanceLoopContext {
-  config: NaxConfig;
-  prd: PRD;
-  prdPath: string;
-  workdir: string;
-  featureDir?: string;
-  hooks: LoadedHooksConfig;
-  feature: string;
-  totalCost: number;
-  iterations: number;
-  storiesCompleted: number;
-  allStoryMetrics: StoryMetrics[];
-  pluginRegistry: PluginRegistry;
-  eventEmitter?: PipelineEventEmitter;
-  statusWriter: StatusWriter;
-  /** Protocol-aware agent resolver — passed from registry at run start */
-  agentGetFn?: AgentGetFn;
-}
-
-export interface AcceptanceLoopResult {
-  success: boolean;
-  prd: PRD;
-  totalCost: number;
-  iterations: number;
-  storiesCompleted: number;
-  prdDirty: boolean;
-}
-
-export function isStubTestFile(content: string): boolean {
-  // Detect skeleton stubs: expect(true).toBe(false) or expect(true).toBe(true) in test bodies
-  return /expect\s*\(\s*true\s*\)\s*\.\s*toBe\s*\(\s*(?:false|true)\s*\)/.test(content);
-}
-
-/** Load spec.md content for AC text */
-async function loadSpecContent(featureDir?: string): Promise<string> {
-  if (!featureDir) return "";
-  const specPath = path.join(featureDir, "spec.md");
-  const specFile = Bun.file(specPath);
-  return (await specFile.exists()) ? await specFile.text() : "";
-}
-
-/** Build result object for loop exit */
-function buildResult(
-  success: boolean,
-  prd: PRD,
-  totalCost: number,
-  iterations: number,
-  storiesCompleted: number,
-  prdDirty: boolean,
-): AcceptanceLoopResult {
-  return { success, prd, totalCost, iterations, storiesCompleted, prdDirty };
-}
-
-/** Generate and add fix stories to PRD */
-async function generateAndAddFixStories(
-  ctx: AcceptanceLoopContext,
-  failures: { failedACs: string[]; testOutput: string },
-  prd: PRD,
-): Promise<FixStory[] | null> {
-  const logger = getSafeLogger();
-  const { getAgent } = await import("../../agents");
-  const agent = (ctx.agentGetFn ?? getAgent)(ctx.config.autoMode.defaultAgent);
-  if (!agent) {
-    logger?.error("acceptance", "Agent not found, cannot generate fix stories");
-    return null;
-  }
-  const modelDef = resolveModel(ctx.config.models[ctx.config.analyze.model]);
-  const fixStories = await generateFixStories(agent, {
-    failedACs: failures.failedACs,
-    testOutput: failures.testOutput,
-    prd,
-    specContent: await loadSpecContent(ctx.featureDir),
-    workdir: ctx.workdir,
-    modelDef,
-    config: ctx.config,
-  });
-  if (fixStories.length === 0) {
-    logger?.error("acceptance", "Failed to generate fix stories");
-    return null;
-  }
-  logger?.info("acceptance", `Generated ${fixStories.length} fix stories`);
-  for (const fixStory of fixStories) {
-    const userStory = convertFixStoryToUserStory(fixStory);
-    prd.userStories.push(userStory);
-    logger?.debug("acceptance", `Fix story added: ${userStory.id}: ${userStory.title}`);
-  }
-  return fixStories;
-}
-
-/** Execute a single fix story through the pipeline */
-async function executeFixStory(
-  ctx: AcceptanceLoopContext,
-  story: UserStory,
-  prd: PRD,
-  iterations: number,
-): Promise<{ success: boolean; cost: number; metrics?: StoryMetrics[] }> {
-  const logger = getSafeLogger();
-  const routing = routeTask(story.title, story.description, story.acceptanceCriteria, story.tags, ctx.config);
-  logger?.info("acceptance", `Starting fix story: ${story.id}`, { storyId: story.id, storyTitle: story.title });
-  await fireHook(
-    ctx.hooks,
-    "on-story-start",
-    hookCtx(ctx.feature, {
-      storyId: story.id,
-      model: routing.modelTier,
-      agent: ctx.config.autoMode.defaultAgent,
-      iteration: iterations,
-    }),
-    ctx.workdir,
-  );
-  const fixContext: PipelineContext = {
-    config: ctx.config,
-    effectiveConfig: ctx.config,
-    prd,
-    story,
-    stories: [story],
-    routing: routing as RoutingResult,
-    workdir: ctx.workdir,
-    featureDir: ctx.featureDir,
-    hooks: ctx.hooks,
-    plugins: ctx.pluginRegistry,
-    storyStartTime: new Date().toISOString(),
-    agentGetFn: ctx.agentGetFn,
-  };
-  const result = await runPipeline(defaultPipeline, fixContext, ctx.eventEmitter);
-  logger?.info("acceptance", `Fix story ${story.id} ${result.success ? "passed" : "failed"}`);
-  return {
-    success: result.success,
-    cost: result.context.agentResult?.estimatedCost || 0,
-    metrics: result.context.storyMetrics,
-  };
-}
-
-/**
- * Run the acceptance retry loop
- *
- * Executes acceptance tests and handles retry logic with fix story generation.
- */
-export async function runAcceptanceLoop(ctx: AcceptanceLoopContext): Promise<AcceptanceLoopResult> {
-  const logger = getSafeLogger();
-  const maxRetries = ctx.config.acceptance.maxRetries;
-
-  let acceptanceRetries = 0;
-  let prd = ctx.prd;
-  let totalCost = ctx.totalCost;
-  let iterations = ctx.iterations;
-  let storiesCompleted = ctx.storiesCompleted;
-  let prdDirty = false;
-
-  logger?.info("acceptance", "All stories complete, running acceptance validation");
-
-  while (acceptanceRetries < maxRetries) {
-    // Run acceptance validation
-    const firstStory = prd.userStories[0];
-    const acceptanceContext: PipelineContext = {
-      config: ctx.config,
-      effectiveConfig: ctx.config,
-      prd,
-      story: firstStory,
-      stories: [firstStory],
-      routing: {
-        complexity: "simple",
-        modelTier: "balanced",
-        testStrategy: "test-after",
-        reasoning: "Acceptance validation",
-      },
-      workdir: ctx.workdir,
-      featureDir: ctx.featureDir,
-      hooks: ctx.hooks,
-      plugins: ctx.pluginRegistry,
-      agentGetFn: ctx.agentGetFn,
-    };
-
-    const { acceptanceStage } = await import("../../pipeline/stages/acceptance");
-    const acceptanceResult = await acceptanceStage.execute(acceptanceContext);
-
-    if (acceptanceResult.action === "continue") {
-      logger?.info("acceptance", "Acceptance validation passed!");
-      return buildResult(true, prd, totalCost, iterations, storiesCompleted, prdDirty);
-    }
-
-    if (acceptanceResult.action !== "fail") {
-      logger?.warn("acceptance", `Unexpected acceptance result: ${acceptanceResult.action}`);
-      return buildResult(false, prd, totalCost, iterations, storiesCompleted, prdDirty);
-    }
-
-    // Handle acceptance test failures
-    const failures = acceptanceContext.acceptanceFailures;
-    if (!failures || failures.failedACs.length === 0) {
-      logger?.error("acceptance", "Acceptance tests failed but no specific failures detected");
-      logger?.warn("acceptance", "Manual intervention required");
-      await fireHook(
-        ctx.hooks,
-        "on-pause",
-        hookCtx(ctx.feature, { reason: "Acceptance tests failed (no failures detected)", cost: totalCost }),
-        ctx.workdir,
-      );
-      return buildResult(false, prd, totalCost, iterations, storiesCompleted, prdDirty);
-    }
-
-    acceptanceRetries++;
-    logger?.warn("acceptance", `Acceptance retry ${acceptanceRetries}/${maxRetries}`, {
-      failedACs: failures.failedACs,
-    });
-
-    if (acceptanceRetries >= maxRetries) {
-      logger?.error("acceptance", "Max acceptance retries reached");
-      logger?.warn("acceptance", "Manual intervention required");
-      logger?.debug("acceptance", 'Run: nax accept --override AC-N "reason" to skip specific ACs');
-      await fireHook(
-        ctx.hooks,
-        "on-pause",
-        hookCtx(ctx.feature, {
-          reason: `Acceptance validation failed after ${maxRetries} retries: ${failures.failedACs.join(", ")}`,
-          cost: totalCost,
-        }),
-        ctx.workdir,
-      );
-      return buildResult(false, prd, totalCost, iterations, storiesCompleted, prdDirty);
-    }
-
-    // Check for stub test file before generating fix stories
-    if (ctx.featureDir) {
-      const testPath = path.join(ctx.featureDir, "acceptance.test.ts");
-      const testFile = Bun.file(testPath);
-      if (await testFile.exists()) {
-        const testContent = await testFile.text();
-        if (isStubTestFile(testContent)) {
-          logger?.warn("acceptance", "Stub tests detected — re-generating acceptance tests");
-          const { unlink } = await import("node:fs/promises");
-          await unlink(testPath);
-          const { acceptanceSetupStage } = await import("../../pipeline/stages/acceptance-setup");
-          await acceptanceSetupStage.execute(acceptanceContext);
-          const newContent = await Bun.file(testPath).text();
-          if (isStubTestFile(newContent)) {
-            logger?.error(
-              "acceptance",
-              "Acceptance test generation failed after retry — manual implementation required",
-            );
-            return buildResult(false, prd, totalCost, iterations, storiesCompleted, prdDirty);
-          }
-        }
-      }
-    }
-
-    // Generate and add fix stories
-    logger?.info("acceptance", "Generating fix stories...");
-    const fixStories = await generateAndAddFixStories(ctx, failures, prd);
-    if (!fixStories) {
-      return buildResult(false, prd, totalCost, iterations, storiesCompleted, prdDirty);
-    }
-
-    await savePRD(prd, ctx.prdPath);
-    prdDirty = true;
-
-    // Execute fix stories
-    logger?.info("acceptance", "Running fix stories...");
-    for (const fixStory of fixStories) {
-      const userStory = prd.userStories.find((s) => s.id === fixStory.id);
-      if (!userStory || userStory.status !== "pending") continue;
-
-      iterations++;
-      const result = await executeFixStory(ctx, userStory, prd, iterations);
-      prd = await loadPRD(ctx.prdPath); // Reload to get updated PRD
-
-      if (result.success) {
-        storiesCompleted++;
-        totalCost += result.cost;
-        if (result.metrics) ctx.allStoryMetrics.push(...result.metrics);
-      }
-
-      await savePRD(prd, ctx.prdPath);
-      prdDirty = true;
-    }
-
-    logger?.info("acceptance", "Re-running acceptance tests...");
-  }
-
-  return buildResult(false, prd, totalCost, iterations, storiesCompleted, prdDirty);
-}

package/src/execution/lifecycle/headless-formatter.ts

@@ -1,83 +0,0 @@
-/**
- * Headless Output Formatting
- *
- * Handles console output formatting for headless (non-TUI) mode.
- * Extracts run header and footer formatting logic from runner.ts.
- */
-
-import chalk from "chalk";
-import type { RunSummary } from "../../logging";
-import { formatRunSummary } from "../../logging";
-import { NAX_VERSION } from "../../version";
-
-export interface RunHeaderOptions {
-  feature: string;
-  totalStories: number;
-  pendingStories: number;
-  workdir: string;
-  formatterMode: "quiet" | "normal" | "verbose" | "json";
-}
-
-export interface RunFooterOptions {
-  finalCounts: {
-    total: number;
-    passed: number;
-    failed: number;
-    skipped: number;
-  };
-  durationMs: number;
-  totalCost: number;
-  startedAt: string;
-  completedAt: string;
-  formatterMode: "quiet" | "normal" | "verbose" | "json";
-}
-
-/**
- * Output run header in headless mode
- */
-export async function outputRunHeader(options: RunHeaderOptions): Promise<void> {
-  const { feature, totalStories, pendingStories, workdir, formatterMode } = options;
-
-  if (formatterMode === "json") {
-    return;
-  }
-
-  console.log("");
-  console.log(chalk.bold(chalk.blue("═".repeat(60))));
-  console.log(chalk.bold(chalk.blue(`  ▶ NAX v${NAX_VERSION} — RUN STARTED`)));
-  console.log(chalk.blue("═".repeat(60)));
-  console.log(`  ${chalk.gray("Feature:")}  ${chalk.cyan(feature)}`);
-  console.log(`  ${chalk.gray("Stories:")}  ${chalk.cyan(`${totalStories} total, ${pendingStories} pending`)}`);
-  console.log(`  ${chalk.gray("Path:")}     ${chalk.dim(workdir)}`);
-  console.log(chalk.blue("═".repeat(60)));
-  console.log("");
-}
-
-/**
- * Output run footer in headless mode
- */
-export function outputRunFooter(options: RunFooterOptions): void {
-  const { finalCounts, durationMs, totalCost, startedAt, completedAt, formatterMode } = options;
-
-  if (formatterMode === "json") {
-    return;
-  }
-
-  const runSummary: RunSummary = {
-    total: finalCounts.total,
-    passed: finalCounts.passed,
-    failed: finalCounts.failed,
-    skipped: finalCounts.skipped,
-    durationMs,
-    totalCost,
-    startedAt,
-    completedAt,
-  };
-
-  const summaryOutput = formatRunSummary(runSummary, {
-    mode: formatterMode,
-    useColor: true,
-  });
-
-  console.log(summaryOutput);
-}

package/src/execution/lifecycle/index.ts

@@ -1,11 +0,0 @@
-/**
- * Lifecycle module exports
- */
-
-export { runAcceptanceLoop, type AcceptanceLoopContext, type AcceptanceLoopResult } from "./acceptance-loop";
-export { outputRunHeader, outputRunFooter, type RunHeaderOptions, type RunFooterOptions } from "./headless-formatter";
-export { handleParallelCompletion, type ParallelCompletionOptions } from "./parallel-lifecycle";
-export { handleRunCompletion, type RunCompletionOptions, type RunCompletionResult } from "./run-completion";
-export { cleanupRun, type RunCleanupOptions } from "./run-cleanup";
-export { setupRun, type RunSetupOptions, type RunSetupResult } from "./run-setup";
-export { runDeferredRegression, type DeferredRegressionOptions, type DeferredRegressionResult } from "./run-regression";

package/src/execution/lifecycle/parallel-lifecycle.ts

@@ -1,101 +0,0 @@
-/**
- * Parallel Execution Lifecycle
- *
- * Handles metrics saving and reporter notifications for parallel execution completion.
- * Extracted from runner.ts to reduce its size.
- */
-
-import { getSafeLogger } from "../../logger";
-import type { StoryMetrics } from "../../metrics";
-import { saveRunMetrics } from "../../metrics";
-import type { PluginRegistry } from "../../plugins/registry";
-import { countStories } from "../../prd";
-import type { PRD } from "../../prd";
-
-export interface ParallelCompletionOptions {
-  runId: string;
-  feature: string;
-  startedAt: string;
-  completedAt: string;
-  prd: PRD;
-  allStoryMetrics: StoryMetrics[];
-  totalCost: number;
-  storiesCompleted: number;
-  durationMs: number;
-  workdir: string;
-  pluginRegistry: PluginRegistry;
-}
-
-/**
- * Handle parallel execution completion:
- * - Save run metrics
- * - Emit reporter events
- */
-export async function handleParallelCompletion(options: ParallelCompletionOptions): Promise<void> {
-  const logger = getSafeLogger();
-  const {
-    runId,
-    feature,
-    startedAt,
-    completedAt,
-    prd,
-    allStoryMetrics,
-    totalCost,
-    storiesCompleted,
-    durationMs,
-    workdir,
-    pluginRegistry,
-  } = options;
-
-  // Save run metrics
-  const runMetrics = {
-    runId,
-    feature,
-    startedAt,
-    completedAt,
-    totalCost,
-    totalStories: allStoryMetrics.length,
-    storiesCompleted,
-    storiesFailed: countStories(prd).failed,
-    totalDurationMs: durationMs,
-    stories: allStoryMetrics,
-  };
-
-  await saveRunMetrics(workdir, runMetrics);
-
-  // Log run completion
-  const finalCounts = countStories(prd);
-  logger?.info("run.complete", "Feature execution completed", {
-    runId,
-    feature,
-    success: true,
-    totalStories: finalCounts.total,
-    storiesCompleted,
-    storiesFailed: finalCounts.failed,
-    storiesPending: finalCounts.pending,
-    totalCost,
-    durationMs,
-  });
-
-  // Emit onRunEnd to reporters
-  const reporters = pluginRegistry.getReporters();
-  for (const reporter of reporters) {
-    if (reporter.onRunEnd) {
-      try {
-        await reporter.onRunEnd({
-          runId,
-          totalDurationMs: durationMs,
-          totalCost,
-          storySummary: {
-            completed: storiesCompleted,
-            failed: finalCounts.failed,
-            skipped: finalCounts.skipped,
-            paused: finalCounts.paused,
-          },
-        });
-      } catch (error) {
-        logger?.warn("plugins", `Reporter '${reporter.name}' onRunEnd failed`, { error });
-      }
-    }
-  }
-}

package/src/execution/lifecycle/precheck-runner.ts

@@ -1,140 +0,0 @@
-/**
- * Precheck Runner
- *
- * Handles precheck validation execution before the main run starts.
- * Validates project state, dependencies, and configuration.
- * Blocks execution on Tier 1 failures, warns on Tier 2 failures.
- */
-
-import { appendFileSync, mkdirSync } from "node:fs";
-import path from "node:path";
-import chalk from "chalk";
-import type { NaxConfig } from "../../config";
-import type { InteractionChain } from "../../interaction/chain";
-import { getSafeLogger } from "../../logger";
-import type { PRD } from "../../prd/types";
-import type { StatusWriter } from "../status-writer";
-
-export interface PrecheckContext {
-  config: NaxConfig;
-  prd: PRD;
-  workdir: string;
-  logFilePath?: string;
-  statusWriter: StatusWriter;
-  headless: boolean;
-  formatterMode: "quiet" | "normal" | "verbose" | "json";
-  interactionChain?: InteractionChain | null;
-  featureName?: string;
-}
-
-/**
- * Run precheck validations before execution starts
- *
- * @throws Error if precheck blockers are found (Tier 1 failures)
- */
-export async function runPrecheckValidation(ctx: PrecheckContext): Promise<void> {
-  const logger = getSafeLogger();
-
-  // Allow tests to skip precheck entirely (git-repo-exists, working-tree-clean, etc. fail in temp dirs)
-  if (process.env.NAX_SKIP_PRECHECK === "1") {
-    logger?.info("precheck", "Skipping precheck validations (NAX_SKIP_PRECHECK=1)");
-    return;
-  }
-
-  logger?.info("precheck", "Running precheck validations...");
-
-  const { runPrecheck } = await import("../../precheck");
-  const precheckResult = await runPrecheck(ctx.config, ctx.prd, {
-    workdir: ctx.workdir,
-    format: "human",
-  });
-
-  // Log precheck results to JSONL
-  if (ctx.logFilePath) {
-    // Ensure directory exists
-    mkdirSync(path.dirname(ctx.logFilePath), { recursive: true });
-
-    const precheckLog = {
-      type: "precheck",
-      timestamp: new Date().toISOString(),
-      passed: precheckResult.output.passed,
-      blockers: precheckResult.output.blockers.map((b) => ({ name: b.name, message: b.message })),
-      warnings: precheckResult.output.warnings.map((w) => ({ name: w.name, message: w.message })),
-      summary: precheckResult.output.summary,
-    };
-    require("node:fs").appendFileSync(ctx.logFilePath, `${JSON.stringify(precheckLog)}\n`);
-  }
-
-  // Handle blockers (Tier 1 failures)
-  if (!precheckResult.output.passed) {
-    logger?.error("precheck", "Precheck failed - execution blocked", {
-      blockers: precheckResult.output.blockers.length,
-      failedChecks: precheckResult.output.blockers.map((b) => b.name),
-    });
-
-    // Update status file with precheck-failed status
-    ctx.statusWriter.setRunStatus("precheck-failed");
-    ctx.statusWriter.setCurrentStory(null);
-    await ctx.statusWriter.update(0, 0);
-
-    // Log detailed error message to console
-    console.error("");
-    console.error(chalk.red("❌ PRECHECK FAILED"));
-    console.error(chalk.red("─".repeat(60)));
-    for (const blocker of precheckResult.output.blockers) {
-      console.error(chalk.red(`✗ ${blocker.name}: ${blocker.message}`));
-    }
-    console.error(chalk.red("─".repeat(60)));
-    console.error(chalk.yellow("\nRun 'nax precheck' for detailed information"));
-    console.error(chalk.dim("Use --skip-precheck to bypass (not recommended)\n"));
-
-    throw new Error(`Precheck failed: ${precheckResult.output.blockers.map((b) => b.name).join(", ")}`);
-  }
-
-  // Handle warnings (Tier 2 failures) - log but continue
-  if (precheckResult.output.warnings.length > 0) {
-    logger?.warn("precheck", "Precheck passed with warnings", {
-      warnings: precheckResult.output.warnings.length,
-      issues: precheckResult.output.warnings.map((w) => w.name),
-    });
-
-    if (ctx.headless && ctx.formatterMode !== "json") {
-      console.log(chalk.yellow("\n⚠️  Precheck warnings:"));
-      for (const warning of precheckResult.output.warnings) {
-        console.log(chalk.yellow(`  ⚠ ${warning.name}: ${warning.message}`));
-      }
-      console.log("");
-    }
-  } else {
-    logger?.info("precheck", "All precheck validations passed");
-  }
-
-  // Story size gate interaction (v0.16.0) - prompt for flagged stories if interaction chain exists
-  if (precheckResult.flaggedStories && precheckResult.flaggedStories.length > 0) {
-    if (ctx.interactionChain && ctx.featureName) {
-      logger?.info("precheck", "Story size gate: prompting user for flagged stories", {
-        count: precheckResult.flaggedStories.length,
-      });
-
-      const { promptForFlaggedStories } = await import("./story-size-prompts");
-      const summary = await promptForFlaggedStories(
-        precheckResult.flaggedStories,
-        ctx.prd,
-        ctx.interactionChain,
-        ctx.featureName,
-      );
-
-      logger?.info("precheck", "Story size gate prompts complete", {
-        approved: summary.approved.length,
-        skipped: summary.skipped.length,
-        aborted: summary.aborted,
-      });
-
-      // PRD has been mutated with skipped stories - no need to return anything
-    } else {
-      logger?.warn("precheck", "Story size gate: interaction chain not available, skipping prompts", {
-        flaggedCount: precheckResult.flaggedStories.length,
-      });
-    }
-  }
-}