@nathapp/nax 0.18.1

package/src/pipeline/types.ts

@@ -0,0 +1,167 @@
+/**
+ * Pipeline Framework Types
+ *
+ * Composable stage-based execution pipeline for refactoring the monolithic runner.
+ */
+
+import type { AgentResult } from "../agents/types";
+import type { NaxConfig } from "../config/schema";
+import type { ConstitutionResult } from "../constitution/types";
+import type { BuiltContext } from "../context/types";
+import type { HooksConfig } from "../hooks/types";
+import type { InteractionChain } from "../interaction/chain";
+import type { StoryMetrics } from "../metrics/types";
+import type { PluginRegistry } from "../plugins/registry";
+import type { PRD, UserStory } from "../prd/types";
+import type { ReviewResult } from "../review/types";
+import type { FailureCategory } from "../tdd/types";
+
+/**
+ * Routing result from complexity classification
+ */
+export interface RoutingResult {
+  /** Classified complexity */
+  complexity: "simple" | "medium" | "complex" | "expert";
+  /** Selected model tier */
+  modelTier: "fast" | "balanced" | "powerful";
+  /** Test strategy */
+  testStrategy: "test-after" | "three-session-tdd" | "three-session-tdd-lite";
+  /** Reasoning for the classification */
+  reasoning: string;
+  /** Estimated cost for this story */
+  estimatedCost?: number;
+}
+
+/**
+ * Pipeline context — shared state passed through all stages.
+ *
+ * Stages read from and write to this context. It accumulates data
+ * as the pipeline progresses through each stage.
+ *
+ * @example
+ * ```ts
+ * const ctx: PipelineContext = {
+ *   config: loadedConfig,
+ *   prd: loadedPRD,
+ *   story: currentStory,
+ *   stories: [currentStory],
+ *   routing: { complexity: "simple", modelTier: "fast", ... },
+ *   workdir: "/home/user/project",
+ *   hooks: loadedHooks,
+ * };
+ * ```
+ */
+export interface PipelineContext {
+  /** Ngent configuration */
+  config: NaxConfig;
+  /** Full PRD document */
+  prd: PRD;
+  /** Current story (or batch leader) */
+  story: UserStory;
+  /** Batch of stories (length 1 for single-story execution) */
+  stories: UserStory[];
+  /** Routing result from complexity classification */
+  routing: RoutingResult;
+  /** Working directory (project root) */
+  workdir: string;
+  /** Feature directory (optional, e.g., nax/features/my-feature/) */
+  featureDir?: string;
+  /** Hooks configuration */
+  hooks: HooksConfig;
+  /** Plugin registry (optional, for plugin-provided extensions) */
+  plugins?: PluginRegistry;
+  /** Interaction chain (optional, for human-in-the-loop triggers) */
+  interaction?: InteractionChain;
+  /** Constitution result (set by constitutionStage) */
+  constitution?: ConstitutionResult;
+  /** Context markdown for the agent (set by contextStage) */
+  contextMarkdown?: string;
+  /** Built context with element-level token tracking (set by contextStage) */
+  builtContext?: BuiltContext;
+  /** Final prompt sent to agent (set by promptStage) */
+  prompt?: string;
+  /** Agent execution result (set by executionStage) */
+  agentResult?: AgentResult;
+  /** Review result (set by reviewStage) */
+  reviewResult?: ReviewResult;
+  /** Acceptance test failures (set by acceptanceStage) */
+  acceptanceFailures?: {
+    failedACs: string[];
+    testOutput: string;
+  };
+  /** Story start timestamp (ISO string, set by runner before pipeline) */
+  storyStartTime?: string;
+  /** Collected story metrics (set by completionStage) */
+  storyMetrics?: StoryMetrics[];
+  /** Whether to retry the story in lite mode after a failure */
+  retryAsLite?: boolean;
+  /** Failure category from TDD orchestrator (set by executionStage on TDD failure) */
+  tddFailureCategory?: FailureCategory;
+}
+
+/**
+ * Stage action — determines how the pipeline proceeds after a stage executes.
+ */
+export type StageAction =
+  /** Continue to the next stage */
+  | { action: "continue"; cost?: number }
+  /** Skip this story (mark as skipped, don't run further stages) */
+  | { action: "skip"; reason: string; cost?: number }
+  /** Mark story as failed (don't run further stages) */
+  | { action: "fail"; reason: string; cost?: number }
+  /** Escalate to a higher tier and retry the pipeline */
+  | { action: "escalate"; reason?: string; cost?: number }
+  /** Pause execution (user intervention required via queue command) */
+  | { action: "pause"; reason: string; cost?: number };
+
+/**
+ * Result returned by a pipeline stage after execution.
+ */
+export type StageResult = StageAction;
+
+/**
+ * A single pipeline stage.
+ *
+ * Stages are composable units of work that execute sequentially.
+ * Each stage can read from and modify the pipeline context, then
+ * return an action that determines whether to continue, skip, fail,
+ * escalate, or pause.
+ *
+ * @example
+ * ```ts
+ * const routingStage: PipelineStage = {
+ *   name: "routing",
+ *   enabled: (ctx) => true,
+ *   execute: async (ctx) => {
+ *     const result = await classifyComplexity(ctx.story);
+ *     ctx.routing = result;
+ *     return { action: "continue" };
+ *   },
+ * };
+ * ```
+ */
+export interface PipelineStage {
+  /** Unique stage identifier (e.g., "routing", "execution", "review") */
+  name: string;
+
+  /**
+   * Determines if this stage should run.
+   *
+   * If false, the stage is skipped and the pipeline continues to the next stage.
+   *
+   * @param ctx - Current pipeline context
+   * @returns true if the stage should execute, false to skip
+   */
+  enabled: (ctx: PipelineContext) => boolean;
+
+  /**
+   * Execute the stage logic.
+   *
+   * Can read from and modify the pipeline context, then returns a result
+   * that determines how the pipeline should proceed.
+   *
+   * @param ctx - Current pipeline context
+   * @returns Stage result indicating next action
+   */
+  execute: (ctx: PipelineContext) => Promise<StageResult>;
+}

package/src/plugins/index.ts

@@ -0,0 +1,31 @@
+/**
+ * Plugin System — Public API
+ *
+ * Exports all plugin types, interfaces, and loading utilities.
+ */
+
+export type {
+  NaxPlugin,
+  PluginType,
+  PluginExtensions,
+  PluginConfigEntry,
+  IReviewPlugin,
+  ReviewCheckResult,
+  IContextProvider,
+  ContextProviderResult,
+  IReporter,
+  RunStartEvent,
+  StoryCompleteEvent,
+  RunEndEvent,
+} from "./types";
+
+// Re-export optimizer types from optimizer module (via types.ts)
+export type {
+  IPromptOptimizer,
+  PromptOptimizerInput,
+  PromptOptimizerResult,
+} from "./types";
+
+export { validatePlugin } from "./validator";
+export { loadPlugins } from "./loader";
+export { PluginRegistry } from "./registry";

package/src/plugins/loader.ts

@@ -0,0 +1,287 @@
+/**
+ * Plugin Loader
+ *
+ * Discovers, imports, validates, and initializes plugins from:
+ * 1. Global directory (~/.nax/plugins/)
+ * 2. Project directory (<project>/nax/plugins/)
+ * 3. Config entries (explicit module paths)
+ */
+
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { getSafeLogger as _getSafeLoggerFromModule } from "../logger";
+import { PluginRegistry } from "./registry";
+import type { NaxPlugin, PluginConfigEntry } from "./types";
+import { validatePlugin } from "./validator";
+
+/**
+ * Swappable error sink — defaults to console.error.
+ * Tests can replace this to capture plugin error output.
+ * @internal
+ */
+export let _pluginErrorSink: (...args: unknown[]) => void = (...args) => console.error(...args);
+
+/** @internal — for testing only */
+export function _setPluginErrorSink(fn: (...args: unknown[]) => void): void {
+  _pluginErrorSink = fn;
+}
+
+/** @internal — reset to default */
+export function _resetPluginErrorSink(): void {
+  _pluginErrorSink = (...args) => console.error(...args);
+}
+
+/**
+ * Safely get logger instance, returns null if not initialized.
+ * Delegates to the module's getSafeLogger which correctly returns null for noopLogger.
+ */
+function getSafeLogger() {
+  return _getSafeLoggerFromModule();
+}
+
+/**
+ * Plugin source metadata.
+ */
+export interface PluginSource {
+  type: "global" | "project" | "config";
+  path: string;
+}
+
+/**
+ * Plugin with source information.
+ */
+export interface LoadedPlugin {
+  plugin: NaxPlugin;
+  source: PluginSource;
+}
+
+/**
+ * Load and validate all plugins from global + project + config sources.
+ *
+ * Load order:
+ * 1. Scan ~/.nax/plugins/ (if exists)
+ * 2. Scan <project>/nax/plugins/ (if exists)
+ * 3. Load explicit modules from config.plugins[]
+ *
+ * Each plugin is validated, then setup() is called with its config.
+ *
+ * @param globalDir - Global plugins directory (e.g., ~/.nax/plugins)
+ * @param projectDir - Project plugins directory (e.g., <project>/nax/plugins)
+ * @param configPlugins - Explicit plugin entries from config
+ * @param projectRoot - Project root directory for resolving relative paths in config
+ * @returns PluginRegistry with all loaded plugins and their sources
+ */
+export async function loadPlugins(
+  globalDir: string,
+  projectDir: string,
+  configPlugins: PluginConfigEntry[],
+  projectRoot?: string,
+): Promise<PluginRegistry> {
+  const loadedPlugins: LoadedPlugin[] = [];
+  const pluginNames = new Set<string>();
+
+  // 1. Load plugins from global directory
+  const globalPlugins = await discoverPlugins(globalDir);
+  for (const plugin of globalPlugins) {
+    const validated = await loadAndValidatePlugin(plugin.path, {});
+    if (validated) {
+      if (pluginNames.has(validated.name)) {
+        const logger = getSafeLogger();
+        logger?.warn("plugins", `Plugin name collision: '${validated.name}' (global directory)`);
+      }
+      loadedPlugins.push({
+        plugin: validated,
+        source: { type: "global", path: plugin.path },
+      });
+      pluginNames.add(validated.name);
+    }
+  }
+
+  // 2. Load plugins from project directory
+  const projectPlugins = await discoverPlugins(projectDir);
+  for (const plugin of projectPlugins) {
+    const validated = await loadAndValidatePlugin(plugin.path, {});
+    if (validated) {
+      if (pluginNames.has(validated.name)) {
+        const logger = getSafeLogger();
+        logger?.warn("plugins", `Plugin name collision: '${validated.name}' (project directory overrides global)`);
+      }
+      loadedPlugins.push({
+        plugin: validated,
+        source: { type: "project", path: plugin.path },
+      });
+      pluginNames.add(validated.name);
+    }
+  }
+
+  // 3. Load plugins from config entries
+  for (const entry of configPlugins) {
+    // Resolve module path relative to project root for relative paths
+    const resolvedModule = resolveModulePath(entry.module, projectRoot);
+    const validated = await loadAndValidatePlugin(resolvedModule, entry.config ?? {}, entry.module);
+    if (validated) {
+      if (pluginNames.has(validated.name)) {
+        const logger = getSafeLogger();
+        logger?.warn("plugins", `Plugin name collision: '${validated.name}' (config entry overrides previous)`);
+      }
+      loadedPlugins.push({
+        plugin: validated,
+        source: { type: "config", path: entry.module },
+      });
+      pluginNames.add(validated.name);
+    }
+  }
+
+  return new PluginRegistry(loadedPlugins);
+}
+
+/**
+ * Discover plugin files in a directory.
+ *
+ * Scans for:
+ * - Single-file plugins (*.ts, *.js, *.mjs)
+ * - Directory plugins with index.ts/index.js/index.mjs
+ *
+ * @param dir - Directory to scan
+ * @returns Array of discovered plugin paths
+ */
+async function discoverPlugins(dir: string): Promise<Array<{ path: string }>> {
+  const discovered: Array<{ path: string }> = [];
+
+  try {
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+
+    for (const entry of entries) {
+      const fullPath = path.join(dir, entry.name);
+
+      if (entry.isFile()) {
+        // Single-file plugin
+        if (isPluginFile(entry.name)) {
+          discovered.push({ path: fullPath });
+        }
+      } else if (entry.isDirectory()) {
+        // Directory plugin — check for index file
+        const indexPaths = ["index.ts", "index.js", "index.mjs"];
+        for (const indexFile of indexPaths) {
+          const indexPath = path.join(fullPath, indexFile);
+          try {
+            await fs.access(indexPath);
+            discovered.push({ path: indexPath });
+            break;
+          } catch {
+            // Index file doesn't exist, try next
+          }
+        }
+      }
+    }
+  } catch (error) {
+    // ERR-1 fix: Only catch ENOENT, re-throw other errors
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+      // Directory doesn't exist — not an error, just no plugins
+      return [];
+    }
+    // Re-throw permission errors, disk failures, etc.
+    throw error;
+  }
+
+  return discovered;
+}
+
+/**
+ * Check if a filename is a valid plugin file.
+ *
+ * @param filename - Filename to check
+ * @returns Whether the file could be a plugin
+ */
+function isPluginFile(filename: string): boolean {
+  return /\.(ts|js|mjs)$/.test(filename) && !filename.endsWith(".test.ts") && !filename.endsWith(".spec.ts");
+}
+
+/**
+ * Resolve a module path, handling relative paths, absolute paths, and npm packages.
+ *
+ * @param modulePath - Module path from config (can be relative, absolute, or npm package)
+ * @param projectRoot - Project root directory for resolving relative paths
+ * @returns Resolved absolute path or npm package name
+ */
+function resolveModulePath(modulePath: string, projectRoot?: string): string {
+  // Absolute paths and npm packages (no leading ./ or ../) work as-is
+  if (path.isAbsolute(modulePath) || (!modulePath.startsWith("./") && !modulePath.startsWith("../"))) {
+    return modulePath;
+  }
+
+  // Relative paths need to be resolved relative to project root
+  if (projectRoot) {
+    return path.resolve(projectRoot, modulePath);
+  }
+
+  // Fallback: resolve relative to cwd (shouldn't happen in normal usage)
+  return path.resolve(modulePath);
+}
+
+/**
+ * Load and validate a plugin from a module path.
+ *
+ * @param modulePath - Path to plugin module (should be resolved)
+ * @param config - Plugin-specific config
+ * @param originalPath - Original path from config (for error messages)
+ * @returns Validated plugin or null if invalid
+ */
+async function loadAndValidatePlugin(
+  modulePath: string,
+  config: Record<string, unknown>,
+  originalPath?: string,
+): Promise<NaxPlugin | null> {
+  try {
+    // Import the module
+    const imported = await import(modulePath);
+
+    // Try default export first, then named exports
+    const module = imported.default || imported;
+
+    // Validate plugin shape
+    const validated = validatePlugin(module);
+    if (!validated) {
+      return null;
+    }
+
+    // Call setup() if defined
+    if (validated.setup) {
+      try {
+        await validated.setup(config);
+      } catch (error) {
+        const logger = getSafeLogger();
+        logger?.error("plugins", `Plugin '${validated.name}' setup failed`, { error });
+        return null;
+      }
+    }
+
+    return validated;
+  } catch (error) {
+    const displayPath = originalPath || modulePath;
+    const errorMsg = error instanceof Error ? error.message : String(error);
+    const logger = getSafeLogger();
+
+    // Provide helpful error message with attempted paths
+    if (errorMsg.includes("Cannot find module") || errorMsg.includes("ENOENT")) {
+      const msg = `Failed to load plugin module '${displayPath}'`;
+      logger?.error("plugins", msg);
+      logger?.error("plugins", `Attempted path: ${modulePath}`);
+      logger?.error(
+        "plugins",
+        "Ensure the module exists and the path is correct (relative paths are resolved from project root)",
+      );
+      // Always emit to sink so tests (and headless mode without logger) can capture output
+      _pluginErrorSink(`[plugins] ${msg}`);
+      _pluginErrorSink(`[plugins] Attempted path: ${modulePath}`);
+      _pluginErrorSink(
+        "[plugins] Ensure the module exists and the path is correct (relative paths are resolved from project root)",
+      );
+    } else {
+      logger?.warn("plugins", `Failed to load plugin from '${displayPath}'`, { error: errorMsg });
+      // Always emit to sink
+      _pluginErrorSink(`[plugins] Failed to load plugin from '${displayPath}': ${errorMsg}`);
+    }
+    return null;
+  }
+}

package/src/plugins/registry.ts

@@ -0,0 +1,168 @@
+/**
+ * Plugin Registry
+ *
+ * Central registry for all loaded plugins with typed getters.
+ */
+
+import type { AgentAdapter } from "../agents/types";
+import { getSafeLogger } from "../logger";
+import type { RoutingStrategy } from "../routing/strategy";
+import type { LoadedPlugin, PluginSource } from "./loader";
+import type { IContextProvider, IPromptOptimizer, IReporter, IReviewPlugin, NaxPlugin } from "./types";
+
+/**
+ * Plugin registry with typed getters for each extension type.
+ *
+ * Created once at run start and passed through the pipeline context.
+ * Provides efficient access to plugins by extension type.
+ */
+export class PluginRegistry {
+  /** All loaded plugins (readonly) */
+  readonly plugins: ReadonlyArray<NaxPlugin>;
+
+  /** Plugin source information (maps plugin name to source) */
+  private readonly sources: Map<string, PluginSource>;
+
+  constructor(loadedPlugins: LoadedPlugin[] | NaxPlugin[]) {
+    // Support both LoadedPlugin[] and NaxPlugin[] for backward compatibility
+    if (loadedPlugins.length > 0 && "plugin" in loadedPlugins[0]) {
+      // New format: LoadedPlugin[]
+      const typed = loadedPlugins as LoadedPlugin[];
+      this.plugins = typed.map((lp) => lp.plugin);
+      this.sources = new Map(typed.map((lp) => [lp.plugin.name, lp.source]));
+    } else {
+      // Legacy format: NaxPlugin[]
+      const typed = loadedPlugins as NaxPlugin[];
+      this.plugins = typed;
+      this.sources = new Map();
+    }
+  }
+
+  /**
+   * Get the source information for a plugin.
+   *
+   * @param pluginName - Name of the plugin
+   * @returns Plugin source or undefined if not found
+   */
+  getSource(pluginName: string): PluginSource | undefined {
+    return this.sources.get(pluginName);
+  }
+
+  /**
+   * Get all prompt optimizers.
+   *
+   * @returns Array of optimizer implementations
+   */
+  getOptimizers(): IPromptOptimizer[] {
+    return this.plugins
+      .filter((p) => p.provides.includes("optimizer"))
+      .map((p) => p.extensions.optimizer)
+      .filter((opt): opt is IPromptOptimizer => opt !== undefined);
+  }
+
+  /**
+   * Get all routing strategies.
+   *
+   * Plugin routers are returned in load order and should be inserted
+   * before built-in strategies in the routing chain.
+   *
+   * @returns Array of routing strategy implementations
+   */
+  getRouters(): RoutingStrategy[] {
+    return this.plugins
+      .filter((p) => p.provides.includes("router"))
+      .map((p) => p.extensions.router)
+      .filter((router): router is RoutingStrategy => router !== undefined);
+  }
+
+  /**
+   * Get agent adapter by name.
+   *
+   * If multiple plugins provide the same agent name, the last loaded wins.
+   *
+   * @param name - Agent name to lookup
+   * @returns Agent adapter or undefined if not found
+   */
+  getAgent(name: string): AgentAdapter | undefined {
+    const agents = this.plugins
+      .filter((p) => p.provides.includes("agent"))
+      .map((p) => p.extensions.agent)
+      .filter((agent): agent is AgentAdapter => agent !== undefined);
+
+    // Last loaded wins on name collision
+    for (let i = agents.length - 1; i >= 0; i--) {
+      if (agents[i].name === name) {
+        return agents[i];
+      }
+    }
+
+    return undefined;
+  }
+
+  /**
+   * Get all review plugins.
+   *
+   * Review plugins run after built-in checks (typecheck, lint, test).
+   * All plugin checks are additive.
+   *
+   * @returns Array of review plugin implementations
+   */
+  getReviewers(): IReviewPlugin[] {
+    return this.plugins
+      .filter((p) => p.provides.includes("reviewer"))
+      .map((p) => p.extensions.reviewer)
+      .filter((reviewer): reviewer is IReviewPlugin => reviewer !== undefined);
+  }
+
+  /**
+   * Get all context providers.
+   *
+   * Context providers fetch external data (Jira, Linear, etc.) and
+   * inject it into agent prompts. All providers are additive, subject
+   * to token budget.
+   *
+   * @returns Array of context provider implementations
+   */
+  getContextProviders(): IContextProvider[] {
+    return this.plugins
+      .filter((p) => p.provides.includes("context-provider"))
+      .map((p) => p.extensions.contextProvider)
+      .filter((provider): provider is IContextProvider => provider !== undefined);
+  }
+
+  /**
+   * Get all reporters.
+   *
+   * Reporters receive run lifecycle events for dashboards, CI, etc.
+   * All reporters are additive and fire-and-forget.
+   *
+   * @returns Array of reporter implementations
+   */
+  getReporters(): IReporter[] {
+    return this.plugins
+      .filter((p) => p.provides.includes("reporter"))
+      .map((p) => p.extensions.reporter)
+      .filter((reporter): reporter is IReporter => reporter !== undefined);
+  }
+
+  /**
+   * Teardown all plugins.
+   *
+   * Calls teardown() on each plugin (if defined) in order.
+   * Logs errors but continues teardown for all plugins.
+   *
+   * Called when the nax run ends (success or failure).
+   */
+  async teardownAll(): Promise<void> {
+    const logger = getSafeLogger();
+    for (const plugin of this.plugins) {
+      if (plugin.teardown) {
+        try {
+          await plugin.teardown();
+        } catch (error) {
+          logger?.error("plugins", `Plugin '${plugin.name}' teardown failed`, { error });
+        }
+      }
+    }
+  }
+}