@nathapp/nax 0.37.0 → 0.38.1

package/src/tdd/verdict.ts

@@ -1,18 +1,17 @@
 /**
- * Verifier Verdict — types and reader
+ * Verifier Verdict — types and categorization
  *
  * The verifier (session 3) writes a structured verdict file to
  * `.nax-verifier-verdict.json` in the workdir. This module reads,
- * validates, and interprets that verdict.
+ * validates, interprets, and categorizes that verdict.
+ *
+ * Re-exports parser and coercer modules for backward compatibility.
  */
 
-import { unlink } from "node:fs/promises";
-import path from "node:path";
-import { getLogger } from "../logger";
 import type { FailureCategory } from "./types";
 
-/** File name written by the verifier agent */
-export const VERDICT_FILE = ".nax-verifier-verdict.json";
+// Re-export for backward compatibility
+export { VERDICT_FILE, isValidVerdict, readVerdict, cleanupVerdict, coerceVerdict } from "./verdict-reader";
 
 /** Structured verdict written by the verifier (session 3) */
 export interface VerifierVerdict {
@@ -71,261 +70,6 @@ export interface VerifierVerdict {
   reasoning: string;
 }
 
-/**
- * Validate that a parsed object has the required fields for a VerifierVerdict.
- * Returns true if the object appears to be a valid verdict.
- */
-function isValidVerdict(obj: unknown): obj is VerifierVerdict {
-  if (!obj || typeof obj !== "object") return false;
-  const v = obj as Record<string, unknown>;
-
-  // Required top-level fields
-  if (v.version !== 1) return false;
-  if (typeof v.approved !== "boolean") return false;
-
-  // tests sub-object
-  if (!v.tests || typeof v.tests !== "object") return false;
-  const tests = v.tests as Record<string, unknown>;
-  if (typeof tests.allPassing !== "boolean") return false;
-  if (typeof tests.passCount !== "number") return false;
-  if (typeof tests.failCount !== "number") return false;
-
-  // testModifications sub-object
-  if (!v.testModifications || typeof v.testModifications !== "object") return false;
-  const mods = v.testModifications as Record<string, unknown>;
-  if (typeof mods.detected !== "boolean") return false;
-  if (!Array.isArray(mods.files)) return false;
-  if (typeof mods.legitimate !== "boolean") return false;
-  if (typeof mods.reasoning !== "string") return false;
-
-  // acceptanceCriteria sub-object
-  if (!v.acceptanceCriteria || typeof v.acceptanceCriteria !== "object") return false;
-  const ac = v.acceptanceCriteria as Record<string, unknown>;
-  if (typeof ac.allMet !== "boolean") return false;
-  if (!Array.isArray(ac.criteria)) return false;
-
-  // quality sub-object
-  if (!v.quality || typeof v.quality !== "object") return false;
-  const quality = v.quality as Record<string, unknown>;
-  if (!["good", "acceptable", "poor"].includes(quality.rating as string)) return false;
-  if (!Array.isArray(quality.issues)) return false;
-
-  // fixes and reasoning
-  if (!Array.isArray(v.fixes)) return false;
-  if (typeof v.reasoning !== "string") return false;
-
-  return true;
-}
-
-/**
- * Coerce a free-form verdict object into the expected VerifierVerdict schema.
- * Maps common agent-improvised patterns (verdict:"PASS", verification_summary, etc.)
- * to the structured format. Returns null if too malformed to coerce.
- */
-export function coerceVerdict(obj: Record<string, unknown>): VerifierVerdict | null {
-  try {
-    // Determine approval status
-    const verdictStr = String(obj.verdict ?? "").toUpperCase();
-    const approved =
-      verdictStr === "PASS" ||
-      verdictStr === "APPROVED" ||
-      verdictStr.startsWith("VERIFIED") ||
-      verdictStr.includes("ALL ACCEPTANCE CRITERIA MET") ||
-      obj.approved === true;
-
-    // Parse test results from verification_summary or top-level
-    let passCount = 0;
-    let failCount = 0;
-    let allPassing = approved;
-    const summary = obj.verification_summary as Record<string, unknown> | undefined;
-    if (summary?.test_results && typeof summary.test_results === "string") {
-      // Parse "45/45 PASS" or "42/45 PASS" patterns
-      const match = (summary.test_results as string).match(/(\d+)\/(\d+)/);
-      if (match) {
-        passCount = Number.parseInt(match[1], 10);
-        const total = Number.parseInt(match[2], 10);
-        failCount = total - passCount;
-        allPassing = failCount === 0;
-      }
-    }
-    // Also check top-level tests object (partial schema compliance)
-    if (obj.tests && typeof obj.tests === "object") {
-      const t = obj.tests as Record<string, unknown>;
-      if (typeof t.passCount === "number") passCount = t.passCount;
-      if (typeof t.failCount === "number") failCount = t.failCount;
-      if (typeof t.allPassing === "boolean") allPassing = t.allPassing;
-    }
-
-    // Parse acceptance criteria from acceptance_criteria_review or acceptanceCriteria
-    const criteria: Array<{ criterion: string; met: boolean; note?: string }> = [];
-    let allMet = approved;
-    const acReview = obj.acceptance_criteria_review as Record<string, unknown> | undefined;
-    if (acReview) {
-      for (const [key, val] of Object.entries(acReview)) {
-        if (key.startsWith("criterion") && val && typeof val === "object") {
-          const c = val as Record<string, unknown>;
-          const met = String(c.status ?? "").toUpperCase() === "SATISFIED" || c.met === true;
-          criteria.push({
-            criterion: String(c.name ?? c.criterion ?? key),
-            met,
-            note: c.evidence ? String(c.evidence).slice(0, 200) : undefined,
-          });
-          if (!met) allMet = false;
-        }
-      }
-    }
-    // Also check top-level acceptanceCriteria
-    if (obj.acceptanceCriteria && typeof obj.acceptanceCriteria === "object") {
-      const ac = obj.acceptanceCriteria as Record<string, unknown>;
-      if (typeof ac.allMet === "boolean") allMet = ac.allMet;
-      if (Array.isArray(ac.criteria)) {
-        for (const c of ac.criteria) {
-          if (c && typeof c === "object") {
-            criteria.push(c as { criterion: string; met: boolean; note?: string });
-          }
-        }
-      }
-    }
-    // Parse summary AC count like "4/4 SATISFIED"
-    if (criteria.length === 0 && summary?.acceptance_criteria && typeof summary.acceptance_criteria === "string") {
-      const acMatch = (summary.acceptance_criteria as string).match(/(\d+)\/(\d+)/);
-      if (acMatch) {
-        const met = Number.parseInt(acMatch[1], 10);
-        const total = Number.parseInt(acMatch[2], 10);
-        allMet = met === total;
-      }
-    }
-
-    // Parse quality
-    let rating: "good" | "acceptable" | "poor" = "acceptable";
-    const qualityStr = summary?.code_quality
-      ? String(summary.code_quality).toLowerCase()
-      : obj.quality && typeof obj.quality === "object"
-        ? String((obj.quality as Record<string, unknown>).rating ?? "acceptable").toLowerCase()
-        : "acceptable";
-    if (qualityStr === "high" || qualityStr === "good") rating = "good";
-    else if (qualityStr === "low" || qualityStr === "poor") rating = "poor";
-
-    // Build coerced verdict
-    return {
-      version: 1,
-      approved,
-      tests: { allPassing, passCount, failCount },
-      testModifications: {
-        detected: false,
-        files: [],
-        legitimate: true,
-        reasoning: "Not assessed in free-form verdict",
-      },
-      acceptanceCriteria: { allMet, criteria },
-      quality: { rating, issues: [] },
-      fixes: Array.isArray(obj.fixes) ? (obj.fixes as string[]) : [],
-      reasoning:
-        typeof obj.reasoning === "string"
-          ? obj.reasoning
-          : typeof obj.overall_status === "string"
-            ? (obj.overall_status as string)
-            : summary?.overall_status
-              ? String(summary.overall_status)
-              : `Coerced from free-form verdict: ${verdictStr}`,
-    };
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Read the verifier verdict file from the workdir.
- *
- * Returns the parsed VerifierVerdict when the file exists and is valid.
- * Attempts tolerant coercion if the file doesn't match the strict schema.
- * Returns null if:
- * - File does not exist
- * - File is not valid JSON
- * - Required fields are missing and coercion fails
- *
- * Never throws.
- */
-export async function readVerdict(workdir: string): Promise<VerifierVerdict | null> {
-  const logger = getLogger();
-  const verdictPath = path.join(workdir, VERDICT_FILE);
-
-  try {
-    const file = Bun.file(verdictPath);
-    const exists = await file.exists();
-    if (!exists) {
-      return null;
-    }
-
-    // Read as text first so we can log raw content on parse failure
-    let rawText: string;
-    try {
-      rawText = await file.text();
-    } catch (readErr) {
-      logger.warn("tdd", "Failed to read verifier verdict file", {
-        path: verdictPath,
-        error: String(readErr),
-      });
-      return null;
-    }
-
-    let parsed: unknown;
-    try {
-      parsed = JSON.parse(rawText);
-    } catch (parseErr) {
-      logger.warn("tdd", "Verifier verdict file is not valid JSON — ignoring", {
-        path: verdictPath,
-        error: String(parseErr),
-        rawContent: rawText.slice(0, 1000),
-      });
-      return null;
-    }
-
-    if (isValidVerdict(parsed)) {
-      return parsed;
-    }
-
-    // Strict validation failed — attempt tolerant coercion
-    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
-      const coerced = coerceVerdict(parsed as Record<string, unknown>);
-      if (coerced) {
-        logger.info("tdd", "Coerced free-form verdict to structured format", {
-          path: verdictPath,
-          approved: coerced.approved,
-          passCount: coerced.tests.passCount,
-          failCount: coerced.tests.failCount,
-        });
-        return coerced;
-      }
-    }
-
-    logger.warn("tdd", "Verifier verdict file missing required fields and coercion failed — ignoring", {
-      path: verdictPath,
-      content: JSON.stringify(parsed).slice(0, 500),
-    });
-    return null;
-  } catch (err) {
-    logger.warn("tdd", "Failed to read verifier verdict file — ignoring", {
-      path: verdictPath,
-      error: String(err),
-    });
-    return null;
-  }
-}
-
-/**
- * Delete the verifier verdict file from the workdir.
- * Ignores all errors (file may not exist, permissions, etc.).
- */
-export async function cleanupVerdict(workdir: string): Promise<void> {
-  const verdictPath = path.join(workdir, VERDICT_FILE);
-  try {
-    await unlink(verdictPath);
-  } catch {
-    // Intentionally ignored — file may not exist or already be deleted
-  }
-}
-
 /** Result of categorizing a verifier verdict */
 export interface VerdictCategorization {
   success: boolean;
@@ -351,7 +95,6 @@ export interface VerdictCategorization {
  * - null verdict, testsPass=false → tests-failing
  */
 export function categorizeVerdict(verdict: VerifierVerdict | null, testsPass: boolean): VerdictCategorization {
-  // No verdict — fall back to test-only check
   if (!verdict) {
     if (testsPass) {
       return { success: true };
@@ -363,14 +106,10 @@ export function categorizeVerdict(verdict: VerifierVerdict | null, testsPass: bo
     };
   }
 
-  // Approved
   if (verdict.approved) {
     return { success: true };
   }
 
-  // Not approved — classify the reason
-
-  // 1. Illegitimate test modifications (implementer cheated)
   if (verdict.testModifications.detected && !verdict.testModifications.legitimate) {
     const files = verdict.testModifications.files.join(", ") || "unknown files";
     return {
@@ -380,7 +119,6 @@ export function categorizeVerdict(verdict: VerifierVerdict | null, testsPass: bo
     };
   }
 
-  // 2. Tests failing
   if (!verdict.tests.allPassing) {
     return {
       success: false,
@@ -389,7 +127,6 @@ export function categorizeVerdict(verdict: VerifierVerdict | null, testsPass: bo
     };
   }
 
-  // 3. Acceptance criteria not met
   if (!verdict.acceptanceCriteria.allMet) {
     const unmet = verdict.acceptanceCriteria.criteria.filter((c) => !c.met).map((c) => c.criterion);
     return {
@@ -399,7 +136,6 @@ export function categorizeVerdict(verdict: VerifierVerdict | null, testsPass: bo
     };
   }
 
-  // 4. Poor quality
   if (verdict.quality.rating === "poor") {
     return {
       success: false,
@@ -408,7 +144,6 @@ export function categorizeVerdict(verdict: VerifierVerdict | null, testsPass: bo
     };
   }
 
-  // Catch-all: verdict says not approved but no clear specific reason
   return {
     success: false,
     failureCategory: "verifier-rejected",

package/src/utils/errors.ts

@@ -0,0 +1,12 @@
+/**
+ * Error utilities
+ */
+
+/**
+ * Extract error message from unknown error type.
+ *
+ * Handles both Error instances and non-Error values that can be thrown in JavaScript.
+ */
+export function errorMessage(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}

package/src/utils/git.ts

@@ -2,9 +2,16 @@
  * Git utility functions
  */
 
-import { spawn } from "bun";
 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.
@@ -20,7 +27,7 @@ const GIT_TIMEOUT_MS = 10_000;
  * @internal
  */
 export async function gitWithTimeout(args: string[], workdir: string): Promise<{ stdout: string; exitCode: number }> {
-  const proc = Bun.spawn(["git", ...args], {
+  const proc = _gitDeps.spawn(["git", ...args], {
     cwd: workdir,
     stdout: "pipe",
     stderr: "pipe",
@@ -146,7 +153,7 @@ export function detectMergeConflict(output: string): boolean {
 export async function autoCommitIfDirty(workdir: string, stage: string, role: string, storyId: string): Promise<void> {
   const logger = getSafeLogger();
   try {
-    const statusProc = Bun.spawn(["git", "status", "--porcelain"], {
+    const statusProc = _gitDeps.spawn(["git", "status", "--porcelain"], {
       cwd: workdir,
       stdout: "pipe",
       stderr: "pipe",
@@ -162,10 +169,10 @@ export async function autoCommitIfDirty(workdir: string, stage: string, role: st
       dirtyFiles: statusOutput.trim().split("\n").length,
     });
 
-    const addProc = Bun.spawn(["git", "add", "-A"], { cwd: workdir, stdout: "pipe", stderr: "pipe" });
+    const addProc = _gitDeps.spawn(["git", "add", "-A"], { cwd: workdir, stdout: "pipe", stderr: "pipe" });
     await addProc.exited;
 
-    const commitProc = Bun.spawn(["git", "commit", "-m", `chore(${storyId}): auto-commit after ${role} session`], {
+    const commitProc = _gitDeps.spawn(["git", "commit", "-m", `chore(${storyId}): auto-commit after ${role} session`], {
       cwd: workdir,
       stdout: "pipe",
       stderr: "pipe",

package/src/utils/json-file.ts

@@ -0,0 +1,72 @@
+/**
+ * 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/verification/executor.ts

@@ -6,6 +6,7 @@
  */
 
 import type { Subprocess } from "bun";
+import { errorMessage } from "../utils/errors";
 import type { TestExecutionResult } from "./types";
 
 /**
@@ -41,7 +42,7 @@ async function drainWithDeadline(proc: Subprocess, deadlineMs: number): Promise<
     if (!isExpectedStreamError) {
       const { getSafeLogger } = await import("../logger");
       getSafeLogger()?.debug("executor", "Unexpected error draining process output", {
-        error: error instanceof Error ? error.message : String(error),
+        error: errorMessage(error),
       });
     }
   }

package/src/verification/smart-runner.ts

@@ -6,6 +6,18 @@
  */
 import { gitWithTimeout } from "../utils/git";
 
+/**
+ * Bun API wrappers — defined before functions to avoid circular type inference.
+ * Use closures so tests mocking Bun.Glob / Bun.file on the global namespace
+ * continue to work (closures evaluate Bun.* at call time).
+ *
+ * @internal
+ */
+const _bunDeps = {
+  glob: (p: string) => new Bun.Glob(p),
+  file: (path: string) => Bun.file(path),
+};
+
 /**
  * Get TypeScript source files changed since the previous commit.
  *
@@ -85,7 +97,7 @@ export async function importGrepFallback(
   // Scan all test files matching the configured patterns
   const testFilePaths: string[] = [];
   for (const pattern of testFilePatterns) {
-    const glob = new Bun.Glob(pattern);
+    const glob = _bunDeps.glob(pattern);
     for await (const file of glob.scan(workdir)) {
       testFilePaths.push(`${workdir}/${file}`);
     }
@@ -96,7 +108,7 @@ export async function importGrepFallback(
   for (const testFile of testFilePaths) {
     let content: string;
     try {
-      content = await Bun.file(testFile).text();
+      content = await _bunDeps.file(testFile).text();
     } catch {
       continue;
     }
@@ -121,7 +133,7 @@ export async function mapSourceToTests(sourceFiles: string[], workdir: string):
     const candidates = [`${workdir}/test/unit/${relative}`, `${workdir}/test/integration/${relative}`];
 
     for (const candidate of candidates) {
-      if (await Bun.file(candidate).exists()) {
+      if (await _bunDeps.file(candidate).exists()) {
         result.push(candidate);
       }
     }
@@ -254,9 +266,17 @@ export function reverseMapTestToSource(testFiles: string[], workdir: string): st
  * Allows tests to swap implementations without using mock.module(),
  * which leaks across files in Bun 1.x due to shared module registry.
  *
+ * Bun API wrappers use closures so that tests mocking Bun.Glob / Bun.file
+ * on the global namespace continue to work (closures evaluate Bun.* at
+ * call time, not at module initialisation time).
+ *
  * @internal - test use only. Do not use in production code.
  */
 export const _smartRunnerDeps = {
+  /** Wraps Bun.Glob construction — injectable for testing. */
+  glob: _bunDeps.glob,
+  /** Wraps Bun.file — injectable for testing. */
+  file: _bunDeps.file,
   getChangedSourceFiles,
   mapSourceToTests,
   importGrepFallback,

package/src/worktree/manager.ts

@@ -1,6 +1,8 @@
 import { existsSync, symlinkSync } from "node:fs";
 import { join } from "node:path";
 import { getSafeLogger } from "../logger";
+import { validateStoryId } from "../prd/validate";
+import { errorMessage } from "../utils/errors";
 import type { WorktreeInfo } from "./types";
 
 export class WorktreeManager {
@@ -9,6 +11,8 @@ export class WorktreeManager {
    * and symlinks node_modules and .env from project root
    */
   async create(projectRoot: string, storyId: string): Promise<void> {
+    validateStoryId(storyId);
+
     const worktreePath = join(projectRoot, ".nax-wt", storyId);
     const branchName = `nax/${storyId}`;
 
@@ -48,7 +52,7 @@ export class WorktreeManager {
       } catch (error) {
         // Clean up worktree if symlinking fails
         await this.remove(projectRoot, storyId);
-        throw new Error(`Failed to symlink node_modules: ${error instanceof Error ? error.message : String(error)}`);
+        throw new Error(`Failed to symlink node_modules: ${errorMessage(error)}`);
       }
     }
 
@@ -61,7 +65,7 @@ export class WorktreeManager {
       } catch (error) {
         // Clean up worktree if symlinking fails
         await this.remove(projectRoot, storyId);
-        throw new Error(`Failed to symlink .env: ${error instanceof Error ? error.message : String(error)}`);
+        throw new Error(`Failed to symlink .env: ${errorMessage(error)}`);
       }
     }
   }
@@ -70,6 +74,8 @@ export class WorktreeManager {
    * Removes worktree and deletes branch
    */
   async remove(projectRoot: string, storyId: string): Promise<void> {
+    validateStoryId(storyId);
+
     const worktreePath = join(projectRoot, ".nax-wt", storyId);
     const branchName = `nax/${storyId}`;
 
@@ -122,7 +128,7 @@ export class WorktreeManager {
       // Log warning but don't fail - worktree is already removed
       const logger = getSafeLogger();
       logger?.warn("worktree", `Failed to delete branch ${branchName}`, {
-        error: error instanceof Error ? error.message : String(error),
+        error: errorMessage(error),
       });
     }
   }

package/src/worktree/merge.ts

@@ -1,4 +1,5 @@
 import { getSafeLogger } from "../logger";
+import { errorMessage } from "../utils/errors";
 import type { WorktreeManager } from "./manager";
 
 export interface MergeResult {
@@ -44,7 +45,7 @@ export class MergeEngine {
           // Log warning but don't fail the merge
           const logger = getSafeLogger();
           logger?.warn("worktree", `Failed to cleanup worktree for ${storyId}`, {
-            error: error instanceof Error ? error.message : String(error),
+            error: errorMessage(error),
           });
         }
 
@@ -294,7 +295,7 @@ export class MergeEngine {
       // Log warning but don't throw - merge might already be aborted
       const logger = getSafeLogger();
       logger?.warn("worktree", "Failed to abort merge", {
-        error: error instanceof Error ? error.message : String(error),
+        error: errorMessage(error),
       });
     }
   }