@bahulam/code 0.1.10 → 0.1.11

package/src/plugins/executor.mjs

@@ -0,0 +1,121 @@
+/**
+ * Plugin Executor — dynamic import() of plugin tool handler modules.
+ *
+ * Plugin tools are .mjs / .js files that export at minimum a `call(input)` function.
+ * They are loaded relative to the plugin directory.
+ */
+
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import path from 'path';
+import { makePluginState } from './state.mjs';
+
+/**
+ * Load a plugin tool handler by resolving its path relative to the plugin directory.
+ * @param {string} pluginDir - Absolute path to the plugin directory
+ * @param {string} handlerPath - Relative path from plugin.yaml (e.g. ./tools/my-tool.mjs)
+ * @returns {Promise<object|null>} { name, description, inputSchema, call } or null
+ */
+export async function loadPluginTool(pluginDir, handlerPath) {
+  try {
+    const absPath = path.resolve(pluginDir, handlerPath);
+    const fileUrl = pathToFileURL(absPath).href;
+
+    // Cache-busting for development: append timestamp
+    const url = `${fileUrl}?t=${Date.now()}`;
+    const mod = await import(url);
+
+    // The module should export at minimum: call(input) => { success, output }
+    if (typeof mod.call !== 'function') {
+      if (process.env.DEBUG) {
+        console.error(`Plugin handler ${handlerPath} does not export a call() function`);
+      }
+      return null;
+    }
+
+    return {
+      name: mod.name || path.basename(handlerPath, path.extname(handlerPath)),
+      description: mod.description || '',
+      inputSchema: mod.inputSchema || mod.input_schema || { type: 'object', properties: {} },
+      call: mod.call,
+      validateInput: mod.validateInput || null,
+    };
+  } catch (err) {
+    if (process.env.DEBUG) {
+      console.error(`Failed to load plugin tool handler ${handlerPath}: ${err.message}`);
+    }
+    return null;
+  }
+}
+
+/**
+ * Create a plugin tool executor for a given plugin directory.
+ * Loads all tool handlers and returns an execute function.
+ *
+ * @param {object} manifest - Normalized plugin manifest
+ * @returns {Promise<{ execute(name, args): Promise<object>, list(): string[] }>}
+ */
+/**
+ * Create a plugin tool executor for a given plugin directory.
+ * Loads all tool handlers and returns an execute function.
+ *
+ * @param {object} manifest - Normalized plugin manifest
+ * @param {object} [opts]
+ * @param {(evt: {plugin: string, op: string, kind: string, target: string, at: string}) => void} [opts.stateEmit]
+ *   Called (debounced) after every state write commits. The workspace
+ *   server threads this in so state changes turn into SSE events for
+ *   live view updates — the Shared Blackboard's reactive pulse.
+ * @returns {Promise<{ execute(name, args): Promise<object>, list(): string[], state: object|null }>}
+ */
+export async function createPluginToolExecutor(manifest, opts = {}) {
+  const pluginDir = manifest._dir || '';
+  const tools = manifest.spec?.tools || [];
+  const handlers = new Map(); // name → { handler, toolDef }
+  const pluginName = manifest.metadata?.name || '';
+
+  for (const toolDef of tools) {
+    if (!toolDef.handler) continue;
+    const handler = await loadPluginTool(pluginDir, toolDef.handler);
+    if (handler) {
+      handlers.set(toolDef.name, { handler, toolDef });
+    }
+  }
+
+  // One state instance per plugin, opened lazily so plugins that never
+  // touch state don't create empty ~/.bahulam/data/<name> directories.
+  let _state = null;
+  function getState() {
+    if (!pluginName) return null; // no name → no isolation → refuse state
+    if (_state) return _state;
+    _state = makePluginState(pluginName, { emit: opts.stateEmit || null });
+    return _state;
+  }
+
+  return {
+    execute: async (name, args, options = {}) => {
+      const entry = handlers.get(name);
+      if (!entry) {
+        return { success: false, output: `Plugin tool not found: ${name}` };
+      }
+      // Inject the shared-blackboard handle. Handlers opt in by naming
+      // it in their signature: `async call(args, { state })`. The
+      // getter defers opening the SQLite file until the first access,
+      // so handlers that don't use state pay no cost.
+      const handlerOpts = {
+        ...options,
+        get state() { return getState(); },
+        pluginName,
+      };
+      try {
+        const result = await entry.handler.call(args || {}, handlerOpts);
+        return result?.success !== false
+          ? { success: true, output: result?.output ?? result, _tool: name, _plugin: pluginName }
+          : { success: false, output: result?.output ?? String(result), _tool: name, _plugin: pluginName };
+      } catch (err) {
+        return { success: false, output: `Plugin tool error (${name}): ${err.message}`, _tool: name, _plugin: pluginName };
+      }
+    },
+    list: () => [...handlers.keys()],
+    /** Get (or open) the plugin's state handle — used by the view API. */
+    get state() { return getState(); },
+  };
+}

package/src/plugins/loader.mjs

@@ -1,138 +1,138 @@
 /**
- * Plugin Loader — load plugins from directory, git, or npm.
+ * Plugin Loader — high-level facade for installing, listing, and removing plugins.
  *
- * Plugins can provide: tools, agents, skills, hooks.
- * Plugin format: a directory with a plugin.json manifest.
+ * Uses PluginRegistry for scanning/loading, and provides git-based install.
+ * Plugin format: a directory with plugin.yaml (bahulam.plugin/1).
  */
 
 import fs from 'fs';
 import path from 'path';
 import os from 'os';
 import { execSync } from 'child_process';
+import { PluginRegistry } from './registry.mjs';
 
 export class PluginLoader {
-    /**
-     * @param {string} [pluginDir] - directory to scan for plugins
-     */
-    constructor(pluginDir) {
-        this.pluginDir = pluginDir ||
-            path.join(os.homedir(), '.claude', 'plugins');
-        this.plugins = new Map();
-    }
-
-    /**
-     * Load plugins from the plugin directory.
-     * @returns {Array<object>} loaded plugin manifests
-     */
-    async loadFromDirectory(dir) {
-        const targetDir = dir || this.pluginDir;
-        const loaded = [];
-
-        try {
-            if (!fs.existsSync(targetDir)) return loaded;
-
-            const entries = fs.readdirSync(targetDir, { withFileTypes: true });
-            for (const entry of entries) {
-                if (!entry.isDirectory()) continue;
-
-                const manifestPath = path.join(targetDir, entry.name, 'plugin.json');
-                if (!fs.existsSync(manifestPath)) continue;
-
-                try {
-                    const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
-                    manifest._dir = path.join(targetDir, entry.name);
-                    manifest._name = entry.name;
-                    this.plugins.set(manifest.name || entry.name, manifest);
-                    loaded.push(manifest);
-                } catch {
-                    // Skip malformed plugins
-                }
-            }
-        } catch {
-            // Directory not readable
+  /**
+   * @param {Object} [options]
+   * @param {string} [options.pluginDir] - Primary plugin directory
+   * @param {string[]} [options.pluginDirs] - Additional plugin directories
+   * @param {string[]} [options.disabled] - Plugin names to disable
+   */
+  constructor(options = {}) {
+    const { pluginDir, pluginDirs, disabled } = options;
+    this.registry = new PluginRegistry({
+      pluginDir: pluginDir || path.join(os.homedir(), '.bahulam', 'plugins'),
+      pluginDirs,
+      disabled,
+    });
+    this.pluginDir = pluginDir || path.join(os.homedir(), '.bahulam', 'plugins');
+  }
+
+  /**
+   * Load all plugins from registered directories.
+   * @returns {PluginRegistry}
+   */
+  load() {
+    this.registry.scan();
+    return this.registry;
+  }
+
+  /**
+   * Load plugins from a specific directory (scans subdirectories).
+   * @param {string} dir
+   * @returns {PluginRegistry}
+   */
+  loadFromDirectory(dir) {
+    this.registry._scanDir(dir);
+    return this.registry;
+  }
+
+  /**
+   * Clone a plugin from a git repo and load it.
+   * @param {string} repoUrl - git repository URL
+   * @param {string} [name] - plugin name (default: repo name)
+   * @returns {object|null} loaded manifest
+   */
+  loadFromGit(repoUrl, name) {
+    const pluginName = name || repoUrl.split('/').pop()?.replace('.git', '') || 'plugin';
+    const targetDir = path.join(this.pluginDir, pluginName);
+
+    try {
+      fs.mkdirSync(this.pluginDir, { recursive: true });
+
+      if (fs.existsSync(targetDir)) {
+        // Update existing
+        execSync('git pull', { cwd: targetDir, stdio: 'pipe' });
+      } else {
+        // Clone new
+        execSync(`git clone --depth 1 ${repoUrl} ${targetDir}`, { stdio: 'pipe' });
+      }
+
+      const manifestPath = path.join(targetDir, 'plugin.yaml');
+      const altPath = path.join(targetDir, 'plugin.json');
+      const exists = fs.existsSync(manifestPath) ? manifestPath : (fs.existsSync(altPath) ? altPath : null);
+
+      if (exists) {
+        const { parsePluginManifestFile } = await import('./manifest.mjs');
+        const manifest = parsePluginManifestFile(exists);
+        if (manifest) {
+          this.registry.register(manifest);
+          return manifest;
         }
-
-        return loaded;
-    }
-
-    /**
-     * Clone a plugin from a git repo and load it.
-     * @param {string} repoUrl - git repository URL
-     * @param {string} [name] - plugin name (default: repo name)
-     * @returns {object|null} loaded manifest
-     */
-    async loadFromGit(repoUrl, name) {
-        const pluginName = name || repoUrl.split('/').pop()?.replace('.git', '') || 'plugin';
-        const targetDir = path.join(this.pluginDir, pluginName);
-
-        try {
-            fs.mkdirSync(this.pluginDir, { recursive: true });
-
-            if (fs.existsSync(targetDir)) {
-                // Update existing
-                execSync('git pull', { cwd: targetDir, stdio: 'pipe' });
-            } else {
-                // Clone new
-                execSync(`git clone --depth 1 ${repoUrl} ${targetDir}`, { stdio: 'pipe' });
-            }
-
-            const manifestPath = path.join(targetDir, 'plugin.json');
-            if (fs.existsSync(manifestPath)) {
-                const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
-                manifest._dir = targetDir;
-                manifest._name = pluginName;
-                this.plugins.set(manifest.name || pluginName, manifest);
-                return manifest;
-            }
-        } catch {
-            // Git operation failed
-        }
-
-        return null;
+      }
+    } catch (err) {
+      if (process.env.DEBUG) {
+        console.error(`Failed to clone plugin ${repoUrl}: ${err.message}`);
+      }
     }
 
-    /**
-     * Get all installed plugins.
-     * @returns {Array<object>}
-     */
-    getInstalledPlugins() {
-        return [...this.plugins.values()];
+    return null;
+  }
+
+  /**
+   * Get all installed plugins.
+   * @returns {object[]}
+   */
+  getInstalledPlugins() {
+    return this.registry.list();
+  }
+
+  /**
+   * Get a plugin by name.
+   * @param {string} name
+   * @returns {object|undefined}
+   */
+  getPlugin(name) {
+    return this.registry.get(name);
+  }
+
+  /**
+   * Remove a plugin by name.
+   * @param {string} name
+   * @returns {boolean}
+   */
+  removePlugin(name) {
+    const plugin = this.registry.get(name);
+    if (!plugin) return false;
+
+    try {
+      if (plugin._dir && fs.existsSync(plugin._dir)) {
+        fs.rmSync(plugin._dir, { recursive: true, force: true });
+      }
+    } catch (err) {
+      if (process.env.DEBUG) {
+        console.error(`Failed to remove plugin directory ${plugin._dir}: ${err.message}`);
+      }
     }
 
-    /**
-     * Get a plugin by name.
-     * @param {string} name
-     * @returns {object|undefined}
-     */
-    getPlugin(name) {
-        return this.plugins.get(name);
-    }
-
-    /**
-     * Remove a plugin by name.
-     * @param {string} name
-     * @returns {boolean}
-     */
-    removePlugin(name) {
-        const plugin = this.plugins.get(name);
-        if (!plugin) return false;
-
-        try {
-            if (plugin._dir && fs.existsSync(plugin._dir)) {
-                fs.rmSync(plugin._dir, { recursive: true, force: true });
-            }
-        } catch {
-            // Best effort
-        }
-
-        return this.plugins.delete(name);
-    }
-
-    /**
-     * Get plugin count.
-     * @returns {number}
-     */
-    count() {
-        return this.plugins.size;
-    }
-}
+    return this.registry.remove(name);
+  }
+
+  /**
+   * Get plugin count.
+   * @returns {number}
+   */
+  count() {
+    return this.registry.count();
+  }
+}

package/src/plugins/manifest.mjs

@@ -0,0 +1,291 @@
+/**
+ * Plugin Manifest Parser — parse and validate bahulam.plugin/1 manifests.
+ *
+ * Supports YAML (plugin.yaml) format.
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { load as yamlLoad } from 'js-yaml';
+
+/**
+ * Parse a YAML text string into an object using js-yaml.
+ * @param {string} text - Raw YAML content
+ * @returns {object}
+ */
+function parseYaml(text) {
+  return yamlLoad(text) || {};
+}
+
+function normalizeToolNames(value) {
+  if (!Array.isArray(value)) return [];
+  return value.map(item => {
+    if (typeof item === 'string') return item.trim();
+    if (item && typeof item === 'object') return String(item.name || item.tool || item.id || '').trim();
+    return '';
+  }).filter(Boolean);
+}
+
+function loadAgentHandler(agentDef, pluginDir) {
+  const handler = String(agentDef.handler || agentDef.file || '').trim();
+  if (!handler || !pluginDir) return {};
+  try {
+    const handlerPath = path.resolve(pluginDir, handler);
+    const raw = fs.readFileSync(handlerPath, 'utf-8');
+    return path.extname(handlerPath).toLowerCase() === '.json'
+      ? JSON.parse(raw)
+      : parseYaml(raw);
+  } catch (err) {
+    if (process.env.DEBUG) {
+      console.error(`Failed to load plugin agent handler ${handler}: ${err.message}`);
+    }
+    return {};
+  }
+}
+
+function normalizeAgentDef(agentDef, pluginName, pluginDir) {
+  const handlerConfig = loadAgentHandler(agentDef, pluginDir);
+  const metadata = handlerConfig.metadata || handlerConfig.meta || {};
+  const agent = handlerConfig.agent || handlerConfig.spec?.agent || {};
+  const handlerTools = (
+    handlerConfig.tools
+    || handlerConfig.spec?.tools
+    || agent.tools
+    || []
+  );
+  const inlineTools = normalizeToolNames(agentDef.tools);
+
+  return {
+    slug: agentDef.slug || metadata.slug || handlerConfig.slug || metadata.name || handlerConfig.name || agentDef.name || '',
+    name: agentDef.name || metadata.name || handlerConfig.name || agentDef.slug || '',
+    description: agentDef.description || metadata.description || handlerConfig.description || '',
+    role: agentDef.role || metadata.role || handlerConfig.role || 'specialist',
+    system_prompt: (
+      agentDef.system_prompt
+      || agentDef.systemPrompt
+      || agentDef.prompt
+      || agent.system_prompt
+      || agent.systemPrompt
+      || agent.prompt
+      || handlerConfig.system_prompt
+      || handlerConfig.prompt
+      || ''
+    ),
+    tools: inlineTools.length ? inlineTools : normalizeToolNames(handlerTools),
+    model: agentDef.model || agent.model || handlerConfig.model || null,
+    models: agentDef.models || agent.models || handlerConfig.models || undefined,
+    max_tokens: agentDef.max_tokens || agent.max_tokens || handlerConfig.max_tokens || undefined,
+    max_iterations: agentDef.max_iterations || agent.max_iterations || handlerConfig.max_iterations || undefined,
+    handler: agentDef.handler || agentDef.file || '',
+    source: `plugin:${pluginName}`,
+    source_scope: 'plugin',
+  };
+}
+
+/**
+ * Parse a plugin manifest from YAML text.
+ * @param {string} yamlText - Raw YAML content
+ * @param {string} [filePath] - Source path for error messages
+ * @returns {object|null} Normalized manifest or null on failure
+ */
+export function parsePluginManifest(yamlText, filePath = '') {
+  try {
+    const raw = parseYaml(yamlText);
+    return normalizeManifest(raw, filePath);
+  } catch (err) {
+    if (process.env.DEBUG) {
+      console.error(`Failed to parse plugin manifest ${filePath}: ${err.message}`);
+    }
+    return null;
+  }
+}
+
+/**
+ * Parse a plugin manifest from a file.
+ * @param {string} manifestPath - Path to plugin.yaml or plugin.json
+ * @returns {object|null}
+ */
+export function parsePluginManifestFile(manifestPath) {
+  try {
+    const ext = path.extname(manifestPath).toLowerCase();
+    const content = fs.readFileSync(manifestPath, 'utf-8');
+    if (ext === '.json') {
+      const raw = JSON.parse(content);
+      return normalizeManifest(raw, manifestPath);
+    }
+    return parsePluginManifest(content, manifestPath);
+  } catch (err) {
+    if (process.env.DEBUG) {
+      console.error(`Failed to read plugin manifest ${manifestPath}: ${err.message}`);
+    }
+    return null;
+  }
+}
+
+/**
+ * Normalize and validate a raw manifest object.
+ * @param {object} raw
+ * @param {string} [source]
+ * @returns {object|null}
+ */
+export function normalizeManifest(raw, source = '') {
+  if (!raw || typeof raw !== 'object') return null;
+
+  const apiVersion = raw.apiVersion || raw.api_version || '';
+  if (apiVersion !== 'bahulam.plugin/1') {
+    if (process.env.DEBUG) {
+      console.warn(`Unsupported plugin apiVersion: ${apiVersion} in ${source}`);
+    }
+    return null;
+  }
+
+  const meta = raw.metadata || raw.meta || {};
+  const spec = raw.spec || raw.plugin || {};
+  const name = meta.name || spec.name || '';
+  if (!name) {
+    if (process.env.DEBUG) {
+      console.warn(`Plugin manifest missing name: ${source}`);
+    }
+    return null;
+  }
+
+  // Normalize agents
+  const agents = [];
+  const pluginDir = source ? path.dirname(source) : '';
+  for (const agentDef of (spec.agents || [])) {
+    const agent = normalizeAgentDef(agentDef, name, pluginDir);
+    if (agent.slug) agents.push(agent);
+  }
+
+  // Normalize tools
+  const tools = [];
+  for (const toolDef of (spec.tools || [])) {
+    const tool = {
+      name: toolDef.name || '',
+      description: toolDef.description || '',
+      input_schema: toolDef.parameters || toolDef.input_schema || toolDef.inputSchema || { type: 'object', properties: {} },
+      handler: toolDef.handler || toolDef.file || '',
+      plugin_name: name,
+    };
+    if (tool.name) tools.push(tool);
+  }
+
+  // Normalize workspace
+  const workspace = spec.workspace || {};
+  if (workspace.views && !Array.isArray(workspace.views)) {
+    workspace.views = [];
+  }
+
+  // Normalize MCP servers — the Plugin=MCP+UX story. Two sources are
+  // merged so authors can either:
+  //   (a) declare mcpServers: {} inline in plugin.yaml (Bahulam-native)
+  //   (b) drop a sibling mcp.json in Claude-Desktop format (portable —
+  //       any config that works in Claude Desktop / Cursor / Cline
+  //       transfers with zero edits)
+  // Inline wins on name collision so authors can override a portable
+  // config for the local plugin without editing mcp.json.
+  const mcpServers = _readMcpServers(spec.mcpServers, source);
+
+  return {
+    apiVersion,
+    kind: raw.kind || 'Plugin',
+    metadata: {
+      name,
+      version: meta.version || '0.0.0',
+      description: meta.description || '',
+      author: meta.author || '',
+      repository: meta.repository || '',
+    },
+    spec: {
+      tools,
+      agents,
+      workspace,
+      mcpServers,
+    },
+    source,
+    _dir: source ? path.dirname(source) : '',
+  };
+}
+
+/**
+ * Merge inline `mcpServers:` from plugin.yaml with a sibling mcp.json.
+ * Both should be dicts of `{<name>: {command|url, args?, env?, headers?}}`
+ * following the Claude Desktop convention. Returns `{}` when neither is
+ * present so callers can iterate without a nullability check.
+ * @param {object|null|undefined} inline
+ * @param {string} manifestPath  used to locate mcp.json next to it
+ * @returns {Object<string, object>}
+ */
+function _readMcpServers(inline, manifestPath) {
+  const merged = {};
+  // Sibling mcp.json first — inline overrides on name collision.
+  if (manifestPath) {
+    const jsonPath = path.join(path.dirname(manifestPath), 'mcp.json');
+    if (fs.existsSync(jsonPath)) {
+      try {
+        const raw = JSON.parse(fs.readFileSync(jsonPath, 'utf-8'));
+        const servers = raw?.mcpServers || raw?.mcp_servers || raw || {};
+        if (servers && typeof servers === 'object') {
+          for (const [name, cfg] of Object.entries(servers)) {
+            if (cfg && typeof cfg === 'object') merged[name] = _normalizeMcpServer(cfg);
+          }
+        }
+      } catch (err) {
+        if (process.env.DEBUG) console.error(`Failed to read ${jsonPath}: ${err.message}`);
+      }
+    }
+  }
+  if (inline && typeof inline === 'object') {
+    for (const [name, cfg] of Object.entries(inline)) {
+      if (cfg && typeof cfg === 'object') merged[name] = _normalizeMcpServer(cfg);
+    }
+  }
+  return merged;
+}
+
+function _normalizeMcpServer(cfg) {
+  return {
+    command: cfg.command || undefined,
+    args: Array.isArray(cfg.args) ? cfg.args : undefined,
+    env: cfg.env && typeof cfg.env === 'object' ? cfg.env : undefined,
+    url: cfg.url || undefined,
+    headers: cfg.headers && typeof cfg.headers === 'object' ? cfg.headers : undefined,
+    transport: cfg.transport || undefined,
+  };
+}
+
+/**
+ * Validate a normalized manifest and return errors.
+ * @param {object} manifest
+ * @returns {{ valid: boolean, errors: string[] }}
+ */
+export function validatePluginManifest(manifest) {
+  const errors = [];
+
+  if (!manifest) {
+    return { valid: false, errors: ['Manifest is null or undefined'] };
+  }
+
+  if (manifest.apiVersion !== 'bahulam.plugin/1') {
+    errors.push(`Unsupported apiVersion: ${manifest.apiVersion}. Expected bahulam.plugin/1`);
+  }
+
+  if (!manifest.metadata?.name) {
+    errors.push('Plugin metadata.name is required');
+  }
+
+  if (manifest.spec) {
+    for (const tool of (manifest.spec.tools || [])) {
+      if (!tool.name) errors.push('Tool missing name');
+      if (!tool.handler) errors.push(`Tool "${tool.name || '(unnamed)'}" missing handler path`);
+    }
+    for (const agent of (manifest.spec.agents || [])) {
+      if (!agent.slug && !agent.name) errors.push('Agent missing slug or name');
+    }
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+  };
+}