@nathapp/nax 0.18.1

package/src/precheck/checks-blockers.ts

@@ -0,0 +1,391 @@
+/**
+ * Precheck Tier 1 Blockers
+ *
+ * Extracted from checks.ts: individual check implementations for Tier 1 blockers.
+ */
+import { existsSync, statSync } from "node:fs";
+import type { NaxConfig } from "../config";
+import type { PRD } from "../prd/types";
+import type { Check } from "./types";
+
+/** Check if directory is a git repository. Uses: git rev-parse --git-dir */
+export async function checkGitRepoExists(workdir: string): Promise<Check> {
+  // First try git rev-parse command
+  const proc = Bun.spawn(["git", "rev-parse", "--git-dir"], {
+    cwd: workdir,
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+
+  const exitCode = await proc.exited;
+  let passed = exitCode === 0;
+
+  // Fallback: if git command fails, check if .git directory exists
+  // This handles test scenarios where .git exists but isn't fully initialized
+  if (!passed) {
+    const gitDir = `${workdir}/.git`;
+    if (existsSync(gitDir)) {
+      const stats = statSync(gitDir);
+      passed = stats.isDirectory();
+    }
+  }
+
+  return {
+    name: "git-repo-exists",
+    tier: "blocker",
+    passed,
+    message: passed ? "git repository detected" : "not a git repository",
+  };
+}
+
+/** Check if working tree is clean. Uses: git status --porcelain */
+export async function checkWorkingTreeClean(workdir: string): Promise<Check> {
+  const proc = Bun.spawn(["git", "status", "--porcelain"], {
+    cwd: workdir,
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+
+  const output = await new Response(proc.stdout).text();
+  const exitCode = await proc.exited;
+  const passed = exitCode === 0 && output.trim() === "";
+
+  return {
+    name: "working-tree-clean",
+    tier: "blocker",
+    passed,
+    message: passed ? "Working tree is clean" : "Uncommitted changes detected",
+  };
+}
+
+/** Check if nax.lock is older than 2 hours. */
+export async function checkStaleLock(workdir: string): Promise<Check> {
+  const lockPath = `${workdir}/nax.lock`;
+  const exists = existsSync(lockPath);
+
+  if (!exists) {
+    return {
+      name: "no-stale-lock",
+      tier: "blocker",
+      passed: true,
+      message: "No lock file present",
+    };
+  }
+
+  try {
+    const file = Bun.file(lockPath);
+    const content = await file.text();
+    const lockData = JSON.parse(content);
+
+    // Support both timestamp (ms) and startedAt (ISO string) formats
+    let lockTimeMs: number;
+    if (lockData.timestamp) {
+      lockTimeMs = lockData.timestamp;
+    } else if (lockData.startedAt) {
+      lockTimeMs = new Date(lockData.startedAt).getTime();
+    } else {
+      // Fallback to file mtime if no timestamp in JSON
+      const stat = statSync(lockPath);
+      lockTimeMs = stat.mtimeMs;
+    }
+
+    const ageMs = Date.now() - lockTimeMs;
+    const twoHoursMs = 2 * 60 * 60 * 1000;
+    const passed = ageMs < twoHoursMs;
+
+    const ageMinutes = Math.floor(ageMs / 60000);
+    const ageHours = Math.floor(ageMinutes / 60);
+
+    return {
+      name: "no-stale-lock",
+      tier: "blocker",
+      passed,
+      message: passed ? "Lock file is fresh" : "stale lock detected (over 2 hours old)",
+    };
+  } catch (error) {
+    return {
+      name: "no-stale-lock",
+      tier: "blocker",
+      passed: false,
+      message: "Failed to read lock file",
+    };
+  }
+}
+
+/** Validate PRD structure and required fields. Auto-defaults: tags=[], status=pending, storyPoints=1 */
+export async function checkPRDValid(prd: PRD): Promise<Check> {
+  const errors: string[] = [];
+
+  // Validate required PRD fields
+  if (!prd.project || prd.project.trim() === "") {
+    errors.push("Missing project field");
+  }
+  if (!prd.feature || prd.feature.trim() === "") {
+    errors.push("Missing feature field");
+  }
+  if (!prd.branchName || prd.branchName.trim() === "") {
+    errors.push("Missing branchName field");
+  }
+  if (!Array.isArray(prd.userStories)) {
+    errors.push("userStories must be an array");
+  }
+
+  // Validate each story
+  if (Array.isArray(prd.userStories)) {
+    for (const story of prd.userStories) {
+      // Auto-default optional fields in-memory (don't modify the PRD)
+      story.tags = story.tags ?? [];
+      story.status = story.status ?? "pending";
+      story.storyPoints = story.storyPoints ?? 1;
+      story.acceptanceCriteria = story.acceptanceCriteria ?? [];
+
+      // Validate required fields
+      if (!story.id || story.id.trim() === "") {
+        errors.push(`Story missing id: ${JSON.stringify(story).slice(0, 50)}`);
+      }
+      if (!story.title || story.title.trim() === "") {
+        errors.push(`Story ${story.id} missing title`);
+      }
+      if (!story.description || story.description.trim() === "") {
+        errors.push(`Story ${story.id} missing description`);
+      }
+    }
+  }
+
+  const passed = errors.length === 0;
+
+  return {
+    name: "prd-valid",
+    tier: "blocker",
+    passed,
+    message: passed ? "PRD structure is valid" : errors.join("; "),
+  };
+}
+
+/** Check if Claude CLI is available. Uses: claude --version */
+export async function checkClaudeCLI(): Promise<Check> {
+  try {
+    const proc = Bun.spawn(["claude", "--version"], {
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+
+    const exitCode = await proc.exited;
+    const passed = exitCode === 0;
+
+    return {
+      name: "claude-cli-available",
+      tier: "blocker",
+      passed,
+      message: passed ? "Claude CLI is available" : "Claude CLI not found. Install from https://claude.ai/download",
+    };
+  } catch {
+    // Bun.spawn throws ENOENT when the binary is not found in PATH.
+    // Treat this as a failed check rather than an unhandled exception so the
+    // rest of the precheck pipeline can continue and report all issues at once.
+    return {
+      name: "claude-cli-available",
+      tier: "blocker",
+      passed: false,
+      message: "Claude CLI not found in PATH. Install from https://claude.ai/download",
+    };
+  }
+}
+
+/** 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}`;
+    // Check if it exists and is a directory
+    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> {
+  // Try multiple possible locations for testCommand
+  const testCommand = config.execution.testCommand || (config.quality?.commands?.test as string | undefined);
+
+  // Skip if explicitly disabled or not configured
+  if (!testCommand || testCommand === null || testCommand === null) {
+    return {
+      name: "test-command-works",
+      tier: "blocker",
+      passed: true,
+      message: "Test command not configured (skipped)",
+    };
+  }
+
+  // Parse command and args
+  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 (error) {
+    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;
+
+  // Skip if explicitly disabled or not configured
+  if (!lintCommand || lintCommand === null || lintCommand === null) {
+    return {
+      name: "lint-command-works",
+      tier: "blocker",
+      passed: true,
+      message: "Lint command not configured (skipped)",
+    };
+  }
+
+  // Parse command and args
+  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 (error) {
+    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;
+
+  // Skip if explicitly disabled or not configured
+  if (!typecheckCommand || typecheckCommand === null || typecheckCommand === null) {
+    return {
+      name: "typecheck-command-works",
+      tier: "blocker",
+      passed: true,
+      message: "Typecheck command not configured (skipped)",
+    };
+  }
+
+  // Parse command and args
+  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 (error) {
+    return {
+      name: "typecheck-command-works",
+      tier: "blocker",
+      passed: false,
+      message: `Typecheck command failed: ${typecheckCommand}`,
+    };
+  }
+}
+
+/** Check if git user is configured. */
+export async function checkGitUserConfigured(workdir?: string): Promise<Check> {
+  const spawnOptions = {
+    stdout: "pipe" as const,
+    stderr: "pipe" as const,
+    ...(workdir && { cwd: workdir }),
+  };
+
+  const nameProc = Bun.spawn(["git", "config", "user.name"], spawnOptions);
+  const emailProc = Bun.spawn(["git", "config", "user.email"], spawnOptions);
+
+  const nameOutput = await new Response(nameProc.stdout).text();
+  const emailOutput = await new Response(emailProc.stdout).text();
+  const nameExitCode = await nameProc.exited;
+  const emailExitCode = await emailProc.exited;
+
+  const hasName = nameExitCode === 0 && nameOutput.trim() !== "";
+  const hasEmail = emailExitCode === 0 && emailOutput.trim() !== "";
+  const passed = hasName && hasEmail;
+
+  return {
+    name: "git-user-configured",
+    tier: "blocker",
+    passed,
+    message: passed
+      ? "Git user is configured"
+      : !hasName && !hasEmail
+        ? "Git user.name and user.email not configured"
+        : !hasName
+          ? "Git user.name not configured"
+          : "Git user.email not configured",
+  };
+}

package/src/precheck/checks-warnings.ts

@@ -0,0 +1,142 @@
+/**
+ * Precheck Tier 2 Warnings
+ *
+ * Extracted from checks.ts: individual check implementations for Tier 2 warnings.
+ * These checks produce warnings but do not block execution.
+ */
+
+import { existsSync } from "node:fs";
+import type { NaxConfig } from "../config";
+import type { PRD } from "../prd/types";
+import type { Check } from "./types";
+
+/**
+ * Check if CLAUDE.md exists.
+ */
+export async function checkClaudeMdExists(workdir: string): Promise<Check> {
+  const claudeMdPath = `${workdir}/CLAUDE.md`;
+  const passed = existsSync(claudeMdPath);
+
+  return {
+    name: "claude-md-exists",
+    tier: "warning",
+    passed,
+    message: passed ? "CLAUDE.md found" : "CLAUDE.md not found (recommended for project context)",
+  };
+}
+
+/**
+ * Check if disk space is above 1GB.
+ */
+export async function checkDiskSpace(): Promise<Check> {
+  const proc = Bun.spawn(["df", "-k", "."], {
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+
+  const output = await new Response(proc.stdout).text();
+  const exitCode = await proc.exited;
+
+  if (exitCode !== 0) {
+    return {
+      name: "disk-space-sufficient",
+      tier: "warning",
+      passed: false,
+      message: "Unable to check disk space",
+    };
+  }
+
+  // Parse df output (second line, fourth column is available space in KB)
+  const lines = output.trim().split("\n");
+  if (lines.length < 2) {
+    return {
+      name: "disk-space-sufficient",
+      tier: "warning",
+      passed: false,
+      message: "Unable to parse disk space output",
+    };
+  }
+
+  const parts = lines[1].split(/\s+/);
+  const availableKB = Number.parseInt(parts[3], 10);
+  const availableGB = availableKB / 1024 / 1024;
+  const passed = availableGB >= 1;
+
+  return {
+    name: "disk-space-sufficient",
+    tier: "warning",
+    passed,
+    message: passed
+      ? `Disk space: ${availableGB.toFixed(2)}GB available`
+      : `Low disk space: ${availableGB.toFixed(2)}GB available`,
+  };
+}
+
+/**
+ * Check if PRD has pending stories.
+ */
+export async function checkPendingStories(prd: PRD): Promise<Check> {
+  const pendingStories = prd.userStories.filter((s) => s.status === "pending");
+  const passed = pendingStories.length > 0;
+
+  return {
+    name: "has-pending-stories",
+    tier: "warning",
+    passed,
+    message: passed ? `${pendingStories.length} pending stories found` : "no pending stories to execute",
+  };
+}
+
+/**
+ * Check if optional commands are configured.
+ */
+export async function checkOptionalCommands(config: NaxConfig): Promise<Check> {
+  const missing: string[] = [];
+
+  if (!config.execution.lintCommand) {
+    missing.push("lint");
+  }
+  if (!config.execution.typecheckCommand) {
+    missing.push("typecheck");
+  }
+
+  const passed = missing.length === 0;
+
+  return {
+    name: "optional-commands-configured",
+    tier: "warning",
+    passed,
+    message: passed ? "All optional commands configured" : `Optional commands not configured: ${missing.join(", ")}`,
+  };
+}
+
+/**
+ * Check if .gitignore covers nax runtime files.
+ * Patterns: nax.lock, runs/, test/tmp/
+ */
+export async function checkGitignoreCoversNax(workdir: string): Promise<Check> {
+  const gitignorePath = `${workdir}/.gitignore`;
+  const exists = existsSync(gitignorePath);
+
+  if (!exists) {
+    return {
+      name: "gitignore-covers-nax",
+      tier: "warning",
+      passed: false,
+      message: ".gitignore not found",
+    };
+  }
+
+  const file = Bun.file(gitignorePath);
+  const content = await file.text();
+  const patterns = ["nax.lock", "runs/", "test/tmp/"];
+  const missing = patterns.filter((pattern) => !content.includes(pattern));
+  const passed = missing.length === 0;
+
+  return {
+    name: "gitignore-covers-nax",
+    tier: "warning",
+    passed,
+    message: passed ? ".gitignore covers nax runtime files" : `.gitignore missing patterns: ${missing.join(", ")}`,
+  };
+}

package/src/precheck/checks.ts

@@ -0,0 +1,30 @@
+/**
+ * Precheck implementation functions
+ *
+ * Re-export barrel for backward compatibility.
+ * Tier 1 blockers: ./checks-blockers
+ * Tier 2 warnings: ./checks-warnings
+ */
+
+// Tier 1 Blockers
+export {
+  checkGitRepoExists,
+  checkWorkingTreeClean,
+  checkStaleLock,
+  checkPRDValid,
+  checkClaudeCLI,
+  checkDependenciesInstalled,
+  checkTestCommand,
+  checkLintCommand,
+  checkTypecheckCommand,
+  checkGitUserConfigured,
+} from "./checks-blockers";
+
+// Tier 2 Warnings
+export {
+  checkClaudeMdExists,
+  checkDiskSpace,
+  checkPendingStories,
+  checkOptionalCommands,
+  checkGitignoreCoversNax,
+} from "./checks-warnings";