@nathapp/nax 0.50.3 → 0.51.0

package/src/utils/git.ts

@@ -1,245 +0,0 @@
-/**
- * Git utility functions
- */
-
-import { getSafeLogger } from "../logger";
-
-/**
- * Injectable dependencies for git subprocess calls — allows tests to intercept
- * Bun.spawn without mock.module().
- *
- * @internal
- */
-export const _gitDeps = { spawn: Bun.spawn };
-
-/**
- * Default timeout for git subprocess calls.
- * Prevents git from hanging indefinitely on locked repos or network mounts.
- */
-const GIT_TIMEOUT_MS = 10_000;
-
-/**
- * Spawn a git command with a hard timeout.
- *
- * Kills the process with SIGKILL after GIT_TIMEOUT_MS if it hasn't exited.
- * Returns empty stdout and exit code 1 on timeout.
- *
- * @internal
- */
-export async function gitWithTimeout(args: string[], workdir: string): Promise<{ stdout: string; exitCode: number }> {
-  const proc = _gitDeps.spawn(["git", ...args], {
-    cwd: workdir,
-    stdout: "pipe",
-    stderr: "pipe",
-  });
-
-  let timedOut = false;
-  const timerId = setTimeout(() => {
-    timedOut = true;
-    try {
-      proc.kill("SIGKILL");
-    } catch {
-      // Process may have already exited
-    }
-  }, GIT_TIMEOUT_MS);
-
-  const exitCode = await proc.exited;
-  clearTimeout(timerId);
-
-  if (timedOut) {
-    return { stdout: "", exitCode: 1 };
-  }
-
-  const stdout = await new Response(proc.stdout).text();
-  return { stdout, exitCode };
-}
-
-/**
- * Capture current git HEAD ref.
- *
- * Returns the current HEAD commit hash, or undefined if git is not available
- * or the command fails (e.g., not in a git repo).
- *
- * @param workdir - Working directory to run git command in
- * @returns Git HEAD ref or undefined on failure
- *
- * @example
- * ```typescript
- * const ref = await captureGitRef("/path/to/repo");
- * if (ref) {
- *   console.log(`Current HEAD: ${ref}`);
- * }
- * ```
- */
-export async function captureGitRef(workdir: string): Promise<string | undefined> {
-  try {
-    const { stdout, exitCode } = await gitWithTimeout(["rev-parse", "HEAD"], workdir);
-    if (exitCode !== 0) return undefined;
-    return stdout.trim() || undefined;
-  } catch {
-    return undefined;
-  }
-}
-
-/**
- * Check if a story ID appears in recent git commit messages.
- *
- * Searches the last N commits for commit messages containing the story ID.
- * Used for state reconciliation: if a failed story has commits in git history,
- * it means the story was partially completed and should be marked as passed.
- *
- * @param workdir - Working directory to run git command in
- * @param storyId - Story ID to search for (e.g., "US-001")
- * @param maxCommits - Maximum number of commits to search (default: 20)
- * @returns true if story ID found in commit messages, false otherwise
- *
- * @example
- * ```typescript
- * const hasCommits = await hasCommitsForStory("/path/to/repo", "US-001");
- * if (hasCommits) {
- *   console.log("Story US-001 has commits in git history");
- * }
- * ```
- */
-export async function hasCommitsForStory(workdir: string, storyId: string, maxCommits = 20): Promise<boolean> {
-  try {
-    const { stdout, exitCode } = await gitWithTimeout(
-      ["log", `-${maxCommits}`, "--oneline", "--grep", storyId],
-      workdir,
-    );
-    if (exitCode !== 0) return false;
-    return stdout.trim().length > 0;
-  } catch {
-    return false;
-  }
-}
-
-/**
- * Detect if git operation output contains merge conflict markers.
- *
- * Git outputs "CONFLICT" in uppercase for merge/rebase conflicts.
- * Also checks lowercase "conflict" for edge cases.
- *
- * @param output - Combined stdout/stderr output from a git operation
- * @returns true if output contains CONFLICT markers
- *
- * @example
- * ```typescript
- * const hasConflict = detectMergeConflict(agentOutput);
- * if (hasConflict) {
- *   // fire merge-conflict trigger
- * }
- * ```
- */
-export function detectMergeConflict(output: string): boolean {
-  return output.includes("CONFLICT") || output.includes("conflict");
-}
-
-/**
- * Auto-commit safety net.
- *
- * If the agent left uncommitted changes after a session, stage and commit them
- * automatically. Prevents the review stage from failing with "uncommitted
- * changes" errors. No-op when the working tree is clean.
- *
- * Used by session-runner.ts (TDD sessions), rectification-gate.ts, and
- * execution.ts (single-session / test-after).
- *
- * @param workdir - Working directory (git repo root)
- * @param stage   - Log stage prefix (e.g. "tdd", "execution")
- * @param role    - Session role for the commit message (e.g. "implementer")
- * @param storyId - Story ID for the commit message
- */
-export async function autoCommitIfDirty(workdir: string, stage: string, role: string, storyId: string): Promise<void> {
-  const logger = getSafeLogger();
-  try {
-    // Guard: only auto-commit if workdir IS the git repository root.
-    // Without this, a workdir nested inside another git repo (e.g. a temp dir
-    // created inside the nax repo during tests) would cause git to walk up and
-    // commit files from the parent repo instead.
-    const topLevelProc = _gitDeps.spawn(["git", "rev-parse", "--show-toplevel"], {
-      cwd: workdir,
-      stdout: "pipe",
-      stderr: "pipe",
-    });
-    const gitRoot = (await new Response(topLevelProc.stdout).text()).trim();
-    await topLevelProc.exited;
-
-    // Normalize paths to handle symlinks (e.g. /tmp → /private/tmp on macOS)
-    const { realpathSync } = await import("node:fs");
-    const realWorkdir = (() => {
-      try {
-        return realpathSync(workdir);
-      } catch {
-        return workdir;
-      }
-    })();
-    const realGitRoot = (() => {
-      try {
-        return realpathSync(gitRoot);
-      } catch {
-        return gitRoot;
-      }
-    })();
-    // Allow: workdir IS the git root, or workdir is a subdirectory (monorepo package)
-    // Reject: workdir has no git repo at all (realGitRoot would be empty/error)
-    const isAtRoot = realWorkdir === realGitRoot;
-    const isSubdir = realGitRoot && realWorkdir.startsWith(`${realGitRoot}/`);
-    if (!isAtRoot && !isSubdir) return;
-
-    const statusProc = _gitDeps.spawn(["git", "status", "--porcelain"], {
-      cwd: workdir,
-      stdout: "pipe",
-      stderr: "pipe",
-    });
-    const statusOutput = await new Response(statusProc.stdout).text();
-    await statusProc.exited;
-
-    if (!statusOutput.trim()) return;
-
-    logger?.warn(stage, `Agent did not commit after ${role} session — auto-committing`, {
-      role,
-      storyId,
-      dirtyFiles: statusOutput.trim().split("\n").length,
-    });
-
-    // Use "git add ." when workdir is a monorepo package subdir — only stages files under
-    // that package, preventing accidental cross-package commits.
-    // Use "git add -A" at repo root to capture renames/deletions across the full tree.
-    const addArgs = isSubdir ? ["git", "add", "."] : ["git", "add", "-A"];
-    const addProc = _gitDeps.spawn(addArgs, { cwd: workdir, stdout: "pipe", stderr: "pipe" });
-    await addProc.exited;
-
-    const commitProc = _gitDeps.spawn(["git", "commit", "-m", `chore(${storyId}): auto-commit after ${role} session`], {
-      cwd: workdir,
-      stdout: "pipe",
-      stderr: "pipe",
-    });
-    await commitProc.exited;
-  } catch {
-    // Silently ignore — auto-commit is best-effort
-  }
-}
-
-/**
- * Capture files changed since a given git ref (for context chaining, ENH-005).
- * Scopes to scopePrefix (story.workdir) when set — prevents cross-package bleeding in monorepos.
- * Returns empty array if baseRef is falsy or git fails.
- */
-export async function captureOutputFiles(
-  workdir: string,
-  baseRef: string | undefined,
-  scopePrefix?: string,
-): Promise<string[]> {
-  if (!baseRef) return [];
-  try {
-    const args = ["diff", "--name-only", `${baseRef}..HEAD`];
-    if (scopePrefix) args.push("--", `${scopePrefix}/`);
-    const proc = _gitDeps.spawn(["git", ...args], { cwd: workdir, stdout: "pipe", stderr: "pipe" });
-    const output = await new Response(proc.stdout).text();
-    await proc.exited;
-    return output.trim().split("\n").filter(Boolean);
-  } catch {
-    return [];
-  }
-}

package/src/utils/json-file.ts

@@ -1,72 +0,0 @@
-/**
- * Shared JSON File I/O Utility
- *
- * Provides type-safe, error-tolerant helpers for reading and writing JSON files.
- * Encapsulates common patterns: existsSync check, try/catch, logging.
- */
-
-import { existsSync } from "node:fs";
-import { getLogger } from "../logger";
-
-/**
- * Load a JSON file with type safety and error handling.
- *
- * Returns null if the file doesn't exist or cannot be parsed.
- * Logs a warning if parsing fails.
- *
- * @param path - File path to load
- * @param context - Logger context (e.g., "config", "hooks", "metrics")
- * @returns Parsed JSON object, or null if file missing or invalid
- *
- * @example
- * ```ts
- * const config = await loadJsonFile<NaxConfig>("nax/config.json", "config");
- * ```
- */
-export async function loadJsonFile<T>(path: string, context = "json-file"): Promise<T | null> {
-  if (!existsSync(path)) {
-    return null;
-  }
-
-  try {
-    const content = await Bun.file(path).json();
-    return content as T;
-  } catch (err) {
-    const logger = getLogger();
-    logger.warn(context, "Failed to parse JSON file", {
-      path,
-      error: String(err),
-    });
-    return null;
-  }
-}
-
-/**
- * Save an object as JSON to a file.
- *
- * Writes formatted JSON (2-space indent) for readability.
- * Creates parent directories if they don't exist.
- *
- * @param path - File path to write to
- * @param data - Object to serialize
- * @param context - Logger context (for errors)
- * @throws Error if write fails
- *
- * @example
- * ```ts
- * await saveJsonFile("nax/config.json", config, "config");
- * ```
- */
-export async function saveJsonFile<T>(path: string, data: T, context = "json-file"): Promise<void> {
-  try {
-    const json = JSON.stringify(data, null, 2);
-    await Bun.write(path, json);
-  } catch (err) {
-    const logger = getLogger();
-    logger.error(context, "Failed to write JSON file", {
-      path,
-      error: String(err),
-    });
-    throw err;
-  }
-}

package/src/utils/log-test-output.ts

@@ -1,25 +0,0 @@
-import type { Logger } from "../logger";
-
-/**
- * Log test output consistently across all pipeline stages.
- *
- * Summary (exitCode, storyId) is logged at the caller's level (error/warn).
- * Raw output is logged at debug level only — last `tailLines` lines.
- *
- * `storyId` is optional: works for per-story verify/acceptance AND for
- * deferred runs (deferred acceptance, deferred regression) with no story context.
- */
-export function logTestOutput(
-  logger: Logger | null | undefined,
-  stage: string,
-  output: string | undefined,
-  opts: { storyId?: string; tailLines?: number } = {},
-): void {
-  if (!logger || !output) return;
-  const tailLines = opts.tailLines ?? 20;
-  const lines = output.split("\n").slice(-tailLines).join("\n");
-  logger.debug(stage, "Test output (tail)", {
-    ...(opts.storyId !== undefined && { storyId: opts.storyId }),
-    output: lines,
-  });
-}

package/src/utils/path-security.ts

@@ -1,73 +0,0 @@
-/**
- * Path security utilities for nax (SEC-1, SEC-2).
- */
-
-import { realpathSync } from "node:fs";
-import { dirname, isAbsolute, join, normalize, resolve } from "node:path";
-
-/**
- * Result of a path validation.
- */
-export interface PathValidationResult {
-  /** Whether the path is valid and allowed */
-  valid: boolean;
-  /** The absolute, normalized path (if valid) */
-  absolutePath?: string;
-  /** Error message if invalid */
-  error?: string;
-}
-
-/**
- * Validates that a module path is within an allowed root directory.
- *
- * @param modulePath - The user-provided path to validate (relative or absolute)
- * @param allowedRoots - Array of absolute paths that are allowed as roots
- * @returns Validation result
- */
-/** Resolve symlinks for a path that may not exist yet (fall back to parent dir). */
-function safeRealpath(p: string): string {
-  try {
-    return realpathSync(p);
-  } catch {
-    // Path doesn't exist — resolve the parent directory instead
-    try {
-      const parent = realpathSync(dirname(p));
-      return join(parent, p.split("/").pop() ?? "");
-    } catch {
-      return p;
-    }
-  }
-}
-
-export function validateModulePath(modulePath: string, allowedRoots: string[]): PathValidationResult {
-  if (!modulePath) {
-    return { valid: false, error: "Module path is empty" };
-  }
-
-  // Resolve symlinks in each root
-  const normalizedRoots = allowedRoots.map((r) => safeRealpath(resolve(r)));
-
-  // If absolute, just check against roots
-  if (isAbsolute(modulePath)) {
-    const absoluteTarget = safeRealpath(normalize(modulePath));
-    const isWithin = normalizedRoots.some((root) => {
-      return absoluteTarget.startsWith(`${root}/`) || absoluteTarget === root;
-    });
-    if (isWithin) {
-      return { valid: true, absolutePath: absoluteTarget };
-    }
-  } else {
-    // If relative, check if it's within any root when resolved relative to that root
-    for (const root of normalizedRoots) {
-      const absoluteTarget = safeRealpath(resolve(join(root, modulePath)));
-      if (absoluteTarget.startsWith(`${root}/`) || absoluteTarget === root) {
-        return { valid: true, absolutePath: absoluteTarget };
-      }
-    }
-  }
-
-  return {
-    valid: false,
-    error: `Path "${modulePath}" is outside allowed roots`,
-  };
-}

package/src/utils/queue-writer.ts

@@ -1,54 +0,0 @@
-/**
- * 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/crash-detector.ts

@@ -1,34 +0,0 @@
-/**
- * Runtime Crash Detector — BUG-070
- *
- * Detects Bun runtime crashes in test output so they can be classified as
- * RUNTIME_CRASH rather than TEST_FAILURE, preventing spurious tier escalation.
- *
- * STUB — implementation is intentionally absent. Tests are RED until
- * the real logic is written.
- */
-
-/**
- * Known patterns emitted by the Bun runtime before any test results
- * when a crash occurs (segfault, panic, etc.).
- */
-export const CRASH_PATTERNS = [
-  "panic(main thread)",
-  "Segmentation fault",
-  "Bun has crashed",
-  "oh no: Bun has crashed",
-] as const;
-
-/**
- * Detect whether the given test runner output contains a Bun runtime crash.
- *
- * Returns true if any known crash pattern is found in the output.
- * These patterns are emitted by Bun itself before any test result lines.
- *
- * @param output - Raw stdout/stderr from the test runner
- */
-export function detectRuntimeCrash(output: string | undefined | null): boolean {
-  // STUB: not implemented yet — always returns false
-  if (!output) return false;
-  return CRASH_PATTERNS.some((pattern) => output.includes(pattern));
-}