@nathapp/nax 0.18.1

package/src/cli/diagnose-analysis.ts

@@ -0,0 +1,159 @@
+/**
+ * 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

@@ -0,0 +1,87 @@
+/**
+ * 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");
+}

package/src/cli/diagnose.ts

@@ -0,0 +1,203 @@
+/**
+ * Diagnose Command
+ *
+ * Reads run artifacts and produces structured diagnosis report.
+ * Pure pattern matching -- no LLM calls, no agents.
+ */
+
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { findProjectDir } from "../config";
+import type { NaxStatusFile } from "../execution/status-file";
+import { getLogger } from "../logger";
+import { loadPRD } from "../prd";
+import { diagnoseStories, generateRecommendations } from "./diagnose-analysis";
+import { formatReport } from "./diagnose-formatter";
+
+export interface DiagnoseOptions {
+  feature?: string;
+  workdir?: string;
+  json?: boolean;
+  verbose?: boolean;
+}
+
+export type FailurePattern =
+  | "GREENFIELD_TDD"
+  | "TEST_MISMATCH"
+  | "ENVIRONMENTAL"
+  | "RATE_LIMITED"
+  | "ISOLATION_VIOLATION"
+  | "MAX_TIERS_EXHAUSTED"
+  | "SESSION_CRASH"
+  | "STALLED"
+  | "LOCK_STALE"
+  | "AUTO_RECOVERED"
+  | "UNKNOWN";
+
+export interface StoryDiagnosis {
+  storyId: string;
+  title: string;
+  status: string;
+  attempts: number;
+  tier?: string;
+  strategy?: string;
+  pattern: FailurePattern;
+  symptom?: string;
+  fixSuggestion?: string;
+}
+
+export interface LockCheck {
+  lockPresent: boolean;
+  pidAlive?: boolean;
+  pid?: number;
+  fixCommand?: string;
+}
+
+export interface DiagnosisReport {
+  runSummary: {
+    feature: string;
+    lastRunTime?: string;
+    status: string;
+    storiesPassed: number;
+    storiesFailed: number;
+    storiesPending: number;
+    cost?: number;
+    commitsProduced: number;
+  };
+  storyBreakdown: StoryDiagnosis[];
+  failureAnalysis: StoryDiagnosis[];
+  lockCheck: LockCheck;
+  recommendations: string[];
+  dataSources: {
+    prdFound: boolean;
+    statusFound: boolean;
+    eventsFound: boolean;
+    gitLogFound: boolean;
+  };
+}
+
+function isProcessAlive(pid: number): boolean {
+  try {
+    const result = Bun.spawnSync(["ps", "-p", String(pid)], { stdout: "ignore", stderr: "ignore" });
+    return result.exitCode === 0;
+  } catch {
+    return false;
+  }
+}
+
+async function loadStatusFile(workdir: string): Promise<NaxStatusFile | null> {
+  const statusPath = join(workdir, ".nax-status.json");
+  if (!existsSync(statusPath)) return null;
+  try {
+    return (await Bun.file(statusPath).json()) as NaxStatusFile;
+  } catch {
+    return null;
+  }
+}
+
+async function countCommitsSince(workdir: string, since?: string): Promise<number> {
+  if (!since) return 0;
+  try {
+    const result = Bun.spawnSync(["git", "log", "--oneline", `--since=${since}`, "--all"], {
+      cwd: workdir,
+      stdout: "pipe",
+      stderr: "ignore",
+    });
+    if (result.exitCode !== 0) return 0;
+    const output = new TextDecoder().decode(result.stdout);
+    return output
+      .trim()
+      .split("\n")
+      .filter((line) => line.length > 0).length;
+  } catch {
+    return 0;
+  }
+}
+
+async function checkLock(workdir: string): Promise<LockCheck> {
+  const lockFile = Bun.file(join(workdir, "nax.lock"));
+  if (!(await lockFile.exists())) return { lockPresent: false };
+  try {
+    const lockData = JSON.parse(await lockFile.text());
+    const pid = lockData.pid;
+    const pidAlive = isProcessAlive(pid);
+    if (!pidAlive) return { lockPresent: true, pidAlive: false, pid, fixCommand: "rm nax.lock" };
+    return { lockPresent: true, pidAlive: true, pid };
+  } catch {
+    return { lockPresent: true };
+  }
+}
+
+/** Run diagnose command */
+export async function diagnoseCommand(options: DiagnoseOptions = {}): Promise<void> {
+  const logger = getLogger();
+  const workdir = options.workdir ?? process.cwd();
+
+  const naxSubdir = findProjectDir(workdir);
+  let projectDir: string | null = naxSubdir ? join(naxSubdir, "..") : null;
+  if (!projectDir && existsSync(join(workdir, "nax"))) {
+    projectDir = workdir;
+  }
+  if (!projectDir) throw new Error("Not in a nax project directory");
+
+  let feature = options.feature;
+  if (!feature) {
+    const status = await loadStatusFile(projectDir);
+    if (status) {
+      feature = status.run.feature;
+    } else {
+      const featuresDir = join(projectDir, "nax", "features");
+      if (!existsSync(featuresDir)) throw new Error("No features found in project");
+      const features = readdirSync(featuresDir, { withFileTypes: true })
+        .filter((e) => e.isDirectory())
+        .map((e) => e.name);
+      if (features.length === 0) throw new Error("No features found");
+      feature = features[0];
+      logger.info("diagnose", "No feature specified, using first found", { feature });
+    }
+  }
+
+  const featureDir = join(projectDir, "nax", "features", feature);
+  const prdPath = join(featureDir, "prd.json");
+  if (!existsSync(prdPath)) throw new Error(`Feature not found: ${feature}`);
+
+  const prd = await loadPRD(prdPath);
+  const status = await loadStatusFile(projectDir);
+  const lockCheck = await checkLock(projectDir);
+  const commitCount = await countCommitsSince(projectDir, status?.run.startedAt);
+
+  const { storyBreakdown, failureAnalysis } = diagnoseStories(prd, status);
+
+  const report: DiagnosisReport = {
+    runSummary: {
+      feature,
+      lastRunTime: status?.run.startedAt,
+      status: status?.run.status ?? "unknown",
+      storiesPassed: prd.userStories.filter((s) => s.status === "passed").length,
+      storiesFailed: prd.userStories.filter((s) => s.status === "failed").length,
+      storiesPending: prd.userStories.filter(
+        (s) => s.status !== "passed" && s.status !== "failed" && s.status !== "skipped",
+      ).length,
+      cost: status?.cost.spent,
+      commitsProduced: commitCount,
+    },
+    storyBreakdown,
+    failureAnalysis,
+    lockCheck,
+    recommendations: [],
+    dataSources: {
+      prdFound: true,
+      statusFound: status !== null,
+      eventsFound: false,
+      gitLogFound: commitCount > 0,
+    },
+  };
+
+  report.recommendations = generateRecommendations(report);
+
+  if (options.json) {
+    console.log(JSON.stringify(report, null, 2));
+  } else {
+    console.log(formatReport(report, options.verbose ?? false));
+  }
+}

package/src/cli/generate.ts

@@ -0,0 +1,127 @@
+/**
+ * `nax generate` CLI Command (v0.16.1)
+ *
+ * Generates agent-specific config files from nax/context.md + auto-injected project metadata.
+ * Replaces `nax constitution generate`.
+ */
+
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import chalk from "chalk";
+import { loadConfig } from "../config/loader";
+import { generateAll, generateFor } from "../context/generator";
+import type { AgentType } from "../context/types";
+
+/** Options for `nax generate` */
+export interface GenerateCommandOptions {
+  /** Path to context file (default: nax/context.md) */
+  context?: string;
+  /** Output directory (default: project root) */
+  output?: string;
+  /** Specific agent to generate for */
+  agent?: string;
+  /** Dry run — preview without writing */
+  dryRun?: boolean;
+  /** Disable auto-injection of project metadata */
+  noAutoInject?: boolean;
+}
+
+const VALID_AGENTS: AgentType[] = ["claude", "opencode", "cursor", "windsurf", "aider"];
+
+/**
+ * `nax generate` command handler.
+ */
+export async function generateCommand(options: GenerateCommandOptions): Promise<void> {
+  const workdir = process.cwd();
+  const contextPath = options.context ? join(workdir, options.context) : join(workdir, "nax/context.md");
+  const outputDir = options.output ? join(workdir, options.output) : workdir;
+  const autoInject = !options.noAutoInject;
+  const dryRun = options.dryRun ?? false;
+
+  // Validate context file
+  if (!existsSync(contextPath)) {
+    console.error(chalk.red(`✗ Context file not found: ${contextPath}`));
+    console.error(chalk.yellow("  Create nax/context.md first, or run `nax init` to scaffold it."));
+    process.exit(1);
+  }
+
+  // Validate agent if specified
+  if (options.agent && !VALID_AGENTS.includes(options.agent as AgentType)) {
+    console.error(chalk.red(`✗ Unknown agent: ${options.agent}`));
+    console.error(chalk.yellow(`  Valid agents: ${VALID_AGENTS.join(", ")}`));
+    process.exit(1);
+  }
+
+  if (dryRun) {
+    console.log(chalk.yellow("⚠ Dry run — no files will be written"));
+  }
+
+  console.log(chalk.blue(`→ Loading context from ${contextPath}`));
+  if (autoInject) {
+    console.log(chalk.dim("  Auto-injecting project metadata..."));
+  }
+
+  // Load config for metadata injection (best-effort, use defaults if not found)
+  let config: Awaited<ReturnType<typeof loadConfig>>;
+  try {
+    config = await loadConfig(workdir);
+  } catch {
+    // Config not required for generate — use empty defaults
+    config = {} as Awaited<ReturnType<typeof loadConfig>>;
+  }
+
+  const genOptions = {
+    contextPath,
+    outputDir,
+    workdir,
+    dryRun,
+    autoInject,
+  };
+
+  try {
+    if (options.agent) {
+      const agent = options.agent as AgentType;
+      console.log(chalk.blue(`→ Generating config for ${agent}...`));
+
+      const result = await generateFor(agent, genOptions, config);
+
+      if (result.error) {
+        console.error(chalk.red(`✗ ${agent}: ${result.error}`));
+        process.exit(1);
+      }
+
+      const suffix = dryRun ? " (dry run)" : "";
+      console.log(chalk.green(`✓ ${agent} → ${result.outputFile} (${result.content.length} bytes${suffix})`));
+    } else {
+      console.log(chalk.blue("→ Generating configs for all agents..."));
+
+      const results = await generateAll(genOptions, config);
+      let errorCount = 0;
+
+      for (const result of results) {
+        if (result.error) {
+          console.error(chalk.red(`✗ ${result.agent}: ${result.error}`));
+          errorCount++;
+        } else {
+          const suffix = dryRun ? " (dry run)" : "";
+          console.log(
+            chalk.green(`✓ ${result.agent} → ${result.outputFile} (${result.content.length} bytes${suffix})`),
+          );
+        }
+      }
+
+      if (errorCount > 0) {
+        console.error(chalk.red(`\n✗ ${errorCount} generation(s) failed`));
+        process.exit(1);
+      }
+    }
+
+    if (!dryRun) {
+      console.log(chalk.green(`\n✓ Agent configs written to ${outputDir}`));
+    }
+  } catch (err) {
+    const error = err instanceof Error ? err.message : String(err);
+    console.error(chalk.red(`✗ Generation failed: ${error}`));
+    process.exit(1);
+  }
+}

package/src/cli/index.ts

@@ -0,0 +1,37 @@
+/**
+ * CLI Utilities
+ */
+
+export { analyzeFeature } from "./analyze";
+export { planCommand } from "./plan";
+export { acceptCommand, type AcceptOptions } from "./accept";
+export {
+  displayCostMetrics,
+  displayLastRunMetrics,
+  displayModelEfficiency,
+  displayFeatureStatus,
+  type FeatureStatusOptions,
+} from "./status";
+export {
+  runsListCommand,
+  runsShowCommand,
+  type RunsListOptions,
+  type RunsShowOptions,
+} from "./runs";
+export {
+  promptsCommand,
+  type PromptsCommandOptions,
+} from "./prompts";
+export { initCommand, type InitOptions } from "./init";
+export { pluginsListCommand } from "./plugins";
+export { diagnoseCommand, type DiagnoseOptions } from "./diagnose";
+export {
+  interactListCommand,
+  interactRespondCommand,
+  interactCancelCommand,
+  type InteractListOptions,
+  type InteractRespondOptions,
+  type InteractCancelOptions,
+} from "./interact";
+export { generateCommand, type GenerateCommandOptions } from "./generate";
+export { configCommand, type ConfigCommandOptions } from "./config";