@nathapp/nax 0.37.0 → 0.38.1

package/src/precheck/checks-system.ts

@@ -0,0 +1,163 @@
+/**
+ * System-level precheck implementations
+ */
+
+import { existsSync, statSync } from "node:fs";
+import type { NaxConfig } from "../config";
+import type { Check } from "./types";
+
+/** Check if dependencies are installed (language-aware). Detects: node_modules, target, venv, vendor */
+export async function checkDependenciesInstalled(workdir: string): Promise<Check> {
+  const depPaths = [
+    { path: "node_modules" },
+    { path: "target" },
+    { path: "venv" },
+    { path: ".venv" },
+    { path: "vendor" },
+  ];
+
+  const found: string[] = [];
+  for (const { path } of depPaths) {
+    const fullPath = `${workdir}/${path}`;
+    if (existsSync(fullPath)) {
+      const stats = statSync(fullPath);
+      if (stats.isDirectory()) {
+        found.push(path);
+      }
+    }
+  }
+
+  const passed = found.length > 0;
+
+  return {
+    name: "dependencies-installed",
+    tier: "blocker",
+    passed,
+    message: passed ? `Dependencies found: ${found.join(", ")}` : "No dependency directories detected",
+  };
+}
+
+/** Check if test command works. Skips silently if command is null/false. */
+export async function checkTestCommand(config: NaxConfig): Promise<Check> {
+  const testCommand = config.execution.testCommand || (config.quality?.commands?.test as string | undefined);
+
+  if (!testCommand || testCommand === null) {
+    return {
+      name: "test-command-works",
+      tier: "blocker",
+      passed: true,
+      message: "Test command not configured (skipped)",
+    };
+  }
+
+  const parts = testCommand.split(" ");
+  const [cmd, ...args] = parts;
+
+  try {
+    const proc = Bun.spawn([cmd, ...args, "--help"], {
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+
+    const exitCode = await proc.exited;
+    const passed = exitCode === 0;
+
+    return {
+      name: "test-command-works",
+      tier: "blocker",
+      passed,
+      message: passed ? "Test command is available" : `Test command failed: ${testCommand}`,
+    };
+  } catch {
+    return {
+      name: "test-command-works",
+      tier: "blocker",
+      passed: false,
+      message: `Test command failed: ${testCommand}`,
+    };
+  }
+}
+
+/** Check if lint command works. Skips silently if command is null/false. */
+export async function checkLintCommand(config: NaxConfig): Promise<Check> {
+  const lintCommand = config.execution.lintCommand;
+
+  if (!lintCommand || lintCommand === null) {
+    return {
+      name: "lint-command-works",
+      tier: "blocker",
+      passed: true,
+      message: "Lint command not configured (skipped)",
+    };
+  }
+
+  const parts = lintCommand.split(" ");
+  const [cmd, ...args] = parts;
+
+  try {
+    const proc = Bun.spawn([cmd, ...args, "--help"], {
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+
+    const exitCode = await proc.exited;
+    const passed = exitCode === 0;
+
+    return {
+      name: "lint-command-works",
+      tier: "blocker",
+      passed,
+      message: passed ? "Lint command is available" : `Lint command failed: ${lintCommand}`,
+    };
+  } catch {
+    return {
+      name: "lint-command-works",
+      tier: "blocker",
+      passed: false,
+      message: `Lint command failed: ${lintCommand}`,
+    };
+  }
+}
+
+/** Check if typecheck command works. Skips silently if command is null/false. */
+export async function checkTypecheckCommand(config: NaxConfig): Promise<Check> {
+  const typecheckCommand = config.execution.typecheckCommand;
+
+  if (!typecheckCommand || typecheckCommand === null) {
+    return {
+      name: "typecheck-command-works",
+      tier: "blocker",
+      passed: true,
+      message: "Typecheck command not configured (skipped)",
+    };
+  }
+
+  const parts = typecheckCommand.split(" ");
+  const [cmd, ...args] = parts;
+
+  try {
+    const proc = Bun.spawn([cmd, ...args, "--help"], {
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+
+    const exitCode = await proc.exited;
+    const passed = exitCode === 0;
+
+    return {
+      name: "typecheck-command-works",
+      tier: "blocker",
+      passed,
+      message: passed
+        ? `Typecheck command is available: ${typecheckCommand}`
+        : `Typecheck command failed: ${typecheckCommand}`,
+    };
+  } catch {
+    return {
+      name: "typecheck-command-works",
+      tier: "blocker",
+      passed: false,
+      message: `Typecheck command failed: ${typecheckCommand}`,
+    };
+  }
+}

package/src/review/orchestrator.ts

@@ -12,17 +12,31 @@ import { spawn } from "bun";
 import type { NaxConfig } from "../config";
 import { getSafeLogger } from "../logger";
 import type { PluginRegistry } from "../plugins";
+import { errorMessage } from "../utils/errors";
 import { runReview } from "./runner";
 import type { ReviewConfig, ReviewResult } from "./types";
 
+/**
+ * Injectable dependencies for getChangedFiles() — allows tests to intercept
+ * spawn calls without requiring the git binary.
+ *
+ * @internal
+ */
+export const _orchestratorDeps = { spawn };
+
 async function getChangedFiles(workdir: string, baseRef?: string): Promise<string[]> {
   try {
     const diffArgs = ["diff", "--name-only"];
     const [stagedProc, unstagedProc, baseProc] = [
-      spawn({ cmd: ["git", ...diffArgs, "--cached"], cwd: workdir, stdout: "pipe", stderr: "pipe" }),
-      spawn({ cmd: ["git", ...diffArgs], cwd: workdir, stdout: "pipe", stderr: "pipe" }),
+      _orchestratorDeps.spawn({ cmd: ["git", ...diffArgs, "--cached"], cwd: workdir, stdout: "pipe", stderr: "pipe" }),
+      _orchestratorDeps.spawn({ cmd: ["git", ...diffArgs], cwd: workdir, stdout: "pipe", stderr: "pipe" }),
       baseRef
-        ? spawn({ cmd: ["git", ...diffArgs, `${baseRef}...HEAD`], cwd: workdir, stdout: "pipe", stderr: "pipe" })
+        ? _orchestratorDeps.spawn({
+            cmd: ["git", ...diffArgs, `${baseRef}...HEAD`],
+            cwd: workdir,
+            stdout: "pipe",
+            stderr: "pipe",
+          })
         : null,
     ];
 
@@ -73,8 +87,7 @@ export class ReviewOrchestrator {
       const reviewers = plugins.getReviewers();
       if (reviewers.length > 0) {
         // Use the story's start ref if available to capture auto-committed changes
-        // biome-ignore lint/suspicious/noExplicitAny: baseRef injected into config for pipeline use
-        const baseRef = (executionConfig as any)?.storyGitRef;
+        const baseRef = executionConfig?.storyGitRef;
         const changedFiles = await getChangedFiles(workdir, baseRef);
         const pluginResults: ReviewResult["pluginReviewers"] = [];
 
@@ -108,7 +121,7 @@ export class ReviewOrchestrator {
               };
             }
           } catch (error) {
-            const errorMsg = error instanceof Error ? error.message : String(error);
+            const errorMsg = errorMessage(error);
             logger?.warn("review", `Plugin reviewer threw error: ${reviewer.name}`, { error: errorMsg });
             pluginResults.push({ name: reviewer.name, passed: false, output: "", error: errorMsg });
             builtIn.pluginReviewers = pluginResults;

package/src/review/runner.ts

@@ -7,8 +7,17 @@
 import { spawn } from "bun";
 import type { ExecutionConfig } from "../config/schema";
 import { getSafeLogger } from "../logger";
+import { errorMessage } from "../utils/errors";
 import type { ReviewCheckName, ReviewCheckResult, ReviewConfig, ReviewResult } from "./types";
 
+/**
+ * Injectable dependencies for runner internals — allows tests to intercept
+ * Bun.file and spawn calls without mock.module().
+ *
+ * @internal
+ */
+export const _reviewRunnerDeps = { spawn, file: Bun.file };
+
 /** Default commands for each check type */
 const DEFAULT_COMMANDS: Record<ReviewCheckName, string> = {
   typecheck: "bun run typecheck",
@@ -21,7 +30,7 @@ const DEFAULT_COMMANDS: Record<ReviewCheckName, string> = {
  */
 async function loadPackageJson(workdir: string): Promise<Record<string, unknown> | null> {
   try {
-    const file = Bun.file(`${workdir}/package.json`);
+    const file = _reviewRunnerDeps.file(`${workdir}/package.json`);
     const content = await file.text();
     return JSON.parse(content);
   } catch {
@@ -80,6 +89,9 @@ async function resolveCommand(
 /** Default timeout for review checks (lint, typecheck). BUG-039. */
 const REVIEW_CHECK_TIMEOUT_MS = 120_000;
 
+/** Grace period between SIGTERM and SIGKILL for review check cleanup. */
+const SIGKILL_GRACE_PERIOD_MS = 5_000;
+
 /**
  * Run a single review check with a hard timeout.
  *
@@ -95,7 +107,7 @@ async function runCheck(check: ReviewCheckName, command: string, workdir: string
     const args = parts.slice(1);
 
     // Spawn the process
-    const proc = spawn({
+    const proc = _reviewRunnerDeps.spawn({
       cmd: [executable, ...args],
       cwd: workdir,
       stdout: "pipe",
@@ -117,7 +129,7 @@ async function runCheck(check: ReviewCheckName, command: string, workdir: string
         } catch {
           /* already exited */
         }
-      }, 5000);
+      }, SIGKILL_GRACE_PERIOD_MS);
     }, REVIEW_CHECK_TIMEOUT_MS);
 
     // Wait for completion
@@ -154,7 +166,7 @@ async function runCheck(check: ReviewCheckName, command: string, workdir: string
       command,
       success: false,
       exitCode: -1,
-      output: error instanceof Error ? error.message : String(error),
+      output: errorMessage(error),
       durationMs: Date.now() - startTime,
     };
   }
@@ -166,7 +178,7 @@ async function runCheck(check: ReviewCheckName, command: string, workdir: string
  */
 async function getUncommittedFilesImpl(workdir: string): Promise<string[]> {
   try {
-    const proc = spawn({
+    const proc = _reviewRunnerDeps.spawn({
       cmd: ["git", "diff", "--name-only", "HEAD"],
       cwd: workdir,
       stdout: "pipe",

package/src/routing/chain.ts

@@ -7,6 +7,7 @@
 
 import { getSafeLogger } from "../logger";
 import type { UserStory } from "../prd/types";
+import { errorMessage } from "../utils/errors";
 import type { RoutingContext, RoutingDecision, RoutingStrategy } from "./strategy";
 
 /**
@@ -51,7 +52,7 @@ export class StrategyChain {
         logger?.error("routing", `Plugin router "${strategy.name}" failed`, {
           strategyName: strategy.name,
           storyId: story.id,
-          error: error instanceof Error ? error.message : String(error),
+          error: errorMessage(error),
         });
         // Continue to next strategy
       }

package/src/routing/loader.ts

@@ -5,6 +5,7 @@
  */
 
 import { resolve } from "node:path";
+import { errorMessage } from "../utils/errors";
 import { validateModulePath } from "../utils/path-security";
 import type { RoutingStrategy } from "./strategy";
 
@@ -56,10 +57,6 @@ export async function loadCustomStrategy(strategyPath: string, workdir: string):
 
     return strategy as RoutingStrategy;
   } catch (error) {
-    throw new Error(
-      `Failed to load custom routing strategy from ${absolutePath}: ${
-        error instanceof Error ? error.message : String(error)
-      }`,
-    );
+    throw new Error(`Failed to load custom routing strategy from ${absolutePath}: ${errorMessage(error)}`);
   }
 }

package/src/tdd/orchestrator.ts

@@ -13,6 +13,7 @@ import { resolveModel } from "../config";
 import { isGreenfieldStory } from "../context/greenfield";
 import { getLogger } from "../logger";
 import type { UserStory } from "../prd";
+import { errorMessage } from "../utils/errors";
 import { captureGitRef } from "../utils/git";
 import { executeWithTimeout } from "../verification";
 import { runFullSuiteGate } from "./rectification-gate";
@@ -379,7 +380,7 @@ export async function runThreeSessionTdd(options: ThreeSessionTddOptions): Promi
     } catch (error) {
       logger.error("tdd", "Failed to rollback git changes after TDD failure", {
         storyId: story.id,
-        error: error instanceof Error ? error.message : String(error),
+        error: errorMessage(error),
       });
     }
   }

package/src/tdd/verdict-reader.ts

@@ -0,0 +1,266 @@
+/**
+ * Verdict file reading, validation, and coercion
+ */
+
+import { unlink } from "node:fs/promises";
+import path from "node:path";
+import { getLogger } from "../logger";
+import type { VerifierVerdict } from "./verdict";
+
+/** File name written by the verifier agent */
+export const VERDICT_FILE = ".nax-verifier-verdict.json";
+
+/**
+ * Validate that a parsed object has the required fields for a VerifierVerdict.
+ * Returns true if the object appears to be a valid verdict.
+ */
+export 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
+  }
+}