@nathapp/nax 0.18.1

package/src/precheck/index.ts

@@ -0,0 +1,247 @@
+/**
+ * Precheck orchestrator
+ *
+ * Runs all prechecks with formatted output. Stops on first Tier 1 blocker (fail-fast).
+ * Collects all Tier 2 warnings. Formats human-readable output with emoji indicators.
+ * Supports --json flag for machine-readable output.
+ */
+
+import type { NaxConfig } from "../config";
+import type { PRD } from "../prd/types";
+import {
+  checkClaudeCLI,
+  checkClaudeMdExists,
+  checkDependenciesInstalled,
+  checkDiskSpace,
+  checkGitRepoExists,
+  checkGitUserConfigured,
+  checkGitignoreCoversNax,
+  checkLintCommand,
+  checkOptionalCommands,
+  checkPRDValid,
+  checkPendingStories,
+  checkStaleLock,
+  checkTestCommand,
+  checkTypecheckCommand,
+  checkWorkingTreeClean,
+} from "./checks";
+import type { Check, PrecheckResult } from "./types";
+
+/** Formatted output with summary */
+export interface PrecheckOutput {
+  /** Whether all checks passed (no blockers) */
+  passed: boolean;
+  /** Tier 1 blockers (if any) */
+  blockers: Check[];
+  /** Tier 2 warnings (if any) */
+  warnings: Check[];
+  /** Summary counts */
+  summary: {
+    total: number;
+    passed: number;
+    failed: number;
+    warnings: number;
+  };
+  /** PRD feature name (for context) */
+  feature: string;
+}
+
+/** Exit codes for precheck command */
+export const EXIT_CODES = {
+  /** All checks passed (or only warnings) */
+  SUCCESS: 0,
+  /** Tier 1 blocker detected */
+  BLOCKER: 1,
+  /** Invalid PRD structure */
+  INVALID_PRD: 2,
+} as const;
+
+/** Options for precheck execution */
+export interface PrecheckOptions {
+  /** Output format: "human" (default) or "json" */
+  format?: "human" | "json";
+  /** Working directory */
+  workdir: string;
+}
+
+/** Extended result with exit code for CLI usage */
+export interface PrecheckResultWithCode {
+  /** Precheck result */
+  result: PrecheckResult;
+  /** Exit code (0=success, 1=blocker, 2=invalid PRD) */
+  exitCode: number;
+  /** Output for display */
+  output: PrecheckOutput;
+  /** Flagged stories from story size gate (v0.16.0) */
+  flaggedStories?: import("./story-size-gate").FlaggedStory[];
+}
+
+/**
+ * Run all precheck validations.
+ * Returns result, exit code, and formatted output.
+ */
+export async function runPrecheck(
+  config: NaxConfig,
+  prd: PRD,
+  options?: PrecheckOptions,
+): Promise<PrecheckResultWithCode> {
+  const workdir = options?.workdir || process.cwd();
+  const format = options?.format || "human";
+
+  const passed: Check[] = [];
+  const blockers: Check[] = [];
+  const warnings: Check[] = [];
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Tier 1 Blockers - fail-fast on first failure
+  // ─────────────────────────────────────────────────────────────────────────────
+
+  const tier1Checks = [
+    () => checkGitRepoExists(workdir),
+    () => checkWorkingTreeClean(workdir),
+    () => checkStaleLock(workdir),
+    () => checkPRDValid(prd),
+    () => checkClaudeCLI(),
+    () => checkDependenciesInstalled(workdir),
+    () => checkTestCommand(config),
+    () => checkLintCommand(config),
+    () => checkTypecheckCommand(config),
+    () => checkGitUserConfigured(workdir),
+  ];
+
+  for (const checkFn of tier1Checks) {
+    const result = await checkFn();
+
+    if (format === "human") {
+      printCheckResult(result);
+    }
+
+    if (result.passed) {
+      passed.push(result);
+    } else {
+      blockers.push(result);
+      // Fail-fast: stop on first blocker
+      break;
+    }
+  }
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Tier 2 Warnings - run all regardless of failures
+  // ─────────────────────────────────────────────────────────────────────────────
+
+  let flaggedStories: import("./story-size-gate").FlaggedStory[] = [];
+
+  // Only run Tier 2 if no blockers
+  if (blockers.length === 0) {
+    const tier2Checks = [
+      () => checkClaudeMdExists(workdir),
+      () => checkDiskSpace(),
+      () => checkPendingStories(prd),
+      () => checkOptionalCommands(config),
+      () => checkGitignoreCoversNax(workdir),
+    ];
+
+    for (const checkFn of tier2Checks) {
+      const result = await checkFn();
+
+      if (format === "human") {
+        printCheckResult(result);
+      }
+
+      if (result.passed) {
+        passed.push(result);
+      } else {
+        warnings.push(result);
+      }
+    }
+
+    // Story size gate (v0.16.0) — separate from standard checks, returns metadata
+    const { checkStorySizeGate } = await import("./story-size-gate");
+    const sizeGateResult = await checkStorySizeGate(config, prd);
+
+    if (format === "human") {
+      printCheckResult(sizeGateResult.check);
+    }
+
+    if (sizeGateResult.check.passed) {
+      passed.push(sizeGateResult.check);
+    } else {
+      warnings.push(sizeGateResult.check);
+      flaggedStories = sizeGateResult.flaggedStories;
+    }
+  }
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Output formatting
+  // ─────────────────────────────────────────────────────────────────────────────
+
+  const output: PrecheckOutput = {
+    passed: blockers.length === 0,
+    blockers,
+    warnings,
+    summary: {
+      total: passed.length + blockers.length + warnings.length,
+      passed: passed.length,
+      failed: blockers.length,
+      warnings: warnings.length,
+    },
+    feature: prd.feature,
+  };
+
+  // Determine exit code
+  let exitCode: number = EXIT_CODES.SUCCESS;
+  if (blockers.length > 0) {
+    // Check if PRD validation failed specifically
+    const hasPRDError = blockers.some((b) => b.name === "prd-valid");
+    exitCode = hasPRDError ? EXIT_CODES.INVALID_PRD : EXIT_CODES.BLOCKER;
+  }
+
+  if (format === "json") {
+    console.log(JSON.stringify(output, null, 2));
+  } else {
+    printSummary(output);
+  }
+
+  return {
+    result: { blockers, warnings },
+    exitCode,
+    output,
+    flaggedStories,
+  };
+}
+
+/**
+ * Print a single check result with emoji indicator.
+ */
+function printCheckResult(check: Check): void {
+  let emoji = "";
+  if (check.passed) {
+    emoji = "✓";
+  } else if (check.tier === "blocker") {
+    emoji = "✗";
+  } else {
+    emoji = "⚠";
+  }
+
+  console.log(`${emoji} ${check.name}: ${check.message}`);
+}
+
+/**
+ * Print summary line with counts.
+ */
+function printSummary(output: PrecheckOutput): void {
+  console.log("");
+  console.log("─────────────────────────────────────────────────────────────────────────────");
+  console.log(`Feature: ${output.feature}`);
+  console.log(
+    `Checks: ${output.summary.total} total | ${output.summary.passed} passed | ${output.summary.failed} failed | ${output.summary.warnings} warnings`,
+  );
+
+  if (output.blockers.length > 0) {
+    console.log("\n❌ BLOCKED: Cannot proceed due to failed prechecks");
+  } else if (output.warnings.length > 0) {
+    console.log("\n⚠️  WARNINGS: Prechecks passed with warnings");
+  } else {
+    console.log("\n✅ PASSED: All prechecks passed");
+  }
+}

package/src/precheck/story-size-gate.ts

@@ -0,0 +1,144 @@
+/**
+ * Story Size Gate (v0.16.0)
+ *
+ * Detects user stories that are too large (waste tokens, yield poor output).
+ * Uses heuristic signals: AC count, description length, bullet point count.
+ * Returns Tier 2 warning with flaggedStory metadata for interaction prompts.
+ */
+
+import type { NaxConfig } from "../config";
+import type { PRD, UserStory } from "../prd/types";
+import type { Check } from "./types";
+
+/** Flagged story metadata */
+export interface FlaggedStory {
+  storyId: string;
+  signals: {
+    acCount: { value: number; threshold: number; flagged: boolean };
+    descriptionLength: { value: number; threshold: number; flagged: boolean };
+    bulletPoints: { value: number; threshold: number; flagged: boolean };
+  };
+  recommendation: string;
+}
+
+/** Story size gate result with metadata */
+export interface StorySizeGateResult {
+  check: Check;
+  flaggedStories: FlaggedStory[];
+}
+
+/**
+ * Count bullet points in text (lines starting with -, *, •, or digit.)
+ */
+function countBulletPoints(text: string): number {
+  const lines = text.split("\n");
+  const bulletPattern = /^\s*[-*•]|\d+\./;
+  return lines.filter((line) => bulletPattern.test(line)).length;
+}
+
+/**
+ * Analyze a single story for size signals
+ */
+function analyzeStory(story: UserStory, config: NaxConfig): FlaggedStory | null {
+  const thresholds = config.precheck?.storySizeGate ?? {
+    enabled: true,
+    maxAcCount: 6,
+    maxDescriptionLength: 2000,
+    maxBulletPoints: 8,
+  };
+
+  const acCount = story.acceptanceCriteria.length;
+  const descriptionLength = story.description.length;
+  const bulletPoints = countBulletPoints(story.description);
+
+  const acFlagged = acCount > thresholds.maxAcCount;
+  const descFlagged = descriptionLength > thresholds.maxDescriptionLength;
+  const bulletsFlagged = bulletPoints > thresholds.maxBulletPoints;
+
+  // Only flag if at least one signal exceeds threshold
+  if (!acFlagged && !descFlagged && !bulletsFlagged) {
+    return null;
+  }
+
+  const signals = {
+    acCount: { value: acCount, threshold: thresholds.maxAcCount, flagged: acFlagged },
+    descriptionLength: {
+      value: descriptionLength,
+      threshold: thresholds.maxDescriptionLength,
+      flagged: descFlagged,
+    },
+    bulletPoints: { value: bulletPoints, threshold: thresholds.maxBulletPoints, flagged: bulletsFlagged },
+  };
+
+  // Build recommendation message
+  const flaggedSignals = [];
+  if (acFlagged) flaggedSignals.push(`${acCount} AC (max ${thresholds.maxAcCount})`);
+  if (descFlagged) flaggedSignals.push(`${descriptionLength} chars (max ${thresholds.maxDescriptionLength})`);
+  if (bulletsFlagged) flaggedSignals.push(`${bulletPoints} bullets (max ${thresholds.maxBulletPoints})`);
+
+  return {
+    storyId: story.id,
+    signals,
+    recommendation: `Story ${story.id} is too large: ${flaggedSignals.join(", ")}. Consider splitting into smaller stories.`,
+  };
+}
+
+/**
+ * Check story size gate for all pending stories
+ */
+export async function checkStorySizeGate(config: NaxConfig, prd: PRD): Promise<StorySizeGateResult> {
+  const gateConfig = config.precheck?.storySizeGate ?? {
+    enabled: true,
+    maxAcCount: 6,
+    maxDescriptionLength: 2000,
+    maxBulletPoints: 8,
+  };
+
+  // Gate disabled - pass with no flags
+  if (!gateConfig.enabled) {
+    return {
+      check: {
+        name: "story-size-gate",
+        tier: "warning",
+        passed: true,
+        message: "Story size gate disabled",
+      },
+      flaggedStories: [],
+    };
+  }
+
+  const pendingStories = prd.userStories.filter((s) => s.status === "pending");
+  const flaggedStories: FlaggedStory[] = [];
+
+  for (const story of pendingStories) {
+    const flagged = analyzeStory(story, config);
+    if (flagged) {
+      flaggedStories.push(flagged);
+    }
+  }
+
+  // If stories are flagged, return warning (Tier 2, non-blocking)
+  if (flaggedStories.length > 0) {
+    const storyIds = flaggedStories.map((f) => f.storyId).join(", ");
+    return {
+      check: {
+        name: "story-size-gate",
+        tier: "warning",
+        passed: false,
+        message: `${flaggedStories.length} large stories detected: ${storyIds}`,
+      },
+      flaggedStories,
+    };
+  }
+
+  // All stories pass size gate
+  return {
+    check: {
+      name: "story-size-gate",
+      tier: "warning",
+      passed: true,
+      message: `All ${pendingStories.length} pending stories within size limits`,
+    },
+    flaggedStories: [],
+  };
+}

package/src/precheck/types.ts

@@ -0,0 +1,31 @@
+/**
+ * Precheck type definitions
+ *
+ * Types for the precheck system including results, checks, statuses, and tiers.
+ */
+
+/** Check tier classification */
+export type CheckTier = "blocker" | "warning";
+
+/** Check execution status */
+export type CheckStatus = "passed" | "failed" | "skipped";
+
+/** Individual check result */
+export interface Check {
+  /** Check identifier (kebab-case) */
+  name: string;
+  /** Severity tier */
+  tier: CheckTier;
+  /** Whether the check passed */
+  passed: boolean;
+  /** Human-readable message explaining the result */
+  message: string;
+}
+
+/** Complete precheck result */
+export interface PrecheckResult {
+  /** Failed Tier 1 checks (execution blockers) */
+  blockers: Check[];
+  /** Failed Tier 2 checks (non-blocking warnings) */
+  warnings: Check[];
+}

package/src/queue/index.ts

@@ -0,0 +1,2 @@
+export type { QueueItem, QueueItemStatus, QueueStats, QueueCommand, QueueFileResult } from "./types";
+export { QueueManager, parseQueueFile } from "./manager";

package/src/queue/manager.ts

@@ -0,0 +1,254 @@
+/**
+ * Queue Manager
+ *
+ * Manages priority queue for user stories.
+ * Supports dependency-based ordering and multi-agent execution.
+ */
+
+import type { QueueCommand, QueueFileResult, QueueItem, QueueItemStatus, QueueStats } from "./types";
+
+export class QueueManager {
+  private items: QueueItem[] = [];
+
+  /**
+   * Add a story to the queue.
+   * Priority is used for ordering (higher = more urgent).
+   */
+  enqueue(storyId: string, title: string, priority: number): void {
+    const existing = this.items.find((item) => item.storyId === storyId);
+    if (existing) {
+      throw new Error(`Story ${storyId} already in queue`);
+    }
+
+    const item: QueueItem = {
+      storyId,
+      title,
+      priority,
+      status: "pending",
+      attempts: 0,
+      addedAt: new Date(),
+    };
+
+    this.items.push(item);
+    // Sort by priority (descending) — higher priority first
+    this.items.sort((a, b) => b.priority - a.priority);
+  }
+
+  /**
+   * Get the next pending item (highest priority).
+   * Returns null if no pending items.
+   */
+  dequeue(): QueueItem | null {
+    const pending = this.items.find((item) => item.status === "pending");
+    return pending ?? null;
+  }
+
+  /**
+   * Peek at the next pending item without removing it.
+   */
+  peek(): QueueItem | null {
+    return this.dequeue();
+  }
+
+  /**
+   * Mark a story as in-progress and assign it to an agent.
+   */
+  markInProgress(storyId: string, assignedAgent: string): void {
+    const item = this.items.find((i) => i.storyId === storyId);
+    if (!item) {
+      throw new Error(`Story ${storyId} not found in queue`);
+    }
+
+    item.status = "in-progress";
+    item.assignedAgent = assignedAgent;
+    item.startedAt = new Date();
+    item.attempts += 1;
+  }
+
+  /**
+   * Mark a story as completed.
+   */
+  markComplete(storyId: string): void {
+    const item = this.items.find((i) => i.storyId === storyId);
+    if (!item) {
+      throw new Error(`Story ${storyId} not found in queue`);
+    }
+
+    item.status = "completed";
+    item.completedAt = new Date();
+  }
+
+  /**
+   * Mark a story as failed with an error message.
+   */
+  markFailed(storyId: string, error: string): void {
+    const item = this.items.find((i) => i.storyId === storyId);
+    if (!item) {
+      throw new Error(`Story ${storyId} not found in queue`);
+    }
+
+    item.status = "failed";
+    item.error = error;
+    item.completedAt = new Date();
+  }
+
+  /**
+   * Reset a story back to pending (e.g., for retry).
+   */
+  resetToPending(storyId: string): void {
+    const item = this.items.find((i) => i.storyId === storyId);
+    if (!item) {
+      throw new Error(`Story ${storyId} not found in queue`);
+    }
+
+    item.status = "pending";
+    item.assignedAgent = undefined;
+    item.startedAt = undefined;
+    item.completedAt = undefined;
+    item.error = undefined;
+    // Re-sort after status change
+    this.items.sort((a, b) => b.priority - a.priority);
+  }
+
+  /**
+   * Get all items with a specific status.
+   */
+  getByStatus(status: QueueItemStatus): QueueItem[] {
+    return this.items.filter((item) => item.status === status);
+  }
+
+  /**
+   * Get a specific item by story ID.
+   */
+  getItem(storyId: string): QueueItem | null {
+    return this.items.find((i) => i.storyId === storyId) ?? null;
+  }
+
+  /**
+   * Get all items in the queue.
+   */
+  getAllItems(): QueueItem[] {
+    return [...this.items];
+  }
+
+  /**
+   * Get queue statistics.
+   */
+  getStats(): QueueStats {
+    return {
+      total: this.items.length,
+      pending: this.items.filter((i) => i.status === "pending").length,
+      inProgress: this.items.filter((i) => i.status === "in-progress").length,
+      completed: this.items.filter((i) => i.status === "completed").length,
+      failed: this.items.filter((i) => i.status === "failed").length,
+      skipped: this.items.filter((i) => i.status === "skipped").length,
+    };
+  }
+
+  /**
+   * Remove a story from the queue entirely.
+   */
+  remove(storyId: string): void {
+    const index = this.items.findIndex((i) => i.storyId === storyId);
+    if (index === -1) {
+      throw new Error(`Story ${storyId} not found in queue`);
+    }
+    this.items.splice(index, 1);
+  }
+
+  /**
+   * Clear all items from the queue.
+   */
+  clear(): void {
+    this.items = [];
+  }
+
+  /**
+   * Check if the queue is empty.
+   */
+  isEmpty(): boolean {
+    return this.items.length === 0;
+  }
+
+  /**
+   * Check if there are any pending items.
+   */
+  hasPending(): boolean {
+    return this.items.some((i) => i.status === "pending");
+  }
+
+  /**
+   * Mark a story as skipped.
+   */
+  markSkipped(storyId: string): void {
+    const item = this.items.find((i) => i.storyId === storyId);
+    if (!item) {
+      throw new Error(`Story ${storyId} not found in queue`);
+    }
+
+    item.status = "skipped";
+    item.error = "Skipped by user command";
+    item.completedAt = new Date();
+  }
+}
+
+/**
+ * Parse queue file content into commands and guidance.
+ *
+ * Commands:
+ * - PAUSE: Pause execution after current story
+ * - ABORT: Mark all remaining stories as skipped and stop
+ * - SKIP US-XXX: Skip a specific story
+ *
+ * Everything else after "--- PENDING ---" is treated as guidance text.
+ */
+export function parseQueueFile(content: string): QueueFileResult {
+  const commands: QueueCommand[] = [];
+  const guidance: string[] = [];
+
+  const lines = content.split("\n");
+  let inPendingSection = false;
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+
+    // Skip empty lines
+    if (!trimmed) {
+      continue;
+    }
+
+    // Check for pending section marker
+    if (trimmed === "--- PENDING ---") {
+      inPendingSection = true;
+      continue;
+    }
+
+    // Parse commands (case-insensitive)
+    const upper = trimmed.toUpperCase();
+
+    if (upper === "PAUSE") {
+      commands.push({ type: "PAUSE" });
+    } else if (upper === "ABORT") {
+      commands.push({ type: "ABORT" });
+    } else if (upper.startsWith("SKIP ")) {
+      // Extract story ID after "SKIP"
+      const storyId = trimmed.substring(5).trim();
+      if (storyId) {
+        commands.push({ type: "SKIP", storyId });
+      } else {
+        // No story ID, treat as guidance
+        guidance.push(trimmed);
+      }
+    } else if (upper === "SKIP") {
+      // SKIP with no story ID, treat as guidance
+      guidance.push(trimmed);
+    } else {
+      // Not a command, treat as guidance if in pending section
+      if (inPendingSection) {
+        guidance.push(trimmed);
+      }
+    }
+  }
+
+  return { commands, guidance };
+}