@build-astron-co/nimbus 0.2.0 → 0.4.0

package/dist/src/plugins/loader.js

@@ -0,0 +1,280 @@
+/**
+ * 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';
+// ---------------------------------------------------------------------------
+// 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) {
+    if (typeof value !== 'object' || value === null) {
+        return false;
+    }
+    const obj = value;
+    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) {
+    if (typeof value !== 'object' || value === null) {
+        return false;
+    }
+    const obj = value;
+    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}. */
+    pluginsDir;
+    /** Plugins that have been successfully loaded in this loader instance. */
+    loadedPlugins = [];
+    /**
+     * @param pluginsDir - Override the default `~/.nimbus/plugins/` scan root.
+     *   Primarily useful in tests.
+     */
+    constructor(pluginsDir = 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() {
+        if (!fs.existsSync(this.pluginsDir)) {
+            return [];
+        }
+        let entries;
+        try {
+            entries = fs.readdirSync(this.pluginsDir, { withFileTypes: true });
+        }
+        catch (err) {
+            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 = [];
+        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) {
+        // --- Step 1: Read manifest -----------------------------------------------
+        const manifestPath = path.join(pluginDir, MANIFEST_FILENAME);
+        let manifestRaw;
+        try {
+            manifestRaw = fs.readFileSync(manifestPath, 'utf-8');
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            throw new Error(`Cannot read manifest at '${manifestPath}': ${msg}`);
+        }
+        let manifestData;
+        try {
+            manifestData = JSON.parse(manifestRaw);
+        }
+        catch (err) {
+            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;
+        // --- 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;
+        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) {
+            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
+            ? moduleExports['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;
+        // 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) {
+                const msg = err instanceof Error ? err.message : String(err);
+                throw new Error(`Plugin '${plugin.name}' onLoad() rejected: ${msg}`);
+            }
+        }
+        const record = { 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() {
+        const discovered = this.discover();
+        const loaded = [];
+        const errors = [];
+        for (const pluginDir of discovered) {
+            try {
+                const record = await this.load(pluginDir);
+                loaded.push(record);
+            }
+            catch (err) {
+                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() {
+        for (const { plugin } of this.loadedPlugins) {
+            if (typeof plugin.onUnload === 'function') {
+                try {
+                    await plugin.onUnload();
+                }
+                catch (err) {
+                    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() {
+        return [...this.loadedPlugins];
+    }
+    /**
+     * The root directory this loader scans for plugins.
+     */
+    get directory() {
+        return this.pluginsDir;
+    }
+}

package/dist/src/plugins/manager.js

@@ -0,0 +1,282 @@
+/**
+ * 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';
+// 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;
+// ---------------------------------------------------------------------------
+// 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, tool) {
+    // 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) => {
+        try {
+            const result = await tool.execute(input);
+            return {
+                output: result.output,
+                isError: !result.success,
+                error: result.success ? undefined : result.output,
+            };
+        }
+        catch (err) {
+            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. */
+    plugins = new Map();
+    /** Loader instance used by this manager. Swappable in tests. */
+    loader;
+    /** Whether {@link init} has been called at least once. */
+    initialized = false;
+    /**
+     * @param loader - Override the default {@link PluginLoader}. Primarily
+     *   useful in tests where a custom plugins directory is needed.
+     */
+    constructor(loader) {
+        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() {
+        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() {
+        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() {
+        const tools = [];
+        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) {
+                    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() {
+        const providers = [];
+        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() {
+        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) {
+        return this.plugins.get(name)?.plugin;
+    }
+    /**
+     * Whether the manager has been initialised (i.e. {@link init} has been
+     * called and completed).
+     */
+    get isInitialized() {
+        return this.initialized;
+    }
+    /**
+     * Number of plugins currently loaded.
+     */
+    get pluginCount() {
+        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();

package/dist/src/plugins/types.js

@@ -0,0 +1,23 @@
+/**
+ * Nimbus Plugin System — Type Definitions
+ *
+ * These interfaces define the contract that every Nimbus plugin must satisfy.
+ * A plugin is a directory installed under ~/.nimbus/plugins/ that contains a
+ * `nimbus-plugin.json` manifest and a JavaScript/TypeScript entry point.
+ *
+ * Plugins may contribute:
+ *   - Custom tools that are injected into the agent's ToolRegistry at startup.
+ *   - Custom LLM provider factories that are registered with the LLM router.
+ *
+ * Lifecycle:
+ *   1. {@link PluginLoader.discover} scans ~/.nimbus/plugins/ for manifests.
+ *   2. {@link PluginLoader.load} imports the `main` entry point and validates
+ *      that it default-exports a {@link NimbusPlugin}.
+ *   3. If defined, {@link NimbusPlugin.onLoad} is awaited before the plugin is
+ *      considered active.
+ *   4. On process exit, {@link PluginManager.shutdown} calls
+ *      {@link NimbusPlugin.onUnload} for every active plugin.
+ *
+ * @module plugins/types
+ */
+export {};