@nathapp/nax 0.50.3 → 0.51.2

package/src/execution/lifecycle/run-cleanup.ts

@@ -1,81 +0,0 @@
-/**
- * Run Cleanup — Finally Block Cleanup Logic
- *
- * Handles cleanup operations that run in the finally block:
- * - Stop heartbeat
- * - Cleanup crash handlers
- * - Fire onRunEnd for reporters
- * - Teardown plugins
- * - Release lock
- */
-
-import type { InteractionChain } from "../../interaction";
-import { getSafeLogger } from "../../logger";
-import type { PluginRegistry } from "../../plugins/registry";
-import { countStories } from "../../prd";
-import type { PRD } from "../../prd";
-import { releaseLock } from "../helpers";
-
-export interface RunCleanupOptions {
-  runId: string;
-  startTime: number;
-  totalCost: number;
-  storiesCompleted: number;
-  prd: PRD;
-  pluginRegistry: PluginRegistry;
-  workdir: string;
-  interactionChain: InteractionChain | null;
-}
-
-/**
- * Execute cleanup operations in finally block
- */
-export async function cleanupRun(options: RunCleanupOptions): Promise<void> {
-  const logger = getSafeLogger();
-  const { runId, startTime, totalCost, storiesCompleted, prd, pluginRegistry, workdir, interactionChain } = options;
-
-  // Fire onRunEnd for reporters (even on failure/abort)
-  const durationMs = Date.now() - startTime;
-  const finalCounts = countStories(prd);
-  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 });
-      }
-    }
-  }
-
-  // Teardown plugins
-  try {
-    await pluginRegistry.teardownAll();
-  } catch (error) {
-    logger?.warn("plugins", "Plugin teardown failed", { error });
-  }
-
-  // Destroy interaction chain (US-008)
-  if (interactionChain) {
-    try {
-      await interactionChain.destroy();
-      logger?.debug("interaction", "Interaction chain destroyed");
-    } catch (error) {
-      logger?.warn("interaction", "Interaction chain cleanup failed", { error });
-    }
-  }
-
-  // Always release lock, even if execution fails
-  await releaseLock(workdir);
-}

package/src/execution/lifecycle/run-completion.ts

@@ -1,247 +0,0 @@
-/**
- * Run Completion — Final Metrics and Status Updates
- *
- * Handles the final steps after sequential execution completes:
- * - Run deferred regression gate (if configured)
- * - Save run metrics
- * - Log completion summary with per-story metrics
- * - Update final status
- */
-
-import type { NaxConfig } from "../../config";
-import { fireHook } from "../../hooks/runner";
-import type { HooksConfig } from "../../hooks/types";
-import { getSafeLogger } from "../../logger";
-import type { StoryMetrics } from "../../metrics";
-import { saveRunMetrics } from "../../metrics";
-import { pipelineEventBus } from "../../pipeline/event-bus";
-import type { AgentGetFn } from "../../pipeline/types";
-import { countStories, isComplete, isStalled } from "../../prd";
-import type { PRD } from "../../prd";
-import type { StatusWriter } from "../status-writer";
-import { runDeferredRegression } from "./run-regression";
-
-/**
- * Injectable dependencies for testing (avoids mock.module() which leaks in Bun 1.x).
- * @internal - test use only.
- */
-export const _runCompletionDeps = {
-  runDeferredRegression,
-  fireHook,
-};
-
-export interface RunCompletionOptions {
-  runId: string;
-  feature: string;
-  startedAt: string;
-  prd: PRD;
-  allStoryMetrics: StoryMetrics[];
-  totalCost: number;
-  storiesCompleted: number;
-  iterations: number;
-  startTime: number;
-  workdir: string;
-  statusWriter: StatusWriter;
-  config: NaxConfig;
-  hooksConfig?: HooksConfig;
-  /** Whether the run used sequential (non-parallel) execution. Defaults to true. */
-  isSequential?: boolean;
-  /** Protocol-aware agent resolver (ACP wiring). Falls back to static getAgent when absent. */
-  agentGetFn?: AgentGetFn;
-}
-
-export interface RunCompletionResult {
-  durationMs: number;
-  runCompletedAt: string;
-  finalCounts: {
-    total: number;
-    passed: number;
-    failed: number;
-    skipped: number;
-    pending: number;
-  };
-}
-
-/**
- * Check if deferred regression should be skipped (RL-006).
- *
- * Smart-skip applies when:
- * 1. All stories have fullSuiteGatePassed === true
- * 2. Execution is sequential (or defaults to sequential when not specified)
- * 3. There is at least one story metric
- */
-function shouldSkipDeferredRegression(allStoryMetrics: StoryMetrics[], isSequential: boolean | undefined): boolean {
-  // Default to sequential mode
-  const effectiveSequential = isSequential !== false;
-
-  // Must be sequential mode
-  if (!effectiveSequential) {
-    return false;
-  }
-
-  // Must have at least one story metric
-  if (allStoryMetrics.length === 0) {
-    return false;
-  }
-
-  // All stories must have fullSuiteGatePassed === true
-  return allStoryMetrics.every((m) => m.fullSuiteGatePassed === true);
-}
-
-/**
- * Handle final run completion: save metrics, log summary, update status
- */
-export async function handleRunCompletion(options: RunCompletionOptions): Promise<RunCompletionResult> {
-  const logger = getSafeLogger();
-  const {
-    runId,
-    feature,
-    startedAt,
-    prd,
-    allStoryMetrics,
-    totalCost,
-    storiesCompleted,
-    iterations,
-    startTime,
-    workdir,
-    statusWriter,
-    config,
-    hooksConfig,
-    isSequential,
-  } = options;
-
-  // Run deferred regression gate before final metrics
-  const regressionMode = config.execution.regressionGate?.mode;
-  if (regressionMode === "deferred" && config.quality.commands.test) {
-    if (shouldSkipDeferredRegression(allStoryMetrics, isSequential)) {
-      logger?.info(
-        "regression",
-        "Smart-skip: skipping deferred regression (all stories passed full-suite gate in sequential mode)",
-      );
-    } else {
-      const regressionResult = await _runCompletionDeps.runDeferredRegression({
-        config,
-        prd,
-        workdir,
-        agentGetFn: options.agentGetFn,
-      });
-
-      logger?.info("regression", "Deferred regression gate completed", {
-        success: regressionResult.success,
-        failedTests: regressionResult.failedTests,
-        affectedStories: regressionResult.affectedStories,
-      });
-
-      if (!regressionResult.success) {
-        // Mark affected stories as regression-failed (RL-004)
-        for (const storyId of regressionResult.affectedStories) {
-          const story = prd.userStories.find((s) => s.id === storyId);
-          if (story) {
-            story.status = "regression-failed";
-          }
-        }
-        // Reflect regression gate failure in run status (RL-004)
-        statusWriter.setRunStatus("failed");
-
-        if (hooksConfig) {
-          await _runCompletionDeps.fireHook(
-            hooksConfig as import("../../hooks/runner").LoadedHooksConfig,
-            "on-final-regression-fail",
-            {
-              event: "on-final-regression-fail",
-              feature,
-              status: "failed",
-              failedTests: regressionResult.failedTests,
-              affectedStories: regressionResult.affectedStories,
-            },
-            workdir,
-          );
-        }
-      }
-    }
-  }
-
-  const durationMs = Date.now() - startTime;
-  const runCompletedAt = new Date().toISOString();
-
-  // Compute final story counts before emitting completion event (RL-002)
-  const finalCounts = countStories(prd);
-
-  // Emit run:completed after regression gate with real story counts (RL-002)
-  pipelineEventBus.emit({
-    type: "run:completed",
-    totalStories: finalCounts.total,
-    passedStories: finalCounts.passed,
-    failedStories: finalCounts.failed,
-    durationMs,
-    totalCost,
-  });
-
-  // Save run metrics (best-effort — disk write errors do not fail the run)
-  const runMetrics = {
-    runId,
-    feature,
-    startedAt,
-    completedAt: runCompletedAt,
-    totalCost,
-    totalStories: allStoryMetrics.length,
-    storiesCompleted,
-    storiesFailed: finalCounts.failed,
-    totalDurationMs: durationMs,
-    stories: allStoryMetrics,
-  };
-
-  try {
-    await saveRunMetrics(workdir, runMetrics);
-  } catch (err) {
-    logger?.warn("run.complete", "Failed to save run metrics", { error: String(err) });
-  }
-
-  // Log run completion
-
-  // Prepare per-story metrics summary
-  const storyMetricsSummary = allStoryMetrics.map((sm) => ({
-    storyId: sm.storyId,
-    complexity: sm.complexity,
-    modelTier: sm.modelTier,
-    modelUsed: sm.modelUsed,
-    attempts: sm.attempts,
-    finalTier: sm.finalTier,
-    success: sm.success,
-    cost: sm.cost,
-    durationMs: sm.durationMs,
-    firstPassSuccess: sm.firstPassSuccess,
-  }));
-
-  logger?.info("run.complete", "Feature execution completed", {
-    runId,
-    feature,
-    success: isComplete(prd),
-    iterations,
-    totalStories: finalCounts.total,
-    storiesCompleted,
-    storiesFailed: finalCounts.failed,
-    storiesPending: finalCounts.pending,
-    totalCost,
-    durationMs,
-    storyMetrics: storyMetricsSummary,
-  });
-
-  // Update final status
-  statusWriter.setPrd(prd);
-  statusWriter.setCurrentStory(null);
-  statusWriter.setRunStatus(isComplete(prd) ? "completed" : isStalled(prd) ? "stalled" : "running");
-  await statusWriter.update(totalCost, iterations);
-
-  return {
-    durationMs,
-    runCompletedAt,
-    finalCounts: {
-      total: finalCounts.total,
-      passed: finalCounts.passed,
-      failed: finalCounts.failed,
-      skipped: finalCounts.skipped,
-      pending: finalCounts.pending,
-    },
-  };
-}

package/src/execution/lifecycle/run-initialization.ts

@@ -1,187 +0,0 @@
-/**
- * Run Initialization
- *
- * Handles initialization tasks before the main execution loop starts:
- * 1. State reconciliation (failed stories with commits)
- * 2. Agent installation check
- * 3. Story count validation
- * 4. Initial PRD analysis
- */
-
-import { join } from "node:path";
-import chalk from "chalk";
-import type { NaxConfig } from "../../config";
-import { AgentNotFoundError, AgentNotInstalledError, StoryLimitExceededError } from "../../errors";
-import { getSafeLogger } from "../../logger";
-import type { AgentGetFn } from "../../pipeline/types";
-import { countStories, loadPRD, markStoryPassed, savePRD } from "../../prd";
-import type { PRD } from "../../prd/types";
-import { runReview } from "../../review/runner";
-import type { ReviewConfig } from "../../review/types";
-import { hasCommitsForStory } from "../../utils/git";
-
-/**
- * Injectable dependencies for reconcileState — allows tests to mock
- * hasCommitsForStory and runReview without mock.module().
- */
-export const _reconcileDeps = {
-  hasCommitsForStory: (workdir: string, storyId: string) => hasCommitsForStory(workdir, storyId),
-  runReview: (reviewConfig: ReviewConfig, workdir: string, executionConfig: NaxConfig["execution"]) =>
-    runReview(reviewConfig, workdir, executionConfig),
-};
-
-export interface InitializationContext {
-  config: NaxConfig;
-  prdPath: string;
-  workdir: string;
-  dryRun: boolean;
-  /** Protocol-aware agent resolver — passed from registry at run start */
-  agentGetFn?: AgentGetFn;
-}
-
-export interface InitializationResult {
-  prd: PRD;
-  storyCounts: {
-    total: number;
-    pending: number;
-    passed: number;
-    failed: number;
-    skipped: number;
-    paused: number;
-    blocked: number;
-  };
-}
-
-/**
- * Reconcile PRD state with git history
- *
- * Checks if failed stories have commits in git history and marks them as passed.
- * For stories that failed at review/autofix stage, re-runs the review before
- * reconciling to ensure the code quality issues were actually fixed.
- */
-async function reconcileState(prd: PRD, prdPath: string, workdir: string, config: NaxConfig): Promise<PRD> {
-  const logger = getSafeLogger();
-  let reconciledCount = 0;
-  let modified = false;
-
-  for (const story of prd.userStories) {
-    if (story.status !== "failed") continue;
-
-    const hasCommits = await _reconcileDeps.hasCommitsForStory(workdir, story.id);
-    if (!hasCommits) continue;
-
-    // Gate: re-run review for stories that failed at review/autofix stage
-    if (story.failureStage === "review" || story.failureStage === "autofix") {
-      const effectiveWorkdir = story.workdir ? join(workdir, story.workdir) : workdir;
-      try {
-        const reviewResult = await _reconcileDeps.runReview(config.review, effectiveWorkdir, config.execution);
-        if (!reviewResult.success) {
-          logger?.warn("reconciliation", "Review still fails — not reconciling story", {
-            storyId: story.id,
-            failureReason: reviewResult.failureReason,
-          });
-          continue;
-        }
-        logger?.info("reconciliation", "Review now passes — reconciling story", { storyId: story.id });
-      } catch {
-        // Non-fatal: if review check errors, skip reconciliation for this story
-        logger?.warn("reconciliation", "Review check errored — not reconciling story", { storyId: story.id });
-        continue;
-      }
-    }
-
-    logger?.warn("reconciliation", "Failed story has commits in git history, marking as passed", {
-      storyId: story.id,
-      title: story.title,
-    });
-    markStoryPassed(prd, story.id);
-    reconciledCount++;
-    modified = true;
-  }
-
-  if (reconciledCount > 0) {
-    logger?.info("reconciliation", `Reconciled ${reconciledCount} failed stories from git history`);
-    await savePRD(prd, prdPath);
-  }
-
-  return prd;
-}
-
-/**
- * Validate agent installation
- */
-async function checkAgentInstalled(config: NaxConfig, dryRun: boolean, agentGetFn?: AgentGetFn): Promise<void> {
-  if (dryRun) return;
-
-  const logger = getSafeLogger();
-  const { getAgent } = await import("../../agents");
-  const agent = (agentGetFn ?? getAgent)(config.autoMode.defaultAgent);
-
-  if (!agent) {
-    logger?.error("execution", "Agent not found", {
-      agent: config.autoMode.defaultAgent,
-    });
-    throw new AgentNotFoundError(config.autoMode.defaultAgent);
-  }
-
-  const installed = await agent.isInstalled();
-  if (!installed) {
-    logger?.error("execution", "Agent is not installed or not in PATH", {
-      agent: config.autoMode.defaultAgent,
-      binary: agent.binary,
-    });
-    logger?.error("execution", "Please install the agent and try again");
-    throw new AgentNotInstalledError(config.autoMode.defaultAgent, agent.binary);
-  }
-}
-
-/**
- * Validate story count doesn't exceed limit
- */
-function validateStoryCount(counts: ReturnType<typeof countStories>, config: NaxConfig): void {
-  const logger = getSafeLogger();
-
-  if (counts.total > config.execution.maxStoriesPerFeature) {
-    logger?.error("execution", "Feature exceeds story limit", {
-      totalStories: counts.total,
-      limit: config.execution.maxStoriesPerFeature,
-    });
-    logger?.error("execution", "Split this feature into smaller features or increase maxStoriesPerFeature in config");
-    throw new StoryLimitExceededError(counts.total, config.execution.maxStoriesPerFeature);
-  }
-}
-
-/**
- * Log the active agent protocol to aid debugging.
- */
-export function logActiveProtocol(config: NaxConfig): void {
-  const logger = getSafeLogger();
-  const protocol = config.agent?.protocol ?? "cli";
-  logger?.info("run-initialization", `Agent protocol: ${protocol}`, { protocol });
-}
-
-/**
- * Initialize execution: validate agent, reconcile state, check limits
- */
-export async function initializeRun(ctx: InitializationContext): Promise<InitializationResult> {
-  const logger = getSafeLogger();
-
-  // Check agent installation
-  await checkAgentInstalled(ctx.config, ctx.dryRun, ctx.agentGetFn);
-
-  // Load and reconcile PRD
-  let prd = await loadPRD(ctx.prdPath);
-  prd = await reconcileState(prd, ctx.prdPath, ctx.workdir, ctx.config);
-
-  // Validate story counts
-  const counts = countStories(prd);
-  validateStoryCount(counts, ctx.config);
-
-  logger?.info("execution", "Run initialization complete", {
-    totalStories: counts.total,
-    doneStories: counts.passed,
-    pendingStories: counts.pending,
-  });
-
-  return { prd, storyCounts: counts };
-}