@nathapp/nax 0.18.1

package/src/queue/types.ts

@@ -0,0 +1,54 @@
+/**
+ * Queue Types
+ *
+ * Priority queue for scheduling user stories across agents.
+ * Enables future parallel agent execution.
+ */
+
+/** Queue item status */
+export type QueueItemStatus = "pending" | "in-progress" | "completed" | "failed" | "skipped";
+
+/** Queue item representing a user story to be executed */
+export interface QueueItem {
+  /** Unique story ID */
+  storyId: string;
+  /** Display title */
+  title: string;
+  /** Priority score (higher = more urgent) */
+  priority: number;
+  /** Current status */
+  status: QueueItemStatus;
+  /** Assigned agent (if any) */
+  assignedAgent?: string;
+  /** Number of retry attempts */
+  attempts: number;
+  /** Timestamp when added to queue */
+  addedAt: Date;
+  /** Timestamp when started (if in-progress) */
+  startedAt?: Date;
+  /** Timestamp when completed/failed */
+  completedAt?: Date;
+  /** Error message (if failed) */
+  error?: string;
+}
+
+/** Queue statistics */
+export interface QueueStats {
+  total: number;
+  pending: number;
+  inProgress: number;
+  completed: number;
+  failed: number;
+  skipped: number;
+}
+
+/** Queue command for mid-run control */
+export type QueueCommand = { type: "PAUSE" } | { type: "ABORT" } | { type: "SKIP"; storyId: string };
+
+/** Result of parsing a queue file */
+export interface QueueFileResult {
+  /** Parsed commands from the queue file */
+  commands: QueueCommand[];
+  /** Non-command lines (existing guidance behavior) */
+  guidance: string[];
+}

package/src/review/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Review Module
+ *
+ * Post-implementation quality verification
+ */
+
+export * from "./types";
+export * from "./runner";

package/src/review/runner.ts

@@ -0,0 +1,172 @@
+/**
+ * Review Runner
+ *
+ * Runs configurable quality checks after story implementation
+ */
+
+import { spawn } from "bun";
+import type { ExecutionConfig } from "../config/schema";
+import type { ReviewCheckName, ReviewCheckResult, ReviewConfig, ReviewResult } from "./types";
+
+/** Default commands for each check type */
+const DEFAULT_COMMANDS: Record<ReviewCheckName, string> = {
+  typecheck: "bun run typecheck",
+  lint: "bun run lint",
+  test: "bun test",
+};
+
+/**
+ * Load package.json from workdir
+ */
+async function loadPackageJson(workdir: string): Promise<Record<string, unknown> | null> {
+  try {
+    const file = Bun.file(`${workdir}/package.json`);
+    const content = await file.text();
+    return JSON.parse(content);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Check if package.json has a script
+ */
+function hasScript(packageJson: Record<string, unknown> | null, scriptName: string): boolean {
+  if (!packageJson) return false;
+  const scripts = packageJson.scripts;
+  if (typeof scripts !== "object" || scripts === null) return false;
+  return scriptName in scripts;
+}
+
+/**
+ * Resolve command for a check
+ * Resolution order:
+ * 1. Explicit executionConfig field (lintCommand/typecheckCommand) - null = disabled
+ * 2. package.json has script -> use 'bun run <script>'
+ * 3. Not found -> return null (skip)
+ */
+async function resolveCommand(
+  check: ReviewCheckName,
+  config: ReviewConfig,
+  executionConfig: ExecutionConfig | undefined,
+  workdir: string,
+): Promise<string | null> {
+  // 1. Check explicit config.execution commands (v0.13 story)
+  if (executionConfig) {
+    if (check === "lint" && executionConfig.lintCommand !== undefined) {
+      return executionConfig.lintCommand; // null = disabled
+    }
+    if (check === "typecheck" && executionConfig.typecheckCommand !== undefined) {
+      return executionConfig.typecheckCommand; // null = disabled
+    }
+  }
+
+  // 2. Check config.review.commands (legacy, backwards compat)
+  if (config.commands[check]) {
+    return config.commands[check] ?? null;
+  }
+
+  // 3. Check package.json
+  const packageJson = await loadPackageJson(workdir);
+  if (hasScript(packageJson, check)) {
+    return `bun run ${check}`;
+  }
+
+  // 4. Not found - return null to skip
+  return null;
+}
+
+/**
+ * Run a single review check
+ */
+async function runCheck(check: ReviewCheckName, command: string, workdir: string): Promise<ReviewCheckResult> {
+  const startTime = Date.now();
+
+  try {
+    // Parse command into executable and args
+    const parts = command.split(/\s+/);
+    const executable = parts[0];
+    const args = parts.slice(1);
+
+    // Spawn the process
+    const proc = spawn({
+      cmd: [executable, ...args],
+      cwd: workdir,
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+
+    // Wait for completion
+    const result = await proc.exited;
+
+    // Collect output
+    const stdout = await new Response(proc.stdout).text();
+    const stderr = await new Response(proc.stderr).text();
+    const output = [stdout, stderr].filter(Boolean).join("\n");
+
+    return {
+      check,
+      command,
+      success: result === 0,
+      exitCode: result,
+      output,
+      durationMs: Date.now() - startTime,
+    };
+  } catch (error) {
+    return {
+      check,
+      command,
+      success: false,
+      exitCode: -1,
+      output: error instanceof Error ? error.message : String(error),
+      durationMs: Date.now() - startTime,
+    };
+  }
+}
+
+/**
+ * Run all configured review checks
+ */
+export async function runReview(
+  config: ReviewConfig,
+  workdir: string,
+  executionConfig?: ExecutionConfig,
+): Promise<ReviewResult> {
+  const startTime = Date.now();
+  const checks: ReviewCheckResult[] = [];
+  let firstFailure: string | undefined;
+
+  for (const checkName of config.checks) {
+    // Resolve command using resolution strategy
+    const command = await resolveCommand(checkName, config, executionConfig, workdir);
+
+    // Skip if explicitly disabled or not found
+    if (command === null) {
+      console.warn(`[nax] Skipping ${checkName} check (command not configured or disabled)`);
+      continue;
+    }
+
+    // Run the check
+    const result = await runCheck(checkName, command, workdir);
+    checks.push(result);
+
+    // Track first failure
+    if (!result.success && !firstFailure) {
+      firstFailure = `${checkName} failed (exit code ${result.exitCode})`;
+    }
+
+    // Stop on first failure (fail-fast)
+    if (!result.success) {
+      break;
+    }
+  }
+
+  const allPassed = checks.every((c) => c.success);
+
+  return {
+    success: allPassed,
+    checks,
+    totalDurationMs: Date.now() - startTime,
+    failureReason: firstFailure,
+  };
+}

package/src/review/types.ts

@@ -0,0 +1,66 @@
+/**
+ * Review Phase Types
+ *
+ * Post-implementation quality verification
+ */
+
+/** Review check name */
+export type ReviewCheckName = "typecheck" | "lint" | "test";
+
+/** Review check result */
+export interface ReviewCheckResult {
+  /** Check name */
+  check: ReviewCheckName;
+  /** Pass or fail */
+  success: boolean;
+  /** Command that was run */
+  command: string;
+  /** Exit code */
+  exitCode: number;
+  /** Output from the command */
+  output: string;
+  /** Duration in milliseconds */
+  durationMs: number;
+}
+
+/** Plugin reviewer result */
+export interface PluginReviewerResult {
+  /** Plugin reviewer name */
+  name: string;
+  /** Pass or fail */
+  passed: boolean;
+  /** Output from the reviewer */
+  output: string;
+  /** Exit code (if applicable) */
+  exitCode?: number;
+  /** Error message if reviewer threw an exception */
+  error?: string;
+}
+
+/** Review phase result */
+export interface ReviewResult {
+  /** All checks passed */
+  success: boolean;
+  /** Individual check results */
+  checks: ReviewCheckResult[];
+  /** Total duration */
+  totalDurationMs: number;
+  /** First failure reason (if any) */
+  failureReason?: string;
+  /** Plugin reviewer results (if any) */
+  pluginReviewers?: PluginReviewerResult[];
+}
+
+/** Review configuration */
+export interface ReviewConfig {
+  /** Enable review phase */
+  enabled: boolean;
+  /** List of checks to run */
+  checks: ReviewCheckName[];
+  /** Custom commands per check */
+  commands: {
+    typecheck?: string;
+    lint?: string;
+    test?: string;
+  };
+}

package/src/routing/builder.ts

@@ -0,0 +1,81 @@
+/**
+ * Routing Strategy Chain Builder
+ *
+ * Builds the strategy chain based on configuration.
+ */
+
+import type { NaxConfig } from "../config";
+import type { PluginRegistry } from "../plugins/registry";
+import { StrategyChain } from "./chain";
+import { loadCustomStrategy } from "./loader";
+import { adaptiveStrategy, keywordStrategy, llmStrategy, manualStrategy } from "./strategies";
+import type { RoutingStrategy } from "./strategy";
+
+/**
+ * Build the routing strategy chain based on configuration.
+ *
+ * Chain order (plugin routers first, then config-based, keyword always last):
+ * - plugin routers (from plugin registry, in load order)
+ * - manual (if strategy = "manual")
+ * - custom (if strategy = "custom")
+ * - llm (if strategy = "llm")
+ * - adaptive (if strategy = "adaptive") [v0.5 Phase 3]
+ * - keyword (always last — never returns null)
+ *
+ * @param config - nax configuration
+ * @param workdir - Working directory for resolving custom strategy paths
+ * @param plugins - Optional plugin registry for plugin-provided routers
+ * @returns Strategy chain instance
+ *
+ * @example
+ * ```ts
+ * const chain = await buildStrategyChain(config, "/path/to/project", plugins);
+ * const decision = chain.route(story, context);
+ * ```
+ */
+export async function buildStrategyChain(
+  config: NaxConfig,
+  workdir: string,
+  plugins?: PluginRegistry,
+): Promise<StrategyChain> {
+  const strategies: RoutingStrategy[] = [];
+
+  // Prepend plugin routers before built-in strategies
+  if (plugins) {
+    const pluginRouters = plugins.getRouters();
+    strategies.push(...pluginRouters);
+  }
+
+  // Add strategies based on config
+  switch (config.routing.strategy) {
+    case "manual":
+      strategies.push(manualStrategy);
+      break;
+
+    case "llm":
+      strategies.push(llmStrategy);
+      break;
+
+    case "adaptive":
+      strategies.push(adaptiveStrategy);
+      break;
+
+    case "custom": {
+      if (!config.routing.customStrategyPath) {
+        throw new Error("routing.customStrategyPath is required when strategy is 'custom'");
+      }
+      const customStrategy = await loadCustomStrategy(config.routing.customStrategyPath, workdir);
+      strategies.push(customStrategy);
+      break;
+    }
+
+    case "keyword":
+      // Keyword will be added at the end anyway
+      break;
+  }
+
+  // Always add keyword strategy as final fallback
+  strategies.push(keywordStrategy);
+
+  return new StrategyChain(strategies);
+}

package/src/routing/chain.ts

@@ -0,0 +1,74 @@
+/**
+ * Strategy Chain
+ *
+ * Executes routing strategies in order, falling through on null returns.
+ * First strategy to return a non-null decision wins.
+ */
+
+import { getSafeLogger } from "../logger";
+import type { UserStory } from "../prd/types";
+import type { RoutingContext, RoutingDecision, RoutingStrategy } from "./strategy";
+
+/**
+ * Strategy chain that tries strategies in order until one returns a decision.
+ *
+ * @example
+ * ```ts
+ * const chain = new StrategyChain([customStrategy, adaptiveStrategy, keywordStrategy]);
+ * const decision = chain.route(story, context);
+ * // Tries custom first, then adaptive, then keyword
+ * // Returns first non-null decision
+ * ```
+ */
+export class StrategyChain {
+  constructor(private readonly strategies: RoutingStrategy[]) {}
+
+  /**
+   * Route a story through the strategy chain.
+   *
+   * Tries each strategy in order:
+   * - If strategy returns a decision → use it
+   * - If strategy returns null → try next strategy
+   * - If strategy throws an error → log it and try next strategy
+   * - If all strategies return null → throw error
+   *
+   * @param story - User story to route
+   * @param context - Routing context
+   * @returns Routing decision from first strategy that handles it
+   * @throws Error if no strategy returns a decision
+   */
+  async route(story: UserStory, context: RoutingContext): Promise<RoutingDecision> {
+    const logger = getSafeLogger();
+
+    for (const strategy of this.strategies) {
+      try {
+        const decision = await strategy.route(story, context);
+        if (decision !== null) {
+          return decision;
+        }
+      } catch (error) {
+        // Log the error and continue to next strategy
+        logger?.error("routing", `Plugin router "${strategy.name}" failed`, {
+          strategyName: strategy.name,
+          storyId: story.id,
+          error: error instanceof Error ? error.message : String(error),
+        });
+        // Continue to next strategy
+      }
+    }
+
+    // This should never happen if keyword strategy is last (it never returns null)
+    throw new Error(
+      `No routing strategy returned a decision for story ${story.id}. Ensure at least one fallback strategy (e.g., keyword) is in the chain.`,
+    );
+  }
+
+  /**
+   * Get the list of strategy names in this chain.
+   *
+   * @returns Array of strategy names
+   */
+  getStrategyNames(): string[] {
+    return this.strategies.map((s) => s.name);
+  }
+}

package/src/routing/index.ts

@@ -0,0 +1,16 @@
+// Core types and interfaces
+export type { RoutingDecision } from "./router";
+export type { RoutingStrategy, RoutingContext, AggregateMetrics } from "./strategy";
+
+// Main routing functions
+export { routeStory, routeTask, classifyComplexity, determineTestStrategy, complexityToModelTier } from "./router";
+
+// Strategy chain
+export { StrategyChain } from "./chain";
+export { buildStrategyChain } from "./builder";
+
+// Built-in strategies
+export { keywordStrategy, llmStrategy, manualStrategy } from "./strategies";
+
+// Custom strategy loader
+export { loadCustomStrategy } from "./loader";

package/src/routing/loader.ts

@@ -0,0 +1,58 @@
+/**
+ * Custom Strategy Loader
+ *
+ * Dynamically imports custom routing strategies from user-provided paths.
+ */
+
+import { resolve } from "node:path";
+import type { RoutingStrategy } from "./strategy";
+
+/**
+ * Load a custom routing strategy from a file path.
+ *
+ * The custom strategy file must export a default object that satisfies
+ * the RoutingStrategy interface.
+ *
+ * @param strategyPath - Path to the custom strategy file (relative to project root or absolute)
+ * @param workdir - Working directory (project root)
+ * @returns Loaded routing strategy
+ * @throws Error if the strategy cannot be loaded or is invalid
+ *
+ * @example
+ * ```ts
+ * const strategy = await loadCustomStrategy("./my-router.ts", process.cwd());
+ * const decision = strategy.route(story, context);
+ * ```
+ */
+export async function loadCustomStrategy(strategyPath: string, workdir: string): Promise<RoutingStrategy> {
+  const absolutePath = resolve(workdir, strategyPath);
+
+  try {
+    // Dynamic import (works with both .ts and .js files in Bun)
+    const module = await import(absolutePath);
+
+    // Expect default export
+    const strategy = module.default;
+
+    if (!strategy) {
+      throw new Error(`Custom strategy at ${absolutePath} does not have a default export`);
+    }
+
+    // Validate strategy interface
+    if (typeof strategy.name !== "string") {
+      throw new Error(`Custom strategy at ${absolutePath} is missing 'name' property`);
+    }
+
+    if (typeof strategy.route !== "function") {
+      throw new Error(`Custom strategy at ${absolutePath} is missing 'route' method`);
+    }
+
+    return strategy as RoutingStrategy;
+  } catch (error) {
+    throw new Error(
+      `Failed to load custom routing strategy from ${absolutePath}: ${
+        error instanceof Error ? error.message : String(error)
+      }`,
+    );
+  }
+}