@nathapp/nax 0.50.3 → 0.51.0

package/src/plugins/loader.ts

@@ -1,352 +0,0 @@
-/**
- * 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 { errorMessage } from "../utils/errors";
-import { validateModulePath } from "../utils/path-security";
-import { createPluginLogger } from "./plugin-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;
-}
-
-/**
- * Extract plugin name from file path.
- * For index files (e.g., /path/to/plugin/index.ts), returns the parent directory name.
- * For single files (e.g., /path/to/plugin.ts), returns the filename without extension.
- *
- * @param pluginPath - Path to plugin file
- * @returns Plugin name
- */
-function extractPluginName(pluginPath: string): string {
-  const basename = path.basename(pluginPath);
-  if (basename === "index.ts" || basename === "index.js" || basename === "index.mjs") {
-    // For index files, use the parent directory name
-    return path.basename(path.dirname(pluginPath));
-  }
-  // For single files, use filename without extension
-  return basename.replace(/\.(ts|js|mjs)$/, "");
-}
-
-/**
- * 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.
- * Plugins can be disabled via config.plugins[].enabled or config.disabledPlugins[].
- *
- * @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
- * @param disabledPlugins - List of plugin names to disable (auto-discovered plugins only)
- * @returns PluginRegistry with all loaded plugins and their sources
- */
-export async function loadPlugins(
-  globalDir: string,
-  projectDir: string,
-  configPlugins: PluginConfigEntry[],
-  projectRoot?: string,
-  disabledPlugins?: string[],
-): Promise<PluginRegistry> {
-  const loadedPlugins: LoadedPlugin[] = [];
-  const effectiveProjectRoot = projectRoot || projectDir;
-  const pluginNames = new Set<string>();
-  const disabledSet = new Set(disabledPlugins ?? []);
-  const logger = getSafeLogger();
-
-  // 1. Load plugins from global directory
-  const globalPlugins = await discoverPlugins(globalDir);
-  for (const plugin of globalPlugins) {
-    const pluginName = extractPluginName(plugin.path);
-    if (disabledSet.has(pluginName)) {
-      logger?.info("plugins", `Skipping disabled plugin: '${pluginName}' (global directory)`);
-      continue;
-    }
-    const validated = await loadAndValidatePlugin(plugin.path, {}, [globalDir]);
-    if (validated) {
-      if (pluginNames.has(validated.name)) {
-        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 pluginName = extractPluginName(plugin.path);
-    if (disabledSet.has(pluginName)) {
-      logger?.info("plugins", `Skipping disabled plugin: '${pluginName}' (project directory)`);
-      continue;
-    }
-    const validated = await loadAndValidatePlugin(plugin.path, {}, [projectDir]);
-    if (validated) {
-      if (pluginNames.has(validated.name)) {
-        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) {
-    // Check if plugin is explicitly disabled in config
-    if (entry.enabled === false) {
-      logger?.info("plugins", `Skipping disabled plugin: '${entry.module}'`);
-      continue;
-    }
-    // Resolve module path relative to effective project root for relative paths
-    const resolvedModule = resolveModulePath(entry.module, effectiveProjectRoot);
-    const validated = await loadAndValidatePlugin(
-      resolvedModule,
-      entry.config ?? {},
-      [globalDir, projectDir, effectiveProjectRoot].filter(Boolean),
-      entry.module,
-    );
-    if (validated) {
-      if (pluginNames.has(validated.name)) {
-        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(
-  initialModulePath: string,
-  config: Record<string, unknown>,
-  allowedRoots: string[] = [],
-  originalPath?: string,
-): Promise<NaxPlugin | null> {
-  let attemptedPath = initialModulePath;
-  try {
-    // SEC-1: Validate module path if it's a file path (not an npm package)
-    let modulePath = initialModulePath;
-    const isFilePath = modulePath.startsWith("/") || modulePath.startsWith("./") || modulePath.startsWith("../");
-
-    if (isFilePath && allowedRoots.length > 0) {
-      const validation = validateModulePath(modulePath, allowedRoots);
-      if (!validation.valid) {
-        const logger = getSafeLogger();
-        logger?.error("plugins", `Security: ${validation.error}`);
-        _pluginErrorSink(`[plugins] Security: ${validation.error}`);
-        return null;
-      }
-      // Use the normalized absolute path from the validator
-      const validatedPath = validation.absolutePath as string;
-      modulePath = validatedPath;
-    }
-
-    // Import the module
-    attemptedPath = modulePath;
-    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 — pass plugin-scoped logger
-    if (validated.setup) {
-      try {
-        const pluginLogger = createPluginLogger(validated.name);
-        await validated.setup(config, pluginLogger);
-      } catch (error) {
-        const logger = getSafeLogger();
-        logger?.error("plugins", `Plugin '${validated.name}' setup failed`, { error });
-        return null;
-      }
-    }
-
-    return validated;
-  } catch (error) {
-    const displayPath = originalPath || initialModulePath;
-    const errorMsg = errorMessage(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: ${attemptedPath}`);
-      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: ${attemptedPath}`);
-      _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/plugin-logger.ts

@@ -1,41 +0,0 @@
-/**
- * Plugin Logger Factory
- *
- * Creates write-only, stage-prefixed loggers for plugins.
- * Each logger auto-tags entries with `plugin:<name>` so plugin
- * output is filterable and cannot impersonate core stages.
- *
- * @module plugins/plugin-logger
- */
-
-import { getSafeLogger } from "../logger";
-import type { PluginLogger } from "./types";
-
-/**
- * Create a PluginLogger scoped to a plugin name.
- *
- * The returned logger delegates to the global nax Logger with
- * `plugin:<pluginName>` as the stage. If the global logger is
- * not initialized (e.g., during tests), calls are silently dropped.
- *
- * @param pluginName - Plugin name used as stage prefix
- * @returns PluginLogger instance
- */
-export function createPluginLogger(pluginName: string): PluginLogger {
-  const stage = `plugin:${pluginName}`;
-
-  return {
-    error(message: string, data?: Record<string, unknown>): void {
-      getSafeLogger()?.error(stage, message, data);
-    },
-    warn(message: string, data?: Record<string, unknown>): void {
-      getSafeLogger()?.warn(stage, message, data);
-    },
-    info(message: string, data?: Record<string, unknown>): void {
-      getSafeLogger()?.info(stage, message, data);
-    },
-    debug(message: string, data?: Record<string, unknown>): void {
-      getSafeLogger()?.debug(stage, message, data);
-    },
-  };
-}

package/src/plugins/registry.ts

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