@nathapp/nax 0.18.1

package/src/utils/queue-writer.ts

@@ -0,0 +1,54 @@
+/**
+ * Queue Writer Utility
+ *
+ * Writes queue commands (PAUSE/ABORT/SKIP) to the queue file.
+ * Used by the TUI to translate keyboard shortcuts into queue commands.
+ */
+
+import type { QueueCommand } from "../queue/types";
+
+/**
+ * Write a queue command to the queue file.
+ *
+ * Appends the command to the queue file in the format expected by parseQueueFile:
+ * - PAUSE
+ * - ABORT
+ * - SKIP <story-id>
+ *
+ * The queue file is checked by the execution runner between stories.
+ *
+ * @param queueFilePath - Path to the queue file
+ * @param command - Queue command to write
+ *
+ * @example
+ * ```typescript
+ * await writeQueueCommand("/tmp/nax/queue.txt", { type: "PAUSE" });
+ * await writeQueueCommand("/tmp/nax/queue.txt", { type: "SKIP", storyId: "US-003" });
+ * ```
+ */
+export async function writeQueueCommand(queueFilePath: string, command: QueueCommand): Promise<void> {
+  let commandLine: string;
+
+  switch (command.type) {
+    case "PAUSE":
+      commandLine = "PAUSE";
+      break;
+    case "ABORT":
+      commandLine = "ABORT";
+      break;
+    case "SKIP":
+      commandLine = `SKIP ${command.storyId}`;
+      break;
+    default: {
+      const _exhaustive: never = command;
+      throw new Error(`Unhandled queue command: ${_exhaustive}`);
+    }
+  }
+
+  // Append command to queue file (create if doesn't exist)
+  const file = Bun.file(queueFilePath);
+  const existingContent = await file.text().catch(() => "");
+  const newContent = existingContent ? `${existingContent.trimEnd()}\n${commandLine}\n` : `${commandLine}\n`;
+
+  await Bun.write(queueFilePath, newContent);
+}

package/src/verification/executor.ts

@@ -0,0 +1,235 @@
+/**
+ * Test Execution Core
+ *
+ * Unified test execution logic with timeout handling and process cleanup.
+ * Extracted from execution/verification.ts to eliminate duplication.
+ */
+
+import type { Subprocess } from "bun";
+import type { TestExecutionResult } from "./types";
+
+/**
+ * Drain stdout+stderr from a killed Bun subprocess with a hard deadline.
+ *
+ * Bun doesn't close piped streams when a child process is killed (unlike Node).
+ * `await new Response(proc.stdout).text()` hangs forever. This races the read
+ * against a timeout so we get whatever output was buffered without blocking.
+ */
+async function drainWithDeadline(proc: Subprocess, deadlineMs: number): Promise<string> {
+  const EMPTY = Symbol("timeout");
+  const race = <T>(p: Promise<T>) =>
+    Promise.race([p, new Promise<typeof EMPTY>((r) => setTimeout(() => r(EMPTY), deadlineMs))]);
+
+  let out = "";
+  try {
+    const stdout = race(new Response(proc.stdout as ReadableStream).text());
+    const stderr = race(new Response(proc.stderr as ReadableStream).text());
+    const [o, e] = await Promise.all([stdout, stderr]);
+    if (o !== EMPTY) out += o;
+    if (e !== EMPTY) out += (out ? "\n" : "") + e;
+  } catch (error) {
+    // Streams may already be destroyed - this is expected after kill
+    // No logger available in this utility function context
+  }
+  return out;
+}
+
+/**
+ * Normalize environment variables for verification subprocess.
+ *
+ * Force standard output mode during orchestrator-controlled test runs by
+ * unsetting AI-optimized env vars (CLAUDECODE, REPL_ID, AGENT).
+ */
+const DEFAULT_STRIP_ENV_VARS = ["CLAUDECODE", "REPL_ID", "AGENT"];
+
+export function normalizeEnvironment(
+  env: Record<string, string | undefined>,
+  stripVars?: string[],
+): Record<string, string | undefined> {
+  const normalized = { ...env };
+  const varsToStrip = stripVars ?? DEFAULT_STRIP_ENV_VARS;
+
+  for (const varName of varsToStrip) {
+    delete normalized[varName];
+  }
+
+  return normalized;
+}
+
+/**
+ * Execute test command with hard timeout and process cleanup.
+ *
+ * Prevents zombie processes by sending SIGTERM, waiting for grace period,
+ * then SIGKILL to entire process group.
+ */
+export async function executeWithTimeout(
+  command: string,
+  timeoutSeconds: number,
+  env?: Record<string, string | undefined>,
+  options?: {
+    shell?: string;
+    gracePeriodMs?: number;
+    drainTimeoutMs?: number;
+    cwd?: string;
+  },
+): Promise<TestExecutionResult> {
+  const shell = options?.shell ?? "/bin/sh";
+  const gracePeriodMs = options?.gracePeriodMs ?? 5000;
+  const drainTimeoutMs = options?.drainTimeoutMs ?? 2000;
+
+  const proc = Bun.spawn([shell, "-c", command], {
+    stdout: "pipe",
+    stderr: "pipe",
+    env: env || normalizeEnvironment(process.env as Record<string, string | undefined>),
+    cwd: options?.cwd,
+  });
+
+  const timeoutMs = timeoutSeconds * 1000;
+  let timeoutId: Timer | null = null;
+  let timedOut = false;
+
+  const timeoutPromise = new Promise<void>((resolve) => {
+    timeoutId = setTimeout(() => {
+      timedOut = true;
+      resolve();
+    }, timeoutMs);
+  });
+
+  const processPromise = proc.exited;
+
+  const raceResult = await Promise.race([processPromise, timeoutPromise]);
+
+  if (timedOut) {
+    const pid = proc.pid;
+
+    // Send SIGTERM to process group (negative PID) to kill children too
+    try {
+      process.kill(-pid, "SIGTERM");
+    } catch (error) {
+      // Fallback: kill direct process if process group kill fails
+      try {
+        proc.kill("SIGTERM");
+      } catch (fallbackError) {
+        // Process may have already exited
+      }
+    }
+
+    // Wait for graceful shutdown
+    await new Promise((resolve) => setTimeout(resolve, gracePeriodMs));
+
+    // Force SIGKILL entire process group if still running
+    try {
+      process.kill(-pid, "SIGKILL");
+    } catch (error) {
+      try {
+        proc.kill("SIGKILL");
+      } catch (fallbackError) {
+        // Process may have already exited
+      }
+    }
+
+    // Bun bug workaround: piped streams don't close after kill
+    const partialOutput = await drainWithDeadline(proc, drainTimeoutMs);
+
+    return {
+      success: false,
+      timeout: true,
+      killed: true,
+      childProcessesKilled: true,
+      output: partialOutput || undefined,
+      error: `EXECUTION_TIMEOUT: Verification process exceeded ${timeoutSeconds}s. Process group (PID ${pid}) killed.`,
+      countsTowardEscalation: false, // Timeout is environmental, not code failure
+    };
+  }
+
+  // Clear timeout if process finished in time
+  if (timeoutId) {
+    clearTimeout(timeoutId);
+  }
+
+  const exitCode = raceResult as number;
+  const stdout = await new Response(proc.stdout).text();
+  const stderr = await new Response(proc.stderr).text();
+  const output = `${stdout}\n${stderr}`;
+
+  return {
+    success: exitCode === 0,
+    timeout: false,
+    exitCode,
+    output,
+    countsTowardEscalation: true,
+  };
+}
+
+/**
+ * Check if a test command already includes --detectOpenHandles.
+ */
+function detectOpenHandlesFlag(command: string): boolean {
+  return command.includes("--detectOpenHandles");
+}
+
+/**
+ * Append --detectOpenHandles to a test command for diagnostic retry.
+ */
+export function appendOpenHandlesFlag(command: string): string {
+  if (detectOpenHandlesFlag(command)) return command;
+  return appendFlag(command, "--detectOpenHandles");
+}
+
+/**
+ * Check if a test command already includes --forceExit.
+ */
+function forceExitFlag(command: string): boolean {
+  return command.includes("--forceExit");
+}
+
+/**
+ * Append --forceExit to a test command to force process exit after tests.
+ */
+export function appendForceExitFlag(command: string): string {
+  if (forceExitFlag(command)) return command;
+  return appendFlag(command, "--forceExit");
+}
+
+/**
+ * Append a flag to a command, inserting before any pipe/redirect.
+ */
+function appendFlag(command: string, flag: string): string {
+  const pipeIndex = command.search(/[|>]/);
+  if (pipeIndex > 0) {
+    return `${command.slice(0, pipeIndex).trimEnd()} ${flag} ${command.slice(pipeIndex)}`;
+  }
+  return `${command} ${flag}`;
+}
+
+/**
+ * Build the final test command based on quality config and retry state.
+ */
+export function buildTestCommand(
+  baseCommand: string,
+  options: {
+    forceExit?: boolean;
+    detectOpenHandles?: boolean;
+    detectOpenHandlesRetries?: number;
+    timeoutRetryCount?: number;
+  },
+): string {
+  let command = baseCommand;
+
+  const { forceExit = false, detectOpenHandles = true, detectOpenHandlesRetries = 1, timeoutRetryCount = 0 } = options;
+
+  // If we've exhausted detectOpenHandles retries, force exit as last resort
+  const exhaustedDiagnosticRetries = timeoutRetryCount > detectOpenHandlesRetries;
+
+  // Apply --forceExit if configured or if diagnostic retries exhausted
+  if (forceExit || exhaustedDiagnosticRetries) {
+    command = appendForceExitFlag(command);
+  }
+
+  // Apply --detectOpenHandles on timeout retries (within cap)
+  if (detectOpenHandles && timeoutRetryCount > 0 && timeoutRetryCount <= detectOpenHandlesRetries) {
+    command = appendOpenHandlesFlag(command);
+  }
+
+  return command;
+}

package/src/verification/gate.ts

@@ -0,0 +1,207 @@
+/**
+ * Verification Gates
+ *
+ * Three verification strategies with unified implementation:
+ * - fullSuite(): Run entire test suite (used by execution/verification.ts)
+ * - scoped(): Run tests for modified files only (used by tdd/orchestrator.ts)
+ * - regression(): Quick smoke test to catch obvious breakage (used by pipeline/stages/verify.ts)
+ */
+
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { buildTestCommand, executeWithTimeout, normalizeEnvironment } from "./executor";
+import { parseTestOutput } from "./parser";
+import type { AssetVerificationResult, VerificationGateOptions, VerificationResult } from "./types";
+
+/**
+ * Verify all expected files exist before running tests.
+ *
+ * Prevents "Tests failed (exit code 1)" with no context by checking
+ * files listed in story.expectedFiles before test execution.
+ */
+export async function verifyAssets(
+  workingDirectory: string,
+  expectedFiles?: string[],
+): Promise<AssetVerificationResult> {
+  if (!expectedFiles || expectedFiles.length === 0) {
+    return {
+      success: true,
+      missingFiles: [],
+    };
+  }
+
+  const missingFiles: string[] = [];
+
+  for (const file of expectedFiles) {
+    const fullPath = join(workingDirectory, file);
+    if (!existsSync(fullPath)) {
+      missingFiles.push(file);
+    }
+  }
+
+  if (missingFiles.length > 0) {
+    return {
+      success: false,
+      missingFiles,
+      error: `ASSET_CHECK_FAILED: Missing files: [${missingFiles.join(", ")}]\nAction: Create the missing files before tests can run.`,
+    };
+  }
+
+  return {
+    success: true,
+    missingFiles: [],
+  };
+}
+
+/**
+ * Run complete verification flow with all safety checks.
+ *
+ * Integrates:
+ * - Pre-flight asset verification
+ * - Execution guard with timeout
+ * - Smart exit-code analysis
+ * - Environment normalization
+ */
+async function runVerificationCore(options: VerificationGateOptions): Promise<VerificationResult> {
+  // Pre-flight asset verification
+  const assetCheck = await verifyAssets(options.workdir, options.expectedFiles);
+  if (!assetCheck.success) {
+    return {
+      status: "ASSET_CHECK_FAILED",
+      success: false,
+      countsTowardEscalation: true,
+      error: assetCheck.error,
+      missingFiles: assetCheck.missingFiles,
+    };
+  }
+
+  // Build command with open handle / force exit flags based on config + retry state
+  const finalCommand = buildTestCommand(options.command, {
+    forceExit: options.forceExit,
+    detectOpenHandles: options.detectOpenHandles,
+    detectOpenHandlesRetries: options.detectOpenHandlesRetries,
+    timeoutRetryCount: options.timeoutRetryCount,
+  });
+
+  // Environment normalization
+  const normalizedEnv = normalizeEnvironment(process.env as Record<string, string | undefined>, options.stripEnvVars);
+
+  // Execution guard with timeout
+  const execution = await executeWithTimeout(finalCommand, options.timeoutSeconds, normalizedEnv, {
+    shell: options.shell,
+    gracePeriodMs: options.gracePeriodMs,
+    drainTimeoutMs: options.drainTimeoutMs,
+    cwd: options.workdir,
+  });
+
+  if (execution.timeout) {
+    return {
+      status: "TIMEOUT",
+      success: false,
+      countsTowardEscalation: false, // Timeout is environmental, not code failure
+      error: execution.error,
+      output: execution.output,
+    };
+  }
+
+  // Smart exit-code analysis
+  const exitCode = execution.exitCode ?? 1; // Default to failure if undefined
+  if (exitCode !== 0 && execution.output) {
+    const analysis = parseTestOutput(execution.output, exitCode);
+
+    if (analysis.isEnvironmentalFailure) {
+      return {
+        status: "ENVIRONMENTAL_FAILURE",
+        success: false,
+        countsTowardEscalation: true,
+        error: analysis.error,
+        output: execution.output,
+        passCount: analysis.passCount,
+        failCount: analysis.failCount,
+      };
+    }
+
+    return {
+      status: "TEST_FAILURE",
+      success: false,
+      countsTowardEscalation: true,
+      output: execution.output,
+      passCount: analysis.passCount,
+      failCount: analysis.failCount,
+    };
+  }
+
+  return {
+    status: "SUCCESS",
+    success: true,
+    countsTowardEscalation: true,
+    output: execution.output,
+  };
+}
+
+/**
+ * Full Suite Verification Gate
+ *
+ * Runs the entire test suite to catch regressions.
+ * Used by: execution/verification.ts
+ *
+ * Strategy:
+ * - Runs all tests without filtering
+ * - Full timeout (typically 120s+)
+ * - Asset verification enabled
+ * - Environment normalization enabled
+ */
+export async function fullSuite(options: VerificationGateOptions): Promise<VerificationResult> {
+  return runVerificationCore(options);
+}
+
+/**
+ * Scoped Verification Gate
+ *
+ * Runs only tests for modified files to provide fast feedback.
+ * Used by: tdd/orchestrator.ts (between sessions)
+ *
+ * Strategy:
+ * - Filters test command to only run affected test files
+ * - Shorter timeout (typically 60s)
+ * - Asset verification enabled
+ * - Environment normalization enabled
+ */
+export async function scoped(options: VerificationGateOptions): Promise<VerificationResult> {
+  // Build scoped command if test paths provided
+  let scopedCommand = options.command;
+  if (options.scopedTestPaths && options.scopedTestPaths.length > 0) {
+    // Append test file paths to command
+    scopedCommand = `${options.command} ${options.scopedTestPaths.join(" ")}`;
+  }
+
+  return runVerificationCore({
+    ...options,
+    command: scopedCommand,
+  });
+}
+
+/**
+ * Regression Verification Gate
+ *
+ * Quick smoke test to catch obvious breakage before full review.
+ * Used by: pipeline/stages/verify.ts
+ *
+ * Strategy:
+ * - Runs all tests (no filtering)
+ * - Shorter timeout (typically 60s)
+ * - NO asset verification (assumes files exist from prior stages)
+ * - Environment normalization enabled
+ * - Waits 2s for agent processes to terminate (OOM prevention)
+ */
+export async function regression(options: VerificationGateOptions): Promise<VerificationResult> {
+  // Wait 2 seconds to let agent child processes fully terminate
+  // This prevents OOM on low-RAM systems when TypeScript language servers
+  // are still in memory while we spawn `bun test`
+  await Bun.sleep(2000);
+
+  return runVerificationCore({
+    ...options,
+    expectedFiles: undefined, // Skip asset verification for regression check
+  });
+}

package/src/verification/index.ts

@@ -0,0 +1,12 @@
+/**
+ * Unified Verification Layer
+ *
+ * Central module for test execution, parsing, and verification gates.
+ * Eliminates duplication across execution/, tdd/, and pipeline/stages/.
+ */
+
+export * from "./types";
+export * from "./executor";
+export * from "./parser";
+export * from "./gate";
+export * from "./rectification";