@nathapp/nax 0.50.3 → 0.51.2

package/src/execution/status-file.ts

@@ -1,264 +0,0 @@
-/**
- * Status File — Machine-readable run state for external tooling
- *
- * Writes a JSON status file that external tools (CI/CD, orchestrators,
- * dashboards) can poll to monitor nax runs without parsing logs.
- *
- * Atomic writes: write to <path>.tmp then rename to <path>
- */
-
-import { rename, unlink } from "node:fs/promises";
-import { resolve } from "node:path";
-import type { NaxConfig } from "../config";
-import type { PRD, StoryStatus, UserStory } from "../prd";
-
-// ============================================================================
-// NaxStatusFile Interface
-// ============================================================================
-
-/** Machine-readable status file written during nax runs */
-export interface NaxStatusFile {
-  /** Schema version for forward compatibility */
-  version: 1;
-
-  /** Run metadata */
-  run: {
-    /** Run ID (e.g. "run-2026-02-25T10-00-00-000Z") */
-    id: string;
-    /** Feature name */
-    feature: string;
-    /** ISO 8601 start timestamp */
-    startedAt: string;
-    /** Current run status */
-    status: "running" | "completed" | "failed" | "stalled" | "crashed" | "precheck-failed";
-    /** Whether this is a dry run */
-    dryRun: boolean;
-    /** Process ID for crash detection */
-    pid: number;
-    /** ISO 8601 crash timestamp (present when status is "crashed") */
-    crashedAt?: string;
-    /** Signal or exception that caused crash (present when status is "crashed") */
-    crashSignal?: string;
-  };
-
-  /** Aggregate progress counts */
-  progress: {
-    /** Total stories in PRD */
-    total: number;
-    /** Stories that passed */
-    passed: number;
-    /** Stories that failed */
-    failed: number;
-    /** Stories that are paused */
-    paused: number;
-    /** Stories that are blocked */
-    blocked: number;
-    /** Stories not yet processed (total - passed - failed - paused - blocked) */
-    pending: number;
-  };
-
-  /** Cost tracking */
-  cost: {
-    /** Accumulated cost in USD */
-    spent: number;
-    /** Cost limit from config (null if not set) */
-    limit: number | null;
-  };
-
-  /** Current story being processed (null if between stories or at run boundaries) */
-  current: {
-    /** Story ID */
-    storyId: string;
-    /** Story title */
-    title: string;
-    /** Complexity level */
-    complexity: string;
-    /** TDD strategy */
-    tddStrategy: string;
-    /** Resolved model name */
-    model: string;
-    /** Current attempt number (1-based) */
-    attempt: number;
-    /** Current phase */
-    phase: string;
-  } | null;
-
-  /** Number of loop iterations completed */
-  iterations: number;
-
-  /** ISO 8601 last-updated timestamp */
-  updatedAt: string;
-
-  /** Elapsed duration in milliseconds */
-  durationMs: number;
-
-  /** ISO 8601 last heartbeat timestamp (updated every 60s during execution) */
-  lastHeartbeat?: string;
-
-  /** Parallel execution info (present when --parallel is used) */
-  parallel?: {
-    /** Whether parallel mode is enabled */
-    enabled: boolean;
-    /** Max concurrent sessions */
-    maxConcurrency: number;
-    /** Currently executing stories in parallel */
-    activeStories: Array<{
-      storyId: string;
-      worktreePath: string;
-    }>;
-  };
-}
-
-// ============================================================================
-// Progress Counting
-// ============================================================================
-
-/**
- * Derive progress counts from PRD story statuses.
- *
- * Counts each story by its current status. `pending` is computed as
- * everything not in the four explicit terminal/waiting states.
- */
-export function countProgress(prd: PRD): NaxStatusFile["progress"] {
-  const stories = prd.userStories;
-  const passed = stories.filter((s) => s.status === "passed").length;
-  const failed = stories.filter((s) => s.status === "failed").length;
-  const paused = stories.filter((s) => s.status === "paused").length;
-  const blocked = stories.filter((s) => s.status === "blocked").length;
-  const total = stories.length;
-  const pending = total - passed - failed - paused - blocked;
-
-  return { total, passed, failed, paused, blocked, pending };
-}
-
-// ============================================================================
-// Run State (for buildStatusSnapshot)
-// ============================================================================
-
-/**
- * Snapshot of current run state used to build NaxStatusFile.
- *
- * This is a value-only snapshot — callers pass in what they have at the
- * current write point. The runner constructs this inline from local variables.
- */
-export interface RunStateSnapshot {
-  /** Unique run identifier */
-  runId: string;
-  /** Feature name */
-  feature: string;
-  /** ISO 8601 start timestamp */
-  startedAt: string;
-  /** Current run status */
-  runStatus: NaxStatusFile["run"]["status"];
-  /** Whether this is a dry run */
-  dryRun: boolean;
-  /** Process ID for crash detection */
-  pid: number;
-  /** Loaded PRD (for progress counting) */
-  prd: PRD;
-  /** Accumulated cost in USD */
-  totalCost: number;
-  /** Cost limit from config (or null) */
-  costLimit: number | null;
-  /** Currently-executing story info (null between stories) */
-  currentStory: {
-    storyId: string;
-    title: string;
-    complexity: string;
-    tddStrategy: string;
-    model: string;
-    attempt: number;
-    phase: string;
-  } | null;
-  /** Number of loop iterations */
-  iterations: number;
-  /** Run start time as ms epoch (for computing durationMs) */
-  startTimeMs: number;
-  /** Parallel execution info (optional) */
-  parallel?: NaxStatusFile["parallel"];
-  /** ISO 8601 crash timestamp (present when status is "crashed") */
-  crashedAt?: string;
-  /** Signal or exception that caused crash (present when status is "crashed") */
-  crashSignal?: string;
-  /** ISO 8601 last heartbeat timestamp (updated every 60s during execution) */
-  lastHeartbeat?: string;
-}
-
-// ============================================================================
-// buildStatusSnapshot
-// ============================================================================
-
-/**
- * Build a NaxStatusFile object from current run state.
- *
- * Derives progress from PRD story statuses. Sets updatedAt and durationMs
- * from the current time. Does not write to disk — call writeStatusFile() for that.
- */
-export function buildStatusSnapshot(state: RunStateSnapshot): NaxStatusFile {
-  const now = Date.now();
-  const snapshot: NaxStatusFile = {
-    version: 1,
-    run: {
-      id: state.runId,
-      feature: state.feature,
-      startedAt: state.startedAt,
-      status: state.runStatus,
-      dryRun: state.dryRun,
-      pid: state.pid,
-      ...(state.crashedAt && { crashedAt: state.crashedAt }),
-      ...(state.crashSignal && { crashSignal: state.crashSignal }),
-    },
-    progress: countProgress(state.prd),
-    cost: {
-      spent: state.totalCost,
-      limit: state.costLimit,
-    },
-    current: state.currentStory,
-    iterations: state.iterations,
-    updatedAt: new Date(now).toISOString(),
-    durationMs: now - state.startTimeMs,
-    ...(state.lastHeartbeat && { lastHeartbeat: state.lastHeartbeat }),
-  };
-
-  if (state.parallel) {
-    snapshot.parallel = state.parallel;
-  }
-
-  return snapshot;
-}
-
-// ============================================================================
-// Atomic Writer
-// ============================================================================
-
-/**
- * Atomically write a NaxStatusFile to disk.
- *
- * Writes to `<path>.tmp` first, then renames to `<path>` to prevent
- * consumers from reading partial JSON during the write.
- *
- * @param filePath - Destination path for the status file
- * @param status   - Status file content to write
- * @throws Error if path traversal is detected
- */
-export async function writeStatusFile(filePath: string, status: NaxStatusFile): Promise<void> {
-  // SEC-1: Validate path to prevent path traversal attacks
-  const resolvedPath = resolve(filePath);
-
-  // Check for path traversal patterns in the original path
-  if (filePath.includes("../") || filePath.includes("..\\")) {
-    throw new Error("Invalid status file path: path traversal detected");
-  }
-
-  const tmpPath = `${resolvedPath}.tmp`;
-
-  // MEM-1: Clean up stale .tmp file if it exists
-  try {
-    await unlink(tmpPath);
-  } catch {
-    // Ignore error if file doesn't exist
-  }
-
-  await Bun.write(tmpPath, JSON.stringify(status, null, 2));
-  await rename(tmpPath, resolvedPath);
-}

package/src/execution/status-writer.ts

@@ -1,181 +0,0 @@
-/**
- * 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 { join } from "node:path";
-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;
-  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, 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 _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._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,
-      });
-    }
-  }
-
-  /**
-   * Write the current status snapshot to feature-level status.json file.
-   *
-   * Called on run completion, failure, or crash to persist the final state
-   * to <featureDir>/status.json. Uses the same NaxStatusFile schema as
-   * the project-level status file.
-   *
-   * No-ops if _prd has not been set.
-   * On failure, logs a warning/error but does not throw (non-fatal).
-   *
-   * @param featureDir - Feature directory (e.g., nax/features/auth-system)
-   * @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 writeFeatureStatus(
-    featureDir: string,
-    totalCost: number,
-    iterations: number,
-    overrides: Partial<RunStateSnapshot> = {},
-  ): Promise<void> {
-    if (!this._prd) return;
-    const safeLogger = getSafeLogger();
-    const featureStatusPath = join(featureDir, "status.json");
-
-    try {
-      const base = this.getSnapshot(totalCost, iterations);
-      if (!base) {
-        throw new Error("Failed to get snapshot");
-      }
-      const state: RunStateSnapshot = { ...base, ...overrides };
-      await writeStatusFile(featureStatusPath, buildStatusSnapshot(state));
-      safeLogger?.debug("status-file", "Feature status written", { path: featureStatusPath });
-    } catch (err) {
-      safeLogger?.warn("status-file", "Failed to write feature status file (non-fatal)", {
-        path: featureStatusPath,
-        error: (err as Error).message,
-      });
-    }
-  }
-}

package/src/execution/story-context.ts

@@ -1,266 +0,0 @@
-/**
- * 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;
-  }
-}
-
-/**
- * Load package-level context.md content if it exists.
- *
- * Reads <packageWorkdir>/nax/context.md and returns its content, or null
- * if the file does not exist.
- *
- * @internal
- */
-async function loadPackageContextMd(packageWorkdir: string): Promise<string | null> {
-  const contextPath = `${packageWorkdir}/nax/context.md`;
-  const file = Bun.file(contextPath);
-  if (!(await file.exists())) return null;
-  return file.text();
-}
-
-/**
- * Build story context returning both markdown and element-level data.
- * Used by `nax prompts` CLI for accurate frontmatter token counts.
- *
- * When `packageWorkdir` is provided (absolute path of story.workdir),
- * appends the package-level nax/context.md after the root context.
- */
-export async function buildStoryContextFull(
-  prd: PRD,
-  story: UserStory,
-  config: NaxConfig,
-  packageWorkdir?: string,
-): 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);
-
-    // MW-003: append package-level context.md if workdir is set
-    let packageSection = "";
-    if (packageWorkdir) {
-      const pkgContent = await loadPackageContextMd(packageWorkdir);
-      if (pkgContent) {
-        packageSection = `\n---\n\n${pkgContent.trim()}`;
-      }
-    }
-
-    if (built.elements.length === 0 && !packageSection) {
-      return undefined;
-    }
-
-    const baseMarkdown = built.elements.length > 0 ? formatContextAsMarkdown(built) : "";
-    const markdown = packageSection ? `${baseMarkdown}${packageSection}` : baseMarkdown;
-
-    return { markdown, 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));
-
-  const logger = getSafeLogger();
-  logger?.debug("routing", "getAllReadyStories: completed set", {
-    completedIds: [...completedIds],
-    totalStories: prd.userStories.length,
-  });
-
-  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}`;
-}