@nathapp/nax 0.50.3 → 0.51.0

package/src/execution/story-selector.ts

@@ -1,76 +0,0 @@
-/**
- * Story Selector (ADR-005, Phase 4)
- *
- * Extracted from sequential-executor.ts: batch/single-story selection logic.
- */
-
-import type { NaxConfig } from "../config";
-import type { RoutingResult } from "../pipeline/types";
-import { getNextStory } from "../prd";
-import type { PRD, UserStory } from "../prd/types";
-import type { StoryBatch } from "./batching";
-import { buildPreviewRouting } from "./executor-types";
-
-export interface StorySelection {
-  story: UserStory;
-  storiesToExecute: UserStory[];
-  routing: RoutingResult;
-  isBatchExecution: boolean;
-}
-
-/**
- * Select the next story (or batch) to execute.
- * Returns null when there are no more stories to run.
- */
-export function selectNextStories(
-  prd: PRD,
-  config: NaxConfig,
-  batchPlan: StoryBatch[],
-  currentBatchIndex: number,
-  lastStoryId: string | null,
-  useBatch: boolean,
-): { selection: StorySelection; nextBatchIndex: number } | null {
-  if (useBatch && currentBatchIndex < batchPlan.length) {
-    const batch = batchPlan[currentBatchIndex];
-    const storiesToExecute = batch.stories.filter(
-      (s) =>
-        !s.passes &&
-        s.status !== "passed" &&
-        s.status !== "skipped" &&
-        s.status !== "blocked" &&
-        s.status !== "failed" &&
-        s.status !== "paused" &&
-        s.status !== "decomposed",
-    );
-
-    if (storiesToExecute.length === 0) {
-      // Batch exhausted (all already done) — advance index, caller retries
-      return { selection: null as unknown as StorySelection, nextBatchIndex: currentBatchIndex + 1 };
-    }
-
-    const story = storiesToExecute[0];
-    return {
-      selection: {
-        story,
-        storiesToExecute,
-        routing: buildPreviewRouting(story, config),
-        isBatchExecution: batch.isBatch && storiesToExecute.length > 1,
-      },
-      nextBatchIndex: currentBatchIndex + 1,
-    };
-  }
-
-  // Single-story fallback
-  const story = getNextStory(prd, lastStoryId, config.execution.rectification?.maxRetries ?? 2);
-  if (!story) return null;
-
-  return {
-    selection: {
-      story,
-      storiesToExecute: [story],
-      routing: buildPreviewRouting(story, config),
-      isBatchExecution: false,
-    },
-    nextBatchIndex: currentBatchIndex,
-  };
-}

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

@@ -1,14 +0,0 @@
-/**
- * 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/timeout-handler.ts

@@ -1,100 +0,0 @@
-/**
- * Timeout Handler Utility
- *
- * Reusable utility for handling process timeouts with graceful SIGTERM→SIGKILL escalation.
- * Ensures all timers are cleaned up in all code paths (exit, timeout, hard deadline).
- */
-
-export interface ProcessTimeoutOptions {
-  /** Grace period in ms between SIGTERM and SIGKILL (default: 5000) */
-  graceMs?: number;
-  /** Callback when timeout occurs */
-  onTimeout?: () => void;
-  /** Hard deadline buffer in ms after SIGKILL (default: 3000) */
-  hardDeadlineBufferMs?: number;
-  /**
-   * Optional injectable kill function for testability.
-   * Defaults to proc.kill(signal).
-   */
-  killFn?: (proc: { kill(signal?: NodeJS.Signals | number): void }, signal: NodeJS.Signals) => void;
-}
-
-export interface ProcessTimeoutResult {
-  exitCode: number;
-  timedOut: boolean;
-}
-
-/**
- * Execute a process with timeout handling.
- *
- * Sends SIGTERM on timeout, followed by SIGKILL after grace period.
- * Ensures all timers are cleared in finally block.
- *
- * @param proc - Subprocess to monitor
- * @param timeoutMs - Timeout in milliseconds
- * @param opts - Timeout options
- * @returns Object with exit code and timeout flag
- */
-export async function withProcessTimeout(
-  proc: {
-    pid: number;
-    exited: Promise<number>;
-    kill(signal?: NodeJS.Signals | number): void;
-  },
-  timeoutMs: number,
-  opts?: ProcessTimeoutOptions,
-): Promise<ProcessTimeoutResult> {
-  const graceMs = opts?.graceMs ?? 5000;
-  const hardDeadlineBufferMs = opts?.hardDeadlineBufferMs ?? 3000;
-  const killFn = opts?.killFn ?? ((p, signal) => p.kill(signal));
-
-  let timedOut = false;
-  let sigkillId: ReturnType<typeof setTimeout> | undefined;
-
-  const timeoutId = setTimeout(() => {
-    timedOut = true;
-    opts?.onTimeout?.();
-    try {
-      killFn(proc, "SIGTERM");
-    } catch {
-      /* already exited */
-    }
-    sigkillId = setTimeout(() => {
-      try {
-        killFn(proc, "SIGKILL");
-      } catch {
-        /* already exited */
-      }
-    }, graceMs);
-  }, timeoutMs);
-
-  let exitCode: number;
-  try {
-    const hardDeadlineMs = timeoutMs + graceMs + hardDeadlineBufferMs;
-    let hardDeadlineId: ReturnType<typeof setTimeout> | undefined;
-    const hardDeadlinePromise = new Promise<number>((resolve) => {
-      hardDeadlineId = setTimeout(() => resolve(-1), hardDeadlineMs);
-    });
-
-    exitCode = await Promise.race([proc.exited, hardDeadlinePromise]);
-    clearTimeout(hardDeadlineId);
-
-    if (exitCode === -1) {
-      try {
-        process.kill(proc.pid, "SIGKILL");
-      } catch {
-        /* already gone */
-      }
-      try {
-        process.kill(-proc.pid, "SIGKILL");
-      } catch {
-        /* no process group */
-      }
-    }
-  } finally {
-    clearTimeout(timeoutId);
-    clearTimeout(sigkillId);
-  }
-
-  return { exitCode, timedOut };
-}

package/src/hooks/index.ts

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

package/src/hooks/runner.ts

@@ -1,280 +0,0 @@
-/**
- * Hook Runner
- *
- * Loads hooks.json and executes hooks at lifecycle events.
- */
-
-import { join } from "node:path";
-import { getLogger } from "../logger";
-import { loadJsonFile } from "../utils/json-file";
-import type { HookContext, HookDef, HookEvent, HooksConfig } from "./types";
-
-const DEFAULT_TIMEOUT = 5000;
-
-/** Extended hooks config that tracks global vs project hooks */
-export interface LoadedHooksConfig extends HooksConfig {
-  /** Global hooks (loaded from ~/.nax/hooks.json) */
-  _global?: HooksConfig;
-  /** Whether global hooks were skipped */
-  _skipGlobal?: boolean;
-}
-
-/**
- * Load hooks config from global and project paths.
- *
- * Both global and project hooks are preserved independently (not merged).
- * The skipGlobal flag in project config disables global hook loading.
- *
- * @param projectDir - Project nax directory path
- * @param globalDir - Global nax directory path (optional)
- * @returns Merged hooks config with both global and project hooks
- */
-export async function loadHooksConfig(projectDir: string, globalDir?: string): Promise<LoadedHooksConfig> {
-  let globalHooks: HooksConfig = { hooks: {} };
-  let projectHooks: HooksConfig = { hooks: {} };
-  let skipGlobal = false;
-
-  // Load project hooks first to check skipGlobal flag
-  const projectPath = join(projectDir, "hooks.json");
-  const projectData = await loadJsonFile<HooksConfig & { skipGlobal?: boolean }>(projectPath, "hooks");
-  if (projectData) {
-    projectHooks = projectData;
-    // Check if project config has skipGlobal flag
-    skipGlobal = projectData.skipGlobal ?? false;
-  }
-
-  // Load global hooks only if not skipped
-  if (!skipGlobal && globalDir) {
-    const globalPath = join(globalDir, "hooks.json");
-    const globalData = await loadJsonFile<HooksConfig>(globalPath, "hooks");
-    if (globalData) {
-      globalHooks = globalData;
-    }
-  }
-
-  // Return project hooks as the main config, with global hooks stored separately
-  return {
-    ...projectHooks,
-    _global: skipGlobal ? undefined : globalHooks,
-    _skipGlobal: skipGlobal,
-  };
-}
-
-/**
- * Escape environment variable values to prevent injection
- * @param value - Raw value to escape
- * @returns Escaped value safe for subprocess environment
- */
-function escapeEnvValue(value: string): string {
-  // Remove null bytes and newlines that could cause issues
-  return value.replace(/\0/g, "").replace(/\n/g, " ").replace(/\r/g, "");
-}
-
-/**
- * Build environment variables from hook context
- * All values are escaped to prevent injection attacks
- */
-function buildEnv(ctx: HookContext): Record<string, string> {
-  const env: Record<string, string> = {
-    NAX_EVENT: escapeEnvValue(ctx.event),
-    NAX_FEATURE: escapeEnvValue(ctx.feature),
-  };
-
-  if (ctx.storyId) env.NAX_STORY_ID = escapeEnvValue(ctx.storyId);
-  if (ctx.status) env.NAX_STATUS = escapeEnvValue(ctx.status);
-  if (ctx.reason) env.NAX_REASON = escapeEnvValue(ctx.reason);
-  if (ctx.cost !== undefined) env.NAX_COST = ctx.cost.toFixed(4);
-  if (ctx.model) env.NAX_MODEL = escapeEnvValue(ctx.model);
-  if (ctx.agent) env.NAX_AGENT = escapeEnvValue(ctx.agent);
-  if (ctx.iteration !== undefined) env.NAX_ITERATION = String(ctx.iteration);
-
-  return env;
-}
-
-/**
- * Detect shell operators that indicate shell interpolation
- * @param command - Command string to check
- * @returns true if shell operators detected
- */
-export function hasShellOperators(command: string): boolean {
-  // Check for common shell operators that require shell interpretation
-  const shellOperators = /[|&;$`<>(){}]/;
-  return shellOperators.test(command);
-}
-
-/**
- * Validate hook command for injection patterns
- * @param command - Command string to validate
- * @throws Error if obvious injection pattern detected
- */
-export function validateHookCommand(command: string): void {
-  // Reject commands with obvious injection patterns
-  const dangerousPatterns = [
-    /\$\([^)]*\)/, // Command substitution $(...) — bounded to avoid ReDoS
-    /`[^`]*`/, // Backtick command substitution — bounded to avoid ReDoS
-    /\|\s*bash/, // Piping to bash
-    /\|\s*sh/, // Piping to sh
-    /;\s*rm\s+-rf/, // Dangerous deletion
-    /&&\s*rm\s+-rf/, // Dangerous deletion after success
-    /\beval\s+/, // SEC-3 fix: eval command
-    /curl\s+[^|]*\|\s*/, // SEC-3 fix: curl piping
-    /python\s+-c/, // SEC-3 fix: python -c execution
-  ];
-
-  for (const pattern of dangerousPatterns) {
-    if (pattern.test(command)) {
-      throw new Error(`Hook command contains dangerous pattern: ${pattern.source}`);
-    }
-  }
-}
-
-/**
- * Parse command string into argv array
- * Simple space-based splitting (does not handle complex quoting)
- * @param command - Command string
- * @returns Array of command and arguments
- */
-export function parseCommandToArgv(command: string): string[] {
-  const home = process.env.HOME ?? process.env.USERPROFILE ?? "";
-  return command
-    .trim()
-    .split(/\s+/)
-    .map((token) => (token.startsWith("~/") ? home + token.slice(1) : token));
-}
-
-/**
- * Execute a single hook
- *
- * SECURITY WARNING: Hook commands are executed as subprocesses.
- * - Commands are parsed into argv arrays to avoid shell injection
- * - Shell operators (|, &&, ;, $, etc.) trigger a security warning
- * - Obvious injection patterns are rejected
- * - Environment variables are escaped
- * - Only configure hooks from trusted sources
- *
- * @param hookDef - Hook definition from config
- * @param ctx - Hook context with environment variables
- * @param workdir - Working directory for command execution
- * @returns Promise with success status and output
- */
-async function executeHook(
-  hookDef: HookDef,
-  ctx: HookContext,
-  workdir: string,
-): Promise<{ success: boolean; output: string }> {
-  if (hookDef.enabled === false) {
-    return { success: true, output: "(disabled)" };
-  }
-
-  // Validate command for injection patterns
-  try {
-    validateHookCommand(hookDef.command);
-  } catch (err) {
-    return {
-      success: false,
-      output: `Security validation failed: ${err}`,
-    };
-  }
-
-  // Warn if shell operators detected
-  const logger = getLogger();
-  if (hasShellOperators(hookDef.command)) {
-    logger.warn("hooks", "[SECURITY] Hook command contains shell operators", {
-      command: hookDef.command,
-      warning: "Shell operators may enable injection attacks. Consider using simple commands only.",
-    });
-  }
-
-  const timeout = hookDef.timeout ?? DEFAULT_TIMEOUT;
-  const env = buildEnv(ctx);
-
-  // Pass full context as JSON via stdin
-  const contextJson = JSON.stringify(ctx);
-
-  // Parse command to argv array (no shell interpolation)
-  const argv = parseCommandToArgv(hookDef.command);
-  if (argv.length === 0) {
-    return { success: false, output: "Empty command" };
-  }
-
-  const proc = Bun.spawn(argv, {
-    cwd: workdir,
-    stdin: new Response(contextJson),
-    stdout: "pipe",
-    stderr: "pipe",
-    env: { ...process.env, ...env },
-  });
-
-  // Timeout handling
-  const timeoutId = setTimeout(() => {
-    proc.kill("SIGTERM");
-  }, timeout);
-
-  const exitCode = await proc.exited;
-  clearTimeout(timeoutId);
-
-  const stdout = await new Response(proc.stdout).text();
-  const stderr = await new Response(proc.stderr).text();
-
-  const output = (stdout + stderr).trim();
-
-  // Check if process was killed by timeout
-  if (exitCode !== 0 && output === "") {
-    return {
-      success: false,
-      output: `Hook timed out after ${timeout}ms`,
-    };
-  }
-
-  return {
-    success: exitCode === 0,
-    output,
-  };
-}
-
-/**
- * Fire a hook event for both global and project hooks.
- *
- * Both hooks fire independently - global failure doesn't block project hook.
- *
- * @param config - Loaded hooks config (contains both global and project hooks)
- * @param event - Hook event name
- * @param ctx - Hook context
- * @param workdir - Working directory
- */
-export async function fireHook(
-  config: LoadedHooksConfig,
-  event: HookEvent,
-  ctx: HookContext,
-  workdir: string,
-): Promise<void> {
-  const logger = getLogger();
-
-  // Fire global hook first (if present and not skipped)
-  if (config._global && !config._skipGlobal) {
-    const globalHookDef = config._global.hooks[event];
-    if (globalHookDef && globalHookDef.enabled !== false) {
-      try {
-        const result = await executeHook(globalHookDef, { ...ctx, event }, workdir);
-        if (!result.success) {
-          logger.warn("hooks", `Global hook ${event} failed`, { event, output: result.output });
-        }
-      } catch (err) {
-        logger.warn("hooks", `Global hook ${event} error`, { event, error: String(err) });
-      }
-    }
-  }
-
-  // Fire project hook (independent of global hook result)
-  const projectHookDef = config.hooks[event];
-  if (projectHookDef && projectHookDef.enabled !== false) {
-    try {
-      const result = await executeHook(projectHookDef, { ...ctx, event }, workdir);
-      if (!result.success) {
-        logger.warn("hooks", `Project hook ${event} failed`, { event, output: result.output });
-      }
-    } catch (err) {
-      logger.warn("hooks", `Project hook ${event} error`, { event, error: String(err) });
-    }
-  }
-}

package/src/hooks/types.ts

@@ -1,79 +0,0 @@
-/**
- * Hook System Types
- *
- * Script-based lifecycle hooks configured via hooks.json.
- */
-
-/** All supported hook events — runtime array used for validation */
-export const HOOK_EVENTS = [
-  "on-start",
-  "on-story-start",
-  "on-story-complete",
-  "on-story-fail",
-  "on-pause",
-  "on-resume",
-  "on-session-end",
-  "on-all-stories-complete",
-  "on-complete",
-  "on-error",
-  "on-final-regression-fail",
-] as const;
-
-/** All supported hook events */
-export type HookEvent = (typeof HOOK_EVENTS)[number];
-
-/** Single hook definition */
-export interface HookDef {
-  /** Command to execute */
-  command: string;
-  /** Timeout in milliseconds (default: 5000) */
-  timeout?: number;
-  /** Whether this hook is enabled (default: true) */
-  enabled?: boolean;
-  /** Interaction prompt (v0.15.0) */
-  interaction?: {
-    /** Interaction type */
-    type: "confirm" | "choose" | "input" | "review" | "notify";
-    /** Summary template (supports {{variable}} syntax) */
-    summary: string;
-    /** Detail template (optional) */
-    detail?: string;
-    /** Fallback behavior on timeout */
-    fallback: "continue" | "skip" | "escalate" | "abort";
-    /** Timeout in milliseconds (optional) */
-    timeout?: number;
-  };
-}
-
-/** hooks.json schema */
-export interface HooksConfig {
-  hooks: Partial<Record<HookEvent, HookDef>>;
-}
-
-/** Context passed to hooks via environment variables */
-export interface HookContext {
-  /** Event name */
-  event: HookEvent;
-  /** Feature name */
-  feature: string;
-  /** Current story ID */
-  storyId?: string;
-  /** Status (pass/fail/paused/error) */
-  status?: string;
-  /** Reason for pause/error */
-  reason?: string;
-  /** Accumulated cost (USD) */
-  cost?: number;
-  /** Current model */
-  model?: string;
-  /** Current agent */
-  agent?: string;
-  /** Current iteration number */
-  iteration?: number;
-  /** Number of failed tests (on-final-regression-fail) */
-  failedTests?: number;
-  /** Stories affected by regression failure (on-final-regression-fail) */
-  affectedStories?: string[];
-  /** Number of sub-stories created (on-story-complete with status "decomposed") */
-  subStoryCount?: number;
-}