@nathapp/nax 0.18.1

package/src/execution/status-writer.ts

@@ -0,0 +1,139 @@
+/**
+ * StatusWriter — Encapsulates status file state and write logic
+ *
+ * Extracted from runner.ts. Manages the _runStatus, _prd, _currentStory state
+ * that was previously tracked as closure variables, plus the BUG-2 consecutive
+ * write failure counter. Provides atomic status file writes via writeStatusFile.
+ */
+
+import type { NaxConfig } from "../config";
+import { getSafeLogger } from "../logger";
+import type { PRD } from "../prd";
+import { type RunStateSnapshot, buildStatusSnapshot, writeStatusFile } from "./status-file";
+
+// ============================================================================
+// StatusWriterContext — fixed run metadata set at construction
+// ============================================================================
+
+export interface StatusWriterContext {
+  /** Unique run identifier */
+  runId: string;
+  /** Feature name */
+  feature: string;
+  /** ISO 8601 run start timestamp */
+  startedAt: string;
+  /** Whether this is a dry run */
+  dryRun: boolean;
+  /** Run start time as ms epoch (for computing durationMs) */
+  startTimeMs: number;
+  /** Process ID for crash detection */
+  pid: number;
+}
+
+// ============================================================================
+// StatusWriter
+// ============================================================================
+
+/**
+ * Manages status file state and write logic for the execution runner.
+ *
+ * Encapsulates all status-file-related mutable state that was previously
+ * tracked as closure variables in runner.ts:
+ * - _runStatus, _prd, _currentStory (set via setters before each write)
+ * - _consecutiveWriteFailures (BUG-2 failure counter, reset on success)
+ *
+ * Usage:
+ *   const sw = new StatusWriter(statusFile, config, { runId, feature, ... });
+ *   sw.setPrd(prd);
+ *   sw.setRunStatus("running");
+ *   sw.setCurrentStory(null);
+ *   await sw.update(totalCost, iterations);
+ */
+export class StatusWriter {
+  private readonly statusFile: string | undefined;
+  private readonly costLimit: number | null;
+  private readonly ctx: StatusWriterContext;
+
+  // Encapsulated mutable state (was closure vars in runner.ts)
+  private _runStatus: RunStateSnapshot["runStatus"] = "running";
+  private _prd: PRD | null = null;
+  private _currentStory: RunStateSnapshot["currentStory"] = null;
+  private _consecutiveWriteFailures = 0; // BUG-2: Track consecutive write failures
+
+  constructor(statusFile: string | undefined, config: NaxConfig, ctx: StatusWriterContext) {
+    this.statusFile = statusFile;
+    this.costLimit = config.execution.costLimit === Number.POSITIVE_INFINITY ? null : config.execution.costLimit;
+    this.ctx = ctx;
+  }
+
+  /** Update the current run status (running / completed / failed / stalled / crashed / precheck-failed) */
+  setRunStatus(status: RunStateSnapshot["runStatus"]): void {
+    this._runStatus = status;
+  }
+
+  /** Update the loaded PRD used for progress counting */
+  setPrd(prd: PRD): void {
+    this._prd = prd;
+  }
+
+  /** Update the currently-executing story info (null between stories) */
+  setCurrentStory(story: RunStateSnapshot["currentStory"]): void {
+    this._currentStory = story;
+  }
+
+  /**
+   * Build a RunStateSnapshot from current state + live runner values.
+   *
+   * Returns null if no PRD has been set yet (status write is a no-op).
+   */
+  getSnapshot(totalCost: number, iterations: number): RunStateSnapshot | null {
+    if (!this._prd) return null;
+    return {
+      runId: this.ctx.runId,
+      feature: this.ctx.feature,
+      startedAt: this.ctx.startedAt,
+      runStatus: this._runStatus,
+      dryRun: this.ctx.dryRun,
+      pid: this.ctx.pid,
+      prd: this._prd,
+      totalCost,
+      costLimit: this.costLimit,
+      iterations,
+      startTimeMs: this.ctx.startTimeMs,
+      currentStory: this._currentStory,
+    };
+  }
+
+  /**
+   * Write the current status to disk (atomic via .tmp + rename).
+   *
+   * No-ops if statusFile was not provided or _prd has not been set.
+   * On failure, logs a warning/error and increments the BUG-2 failure counter.
+   * Counter resets to 0 on next successful write.
+   *
+   * @param totalCost - Accumulated cost at this write point
+   * @param iterations - Loop iteration count at this write point
+   * @param overrides  - Optional partial snapshot overrides (spread last)
+   */
+  async update(totalCost: number, iterations: number, overrides: Partial<RunStateSnapshot> = {}): Promise<void> {
+    if (!this.statusFile || !this._prd) return;
+    const safeLogger = getSafeLogger();
+    try {
+      const base = this.getSnapshot(totalCost, iterations);
+      if (!base) {
+        throw new Error("Failed to get snapshot");
+      }
+      const state: RunStateSnapshot = { ...base, ...overrides };
+      await writeStatusFile(this.statusFile, buildStatusSnapshot(state));
+      this._consecutiveWriteFailures = 0; // Reset counter on success
+    } catch (err) {
+      this._consecutiveWriteFailures++;
+      const logLevel = this._consecutiveWriteFailures >= 3 ? "error" : "warn";
+      safeLogger?.[logLevel]("status-file", "Failed to write status file (non-fatal)", {
+        path: this.statusFile,
+        error: (err as Error).message,
+        consecutiveFailures: this._consecutiveWriteFailures,
+      });
+    }
+  }
+}

package/src/execution/story-context.ts

@@ -0,0 +1,229 @@
+/**
+ * Story Context Building
+ *
+ * Extracted from helpers.ts: context building and story readiness functions.
+ */
+
+import type { NaxConfig } from "../config";
+import { buildContext, formatContextAsMarkdown } from "../context";
+import type { BuiltContext, ContextBudget, StoryContext } from "../context";
+import type { HookContext } from "../hooks";
+import { getLogger } from "../logger";
+import type { PRD, UserStory } from "../prd";
+
+/** Safely get logger instance, returns null if not initialized */
+function getSafeLogger() {
+  try {
+    return getLogger();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Maximum tokens allowed in context budget for Claude agents.
+ *
+ * Claude has 200k token context window, but we reserve space for system prompt,
+ * agent instructions, conversation history, and output buffer. 100k token limit
+ * for story context is conservative but safe, leaving 100k tokens for agent
+ * reasoning and responses.
+ */
+const CONTEXT_MAX_TOKENS = 100_000;
+
+/**
+ * Tokens reserved for agent instructions and prompts.
+ *
+ * Agent needs space for task instructions, TDD prompts, hook output.
+ * 10k token reservation is safe upper bound for all instruction scenarios.
+ */
+const CONTEXT_RESERVED_TOKENS = 10_000;
+
+/** Result from executing a batch or single story */
+export interface ExecutionResult {
+  success: boolean;
+  cost: number;
+  storiesProcessed: string[];
+}
+
+/**
+ * Build a hook context object
+ *
+ * @param feature - Feature name
+ * @param opts - Optional context fields to override
+ * @returns Hook context with event set to "on-start" (overridden by fireHook)
+ */
+export function hookCtx(feature: string, opts?: Partial<Omit<HookContext, "event" | "feature">>): HookContext {
+  return {
+    event: "on-start", // overridden by fireHook
+    feature,
+    ...opts,
+  };
+}
+
+/**
+ * Maybe build context if enabled
+ *
+ * @param prd - PRD to build context from
+ * @param story - Current story being executed
+ * @param config - Ngent config
+ * @param useContext - Whether to build context
+ * @returns Context markdown or undefined if disabled/failed
+ */
+export async function maybeGetContext(
+  prd: PRD,
+  story: UserStory,
+  config: NaxConfig,
+  useContext: boolean,
+): Promise<string | undefined> {
+  if (!useContext) {
+    return undefined;
+  }
+
+  const logger = getSafeLogger();
+  logger?.debug("context", "Building context...");
+  const contextMarkdown = await buildStoryContext(prd, story, config);
+  if (contextMarkdown) {
+    logger?.debug("context", "Context built successfully");
+  }
+  return contextMarkdown;
+}
+
+/**
+ * Build story context for context builder
+ *
+ * @param prd - PRD containing all stories
+ * @param story - Current story to build context for
+ * @param config - Ngent config
+ * @returns Context markdown or undefined if no context available
+ */
+export async function buildStoryContext(prd: PRD, story: UserStory, _config: NaxConfig): Promise<string | undefined> {
+  try {
+    const storyContext: StoryContext = {
+      prd,
+      currentStoryId: story.id,
+      workdir: process.cwd(),
+      config: _config,
+    };
+
+    const budget: ContextBudget = {
+      maxTokens: CONTEXT_MAX_TOKENS,
+      reservedForInstructions: CONTEXT_RESERVED_TOKENS,
+      availableForContext: CONTEXT_MAX_TOKENS - CONTEXT_RESERVED_TOKENS,
+    };
+
+    const built = await buildContext(storyContext, budget);
+
+    if (built.elements.length === 0) {
+      return undefined;
+    }
+
+    return formatContextAsMarkdown(built);
+  } catch (error) {
+    const logger = getSafeLogger();
+    logger?.warn("context", "Context builder failed", {
+      error: (error as Error).message,
+    });
+    return undefined;
+  }
+}
+
+/**
+ * Build story context returning both markdown and element-level data.
+ * Used by `nax prompts` CLI for accurate frontmatter token counts.
+ */
+export async function buildStoryContextFull(
+  prd: PRD,
+  story: UserStory,
+  config: NaxConfig,
+): Promise<{ markdown: string; builtContext: BuiltContext } | undefined> {
+  try {
+    const storyContext: StoryContext = {
+      prd,
+      currentStoryId: story.id,
+      workdir: process.cwd(),
+      config,
+    };
+
+    const budget: ContextBudget = {
+      maxTokens: CONTEXT_MAX_TOKENS,
+      reservedForInstructions: CONTEXT_RESERVED_TOKENS,
+      availableForContext: CONTEXT_MAX_TOKENS - CONTEXT_RESERVED_TOKENS,
+    };
+
+    const built = await buildContext(storyContext, budget);
+
+    if (built.elements.length === 0) {
+      return undefined;
+    }
+
+    return { markdown: formatContextAsMarkdown(built), builtContext: built };
+  } catch (error) {
+    const logger = getSafeLogger();
+    logger?.warn("context", "Context builder failed", {
+      error: (error as Error).message,
+    });
+    return undefined;
+  }
+}
+
+/**
+ * Get all stories that are ready to execute (pending, dependencies satisfied)
+ *
+ * @param prd - PRD containing all stories
+ * @returns Array of stories that can be executed now
+ */
+export function getAllReadyStories(prd: PRD): UserStory[] {
+  const completedIds = new Set(prd.userStories.filter((s) => s.passes || s.status === "skipped").map((s) => s.id));
+
+  return prd.userStories.filter(
+    (s) =>
+      !s.passes &&
+      s.status !== "skipped" &&
+      s.status !== "failed" &&
+      s.status !== "paused" &&
+      s.status !== "blocked" &&
+      s.dependencies.every((dep) => completedIds.has(dep)),
+  );
+}
+
+/** Story counts for progress display */
+export interface StoryCounts {
+  total: number;
+  passed: number;
+  failed: number;
+  pending: number;
+}
+
+/**
+ * Format a progress line with counts, cost, and ETA
+ *
+ * @param counts - Story counts (total, passed, failed, pending)
+ * @param totalCost - Total cost so far
+ * @param costLimit - Cost limit from config
+ * @param elapsedMs - Elapsed time in milliseconds
+ * @param totalStories - Total number of stories (for ETA calculation)
+ * @returns Formatted progress string
+ */
+export function formatProgress(
+  counts: StoryCounts,
+  totalCost: number,
+  costLimit: number,
+  elapsedMs: number,
+  totalStories: number,
+): string {
+  const completedStories = counts.passed + counts.failed;
+  const remainingStories = totalStories - completedStories;
+
+  // Calculate ETA from average story duration
+  let etaText = "calculating...";
+  if (completedStories > 0 && remainingStories > 0) {
+    const avgDurationPerStory = elapsedMs / completedStories;
+    const etaMs = avgDurationPerStory * remainingStories;
+    const etaMinutes = Math.round(etaMs / 1000 / 60);
+    etaText = `~${etaMinutes} min remaining`;
+  } else if (remainingStories === 0) {
+    etaText = "complete";
+  }
+
+  return `Progress: ${completedStories}/${totalStories} stories | ${counts.passed} passed | ${counts.failed} failed | $${totalCost.toFixed(2)}/$${costLimit.toFixed(2)} | ${etaText}`;
+}

package/src/execution/test-output-parser.ts

@@ -0,0 +1,14 @@
+/**
+ * Test Output Parser
+ *
+ * DEPRECATED: Use src/verification/parser.ts instead.
+ * This file is kept for backward compatibility only.
+ */
+
+// Re-export from unified verification layer
+export {
+  type TestFailure,
+  type TestSummary,
+  parseBunTestOutput,
+  formatFailureSummary,
+} from "../verification/parser";

package/src/execution/verification.ts

@@ -0,0 +1,72 @@
+/**
+ * ADR-003: Robust Orchestration Feedback Loop - Verification Module
+ *
+ * DEPRECATED: Use src/verification/ unified layer instead.
+ * This file is kept for backward compatibility only.
+ *
+ * Implements Decisions 3-6:
+ * - Pre-Flight Asset Verification
+ * - Execution Guard (Verification Timeout)
+ * - Smart Exit-Code Analysis
+ * - Environment Normalization
+ */
+
+// Re-export from unified verification layer
+export {
+  type AssetVerificationResult,
+  type TestExecutionResult as TimeoutExecutionResult,
+  type TestOutputAnalysis,
+  type VerificationResult,
+  type VerificationStatus,
+  verifyAssets,
+  executeWithTimeout,
+  parseTestOutput,
+  getEnvironmentalEscalationThreshold,
+  normalizeEnvironment,
+  appendOpenHandlesFlag,
+  appendForceExitFlag,
+  buildTestCommand,
+} from "../verification";
+
+// Adapter function for backward compatibility
+import { fullSuite } from "../verification";
+import type { VerificationGateOptions } from "../verification/types";
+
+/**
+ * Run complete verification flow with all ADR-003 safety checks.
+ *
+ * @deprecated Use fullSuite() from src/verification/gate.ts instead
+ */
+export async function runVerification(options: {
+  workingDirectory: string;
+  expectedFiles?: string[];
+  command: string;
+  timeoutSeconds: number;
+  forceExit?: boolean;
+  detectOpenHandles?: boolean;
+  detectOpenHandlesRetries?: number;
+  timeoutRetryCount?: number;
+  gracePeriodMs?: number;
+  drainTimeoutMs?: number;
+  shell?: string;
+  stripEnvVars?: string[];
+  cwd?: string;
+}) {
+  // Map old options to new VerificationGateOptions
+  const gateOptions: VerificationGateOptions = {
+    workdir: options.workingDirectory,
+    expectedFiles: options.expectedFiles,
+    command: options.command,
+    timeoutSeconds: options.timeoutSeconds,
+    forceExit: options.forceExit,
+    detectOpenHandles: options.detectOpenHandles,
+    detectOpenHandlesRetries: options.detectOpenHandlesRetries,
+    timeoutRetryCount: options.timeoutRetryCount,
+    gracePeriodMs: options.gracePeriodMs,
+    drainTimeoutMs: options.drainTimeoutMs,
+    shell: options.shell,
+    stripEnvVars: options.stripEnvVars,
+  };
+
+  return fullSuite(gateOptions);
+}

package/src/hooks/index.ts

@@ -0,0 +1,2 @@
+export type { HookEvent, HookDef, HooksConfig, HookContext } from "./types";
+export { loadHooksConfig, fireHook, type LoadedHooksConfig } from "./runner";