@nathapp/nax 0.18.1

package/src/context/types.ts

@@ -0,0 +1,98 @@
+/**
+ * Context Generator Types (v0.16.1)
+ *
+ * Types for generating agent config files from nax/context.md.
+ * Replaces ConstitutionContent from the old constitution generator.
+ */
+
+/** Auto-injected project metadata */
+export interface ProjectMetadata {
+  /** Project name from manifest file */
+  name?: string;
+  /** Detected language/runtime (e.g. "TypeScript", "Go", "Rust", "Python") */
+  language?: string;
+  /** Key dependencies (framework, ORM, test runner, etc.) */
+  dependencies: string[];
+  /** Test command from nax config */
+  testCommand?: string;
+  /** Lint command from nax config */
+  lintCommand?: string;
+  /** Typecheck command from nax config */
+  typecheckCommand?: string;
+}
+
+/** Context content passed to generators */
+export interface ContextContent {
+  /** Raw markdown from nax/context.md */
+  markdown: string;
+  /** Auto-injected project metadata (if enabled) */
+  metadata?: ProjectMetadata;
+}
+
+/** Agent config generator interface */
+export interface AgentContextGenerator {
+  /** Generator name (e.g., 'claude', 'opencode', 'cursor') */
+  name: string;
+  /** Output filename (e.g., 'CLAUDE.md', '.cursorrules') */
+  outputFile: string;
+  /** Generate agent-specific config file content from context */
+  generate(context: ContextContent): string;
+}
+
+/** All available generator types */
+export type AgentType = "claude" | "opencode" | "cursor" | "windsurf" | "aider";
+
+/** Generator registry map */
+export type GeneratorMap = Record<AgentType, AgentContextGenerator>;
+
+/** A single context element (file content, error, story summary, etc.) */
+export interface ContextElement {
+  /** Element type identifier */
+  type: string;
+  /** Content text */
+  content: string;
+  /** Estimated token count */
+  tokens: number;
+  /** Priority (higher = selected first when budgeting) */
+  priority: number;
+  /** Story ID (for story/dependency elements) */
+  storyId?: string;
+  /** File path (for file elements) */
+  filePath?: string;
+  /** Human-readable label (optional) */
+  label?: string;
+}
+
+/** Token budget for context building */
+export interface ContextBudget {
+  /** Total token limit */
+  maxTokens: number;
+  /** Tokens reserved for instructions/system prompt */
+  reservedForInstructions: number;
+  /** Tokens available for context elements */
+  availableForContext: number;
+}
+
+/** Input to the context builder */
+export interface StoryContext {
+  /** PRD containing all stories */
+  prd: import("../prd/types").PRD;
+  /** ID of the current story being worked on */
+  currentStoryId: string;
+  /** Working directory for file scanning */
+  workdir?: string;
+  /** nax config (for context settings) */
+  config?: import("../config").NaxConfig;
+}
+
+/** Output of the context builder */
+export interface BuiltContext {
+  /** Selected context elements (within budget) */
+  elements: ContextElement[];
+  /** Total tokens used */
+  totalTokens: number;
+  /** Whether some elements were truncated due to budget */
+  truncated: boolean;
+  /** Human-readable summary */
+  summary: string;
+}

package/src/errors.ts

@@ -0,0 +1,67 @@
+/**
+ * Typed Error Classes for nax
+ *
+ * Replaces process.exit(1) patterns with structured errors that can be caught
+ * and handled by the CLI layer or tests.
+ */
+
+/**
+ * Base error class for all nax errors.
+ */
+export class NaxError extends Error {
+  constructor(
+    message: string,
+    public readonly code: string,
+    public readonly context?: Record<string, unknown>,
+  ) {
+    super(message);
+    this.name = "NaxError";
+    Error.captureStackTrace(this, this.constructor);
+  }
+}
+
+/**
+ * Agent not found or not installed.
+ */
+export class AgentNotFoundError extends NaxError {
+  constructor(agentName: string, binary?: string) {
+    super(`Agent "${agentName}" not found or not installed`, "AGENT_NOT_FOUND", { agentName, binary });
+    this.name = "AgentNotFoundError";
+  }
+}
+
+/**
+ * Agent binary not in PATH.
+ */
+export class AgentNotInstalledError extends NaxError {
+  constructor(agentName: string, binary: string) {
+    super(`Agent "${agentName}" is not installed or not in PATH: ${binary}`, "AGENT_NOT_INSTALLED", {
+      agentName,
+      binary,
+    });
+    this.name = "AgentNotInstalledError";
+  }
+}
+
+/**
+ * Feature exceeds story limit.
+ */
+export class StoryLimitExceededError extends NaxError {
+  constructor(totalStories: number, limit: number) {
+    super(`Feature exceeds story limit: ${totalStories} stories (max: ${limit})`, "STORY_LIMIT_EXCEEDED", {
+      totalStories,
+      limit,
+    });
+    this.name = "StoryLimitExceededError";
+  }
+}
+
+/**
+ * Another nax process is already running.
+ */
+export class LockAcquisitionError extends NaxError {
+  constructor(workdir: string) {
+    super("Another nax process is already running in this directory", "LOCK_ACQUISITION_FAILED", { workdir });
+    this.name = "LockAcquisitionError";
+  }
+}

package/src/execution/batching.ts

@@ -0,0 +1,157 @@
+/**
+ * Story batching logic
+ *
+ * Groups consecutive simple-complexity stories into batches for efficient execution.
+ */
+
+import type { UserStory } from "../prd";
+
+/**
+ * Default maximum number of stories per batch.
+ *
+ * Rationale:
+ * - Batch size must balance efficiency vs. blast radius
+ * - 4 stories is optimal for most simple tasks (e.g., add 4 similar util functions)
+ * - Keeps prompts manageable (~1500 tokens per story = ~6000 tokens total context)
+ * - If one story in batch fails, only 3 others retry at next tier (acceptable waste)
+ * - Larger batches (8+) increase risk of cascading failures and context overload
+ *
+ * This default can be overridden via config or function parameter.
+ */
+const DEFAULT_MAX_BATCH_SIZE = 4;
+
+/**
+ * Story batch for grouped execution
+ */
+export interface StoryBatch {
+  /** Stories in this batch */
+  stories: UserStory[];
+  /** True if this is a batch of multiple stories, false if single story */
+  isBatch: boolean;
+}
+
+/**
+ * Group consecutive simple-complexity stories into batches (max 4 per batch).
+ * Non-simple stories execute individually.
+ *
+ * @param stories - Array of user stories to batch
+ * @param maxBatchSize - Maximum stories per batch (default: 4)
+ * @returns Array of story batches
+ *
+ * @example
+ * ```typescript
+ * const stories = [simpleStory1, simpleStory2, complexStory, simpleStory3];
+ * const batches = groupStoriesIntoBatches(stories);
+ * // Returns: [
+ * //   { stories: [simpleStory1, simpleStory2], isBatch: true },
+ * //   { stories: [complexStory], isBatch: false },
+ * //   { stories: [simpleStory3], isBatch: false }
+ * // ]
+ * ```
+ */
+export function groupStoriesIntoBatches(stories: UserStory[], maxBatchSize = DEFAULT_MAX_BATCH_SIZE): StoryBatch[] {
+  const batches: StoryBatch[] = [];
+  let currentBatch: UserStory[] = [];
+
+  for (const story of stories) {
+    const isSimple = story.routing?.complexity === "simple";
+
+    if (isSimple && currentBatch.length < maxBatchSize) {
+      // Add to current batch
+      currentBatch.push(story);
+    } else {
+      // Flush current batch if it exists
+      if (currentBatch.length > 0) {
+        batches.push({
+          stories: [...currentBatch],
+          isBatch: currentBatch.length > 1,
+        });
+        currentBatch = [];
+      }
+
+      // Add non-simple story as individual batch
+      if (!isSimple) {
+        batches.push({
+          stories: [story],
+          isBatch: false,
+        });
+      } else {
+        // Start new batch with this simple story
+        currentBatch.push(story);
+      }
+    }
+  }
+
+  // Flush remaining batch
+  if (currentBatch.length > 0) {
+    batches.push({
+      stories: [...currentBatch],
+      isBatch: currentBatch.length > 1,
+    });
+  }
+
+  return batches;
+}
+
+/**
+ * Precompute the full batch plan from ready stories.
+ * This eliminates O(n²) re-checking by computing all batches upfront.
+ * Maintains original story order from PRD.
+ *
+ * @param stories - Array of ready user stories (already filtered for dependencies)
+ * @param maxBatchSize - Maximum stories per batch (default: 4)
+ * @returns Array of story batches ready for sequential execution
+ *
+ * @example
+ * ```typescript
+ * const readyStories = getAllReadyStories(prd);
+ * const batchPlan = precomputeBatchPlan(readyStories);
+ * // Iterate through batches sequentially
+ * for (const batch of batchPlan) {
+ *   await executeBatch(batch);
+ * }
+ * ```
+ */
+export function precomputeBatchPlan(stories: UserStory[], maxBatchSize = DEFAULT_MAX_BATCH_SIZE): StoryBatch[] {
+  const batches: StoryBatch[] = [];
+  let currentBatch: UserStory[] = [];
+
+  for (const story of stories) {
+    const isSimple = story.routing?.complexity === "simple" && story.routing?.testStrategy === "test-after";
+
+    if (isSimple && currentBatch.length < maxBatchSize) {
+      // Add to current batch
+      currentBatch.push(story);
+    } else {
+      // Flush current batch if it exists
+      if (currentBatch.length > 0) {
+        batches.push({
+          stories: [...currentBatch],
+          isBatch: currentBatch.length > 1,
+        });
+        currentBatch = [];
+      }
+
+      // Add non-simple story as individual batch
+      if (!isSimple) {
+        batches.push({
+          stories: [story],
+          isBatch: false,
+        });
+      } else {
+        // Start new batch with this simple story
+        currentBatch.push(story);
+      }
+    }
+  }
+
+  // Flush remaining batch
+  if (currentBatch.length > 0) {
+    batches.push({
+      stories: [...currentBatch],
+      isBatch: currentBatch.length > 1,
+    });
+  }
+
+  return batches;
+}

package/src/execution/crash-recovery.ts

@@ -0,0 +1,373 @@
+/**
+ * Crash Recovery — Signal handlers, heartbeat, and exit summary
+ *
+ * Implements US-007:
+ * - SIGTERM/SIGINT/SIGHUP handlers
+ * - Uncaught exception handlers
+ * - Fatal log + status.json update to "crashed"
+ * - Heartbeat every 60s during agent execution
+ * - Exit summary entry on normal exit
+ */
+
+import { getSafeLogger } from "../logger";
+import type { PidRegistry } from "./pid-registry";
+import type { StatusWriter } from "./status-writer";
+
+/**
+ * Crash recovery context — dependencies injected at setup
+ * (BUG-1 fix: use getters to avoid capturing stale closure values)
+ */
+export interface CrashRecoveryContext {
+  statusWriter: StatusWriter;
+  getTotalCost: () => number;
+  getIterations: () => number;
+  jsonlFilePath?: string;
+  pidRegistry?: PidRegistry;
+  // BUG-017: Additional context for run.complete event on SIGTERM
+  runId?: string;
+  feature?: string;
+  getStartTime?: () => number;
+  getTotalStories?: () => number;
+  getStoriesCompleted?: () => number;
+}
+
+/**
+ * Heartbeat timer handle (for cleanup)
+ */
+let heartbeatTimer: Timer | null = null;
+
+/**
+ * Track whether crash handlers have been installed
+ */
+let handlersInstalled = false;
+
+/**
+ * Write fatal log entry to JSONL file
+ */
+async function writeFatalLog(jsonlFilePath: string | undefined, signal: string, error?: Error): Promise<void> {
+  if (!jsonlFilePath) return;
+
+  try {
+    const fatalEntry = {
+      timestamp: new Date().toISOString(),
+      level: "error",
+      stage: "crash-recovery",
+      message: error ? `Uncaught exception: ${error.message}` : `Process terminated by ${signal}`,
+      data: {
+        signal,
+        ...(error && {
+          stack: error.stack,
+          name: error.name,
+        }),
+      },
+    };
+
+    const line = `${JSON.stringify(fatalEntry)}\n`;
+    // Use appendFileSync from node:fs to ensure file is created if it doesn't exist
+    const { appendFileSync } = await import("node:fs");
+    appendFileSync(jsonlFilePath, line, "utf8");
+  } catch (err) {
+    console.error("[crash-recovery] Failed to write fatal log:", err);
+  }
+}
+
+/**
+ * Write run.complete event to JSONL file (BUG-017)
+ * Called on SIGTERM to emit final run summary before exit
+ */
+async function writeRunComplete(ctx: CrashRecoveryContext, exitReason: string): Promise<void> {
+  if (!ctx.jsonlFilePath || !ctx.runId || !ctx.feature) return;
+
+  const logger = getSafeLogger();
+
+  try {
+    const totalCost = ctx.getTotalCost();
+    const iterations = ctx.getIterations();
+    const startTime = ctx.getStartTime?.() ?? Date.now();
+    const durationMs = Date.now() - startTime;
+    const totalStories = ctx.getTotalStories?.() ?? 0;
+    const storiesCompleted = ctx.getStoriesCompleted?.() ?? 0;
+
+    const runCompleteEntry = {
+      timestamp: new Date().toISOString(),
+      level: "info",
+      stage: "run.complete",
+      message: "Feature execution terminated",
+      data: {
+        runId: ctx.runId,
+        feature: ctx.feature,
+        success: false,
+        exitReason,
+        totalCost,
+        iterations,
+        totalStories,
+        storiesCompleted,
+        durationMs,
+      },
+    };
+
+    const line = `${JSON.stringify(runCompleteEntry)}\n`;
+    const { appendFileSync } = await import("node:fs");
+    appendFileSync(ctx.jsonlFilePath, line, "utf8");
+    logger?.debug("crash-recovery", "run.complete event written", { exitReason });
+  } catch (err) {
+    console.error("[crash-recovery] Failed to write run.complete event:", err);
+  }
+}
+
+/**
+ * Update status.json to "crashed" state
+ */
+async function updateStatusToCrashed(
+  statusWriter: StatusWriter,
+  totalCost: number,
+  iterations: number,
+  signal: string,
+): Promise<void> {
+  try {
+    statusWriter.setRunStatus("crashed");
+    await statusWriter.update(totalCost, iterations, {
+      crashedAt: new Date().toISOString(),
+      crashSignal: signal,
+    });
+  } catch (err) {
+    console.error("[crash-recovery] Failed to update status.json:", err);
+  }
+}
+
+/**
+ * Install signal handlers for crash recovery
+ * (MEM-1 fix: return cleanup function to unregister handlers)
+ */
+export function installCrashHandlers(ctx: CrashRecoveryContext): () => void {
+  if (handlersInstalled) {
+    return () => {}; // Prevent duplicate installations
+  }
+
+  const logger = getSafeLogger();
+
+  // Signal handler
+  const handleSignal = async (signal: NodeJS.Signals) => {
+    logger?.error("crash-recovery", `Received ${signal}, shutting down...`, { signal });
+
+    // Kill all spawned agent processes
+    if (ctx.pidRegistry) {
+      await ctx.pidRegistry.killAll();
+    }
+
+    // Write fatal log
+    await writeFatalLog(ctx.jsonlFilePath, signal);
+
+    // Write run.complete event (BUG-017)
+    await writeRunComplete(ctx, signal.toLowerCase());
+
+    // Update status.json to crashed
+    await updateStatusToCrashed(ctx.statusWriter, ctx.getTotalCost(), ctx.getIterations(), signal);
+
+    // Stop heartbeat
+    stopHeartbeat();
+
+    // Exit cleanly
+    process.exit(128 + getSignalNumber(signal));
+  };
+
+  const sigtermHandler = () => handleSignal("SIGTERM");
+  const sigintHandler = () => handleSignal("SIGINT");
+  const sighupHandler = () => handleSignal("SIGHUP");
+
+  // Install signal handlers
+  process.on("SIGTERM", sigtermHandler);
+  process.on("SIGINT", sigintHandler);
+  process.on("SIGHUP", sighupHandler);
+
+  // Uncaught exception handler
+  const uncaughtExceptionHandler = async (error: Error) => {
+    logger?.error("crash-recovery", "Uncaught exception", {
+      error: error.message,
+      stack: error.stack,
+    });
+
+    // Kill all spawned agent processes
+    if (ctx.pidRegistry) {
+      await ctx.pidRegistry.killAll();
+    }
+
+    // Write fatal log with stack trace
+    await writeFatalLog(ctx.jsonlFilePath, "uncaughtException", error);
+
+    // Update status.json to crashed
+    await updateStatusToCrashed(ctx.statusWriter, ctx.getTotalCost(), ctx.getIterations(), "uncaughtException");
+
+    // Stop heartbeat
+    stopHeartbeat();
+
+    // Exit with error code
+    process.exit(1);
+  };
+  process.on("uncaughtException", uncaughtExceptionHandler);
+
+  // Unhandled promise rejection handler
+  const unhandledRejectionHandler = async (reason: unknown, promise: Promise<unknown>) => {
+    const error = reason instanceof Error ? reason : new Error(String(reason));
+    logger?.error("crash-recovery", "Unhandled promise rejection", {
+      error: error.message,
+      stack: error.stack,
+    });
+
+    // Kill all spawned agent processes
+    if (ctx.pidRegistry) {
+      await ctx.pidRegistry.killAll();
+    }
+
+    // Write fatal log
+    await writeFatalLog(ctx.jsonlFilePath, "unhandledRejection", error);
+
+    // Update status.json to crashed
+    await updateStatusToCrashed(ctx.statusWriter, ctx.getTotalCost(), ctx.getIterations(), "unhandledRejection");
+
+    // Stop heartbeat
+    stopHeartbeat();
+
+    // Exit with error code
+    process.exit(1);
+  };
+  process.on("unhandledRejection", unhandledRejectionHandler);
+
+  handlersInstalled = true;
+  logger?.debug("crash-recovery", "Crash handlers installed");
+
+  // Return cleanup function
+  return () => {
+    process.removeListener("SIGTERM", sigtermHandler);
+    process.removeListener("SIGINT", sigintHandler);
+    process.removeListener("SIGHUP", sighupHandler);
+    process.removeListener("uncaughtException", uncaughtExceptionHandler);
+    process.removeListener("unhandledRejection", unhandledRejectionHandler);
+    handlersInstalled = false;
+    logger?.debug("crash-recovery", "Crash handlers unregistered");
+  };
+}
+
+/**
+ * Start heartbeat timer (60s interval)
+ */
+export function startHeartbeat(
+  statusWriter: StatusWriter,
+  getTotalCost: () => number,
+  getIterations: () => number,
+  jsonlFilePath?: string,
+): void {
+  const logger = getSafeLogger();
+
+  // Stop any existing heartbeat first
+  stopHeartbeat();
+
+  heartbeatTimer = setInterval(async () => {
+    logger?.debug("crash-recovery", "Heartbeat");
+
+    // Write heartbeat to JSONL
+    if (jsonlFilePath) {
+      try {
+        const heartbeatEntry = {
+          timestamp: new Date().toISOString(),
+          level: "debug",
+          stage: "heartbeat",
+          message: "Process alive",
+          data: {
+            pid: process.pid,
+            memoryUsageMB: Math.round(process.memoryUsage().heapUsed / 1024 / 1024),
+          },
+        };
+        const line = `${JSON.stringify(heartbeatEntry)}\n`;
+        const { appendFileSync } = await import("node:fs");
+        appendFileSync(jsonlFilePath, line, "utf8");
+      } catch (err) {
+        logger?.warn("crash-recovery", "Failed to write heartbeat", { error: (err as Error).message });
+      }
+    }
+
+    // Update status.json (no-op if nothing changed, but keeps lastHeartbeat fresh)
+    try {
+      await statusWriter.update(getTotalCost(), getIterations(), {
+        lastHeartbeat: new Date().toISOString(),
+      });
+    } catch (err) {
+      logger?.warn("crash-recovery", "Failed to update status during heartbeat", {
+        error: (err as Error).message,
+      });
+    }
+  }, 60_000); // 60 seconds
+
+  logger?.debug("crash-recovery", "Heartbeat started (60s interval)");
+}
+
+/**
+ * Stop heartbeat timer
+ */
+export function stopHeartbeat(): void {
+  if (heartbeatTimer) {
+    clearInterval(heartbeatTimer);
+    heartbeatTimer = null;
+    getSafeLogger()?.debug("crash-recovery", "Heartbeat stopped");
+  }
+}
+
+/**
+ * Write exit summary entry to JSONL
+ */
+export async function writeExitSummary(
+  jsonlFilePath: string | undefined,
+  totalCost: number,
+  iterations: number,
+  storiesCompleted: number,
+  durationMs: number,
+): Promise<void> {
+  if (!jsonlFilePath) return;
+
+  const logger = getSafeLogger();
+
+  try {
+    const summaryEntry = {
+      timestamp: new Date().toISOString(),
+      level: "info",
+      stage: "exit-summary",
+      message: "Run completed",
+      data: {
+        totalCost,
+        iterations,
+        storiesCompleted,
+        durationMs,
+        exitedCleanly: true,
+      },
+    };
+
+    const line = `${JSON.stringify(summaryEntry)}\n`;
+    // Use appendFileSync from node:fs to ensure file is created if it doesn't exist
+    const { appendFileSync } = await import("node:fs");
+    appendFileSync(jsonlFilePath, line, "utf8");
+    logger?.debug("crash-recovery", "Exit summary written");
+  } catch (err) {
+    logger?.warn("crash-recovery", "Failed to write exit summary", { error: (err as Error).message });
+  }
+}
+
+/**
+ * Get numeric signal number for exit code
+ */
+function getSignalNumber(signal: NodeJS.Signals): number {
+  const signalMap: Record<string, number> = {
+    SIGTERM: 15,
+    SIGINT: 2,
+    SIGHUP: 1,
+  };
+  return signalMap[signal] ?? 15;
+}
+
+/**
+ * Reset handlers (for testing)
+ * @internal
+ */
+export function resetCrashHandlers(): void {
+  handlersInstalled = false;
+  stopHeartbeat();
+}