@build-astron-co/nimbus 0.2.0

package/src/mcp/manager.ts

@@ -0,0 +1,133 @@
+/**
+ * MCP Manager
+ *
+ * Manages multiple MCP server connections and provides a unified
+ * interface for tool discovery and registration.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { homedir } from 'node:os';
+import { MCPClient, type MCPServerConfig } from './client';
+import type { ToolDefinition, ToolRegistry } from '../tools/schemas/types';
+
+/** Configuration file format for MCP servers */
+export interface MCPConfig {
+  mcpServers?: Record<string, Omit<MCPServerConfig, 'name'>>;
+}
+
+export class MCPManager {
+  private clients: Map<string, MCPClient> = new Map();
+  private initialized = false;
+
+  /**
+   * Load MCP server configurations from config files.
+   * Searches: .nimbus/mcp.json, nimbus.json, ~/.nimbus/mcp.json
+   */
+  async loadConfig(cwd?: string): Promise<void> {
+    const configPaths = [
+      cwd ? path.join(cwd, '.nimbus', 'mcp.json') : null,
+      cwd ? path.join(cwd, 'nimbus.json') : null,
+      path.join(homedir(), '.nimbus', 'mcp.json'),
+    ].filter((p): p is string => p !== null);
+
+    for (const configPath of configPaths) {
+      if (fs.existsSync(configPath)) {
+        try {
+          const content = fs.readFileSync(configPath, 'utf-8');
+          const config: MCPConfig = JSON.parse(content) as MCPConfig;
+          if (config.mcpServers) {
+            for (const [name, serverConfig] of Object.entries(config.mcpServers)) {
+              if (!this.clients.has(name)) {
+                this.clients.set(name, new MCPClient({ ...serverConfig, name }));
+              }
+            }
+          }
+        } catch {
+          // Skip invalid config files
+        }
+      }
+    }
+
+    this.initialized = true;
+  }
+
+  /**
+   * Connect to all configured MCP servers and discover tools.
+   * Lazy servers are skipped until explicitly needed.
+   */
+  async connectAll(): Promise<void> {
+    if (!this.initialized) {
+      await this.loadConfig();
+    }
+
+    const connectPromises: Promise<void>[] = [];
+    for (const [name, client] of this.clients) {
+      if (!client.config.lazy) {
+        connectPromises.push(
+          client
+            .connect()
+            .then(() => client.listTools())
+            .then(() => undefined)
+            .catch((err: unknown) => {
+              const msg = err instanceof Error ? err.message : String(err);
+              console.warn(`MCP server '${name}' failed to connect: ${msg}`);
+            })
+        );
+      }
+    }
+
+    await Promise.all(connectPromises);
+  }
+
+  /**
+   * Get all tool definitions from connected MCP servers.
+   */
+  getAllTools(): ToolDefinition[] {
+    const tools: ToolDefinition[] = [];
+    for (const client of this.clients.values()) {
+      if (client.isConnected) {
+        tools.push(...client.toToolDefinitions());
+      }
+    }
+    return tools;
+  }
+
+  /**
+   * Register all MCP tools into a tool registry.
+   */
+  registerTools(registry: ToolRegistry): void {
+    for (const tool of this.getAllTools()) {
+      try {
+        registry.register(tool);
+      } catch {
+        // Skip duplicate tool names
+      }
+    }
+  }
+
+  /**
+   * Get a specific client by server name.
+   */
+  getClient(name: string): MCPClient | undefined {
+    return this.clients.get(name);
+  }
+
+  /**
+   * Disconnect all MCP servers.
+   */
+  async disconnectAll(): Promise<void> {
+    const disconnectPromises = Array.from(this.clients.values()).map(client => client.disconnect());
+    await Promise.all(disconnectPromises);
+  }
+
+  /** Number of configured servers */
+  get serverCount(): number {
+    return this.clients.size;
+  }
+
+  /** Number of connected servers */
+  get connectedCount(): number {
+    return Array.from(this.clients.values()).filter(c => c.isConnected).length;
+  }
+}

package/src/nimbus.ts

@@ -0,0 +1,214 @@
+#!/usr/bin/env bun
+/**
+ * Nimbus CLI — Main Entry Point
+ *
+ * Single-process embedded architecture. All modules (LLM, tools, state,
+ * enterprise, engine, generator) run in-process — no HTTP services needed.
+ *
+ * Usage:
+ *   bun src/nimbus.ts --version
+ *   bun src/nimbus.ts --help
+ *   bun src/nimbus.ts chat
+ *   bun src/nimbus.ts ask "what is terraform"
+ *   bun src/nimbus.ts generate terraform --provider aws
+ *   bun src/nimbus.ts tf plan
+ */
+
+import { VERSION } from './version';
+
+/**
+ * Non-blocking update check. Fires a single HTTPS HEAD request to npm
+ * and prints a one-liner to stderr if a newer version exists. The check
+ * uses a 3-second timeout so it never slows startup.
+ */
+function checkForUpdates(): void {
+  // Only check for interactive TTY sessions, not in CI
+  if (!process.stderr.isTTY || process.env.CI || process.env.NIMBUS_NO_UPDATE_CHECK) {
+    return;
+  }
+
+  // Fire-and-forget — deferred to let the TUI render first
+  (async () => {
+    try {
+      // Small delay so the check doesn't compete with startup I/O
+      await new Promise(r => setTimeout(r, 500));
+      const controller = new AbortController();
+      const timeout = setTimeout(() => controller.abort(), 1500);
+
+      const res = await fetch('https://registry.npmjs.org/@build-astron-co/nimbus/latest', {
+        signal: controller.signal,
+        headers: { Accept: 'application/json' },
+      });
+      clearTimeout(timeout);
+
+      if (!res.ok) {
+        return;
+      }
+
+      const data = (await res.json()) as { version?: string };
+      const latest = data.version;
+      if (!latest || latest === VERSION) {
+        return;
+      }
+
+      // Simple semver comparison: split on dots, compare numerically
+      const current = VERSION.split('.').map(Number);
+      const remote = latest.split('.').map(Number);
+      let isNewer = false;
+      for (let i = 0; i < 3; i++) {
+        if ((remote[i] ?? 0) > (current[i] ?? 0)) {
+          isNewer = true;
+          break;
+        }
+        if ((remote[i] ?? 0) < (current[i] ?? 0)) {
+          break;
+        }
+      }
+
+      if (isNewer) {
+        process.stderr.write(
+          `\x1b[33m  Update available: ${VERSION} → ${latest}. Run: nimbus upgrade\x1b[0m\n`
+        );
+      }
+    } catch {
+      // Network errors are silently ignored
+    }
+  })();
+}
+
+// ---------------------------------------------------------------------------
+// Global error handlers (Gap 6: prevent silent crashes from unhandled promises)
+// ---------------------------------------------------------------------------
+
+process.on('unhandledRejection', reason => {
+  const msg = reason instanceof Error ? reason.message : String(reason);
+  process.stderr.write(`\x1b[31mUnhandled promise rejection: ${msg}\x1b[0m\n`);
+  // Don't exit — let the TUI continue running. The user can see the error
+  // and decide whether to continue or quit.
+});
+
+process.on('uncaughtException', error => {
+  process.stderr.write(`\x1b[31mUncaught exception: ${error.message}\x1b[0m\n`);
+  if (error.stack) {
+    process.stderr.write(`\x1b[2m${error.stack}\x1b[0m\n`);
+  }
+  // For uncaught exceptions, set exit code but let cleanup run
+  process.exitCode = 1;
+});
+
+async function main() {
+  const args = process.argv.slice(2);
+
+  // Handle --version and -v before anything else (no init needed)
+  if (args[0] === '--version' || args[0] === '-v') {
+    console.log(`nimbus ${VERSION}`);
+    process.exit(0);
+  }
+
+  // Show help when explicitly requested — handles both `nimbus --help`
+  // and subcommand-level help like `nimbus chat --help` or `nimbus tf -h`.
+  if (args.includes('--help') || args.includes('-h')) {
+    const otherArgs = args.filter(a => a !== '--help' && a !== '-h');
+    args.length = 0;
+    args.push('help', ...otherArgs);
+  }
+
+  // Kick off a non-blocking update check (fire-and-forget)
+  checkForUpdates();
+
+  // Default no-args: launch chat (or onboarding if first run)
+  if (args.length === 0) {
+    const { needsOnboarding } = await import('./commands/onboarding');
+    if (needsOnboarding()) {
+      args[0] = 'onboarding';
+    } else {
+      args[0] = 'chat';
+    }
+  }
+
+  // Initialize the application (SQLite, LLM router, etc.)
+  const { initApp, shutdownApp } = await import('./app');
+
+  // Register shutdown hooks for clean exit.
+  // Use process.exitCode instead of process.exit() to avoid racing
+  // with finally blocks and async cleanup in the TUI.
+  let cleaningUp = false;
+  const cleanup = async () => {
+    if (cleaningUp) {
+      return;
+    } // Prevent double-cleanup on rapid Ctrl+C
+    cleaningUp = true;
+    await shutdownApp();
+    process.exitCode = 0;
+  };
+
+  process.on('SIGINT', cleanup);
+  process.on('SIGTERM', cleanup);
+
+  try {
+    // Commands that don't need full initialization
+    const noInitCommands = new Set([
+      'help',
+      'version',
+      'doctor',
+      'onboarding',
+      'upgrade',
+      'update',
+    ]);
+
+    if (!noInitCommands.has(args[0])) {
+      // Show brief startup indicator for interactive commands
+      if (args[0] === 'chat' && process.stderr.isTTY) {
+        process.stderr.write('\x1b[2mStarting Nimbus...\x1b[0m');
+      }
+      await initApp();
+      if (args[0] === 'chat' && process.stderr.isTTY) {
+        process.stderr.write('\r\x1b[K');
+      }
+    }
+
+    // Import and run CLI command router
+    const { runCommand } = await import('./cli');
+    await runCommand(args);
+
+    // After onboarding, clear auth cache, initialize app, and launch chat
+    if (args[0] === 'onboarding') {
+      // Clear the auth-bridge cache so the router picks up freshly-saved credentials
+      try {
+        const { clearAuthCache } = await import('./llm/auth-bridge');
+        clearAuthCache();
+      } catch {
+        /* non-critical */
+      }
+      await initApp();
+      await runCommand(['chat']);
+    }
+  } catch (error: any) {
+    const msg = error.message || String(error);
+    if (msg.includes('bun:sqlite') || msg.includes('bun:')) {
+      console.error(
+        'Error: Nimbus requires the Bun runtime (for bun:sqlite and other built-in APIs).'
+      );
+      console.error('');
+      console.error('If you have Bun installed, run:');
+      console.error('  bun src/nimbus.ts');
+      console.error('');
+      console.error('To install Bun:');
+      console.error('  curl -fsSL https://bun.sh/install | bash');
+      console.error('');
+      console.error('Or install the pre-built binary (no Bun required):');
+      console.error('  brew install the-ai-project-co/tap/nimbus');
+      console.error('  # or download from GitHub Releases');
+    } else if (error.code === 'MODULE_NOT_FOUND') {
+      console.error(`Error: Missing module — ${msg}`);
+      console.error('Run "bun install" to install dependencies.');
+    } else {
+      console.error(`Error: ${msg}`);
+    }
+    process.exit(1);
+  } finally {
+    await shutdownApp();
+  }
+}
+
+main();

package/src/plugins/index.ts

@@ -0,0 +1,27 @@
+/**
+ * Nimbus Plugin System — Public API
+ *
+ * Re-exports the primary class and types needed by the rest of the
+ * application and by external consumers that want to integrate with the
+ * plugin system without importing internal submodules directly.
+ *
+ * @module plugins
+ */
+
+// Manager (class + singleton)
+export { PluginManager, pluginManager } from './manager';
+export type { PluginInfo, PluginInitResult } from './manager';
+
+// Loader (class — exposed for testing and advanced use)
+export { PluginLoader } from './loader';
+
+// Public types
+export type {
+  NimbusPlugin,
+  PluginToolDefinition,
+  PluginProviderDefinition,
+  PluginManifest,
+  PluginPermissionTier,
+  LoadedPlugin,
+  PluginLoadError,
+} from './types';

package/src/plugins/loader.ts

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