@nathapp/nax 0.50.2 → 0.51.0

package/src/cli/config-display.ts

@@ -1,285 +0,0 @@
-/**
- * Config Display
- *
- * Format and display configuration with descriptions and explanations.
- */
-
-import { existsSync } from "node:fs";
-import { join } from "node:path";
-import { findProjectDir, globalConfigPath } from "../config/loader";
-import type { NaxConfig } from "../config/schema";
-import { FIELD_DESCRIPTIONS } from "./config-descriptions";
-import { deepDiffConfigs } from "./config-diff";
-import { loadGlobalConfig, loadProjectConfig } from "./config-get";
-
-export { FIELD_DESCRIPTIONS };
-
-/** Options for config command */
-export interface ConfigCommandOptions {
-  /** Show field explanations */
-  explain?: boolean;
-  /** Show only fields where project overrides global */
-  diff?: boolean;
-}
-
-/**
- * Display effective configuration with optional explanations.
- *
- * @param config - Loaded configuration
- * @param options - Command options
- */
-export async function configCommand(config: NaxConfig, options: ConfigCommandOptions = {}): Promise<void> {
-  const { explain = false, diff = false } = options;
-
-  // Validate mutually exclusive flags
-  if (explain && diff) {
-    console.error("Error: --explain and --diff are mutually exclusive");
-    process.exit(1);
-  }
-
-  // Determine sources
-  const sources = determineConfigSources();
-
-  if (diff) {
-    // Diff mode: show only fields where project overrides global
-    const projectConf = await loadProjectConfig();
-
-    if (!projectConf) {
-      console.log("No project config found — using global defaults");
-      return;
-    }
-
-    const globalConf = await loadGlobalConfig();
-    const diffs = deepDiffConfigs(globalConf, projectConf);
-
-    if (diffs.length === 0) {
-      console.log("No differences between project and global config");
-      return;
-    }
-
-    console.log("# Config Differences (Project overrides Global)");
-    console.log();
-    console.log("─".repeat(80));
-    console.log(`${"Field".padEnd(40)}${"Project Value".padEnd(20)}Global Value`);
-    console.log("─".repeat(80));
-
-    for (const diff of diffs) {
-      const path = diff.path.padEnd(40);
-      const projectVal = formatValueForTable(diff.projectValue);
-      const globalVal = formatValueForTable(diff.globalValue);
-
-      console.log(`${path}${projectVal.padEnd(20)}${globalVal}`);
-
-      // Show description if available
-      const description = FIELD_DESCRIPTIONS[diff.path];
-      if (description) {
-        console.log(`${"".padEnd(40)}↳ ${description}`);
-      }
-    }
-
-    console.log("─".repeat(80));
-  } else if (explain) {
-    console.log("# nax Configuration");
-    console.log("#");
-    console.log("# Resolution order: defaults → global → project → CLI overrides");
-    console.log(`# Global config: ${sources.global ? sources.global : "(not found)"}`);
-    console.log(`# Project config: ${sources.project ? sources.project : "(not found)"}`);
-    console.log();
-
-    // Recursively display config with descriptions
-    displayConfigWithDescriptions(config, [], sources);
-  } else {
-    // Default view: JSON with header showing config sources
-    console.log("// nax Configuration");
-    console.log("// Resolution order: defaults → global → project → CLI overrides");
-    console.log(`// Global config: ${sources.global ? sources.global : "(not found)"}`);
-    console.log(`// Project config: ${sources.project ? sources.project : "(not found)"}`);
-    console.log();
-    console.log(JSON.stringify(config, null, 2));
-  }
-}
-
-/**
- * Determine which config files are present.
- *
- * @returns Paths to global and project config files (null if not found)
- */
-function determineConfigSources(): { global: string | null; project: string | null } {
-  const globalPath = globalConfigPath();
-  const projectDir = findProjectDir();
-  const projectPath = projectDir ? join(projectDir, "config.json") : null;
-
-  return {
-    global: fileExists(globalPath) ? globalPath : null,
-    project: projectPath && fileExists(projectPath) ? projectPath : null,
-  };
-}
-
-/**
- * Check if a file exists.
- *
- * @param path - File path to check
- * @returns True if file exists, false otherwise
- */
-function fileExists(path: string): boolean {
-  return existsSync(path);
-}
-
-/**
- * Display configuration with descriptions and source annotations.
- *
- * @param obj - Configuration object or value
- * @param path - Current path in config tree
- * @param sources - Config source paths
- * @param indent - Current indentation level
- */
-function displayConfigWithDescriptions(
-  obj: unknown,
-  path: string[],
-  sources: { global: string | null; project: string | null },
-  indent = 0,
-): void {
-  const indentStr = "  ".repeat(indent);
-  const pathStr = path.join(".");
-
-  // Handle primitives and arrays
-  if (obj === null || obj === undefined || typeof obj !== "object" || Array.isArray(obj)) {
-    const description = FIELD_DESCRIPTIONS[pathStr];
-    const value = formatValue(obj);
-
-    if (description) {
-      console.log(`${indentStr}# ${description}`);
-    }
-
-    const key = path[path.length - 1] || "";
-    console.log(`${indentStr}${key}: ${value}`);
-    console.log();
-    return;
-  }
-
-  // Handle objects
-  const entries = Object.entries(obj as Record<string, unknown>);
-
-  // Special handling for prompts section: always show overrides documentation
-  const objAsRecord = obj as Record<string, unknown>;
-  const isPromptsSection = path.join(".") === "prompts";
-  if (isPromptsSection && !objAsRecord.overrides) {
-    // Add prompts.overrides documentation even if not in config
-    const description = FIELD_DESCRIPTIONS["prompts.overrides"];
-    if (description) {
-      console.log(`${indentStr}# prompts.overrides: ${description}`);
-    }
-
-    // Show role examples
-    const roles = ["test-writer", "implementer", "verifier", "single-session"];
-    console.log(`${indentStr}overrides:`);
-    for (const role of roles) {
-      const roleDesc = FIELD_DESCRIPTIONS[`prompts.overrides.${role}`];
-      if (roleDesc) {
-        console.log(`${indentStr}  # ${roleDesc}`);
-        // Extract the example path from description
-        const match = roleDesc.match(/e\.g\., "([^"]+)"/);
-        if (match) {
-          console.log(`${indentStr}  # ${role}: "${match[1]}"`);
-        }
-      }
-    }
-    console.log();
-    return;
-  }
-
-  for (let i = 0; i < entries.length; i++) {
-    const [key, value] = entries[i];
-    const currentPath = [...path, key];
-    const currentPathStr = currentPath.join(".");
-    const description = FIELD_DESCRIPTIONS[currentPathStr];
-
-    // Display description comment if available
-    if (description) {
-      // Include path for direct subsections of key configuration sections
-      // (to improve clarity of important configs like multi-agent setup)
-      const pathParts = currentPathStr.split(".");
-      // Only show path for 2-level paths (e.g., "autoMode.enabled", "models.fast")
-      // to keep deeply nested descriptions concise
-      const isDirectSubsection = pathParts.length === 2;
-      const isKeySection = ["prompts", "autoMode", "models", "routing"].includes(pathParts[0]);
-      const shouldIncludePath = isKeySection && isDirectSubsection;
-      const comment = shouldIncludePath ? `${currentPathStr}: ${description}` : description;
-      console.log(`${indentStr}# ${comment}`);
-    }
-
-    // Handle nested objects
-    if (value !== null && typeof value === "object" && !Array.isArray(value)) {
-      console.log(`${indentStr}${key}:`);
-      displayConfigWithDescriptions(value, currentPath, sources, indent + 1);
-    } else {
-      // Display value
-      const formattedValue = formatValue(value);
-      console.log(`${indentStr}${key}: ${formattedValue}`);
-
-      // Add blank line after each top-level section
-      if (indent === 0 && i < entries.length - 1) {
-        console.log();
-      }
-    }
-  }
-}
-
-/**
- * Format a config value for display.
- *
- * @param value - Value to format
- * @returns Formatted string
- */
-function formatValue(value: unknown): string {
-  if (value === null) return "null";
-  if (value === undefined) return "undefined";
-  if (typeof value === "string") return `"${value}"`;
-  if (typeof value === "boolean") return String(value);
-  if (typeof value === "number") return String(value);
-  if (Array.isArray(value)) {
-    if (value.length === 0) return "[]";
-    if (value.length <= 3) {
-      return `[${value.map((v) => formatValue(v)).join(", ")}]`;
-    }
-    return `[${value
-      .slice(0, 3)
-      .map((v) => formatValue(v))
-      .join(", ")}, ... (${value.length} items)]`;
-  }
-  if (typeof value === "object") {
-    return JSON.stringify(value);
-  }
-  return String(value);
-}
-
-/**
- * Format a config value for table display (shorter format).
- *
- * @param value - Value to format
- * @returns Formatted string (max ~18 chars)
- */
-function formatValueForTable(value: unknown): string {
-  if (value === null) return "null";
-  if (value === undefined) return "undefined";
-  if (typeof value === "string") {
-    if (value.length > 15) {
-      return `"${value.slice(0, 12)}..."`;
-    }
-    return `"${value}"`;
-  }
-  if (typeof value === "boolean") return String(value);
-  if (typeof value === "number") return String(value);
-  if (Array.isArray(value)) {
-    if (value.length === 0) return "[]";
-    return `[...${value.length}]`;
-  }
-  if (typeof value === "object") {
-    const str = JSON.stringify(value);
-    if (str.length > 15) {
-      return "{...}";
-    }
-    return str;
-  }
-  return String(value);
-}

package/src/cli/config-get.ts

@@ -1,55 +0,0 @@
-/**
- * Config Loading
- *
- * Load global and project configuration files.
- */
-
-import { existsSync } from "node:fs";
-import { join } from "node:path";
-import { DEFAULT_CONFIG } from "../config/defaults";
-import { findProjectDir, globalConfigPath } from "../config/loader";
-import { deepMergeConfig } from "../config/merger";
-
-/**
- * Load and parse a JSON config file.
- *
- * @param path - Path to config file
- * @returns Parsed config object or null if file doesn't exist
- */
-export async function loadConfigFile(path: string): Promise<Record<string, unknown> | null> {
-  if (!existsSync(path)) return null;
-  try {
-    return await Bun.file(path).json();
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Load global config merged with defaults.
- *
- * @returns Global config object (defaults + global overrides)
- */
-export async function loadGlobalConfig(): Promise<Record<string, unknown>> {
-  const globalPath = globalConfigPath();
-  const globalConf = await loadConfigFile(globalPath);
-
-  if (!globalConf) {
-    return structuredClone(DEFAULT_CONFIG as unknown as Record<string, unknown>);
-  }
-
-  return deepMergeConfig(structuredClone(DEFAULT_CONFIG as unknown as Record<string, unknown>), globalConf);
-}
-
-/**
- * Load project config (raw, without defaults or global).
- *
- * @returns Project config object or null if not found
- */
-export async function loadProjectConfig(): Promise<Record<string, unknown> | null> {
-  const projectDir = findProjectDir();
-  if (!projectDir) return null;
-
-  const projectPath = join(projectDir, "config.json");
-  return await loadConfigFile(projectPath);
-}

package/src/cli/config.ts

@@ -1,14 +0,0 @@
-/**
- * Config Command
- *
- * Re-exports config display and loading utilities.
- */
-
-// Display exports
-export { configCommand, FIELD_DESCRIPTIONS, type ConfigCommandOptions } from "./config-display";
-
-// Loading exports
-export { loadConfigFile, loadGlobalConfig, loadProjectConfig } from "./config-get";
-
-// Diff exports
-export { deepDiffConfigs, deepEqual, type ConfigDiff } from "./config-diff";

package/src/cli/constitution.ts

@@ -1,17 +0,0 @@
-/**
- * Constitution CLI Command
- *
- * Generates agent-specific config files from nax/constitution.md.
- */
-
-/** Constitution generate options */
-export interface ConstitutionGenerateOptions {
-  /** Path to constitution file (default: nax/constitution.md) */
-  constitution?: string;
-  /** Output directory (default: project root) */
-  output?: string;
-  /** Specific agent to generate for (default: all) */
-  agent?: string;
-  /** Dry run mode (don't write files) */
-  dryRun?: boolean;
-}

package/src/cli/diagnose-analysis.ts

@@ -1,159 +0,0 @@
-/**
- * Diagnose Analysis
- *
- * Extracted from diagnose.ts: failure pattern detection, symptom descriptions,
- * fix suggestions, and recommendation generation.
- */
-
-import type { NaxStatusFile } from "../execution/status-file";
-import type { UserStory } from "../prd";
-import type { PRD } from "../prd/types";
-import type { DiagnosisReport, FailurePattern, StoryDiagnosis } from "./diagnose";
-
-/** Detect failure pattern for a story */
-export function detectFailurePattern(story: UserStory, prd: PRD, status: NaxStatusFile | null): FailurePattern {
-  if (
-    story.status === "passed" &&
-    story.priorErrors?.some((err) => err.toLowerCase().includes("greenfield-no-tests"))
-  ) {
-    return "AUTO_RECOVERED";
-  }
-
-  if (story.status !== "failed" && story.status !== "blocked" && story.status !== "paused") {
-    return "UNKNOWN";
-  }
-
-  if (
-    story.failureCategory === "greenfield-no-tests" ||
-    story.priorErrors?.some((err) => err.toLowerCase().includes("greenfield-no-tests"))
-  ) {
-    return "GREENFIELD_TDD";
-  }
-
-  const testFailingCount = story.priorErrors?.filter((err) => err.toLowerCase().includes("tests-failing")).length || 0;
-  if (testFailingCount >= 2) return "TEST_MISMATCH";
-
-  if (
-    story.priorErrors?.some((err) => err.toLowerCase().includes("precheck-failed")) ||
-    (status?.progress.blocked ?? 0) > 0
-  ) {
-    return "ENVIRONMENTAL";
-  }
-
-  if (story.priorErrors?.some((err) => err.toLowerCase().includes("ratelimited"))) return "RATE_LIMITED";
-  if (story.failureCategory === "isolation-violation") return "ISOLATION_VIOLATION";
-  if (status?.run.status === "stalled") return "STALLED";
-  if (story.priorErrors?.some((err) => err.toLowerCase().includes("session-failure"))) return "SESSION_CRASH";
-  if (story.attempts > 3) return "MAX_TIERS_EXHAUSTED";
-
-  return "UNKNOWN";
-}
-
-/** Get symptom description for a pattern */
-export function getPatternSymptom(pattern: FailurePattern): string {
-  const symptoms: Record<FailurePattern, string> = {
-    GREENFIELD_TDD: "Story attempted in greenfield project with no existing tests",
-    TEST_MISMATCH: "Multiple test failures across attempts",
-    ENVIRONMENTAL: "Environment prechecks failed or blockers detected",
-    RATE_LIMITED: "API rate limit exceeded",
-    ISOLATION_VIOLATION: "Story modified files outside its scope",
-    MAX_TIERS_EXHAUSTED: "Story attempted at all configured model tiers without success",
-    SESSION_CRASH: "Agent session crashed without producing commits",
-    STALLED: "All stories blocked or paused -- no forward progress possible",
-    LOCK_STALE: "Lock file present but process is dead",
-    AUTO_RECOVERED: "Greenfield issue detected but S5 auto-recovery succeeded",
-    UNKNOWN: "Unknown failure pattern",
-  };
-  return symptoms[pattern] ?? "Unknown failure pattern";
-}
-
-/** Get fix suggestion for a pattern */
-export function getPatternFixSuggestion(pattern: FailurePattern, _story: UserStory): string {
-  const fixes: Record<FailurePattern, string> = {
-    GREENFIELD_TDD: "Add --greenfield flag or bootstrap with scaffolding tests first",
-    TEST_MISMATCH: "Review acceptance criteria; tests may be too strict or story underspecified",
-    ENVIRONMENTAL: "Fix precheck issues (deps, env, build) before re-running",
-    RATE_LIMITED: "Wait for rate limit to reset or increase tier limits",
-    ISOLATION_VIOLATION: "Narrow story scope or adjust expectedFiles to allow cross-file changes",
-    MAX_TIERS_EXHAUSTED: "Simplify story or split into smaller sub-stories",
-    SESSION_CRASH: "Check agent logs for crash details; may need manual intervention",
-    STALLED: "Resolve blocked stories or skip them to unblock dependencies",
-    LOCK_STALE: "Run: rm nax.lock",
-    AUTO_RECOVERED: "No action needed -- S5 successfully handled greenfield scenario",
-    UNKNOWN: "Review logs and prior errors for clues",
-  };
-  return fixes[pattern] ?? "Review logs and prior errors for clues";
-}
-
-/** Generate recommendations based on diagnosis */
-export function generateRecommendations(report: DiagnosisReport): string[] {
-  const recommendations: string[] = [];
-
-  if (report.lockCheck.lockPresent && report.lockCheck.pidAlive === false) {
-    recommendations.push(`Remove stale lock: ${report.lockCheck.fixCommand}`);
-  }
-
-  const criticalPatterns = report.failureAnalysis.filter((f) =>
-    ["ENVIRONMENTAL", "STALLED", "SESSION_CRASH"].includes(f.pattern),
-  );
-  if (criticalPatterns.length > 0) {
-    recommendations.push(
-      `Fix ${criticalPatterns.length} critical blocker(s): ${criticalPatterns.map((f) => f.storyId).join(", ")}`,
-    );
-  }
-
-  if (report.failureAnalysis.some((f) => f.pattern === "RATE_LIMITED")) {
-    recommendations.push("Wait for rate limits to reset before re-running");
-  }
-
-  if (report.failureAnalysis.some((f) => f.pattern === "GREENFIELD_TDD")) {
-    recommendations.push("Consider adding --greenfield flag or bootstrap tests for greenfield stories");
-  }
-
-  if (report.runSummary.storiesFailed > 0 && recommendations.length === 0) {
-    recommendations.push(`Re-run with: nax run -f ${report.runSummary.feature}`);
-  }
-
-  if (report.runSummary.storiesFailed === 0 && report.runSummary.storiesPending === 0) {
-    recommendations.push("All stories passed -- feature is complete!");
-  }
-
-  return recommendations;
-}
-
-/** Diagnose each story and build story breakdown + failure analysis lists */
-export function diagnoseStories(
-  prd: PRD,
-  status: NaxStatusFile | null,
-): { storyBreakdown: StoryDiagnosis[]; failureAnalysis: StoryDiagnosis[] } {
-  const storyBreakdown: StoryDiagnosis[] = [];
-  const failureAnalysis: StoryDiagnosis[] = [];
-
-  for (const story of prd.userStories) {
-    const pattern = detectFailurePattern(story, prd, status);
-    const diagnosis: StoryDiagnosis = {
-      storyId: story.id,
-      title: story.title,
-      status: story.status,
-      attempts: story.attempts,
-      tier: story.routing?.modelTier,
-      strategy: story.routing?.testStrategy,
-      pattern,
-    };
-
-    storyBreakdown.push(diagnosis);
-
-    if (
-      story.status === "failed" ||
-      story.status === "blocked" ||
-      story.status === "paused" ||
-      pattern === "AUTO_RECOVERED"
-    ) {
-      diagnosis.symptom = getPatternSymptom(pattern);
-      diagnosis.fixSuggestion = getPatternFixSuggestion(pattern, story);
-      failureAnalysis.push(diagnosis);
-    }
-  }
-
-  return { storyBreakdown, failureAnalysis };
-}

package/src/cli/diagnose-formatter.ts

@@ -1,87 +0,0 @@
-/**
- * Diagnose Report Formatter
- *
- * Extracted from diagnose.ts: human-readable output formatting for the diagnosis report.
- */
-
-import chalk from "chalk";
-import type { DiagnosisReport } from "./diagnose";
-
-/** Format diagnosis report as human-readable text */
-export function formatReport(report: DiagnosisReport, verbose: boolean): string {
-  const lines: string[] = [];
-
-  lines.push(chalk.bold(`\nDiagnosis Report: ${report.runSummary.feature}\n`));
-
-  if (!report.dataSources.eventsFound) {
-    lines.push(chalk.yellow("[WARN] events.jsonl not found -- diagnosis limited to PRD + git log\n"));
-  }
-
-  // Run Summary
-  lines.push(chalk.bold("Run Summary\n"));
-  if (report.runSummary.lastRunTime) {
-    lines.push(chalk.dim(`   Last Run:    ${report.runSummary.lastRunTime}`));
-  }
-  lines.push(chalk.dim(`   Status:      ${report.runSummary.status}`));
-  lines.push(chalk.green(`   Passed:      ${report.runSummary.storiesPassed}`));
-  lines.push(chalk.red(`   Failed:      ${report.runSummary.storiesFailed}`));
-  lines.push(chalk.dim(`   Pending:     ${report.runSummary.storiesPending}`));
-  if (report.runSummary.cost !== undefined) {
-    lines.push(chalk.dim(`   Cost:        $${report.runSummary.cost.toFixed(4)}`));
-  }
-  lines.push(chalk.dim(`   Commits:     ${report.runSummary.commitsProduced}`));
-  lines.push("");
-
-  // Story Breakdown (verbose only)
-  if (verbose && report.storyBreakdown.length > 0) {
-    lines.push(chalk.bold("Story Breakdown\n"));
-    for (const story of report.storyBreakdown) {
-      const icon = story.status === "passed" ? "[OK]" : story.status === "failed" ? "[FAIL]" : "[ ]";
-      const pattern = story.pattern !== "UNKNOWN" ? chalk.yellow(` [${story.pattern}]`) : "";
-      lines.push(`   ${icon} ${story.storyId}: ${story.title}${pattern}`);
-      if (verbose && story.tier) {
-        lines.push(chalk.dim(`      Tier: ${story.tier}, Strategy: ${story.strategy}, Attempts: ${story.attempts}`));
-      }
-    }
-    lines.push("");
-  }
-
-  // Failure Analysis
-  if (report.failureAnalysis.length > 0) {
-    lines.push(chalk.bold("Failure Analysis\n"));
-    for (const failure of report.failureAnalysis) {
-      const level = failure.pattern === "AUTO_RECOVERED" ? chalk.green("INFO") : chalk.red("ERROR");
-      lines.push(`   ${level} ${failure.storyId}: ${failure.title}`);
-      lines.push(chalk.dim(`      Pattern:     ${failure.pattern}`));
-      if (failure.symptom) {
-        lines.push(chalk.dim(`      Symptom:     ${failure.symptom}`));
-      }
-      if (failure.fixSuggestion) {
-        lines.push(chalk.yellow(`      Fix:         ${failure.fixSuggestion}`));
-      }
-      lines.push("");
-    }
-  }
-
-  // Lock Check
-  lines.push(chalk.bold("Lock Check\n"));
-  if (!report.lockCheck.lockPresent) {
-    lines.push(chalk.dim("   No lock file present\n"));
-  } else if (report.lockCheck.pidAlive === false) {
-    lines.push(chalk.red(`   [FAIL] Stale lock detected (PID ${report.lockCheck.pid} is dead)`));
-    lines.push(chalk.yellow(`   Fix: ${report.lockCheck.fixCommand}\n`));
-  } else {
-    lines.push(chalk.green(`   [OK] Active lock (PID ${report.lockCheck.pid})\n`));
-  }
-
-  // Recommendations
-  if (report.recommendations.length > 0) {
-    lines.push(chalk.bold("Recommendations\n"));
-    for (let i = 0; i < report.recommendations.length; i++) {
-      lines.push(`   ${i + 1}. ${report.recommendations[i]}`);
-    }
-    lines.push("");
-  }
-
-  return lines.join("\n");
-}