@nathapp/nax 0.50.2 → 0.51.0

package/src/execution/pid-registry.ts

@@ -1,275 +0,0 @@
-/**
- * PID Registry — Track and cleanup spawned agent processes
- *
- * Implements BUG-002:
- * - Track PIDs of spawned Claude Code processes
- * - Write .nax-pids file for persistence across crashes
- * - Support killAll() for crash signal handlers
- * - Support cleanupStale() for startup cleanup
- * - Use process groups (setsid) on Linux, direct kill on macOS
- */
-
-import { existsSync } from "node:fs";
-import { appendFile } from "node:fs/promises";
-import { getSafeLogger } from "../logger";
-
-/**
- * PID registry file name
- */
-const PID_REGISTRY_FILE = ".nax-pids";
-
-/**
- * PID registry entry
- */
-interface PidEntry {
-  pid: number;
-  spawnedAt: string;
-  workdir: string;
-}
-
-/**
- * PID Registry — Track spawned agent processes and cleanup orphans
- *
- * Maintains a .nax-pids file in the workdir to track spawned processes.
- * On crash, signal handlers call killAll() to terminate all tracked PIDs.
- * On startup, runner calls cleanupStale() to kill any orphaned processes from previous runs.
- *
- * @example
- * ```ts
- * const registry = new PidRegistry("/path/to/project");
- * await registry.register(12345);
- * // ... later, on crash or shutdown
- * await registry.killAll();
- * ```
- */
-export class PidRegistry {
-  private readonly workdir: string;
-  private readonly pidsFilePath: string;
-  private readonly pids: Set<number> = new Set();
-  private readonly platform: NodeJS.Platform;
-
-  /**
-   * Create a new PID registry for the given workdir.
-   *
-   * @param workdir - Working directory where .nax-pids will be stored
-   * @param platform - Optional platform override (for testing)
-   */
-  constructor(workdir: string, platform?: NodeJS.Platform) {
-    this.workdir = workdir;
-    this.pidsFilePath = `${workdir}/${PID_REGISTRY_FILE}`;
-    this.platform = platform ?? process.platform;
-  }
-
-  /**
-   * Register a spawned process PID.
-   *
-   * Adds the PID to the in-memory set and writes to .nax-pids file.
-   *
-   * @param pid - Process ID to register
-   */
-  async register(pid: number): Promise<void> {
-    const logger = getSafeLogger();
-    this.pids.add(pid);
-
-    const entry: PidEntry = {
-      pid,
-      spawnedAt: new Date().toISOString(),
-      workdir: this.workdir,
-    };
-
-    try {
-      // Atomically append to .nax-pids file (one JSON entry per line)
-      const line = `${JSON.stringify(entry)}\n`;
-      await appendFile(this.pidsFilePath, line);
-      logger?.debug("pid-registry", `Registered PID ${pid}`, { pid });
-    } catch (err) {
-      logger?.warn("pid-registry", `Failed to write PID ${pid} to registry`, {
-        error: (err as Error).message,
-      });
-    }
-  }
-
-  /**
-   * Unregister a process PID (e.g., after clean exit).
-   *
-   * Removes the PID from the in-memory set and rewrites .nax-pids file.
-   *
-   * @param pid - Process ID to unregister
-   */
-  async unregister(pid: number): Promise<void> {
-    const logger = getSafeLogger();
-    this.pids.delete(pid);
-
-    try {
-      // Rewrite .nax-pids file without the unregistered PID
-      await this.writePidsFile();
-      logger?.debug("pid-registry", `Unregistered PID ${pid}`, { pid });
-    } catch (err) {
-      logger?.warn("pid-registry", `Failed to unregister PID ${pid}`, {
-        error: (err as Error).message,
-      });
-    }
-  }
-
-  /**
-   * Kill all registered processes.
-   *
-   * Called by crash signal handlers to cleanup spawned agent processes.
-   * Uses process groups (setsid) on Linux, direct kill on macOS.
-   *
-   * On Linux: kill -TERM -<pid> kills the entire process group
-   * On macOS: kill -TERM <pid> kills the process directly
-   */
-  async killAll(): Promise<void> {
-    const logger = getSafeLogger();
-    const pids = Array.from(this.pids);
-
-    if (pids.length === 0) {
-      logger?.debug("pid-registry", "No PIDs to kill");
-      return;
-    }
-
-    logger?.info("pid-registry", `Killing ${pids.length} registered processes`, { pids });
-
-    const killPromises = pids.map((pid) => this.killPid(pid));
-    await Promise.allSettled(killPromises);
-
-    // Clear the registry file
-    try {
-      await Bun.write(this.pidsFilePath, "");
-      this.pids.clear();
-      logger?.info("pid-registry", "All registered PIDs killed and registry cleared");
-    } catch (err) {
-      logger?.warn("pid-registry", "Failed to clear registry file", {
-        error: (err as Error).message,
-      });
-    }
-  }
-
-  /**
-   * Cleanup stale PIDs from previous runs.
-   *
-   * Called at runner startup before lock acquisition.
-   * Reads .nax-pids file and kills any still-running processes.
-   */
-  async cleanupStale(): Promise<void> {
-    const logger = getSafeLogger();
-
-    if (!existsSync(this.pidsFilePath)) {
-      logger?.debug("pid-registry", "No stale PIDs file found");
-      return;
-    }
-
-    try {
-      const content = await Bun.file(this.pidsFilePath).text();
-      const lines = content
-        .split("\n")
-        .filter((line) => line.trim())
-        .map((line) => {
-          try {
-            return JSON.parse(line) as PidEntry;
-          } catch {
-            return null;
-          }
-        })
-        .filter((entry): entry is PidEntry => entry !== null);
-
-      if (lines.length === 0) {
-        logger?.debug("pid-registry", "No stale PIDs to cleanup");
-        await Bun.write(this.pidsFilePath, "");
-        return;
-      }
-
-      const stalePids = lines.map((entry) => entry.pid);
-      logger?.info("pid-registry", `Cleaning up ${stalePids.length} stale PIDs from previous run`, {
-        pids: stalePids,
-      });
-
-      const killPromises = stalePids.map((pid) => this.killPid(pid));
-      await Promise.allSettled(killPromises);
-
-      // Clear the registry file after cleanup
-      await Bun.write(this.pidsFilePath, "");
-      logger?.info("pid-registry", "Stale PIDs cleanup completed");
-    } catch (err) {
-      logger?.warn("pid-registry", "Failed to cleanup stale PIDs", {
-        error: (err as Error).message,
-      });
-    }
-  }
-
-  /**
-   * Kill a single PID.
-   *
-   * Uses process groups on Linux (kill -TERM -<pid>), direct kill on macOS (kill -TERM <pid>).
-   * Ignores ESRCH (process not found) errors.
-   *
-   * @param pid - Process ID to kill
-   */
-  private async killPid(pid: number): Promise<void> {
-    const logger = getSafeLogger();
-
-    try {
-      // Check if process exists first
-      const checkProc = Bun.spawn(["kill", "-0", String(pid)], {
-        stdout: "pipe",
-        stderr: "pipe",
-      });
-      const checkCode = await checkProc.exited;
-
-      if (checkCode !== 0) {
-        // Process doesn't exist, skip
-        logger?.debug("pid-registry", `PID ${pid} not found (already exited)`, { pid });
-        return;
-      }
-
-      // On Linux, use process groups (kill -TERM -<pid>)
-      // On macOS, use direct kill (kill -TERM <pid>)
-      const killArgs = this.platform === "linux" ? ["kill", "-TERM", `-${pid}`] : ["kill", "-TERM", String(pid)];
-
-      const killProc = Bun.spawn(killArgs, {
-        stdout: "pipe",
-        stderr: "pipe",
-      });
-
-      const killCode = await killProc.exited;
-
-      if (killCode === 0) {
-        logger?.debug("pid-registry", `Killed PID ${pid}`, { pid });
-      } else {
-        const stderr = await new Response(killProc.stderr).text();
-        logger?.warn("pid-registry", `Failed to kill PID ${pid}`, {
-          pid,
-          exitCode: killCode,
-          stderr: stderr.trim(),
-        });
-      }
-    } catch (err) {
-      logger?.warn("pid-registry", `Error killing PID ${pid}`, {
-        pid,
-        error: (err as Error).message,
-      });
-    }
-  }
-
-  /**
-   * Rewrite .nax-pids file with current in-memory PIDs.
-   */
-  private async writePidsFile(): Promise<void> {
-    const entries = Array.from(this.pids).map((pid) => ({
-      pid,
-      spawnedAt: new Date().toISOString(),
-      workdir: this.workdir,
-    }));
-
-    const content = entries.map((entry) => JSON.stringify(entry)).join("\n");
-    await Bun.write(this.pidsFilePath, content ? `${content}\n` : "");
-  }
-
-  /**
-   * Get all registered PIDs (for testing)
-   */
-  getPids(): number[] {
-    return Array.from(this.pids);
-  }
-}

package/src/execution/pipeline-result-handler.ts

@@ -1,221 +0,0 @@
-/**
- * Pipeline Result Handlers (ADR-005, Phase 4)
- *
- * Handles pipeline success, failure outcomes after story execution.
- * Dry-run handling: see execution/dry-run.ts
- * applyCachedRouting: removed (P4-001 — pipeline routing stage is sole source)
- */
-
-import type { NaxConfig } from "../config";
-import type { LoadedHooksConfig } from "../hooks";
-import type { InteractionChain } from "../interaction/chain";
-import { getSafeLogger } from "../logger";
-import type { StoryMetrics } from "../metrics";
-import { pipelineEventBus } from "../pipeline/event-bus";
-import type { PipelineRunResult } from "../pipeline/runner";
-import type { PluginRegistry } from "../plugins";
-import { countStories, markStoryFailed, markStoryPaused, savePRD } from "../prd";
-import type { PRD, UserStory } from "../prd/types";
-import type { routeTask } from "../routing";
-import { captureOutputFiles } from "../utils/git";
-import { handleTierEscalation } from "./escalation";
-import { appendProgress } from "./progress";
-
-/** Filter noise from output files (test files, lock files, nax runtime files) */
-function filterOutputFiles(files: string[]): string[] {
-  const NOISE = [
-    /\.test\.(ts|js|tsx|jsx)$/,
-    /\.spec\.(ts|js|tsx|jsx)$/,
-    /package-lock\.json$/,
-    /bun\.lock(b?)$/,
-    /\.gitignore$/,
-    /^nax\//,
-  ];
-  return files.filter((f) => !NOISE.some((p) => p.test(f))).slice(0, 15);
-}
-
-export interface PipelineHandlerContext {
-  config: NaxConfig;
-  prd: PRD;
-  prdPath: string;
-  workdir: string;
-  featureDir?: string;
-  hooks: LoadedHooksConfig;
-  feature: string;
-  totalCost: number;
-  startTime: number;
-  runId: string;
-  pluginRegistry: PluginRegistry;
-  story: UserStory;
-  storiesToExecute: UserStory[];
-  routing: ReturnType<typeof routeTask>;
-  isBatchExecution: boolean;
-  allStoryMetrics: StoryMetrics[];
-  storyGitRef: string | null | undefined;
-  interactionChain?: InteractionChain | null;
-  storyStartTime?: number;
-}
-
-export interface PipelineSuccessResult {
-  storiesCompletedDelta: number;
-  costDelta: number;
-  prd: PRD;
-  prdDirty: boolean;
-}
-
-export async function handlePipelineSuccess(
-  ctx: PipelineHandlerContext,
-  pipelineResult: PipelineRunResult,
-): Promise<PipelineSuccessResult> {
-  const logger = getSafeLogger();
-  const costDelta = pipelineResult.context.agentResult?.estimatedCost || 0;
-  const prd = ctx.prd;
-
-  if (pipelineResult.context.storyMetrics) {
-    ctx.allStoryMetrics.push(...pipelineResult.context.storyMetrics);
-  }
-
-  const storiesCompletedDelta = ctx.storiesToExecute.length;
-  for (const completedStory of ctx.storiesToExecute) {
-    const now = Date.now();
-    logger?.info("story.complete", "Story completed successfully", {
-      storyId: completedStory.id,
-      storyTitle: completedStory.title,
-      totalCost: ctx.totalCost + costDelta,
-      runElapsedMs: now - ctx.startTime,
-      storyDurationMs: ctx.storyStartTime ? now - ctx.storyStartTime : undefined,
-    });
-
-    pipelineEventBus.emit({
-      type: "story:completed",
-      storyId: completedStory.id,
-      story: completedStory,
-      passed: true,
-      runElapsedMs: Date.now() - ctx.startTime,
-      cost: costDelta,
-      modelTier: ctx.routing.modelTier,
-      testStrategy: ctx.routing.testStrategy,
-    });
-  }
-
-  // ENH-005: Capture output files for context chaining
-  if (ctx.storyGitRef) {
-    for (const completedStory of ctx.storiesToExecute) {
-      try {
-        const rawFiles = await captureOutputFiles(ctx.workdir, ctx.storyGitRef, completedStory.workdir);
-        const filtered = filterOutputFiles(rawFiles);
-        if (filtered.length > 0) {
-          completedStory.outputFiles = filtered;
-        }
-      } catch {
-        // Non-fatal — context chaining is best-effort
-      }
-    }
-  }
-
-  const updatedCounts = countStories(prd);
-  logger?.info("progress", "Progress update", {
-    totalStories: updatedCounts.total,
-    passedStories: updatedCounts.passed,
-    failedStories: updatedCounts.failed,
-    pendingStories: updatedCounts.pending,
-    totalCost: ctx.totalCost + costDelta,
-    costLimit: ctx.config.execution.costLimit,
-    elapsedMs: Date.now() - ctx.startTime,
-    storyDurationMs: ctx.storyStartTime ? Date.now() - ctx.storyStartTime : undefined,
-  });
-
-  return { storiesCompletedDelta, costDelta, prd, prdDirty: true };
-}
-
-export interface PipelineFailureResult {
-  prd: PRD;
-  prdDirty: boolean;
-  costDelta: number;
-}
-
-export async function handlePipelineFailure(
-  ctx: PipelineHandlerContext,
-  pipelineResult: PipelineRunResult,
-): Promise<PipelineFailureResult> {
-  const logger = getSafeLogger();
-  let prd = ctx.prd;
-  let prdDirty = false;
-  // Always capture cost even for failed stories — agent ran and spent tokens
-  const costDelta = pipelineResult.context.agentResult?.estimatedCost || 0;
-
-  switch (pipelineResult.finalAction) {
-    case "pause":
-      markStoryPaused(prd, ctx.story.id);
-      await savePRD(prd, ctx.prdPath);
-      prdDirty = true;
-      logger?.warn("pipeline", "Story paused", { storyId: ctx.story.id, reason: pipelineResult.reason });
-      pipelineEventBus.emit({
-        type: "story:paused",
-        storyId: ctx.story.id,
-        reason: pipelineResult.reason || "Pipeline paused",
-        cost: ctx.totalCost,
-      });
-      break;
-
-    case "skip":
-      logger?.warn("pipeline", "Story skipped", { storyId: ctx.story.id, reason: pipelineResult.reason });
-      prdDirty = true;
-      break;
-
-    case "fail":
-      markStoryFailed(prd, ctx.story.id, pipelineResult.context.tddFailureCategory, pipelineResult.stoppedAtStage);
-      await savePRD(prd, ctx.prdPath);
-      prdDirty = true;
-      logger?.error("pipeline", "Story failed", { storyId: ctx.story.id, reason: pipelineResult.reason });
-
-      if (ctx.featureDir) {
-        await appendProgress(ctx.featureDir, ctx.story.id, "failed", `${ctx.story.title} — ${pipelineResult.reason}`);
-      }
-
-      pipelineEventBus.emit({
-        type: "story:failed",
-        storyId: ctx.story.id,
-        story: ctx.story,
-        reason: pipelineResult.reason || "Pipeline failed",
-        countsTowardEscalation: true,
-        feature: ctx.feature,
-        attempts: ctx.story.attempts,
-      });
-
-      if (ctx.story.attempts !== undefined && ctx.story.attempts >= ctx.config.execution.rectification.maxRetries) {
-        await pipelineEventBus.emitAsync({
-          type: "human-review:requested",
-          storyId: ctx.story.id,
-          reason: pipelineResult.reason || "Max retries exceeded",
-          feature: ctx.feature,
-          attempts: ctx.story.attempts,
-        });
-      }
-      break;
-
-    case "escalate": {
-      const escalationResult = await handleTierEscalation({
-        story: ctx.story,
-        storiesToExecute: ctx.storiesToExecute,
-        isBatchExecution: ctx.isBatchExecution,
-        routing: ctx.routing,
-        pipelineResult,
-        config: ctx.config,
-        prd,
-        prdPath: ctx.prdPath,
-        featureDir: ctx.featureDir,
-        hooks: ctx.hooks,
-        feature: ctx.feature,
-        totalCost: ctx.totalCost,
-        workdir: ctx.workdir,
-        attemptCost: pipelineResult.context.agentResult?.estimatedCost || 0,
-      });
-      prd = escalationResult.prd;
-      prdDirty = escalationResult.prdDirty;
-      break;
-    }
-  }
-
-  return { prd, prdDirty, costDelta };
-}

package/src/execution/progress.ts

@@ -1,27 +0,0 @@
-/**
- * Progress Logging
- *
- * Append timestamped entries to progress.txt after story completion.
- */
-
-import { mkdirSync } from "node:fs";
-import { join } from "node:path";
-import type { StoryStatus } from "../prd";
-
-/** Append a progress entry to progress.txt */
-export async function appendProgress(
-  featureDir: string,
-  storyId: string,
-  status: StoryStatus,
-  message: string,
-): Promise<void> {
-  mkdirSync(featureDir, { recursive: true });
-  const progressPath = join(featureDir, "progress.txt");
-  const timestamp = new Date().toISOString();
-  const entry = `[${timestamp}] ${storyId} — ${status.toUpperCase()} — ${message}\n`;
-
-  // Append to file (creates if doesn't exist)
-  const file = Bun.file(progressPath);
-  const existing = (await file.exists()) ? await file.text() : "";
-  await Bun.write(progressPath, existing + entry);
-}

package/src/execution/queue-handler.ts

@@ -1,109 +0,0 @@
-/**
- * Queue File Handler
- *
- * Provides atomic read/write operations for .queue.txt command files.
- * Uses rename-before-read pattern to prevent race conditions.
- */
-
-import path from "node:path";
-import { getLogger } from "../logger";
-import { parseQueueFile } from "../queue";
-import type { QueueCommand } from "../queue";
-
-/**
- * Safely get logger instance, returns null if not initialized
- */
-function getSafeLogger() {
-  try {
-    return getLogger();
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Read and parse queue file atomically.
- * Uses rename-before-read pattern to prevent race conditions:
- * 1. Rename .queue.txt → .queue.txt.processing (atomic operation)
- * 2. Read from .queue.txt.processing
- * 3. Delete .queue.txt.processing after processing
- *
- * This ensures commands written during processing aren't lost.
- *
- * @param workdir - Working directory containing .queue.txt
- * @returns Array of parsed queue commands, or empty array if no queue file
- *
- * @example
- * ```typescript
- * const commands = await readQueueFile("/path/to/project");
- * for (const cmd of commands) {
- *   if (cmd.type === "PAUSE") {
- *     // Handle pause
- *   }
- * }
- * await clearQueueFile("/path/to/project");
- * ```
- */
-export async function readQueueFile(workdir: string): Promise<QueueCommand[]> {
-  const queuePath = path.join(workdir, ".queue.txt");
-  const processingPath = path.join(workdir, ".queue.txt.processing");
-  const logger = getSafeLogger();
-
-  try {
-    // Check if queue file exists
-    const file = Bun.file(queuePath);
-    const exists = await file.exists();
-    if (!exists) {
-      return [];
-    }
-
-    // Atomically rename to .processing (prevents concurrent reads)
-    try {
-      await Bun.spawn(["mv", queuePath, processingPath], { stdout: "pipe" }).exited;
-    } catch (error) {
-      // File was already moved by another process, or doesn't exist anymore
-      return [];
-    }
-
-    // Read from processing file
-    const processingFile = Bun.file(processingPath);
-    const content = await processingFile.text();
-    const result = parseQueueFile(content);
-
-    return result.commands;
-  } catch (error) {
-    logger?.warn("queue", "Failed to read queue file", {
-      error: (error as Error).message,
-    });
-    return [];
-  }
-}
-
-/**
- * Clear queue file after processing commands.
- * Deletes .queue.txt.processing file.
- *
- * @param workdir - Working directory containing .queue.txt.processing
- *
- * @example
- * ```typescript
- * const commands = await readQueueFile("/path/to/project");
- * // Process commands...
- * await clearQueueFile("/path/to/project");
- * ```
- */
-export async function clearQueueFile(workdir: string): Promise<void> {
-  const processingPath = path.join(workdir, ".queue.txt.processing");
-  const logger = getSafeLogger();
-  try {
-    const file = Bun.file(processingPath);
-    const exists = await file.exists();
-    if (exists) {
-      await Bun.spawn(["rm", processingPath], { stdout: "pipe" }).exited;
-    }
-  } catch (error) {
-    logger?.warn("queue", "Failed to clear queue file", {
-      error: (error as Error).message,
-    });
-  }
-}