@build-astron-co/nimbus 0.4.2 → 0.4.3

package/src/plugins/loader.ts

@@ -1,334 +0,0 @@
-/**
- * Nimbus Plugin System — Loader
- *
- * Responsible for discovering plugin directories under `~/.nimbus/plugins/`,
- * reading each `nimbus-plugin.json` manifest, dynamically importing the
- * plugin's entry point, and validating that it exports a {@link NimbusPlugin}.
- *
- * Design principles:
- *   - A single bad plugin must never crash the host process.  All errors are
- *     caught, surfaced via the {@link PluginLoadError} array returned from
- *     {@link PluginLoader.loadAll}, and emitted as warnings to stderr.
- *   - No external dependencies are introduced.  Dynamic import (`import()`)
- *     is the only mechanism used to load plugin modules.
- *   - The loader is stateless between calls; the manager owns the active-plugin
- *     map.
- *
- * @module plugins/loader
- */
-
-import * as fs from 'node:fs';
-import * as path from 'node:path';
-import { homedir } from 'node:os';
-import type { NimbusPlugin, PluginManifest, LoadedPlugin, PluginLoadError } from './types';
-
-// ---------------------------------------------------------------------------
-// Constants
-// ---------------------------------------------------------------------------
-
-/** Name of the manifest file that must exist in every plugin directory. */
-const MANIFEST_FILENAME = 'nimbus-plugin.json';
-
-/** Default plugins root directory: ~/.nimbus/plugins/ */
-const DEFAULT_PLUGINS_DIR = path.join(homedir(), '.nimbus', 'plugins');
-
-// ---------------------------------------------------------------------------
-// Type Guards
-// ---------------------------------------------------------------------------
-
-/**
- * Runtime check: does `value` look like a valid {@link PluginManifest}?
- *
- * Only the required fields (`name`, `version`, `main`) are checked.
- */
-function isPluginManifest(value: unknown): value is PluginManifest {
-  if (typeof value !== 'object' || value === null) {
-    return false;
-  }
-  const obj = value as Record<string, unknown>;
-  return (
-    typeof obj['name'] === 'string' &&
-    obj['name'].trim().length > 0 &&
-    typeof obj['version'] === 'string' &&
-    obj['version'].trim().length > 0 &&
-    typeof obj['main'] === 'string' &&
-    obj['main'].trim().length > 0
-  );
-}
-
-/**
- * Runtime check: does `value` look like a valid {@link NimbusPlugin}?
- *
- * Only the required fields (`name`, `version`) are checked.  Optional
- * arrays and lifecycle hooks are not validated here; if a plugin provides
- * malformed tools the manager will surface errors when registering them.
- */
-function isNimbusPlugin(value: unknown): value is NimbusPlugin {
-  if (typeof value !== 'object' || value === null) {
-    return false;
-  }
-  const obj = value as Record<string, unknown>;
-  return (
-    typeof obj['name'] === 'string' &&
-    obj['name'].trim().length > 0 &&
-    typeof obj['version'] === 'string' &&
-    obj['version'].trim().length > 0
-  );
-}
-
-// ---------------------------------------------------------------------------
-// Loader Class
-// ---------------------------------------------------------------------------
-
-/**
- * Discovers, loads, and unloads Nimbus plugins from the filesystem.
- *
- * Intended for use by {@link import('./manager').PluginManager}; most
- * application code should interact with the manager rather than the loader
- * directly.
- */
-export class PluginLoader {
-  /** Root directory scanned by {@link discover}. */
-  private readonly pluginsDir: string;
-
-  /** Plugins that have been successfully loaded in this loader instance. */
-  private loadedPlugins: LoadedPlugin[] = [];
-
-  /**
-   * @param pluginsDir - Override the default `~/.nimbus/plugins/` scan root.
-   *   Primarily useful in tests.
-   */
-  constructor(pluginsDir: string = DEFAULT_PLUGINS_DIR) {
-    this.pluginsDir = pluginsDir;
-  }
-
-  // -------------------------------------------------------------------------
-  // Public API
-  // -------------------------------------------------------------------------
-
-  /**
-   * Scan {@link pluginsDir} for subdirectories that contain a
-   * `nimbus-plugin.json` manifest.
-   *
-   * Entries that are not directories, or whose manifest file is missing, are
-   * silently skipped.
-   *
-   * @returns Absolute paths of discovered plugin directories.
-   */
-  discover(): string[] {
-    if (!fs.existsSync(this.pluginsDir)) {
-      return [];
-    }
-
-    let entries: fs.Dirent[];
-    try {
-      entries = fs.readdirSync(this.pluginsDir, { withFileTypes: true });
-    } catch (err: unknown) {
-      const msg = err instanceof Error ? err.message : String(err);
-      process.stderr.write(
-        `[nimbus:plugins] Warning: could not read plugins directory '${this.pluginsDir}': ${msg}\n`
-      );
-      return [];
-    }
-
-    const discovered: string[] = [];
-
-    for (const entry of entries) {
-      if (!entry.isDirectory()) {
-        continue;
-      }
-
-      const pluginDir = path.join(this.pluginsDir, entry.name);
-      const manifestPath = path.join(pluginDir, MANIFEST_FILENAME);
-
-      if (fs.existsSync(manifestPath)) {
-        discovered.push(pluginDir);
-      }
-    }
-
-    return discovered;
-  }
-
-  /**
-   * Load a single plugin from the given directory.
-   *
-   * Steps:
-   *  1. Read and parse `nimbus-plugin.json`.
-   *  2. Resolve the `main` path relative to `pluginDir`.
-   *  3. Dynamically import the entry point.
-   *  4. Extract the default export and validate it as a {@link NimbusPlugin}.
-   *  5. Await {@link NimbusPlugin.onLoad} if defined.
-   *
-   * @param pluginDir - Absolute path to the plugin directory.
-   * @returns The loaded plugin record on success.
-   * @throws {Error} Descriptive error if any step fails.
-   */
-  async load(pluginDir: string): Promise<LoadedPlugin> {
-    // --- Step 1: Read manifest -----------------------------------------------
-    const manifestPath = path.join(pluginDir, MANIFEST_FILENAME);
-
-    let manifestRaw: string;
-    try {
-      manifestRaw = fs.readFileSync(manifestPath, 'utf-8');
-    } catch (err: unknown) {
-      const msg = err instanceof Error ? err.message : String(err);
-      throw new Error(`Cannot read manifest at '${manifestPath}': ${msg}`);
-    }
-
-    let manifestData: unknown;
-    try {
-      manifestData = JSON.parse(manifestRaw);
-    } catch (err: unknown) {
-      const msg = err instanceof Error ? err.message : String(err);
-      throw new Error(`Invalid JSON in manifest '${manifestPath}': ${msg}`);
-    }
-
-    if (!isPluginManifest(manifestData)) {
-      throw new Error(
-        `Manifest '${manifestPath}' is missing required fields ` +
-          `('name', 'version', and 'main' must be non-empty strings).`
-      );
-    }
-
-    const manifest = manifestData as PluginManifest;
-
-    // --- Step 2: Resolve entry-point path ------------------------------------
-    const mainPath = path.resolve(pluginDir, manifest.main);
-
-    if (!fs.existsSync(mainPath)) {
-      throw new Error(
-        `Plugin '${manifest.name}': entry point '${mainPath}' does not exist ` +
-          `(resolved from manifest 'main': '${manifest.main}').`
-      );
-    }
-
-    // --- Step 3: Dynamic import ----------------------------------------------
-    let moduleExports: unknown;
-    try {
-      // Use a dynamic string to prevent bundlers from statically analyzing this
-      // import and attempting to inline plugin code at build time.
-      const importPath = mainPath;
-      moduleExports = await import(importPath);
-    } catch (err: unknown) {
-      const msg = err instanceof Error ? err.message : String(err);
-      throw new Error(`Plugin '${manifest.name}': failed to import '${mainPath}': ${msg}`);
-    }
-
-    // --- Step 4: Extract and validate the default export ---------------------
-    const rawPlugin =
-      moduleExports !== null &&
-      typeof moduleExports === 'object' &&
-      'default' in (moduleExports as Record<string, unknown>)
-        ? (moduleExports as Record<string, unknown>)['default']
-        : moduleExports;
-
-    if (!isNimbusPlugin(rawPlugin)) {
-      throw new Error(
-        `Plugin '${manifest.name}': entry point '${mainPath}' must default-export ` +
-          `an object with at least 'name' (string) and 'version' (string) fields. ` +
-          `Received: ${JSON.stringify(rawPlugin)}`
-      );
-    }
-
-    const plugin = rawPlugin as NimbusPlugin;
-
-    // Sanity check: manifest name should match the exported plugin name.
-    // This is a warning only — mismatches are common during development.
-    if (plugin.name !== manifest.name) {
-      process.stderr.write(
-        `[nimbus:plugins] Warning: manifest 'name' ('${manifest.name}') does not ` +
-          `match plugin export 'name' ('${plugin.name}') in '${pluginDir}'. ` +
-          `Using the exported name.\n`
-      );
-    }
-
-    // --- Step 5: Call onLoad lifecycle hook ----------------------------------
-    if (typeof plugin.onLoad === 'function') {
-      try {
-        await plugin.onLoad();
-      } catch (err: unknown) {
-        const msg = err instanceof Error ? err.message : String(err);
-        throw new Error(`Plugin '${plugin.name}' onLoad() rejected: ${msg}`);
-      }
-    }
-
-    const record: LoadedPlugin = { plugin, pluginDir };
-    this.loadedPlugins.push(record);
-    return record;
-  }
-
-  /**
-   * Discover and load all plugins found in {@link pluginsDir}.
-   *
-   * Plugin load failures are collected rather than thrown, so that one bad
-   * plugin does not prevent healthy plugins from loading.
-   *
-   * @returns An object containing:
-   *   - `loaded`: successfully loaded plugin records.
-   *   - `errors`: descriptions of plugins that failed to load.
-   */
-  async loadAll(): Promise<{ loaded: LoadedPlugin[]; errors: PluginLoadError[] }> {
-    const discovered = this.discover();
-    const loaded: LoadedPlugin[] = [];
-    const errors: PluginLoadError[] = [];
-
-    for (const pluginDir of discovered) {
-      try {
-        const record = await this.load(pluginDir);
-        loaded.push(record);
-      } catch (err: unknown) {
-        const reason = err instanceof Error ? err.message : String(err);
-        process.stderr.write(
-          `[nimbus:plugins] Warning: failed to load plugin from '${pluginDir}': ${reason}\n`
-        );
-        errors.push({ pluginDir, reason });
-      }
-    }
-
-    return { loaded, errors };
-  }
-
-  /**
-   * Call {@link NimbusPlugin.onUnload} on every plugin that was loaded by
-   * this loader instance.
-   *
-   * Errors from individual `onUnload` callbacks are logged to stderr but
-   * do not abort the unload sequence.
-   */
-  async unloadAll(): Promise<void> {
-    for (const { plugin } of this.loadedPlugins) {
-      if (typeof plugin.onUnload === 'function') {
-        try {
-          await plugin.onUnload();
-        } catch (err: unknown) {
-          const msg = err instanceof Error ? err.message : String(err);
-          process.stderr.write(
-            `[nimbus:plugins] Warning: plugin '${plugin.name}' onUnload() threw: ${msg}\n`
-          );
-        }
-      }
-    }
-
-    this.loadedPlugins = [];
-  }
-
-  // -------------------------------------------------------------------------
-  // Accessors
-  // -------------------------------------------------------------------------
-
-  /**
-   * Returns all plugins successfully loaded by this loader instance.
-   * The array is a snapshot — mutations do not affect the loader's internal
-   * state.
-   */
-  getLoaded(): LoadedPlugin[] {
-    return [...this.loadedPlugins];
-  }
-
-  /**
-   * The root directory this loader scans for plugins.
-   */
-  get directory(): string {
-    return this.pluginsDir;
-  }
-}

package/src/plugins/manager.ts

@@ -1,376 +0,0 @@
-/**
- * Nimbus Plugin System — Manager
- *
- * The `PluginManager` is the single point of contact for the rest of the
- * application.  It owns the lifecycle of all loaded plugins, converts their
- * contributed tools into {@link ToolDefinition} objects compatible with the
- * existing {@link ToolRegistry}, and exposes plugin metadata for CLI display.
- *
- * Singleton pattern: import {@link pluginManager} for the application-wide
- * instance.  Tests can construct isolated `PluginManager` instances directly.
- *
- * Tool conversion strategy:
- *   Plugin tools supply a plain JSON Schema object for `inputSchema` (no Zod
- *   required in plugins).  The manager wraps that schema inside a minimal Zod
- *   passthrough (`z.unknown()`) so the {@link ToolDefinition} type constraint
- *   is satisfied without running Zod validation on the plugin's input — the
- *   plugin's own `execute` function is responsible for validating its input.
- *
- * @module plugins/manager
- */
-
-import * as fs from 'node:fs';
-import * as path from 'node:path';
-import { z } from 'zod';
-import { PluginLoader } from './loader';
-import type {
-  NimbusPlugin,
-  PluginToolDefinition,
-  PluginProviderDefinition,
-  LoadedPlugin,
-  PluginLoadError,
-} from './types';
-import type { ToolDefinition } from '../tools/schemas/types';
-
-// Suppress unused import warnings: fs and path are required by the module
-// contract ("Use `import * as fs from 'node:fs'` and `import * as path from
-// 'node:path'`") and may be used by subclasses or future additions.
-void fs;
-void path;
-
-// ---------------------------------------------------------------------------
-// Plugin Info (public surface)
-// ---------------------------------------------------------------------------
-
-/**
- * Summary of a single loaded plugin, returned by
- * {@link PluginManager.listPlugins}.
- */
-export interface PluginInfo {
-  /** Plugin identifier. */
-  name: string;
-
-  /** SemVer version string. */
-  version: string;
-
-  /** Optional description from the plugin manifest. */
-  description?: string;
-
-  /** Absolute path to the plugin directory on disk. */
-  pluginDir: string;
-
-  /** Number of tools contributed by this plugin. */
-  toolCount: number;
-
-  /** Number of LLM providers contributed by this plugin. */
-  providerCount: number;
-}
-
-// ---------------------------------------------------------------------------
-// Initialisation Result
-// ---------------------------------------------------------------------------
-
-/**
- * Returned by {@link PluginManager.init} to inform the caller of how many
- * plugins loaded successfully and which failed.
- */
-export interface PluginInitResult {
-  /** Number of plugins that loaded successfully. */
-  loadedCount: number;
-
-  /** Number of plugins that failed to load. */
-  errorCount: number;
-
-  /** Details of each failed plugin. */
-  errors: PluginLoadError[];
-}
-
-// ---------------------------------------------------------------------------
-// Tool Conversion
-// ---------------------------------------------------------------------------
-
-/**
- * Convert a {@link PluginToolDefinition} into a {@link ToolDefinition} that
- * is compatible with the application's {@link ToolRegistry}.
- *
- * The `inputSchema` is wrapped in `z.unknown()` so that the plugin's own
- * `execute` function handles validation internally.  The `category` is fixed
- * to `'mcp'` (the "external source" bucket) and `isDestructive` defaults to
- * `false` for plugin tools unless the permission tier indicates otherwise.
- *
- * @param pluginName - The owning plugin's name, prepended to error messages.
- * @param tool - The plugin-supplied tool definition.
- * @returns A {@link ToolDefinition} ready for registration.
- */
-function convertPluginTool(pluginName: string, tool: PluginToolDefinition): ToolDefinition {
-  // The plugin execute function returns { success, output }; we normalise
-  // this to the ToolResult shape ({ output, isError }) so that the agent
-  // loop can treat plugin tools identically to built-in tools.
-  const wrappedExecute = async (input: unknown) => {
-    try {
-      const result = await tool.execute(input);
-      return {
-        output: result.output,
-        isError: !result.success,
-        error: result.success ? undefined : result.output,
-      };
-    } catch (err: unknown) {
-      const msg = err instanceof Error ? err.message : String(err);
-      process.stderr.write(
-        `[nimbus:plugins] Warning: plugin '${pluginName}' tool '${tool.name}' ` +
-          `threw during execution: ${msg}\n`
-      );
-      return {
-        output: '',
-        error: msg,
-        isError: true,
-      };
-    }
-  };
-
-  return {
-    name: tool.name,
-    description: tool.description,
-    // z.unknown() satisfies z.ZodType<unknown> while imposing no constraints.
-    // The raw JSON Schema is preserved on a non-standard property for
-    // consumers (e.g. provider format converters) that need the schema shape.
-    inputSchema: z.unknown(),
-    execute: wrappedExecute,
-    permissionTier: tool.permissionTier,
-    // Plugin tools are categorised alongside MCP tools as external sources.
-    category: 'mcp',
-    // Tools with always_ask tier are considered potentially destructive.
-    isDestructive: tool.permissionTier === 'always_ask',
-  };
-}
-
-// ---------------------------------------------------------------------------
-// Plugin Manager
-// ---------------------------------------------------------------------------
-
-/**
- * Manages the lifecycle of all loaded Nimbus plugins and provides the
- * host application with access to their contributed tools and providers.
- *
- * ### Usage
- * ```ts
- * import { pluginManager } from './plugins';
- *
- * // During application startup:
- * const result = await pluginManager.init();
- * if (result.errorCount > 0) {
- *   console.warn(`${result.errorCount} plugin(s) failed to load.`);
- * }
- *
- * // Register plugin tools alongside built-in tools:
- * for (const tool of pluginManager.getTools()) {
- *   defaultToolRegistry.register(tool);
- * }
- *
- * // During shutdown:
- * await pluginManager.shutdown();
- * ```
- */
-export class PluginManager {
-  /** Map of plugin name → loaded plugin record. */
-  private plugins: Map<string, LoadedPlugin> = new Map();
-
-  /** Loader instance used by this manager. Swappable in tests. */
-  private readonly loader: PluginLoader;
-
-  /** Whether {@link init} has been called at least once. */
-  private initialized = false;
-
-  /**
-   * @param loader - Override the default {@link PluginLoader}. Primarily
-   *   useful in tests where a custom plugins directory is needed.
-   */
-  constructor(loader?: PluginLoader) {
-    this.loader = loader ?? new PluginLoader();
-  }
-
-  // -------------------------------------------------------------------------
-  // Lifecycle
-  // -------------------------------------------------------------------------
-
-  /**
-   * Discover and load all plugins from `~/.nimbus/plugins/`.
-   *
-   * Safe to call multiple times; subsequent calls are no-ops and return the
-   * same result summary (plugins are not reloaded).
-   *
-   * @returns A summary of how many plugins loaded and which failed.
-   */
-  async init(): Promise<PluginInitResult> {
-    if (this.initialized) {
-      return {
-        loadedCount: this.plugins.size,
-        errorCount: 0,
-        errors: [],
-      };
-    }
-
-    const { loaded, errors } = await this.loader.loadAll();
-
-    for (const record of loaded) {
-      const { plugin } = record;
-
-      // Guard against duplicate plugin names across directories.
-      if (this.plugins.has(plugin.name)) {
-        process.stderr.write(
-          `[nimbus:plugins] Warning: duplicate plugin name '${plugin.name}' ` +
-            `found in '${record.pluginDir}'. The later plugin will be skipped.\n`
-        );
-        continue;
-      }
-
-      this.plugins.set(plugin.name, record);
-    }
-
-    this.initialized = true;
-
-    return {
-      loadedCount: this.plugins.size,
-      errorCount: errors.length,
-      errors,
-    };
-  }
-
-  /**
-   * Call `onUnload` on all active plugins and clear the internal registry.
-   *
-   * After this call the manager is reset to its pre-init state.
-   */
-  async shutdown(): Promise<void> {
-    await this.loader.unloadAll();
-    this.plugins.clear();
-    this.initialized = false;
-  }
-
-  // -------------------------------------------------------------------------
-  // Tool Access
-  // -------------------------------------------------------------------------
-
-  /**
-   * Return a flattened array of {@link ToolDefinition} objects built from
-   * every tool contributed by every loaded plugin.
-   *
-   * Tools whose conversion fails are skipped with a stderr warning so that
-   * a malformed tool definition in one plugin does not prevent valid tools
-   * from other plugins being registered.
-   *
-   * @returns Array of converted tool definitions ready for {@link ToolRegistry.register}.
-   */
-  getTools(): ToolDefinition[] {
-    const tools: ToolDefinition[] = [];
-
-    for (const { plugin } of Array.from(this.plugins.values())) {
-      if (!plugin.tools || plugin.tools.length === 0) {
-        continue;
-      }
-
-      for (const pluginTool of plugin.tools) {
-        try {
-          tools.push(convertPluginTool(plugin.name, pluginTool));
-        } catch (err: unknown) {
-          const msg = err instanceof Error ? err.message : String(err);
-          process.stderr.write(
-            `[nimbus:plugins] Warning: plugin '${plugin.name}' tool ` +
-              `'${pluginTool.name}' could not be converted: ${msg}\n`
-          );
-        }
-      }
-    }
-
-    return tools;
-  }
-
-  // -------------------------------------------------------------------------
-  // Provider Access
-  // -------------------------------------------------------------------------
-
-  /**
-   * Return a flattened array of all {@link PluginProviderDefinition} objects
-   * contributed by loaded plugins.
-   *
-   * Callers (typically the LLM router) are responsible for calling each
-   * factory and registering the resulting provider instance.
-   *
-   * @returns Array of provider definitions in load order.
-   */
-  getProviders(): PluginProviderDefinition[] {
-    const providers: PluginProviderDefinition[] = [];
-
-    for (const { plugin } of Array.from(this.plugins.values())) {
-      if (!plugin.providers || plugin.providers.length === 0) {
-        continue;
-      }
-      providers.push(...plugin.providers);
-    }
-
-    return providers;
-  }
-
-  // -------------------------------------------------------------------------
-  // Introspection
-  // -------------------------------------------------------------------------
-
-  /**
-   * Return summary information about every currently loaded plugin.
-   *
-   * Useful for `nimbus plugin list` style CLI commands.
-   */
-  listPlugins(): PluginInfo[] {
-    return Array.from(this.plugins.values()).map(({ plugin, pluginDir }) => ({
-      name: plugin.name,
-      version: plugin.version,
-      description: plugin.description,
-      pluginDir,
-      toolCount: plugin.tools?.length ?? 0,
-      providerCount: plugin.providers?.length ?? 0,
-    }));
-  }
-
-  /**
-   * Look up a single loaded plugin by name.
-   *
-   * @param name - The plugin's `name` field.
-   * @returns The {@link NimbusPlugin} if found, or `undefined`.
-   */
-  getPlugin(name: string): NimbusPlugin | undefined {
-    return this.plugins.get(name)?.plugin;
-  }
-
-  /**
-   * Whether the manager has been initialised (i.e. {@link init} has been
-   * called and completed).
-   */
-  get isInitialized(): boolean {
-    return this.initialized;
-  }
-
-  /**
-   * Number of plugins currently loaded.
-   */
-  get pluginCount(): number {
-    return this.plugins.size;
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Application-wide Singleton
-// ---------------------------------------------------------------------------
-
-/**
- * Application-wide plugin manager instance.
- *
- * Import this wherever you need to access plugin tools or providers at
- * runtime.
- *
- * @example
- * ```ts
- * import { pluginManager } from '../plugins';
- * await pluginManager.init();
- * ```
- */
-export const pluginManager = new PluginManager();