@aion0/forge 0.5.21 → 0.5.22

package/lib/pipeline.ts

@@ -31,11 +31,16 @@ export interface WorkflowNode {
   id: string;
   project: string;
   prompt: string;
-  mode?: 'claude' | 'shell';  // default: 'claude' (agent -p), 'shell' runs raw shell command
+  mode?: 'claude' | 'shell' | 'plugin';  // default: 'claude', 'shell' runs command, 'plugin' runs plugin action
   agent?: string;              // agent ID (default: from settings)
   branch?: string;             // auto checkout this branch before running (supports templates)
+  // Plugin mode fields
+  plugin?: string;             // plugin ID (e.g., 'jenkins', 'docker')
+  pluginAction?: string;       // action name (e.g., 'trigger', 'build'), defaults to plugin's defaultAction
+  pluginParams?: Record<string, any>;  // per-use parameters
+  pluginWait?: boolean;        // auto-run 'wait' action after main action
   dependsOn: string[];
-  outputs: { name: string; extract: 'result' | 'git_diff' | 'stdout' }[];
+  outputs: { name: string; extract: 'result' | 'git_diff' | 'stdout' | 'plugin' }[];
   routes: { condition: string; next: string }[];
   maxIterations: number;
 }
@@ -302,9 +307,13 @@ function parseWorkflow(raw: string): Workflow {
       id,
       project: n.project || '',
       prompt: n.prompt || '',
-      mode: n.mode || 'claude',
+      mode: n.mode || (n.plugin ? 'plugin' : 'claude'),
       agent: n.agent || undefined,
       branch: n.branch || undefined,
+      plugin: n.plugin || undefined,
+      pluginAction: n.plugin_action || n.pluginAction || undefined,
+      pluginParams: n.plugin_params || n.pluginParams || n.params || undefined,
+      pluginWait: n.plugin_wait || n.pluginWait || n.wait || false,
       dependsOn: n.depends_on || n.dependsOn || [],
       outputs: (n.outputs || []).map((o: any) => ({
         name: o.name,
@@ -1024,7 +1033,7 @@ export function cancelPipeline(id: string): boolean {
 
 // ─── Node Scheduling ──────────────────────────────────────
 
-function scheduleReadyNodes(pipeline: Pipeline, workflow: Workflow) {
+async function scheduleReadyNodes(pipeline: Pipeline, workflow: Workflow) {
   const ctx = { input: pipeline.input, vars: pipeline.vars, nodes: pipeline.nodes };
 
   for (const nodeId of pipeline.nodeOrder) {
@@ -1089,7 +1098,55 @@ function scheduleReadyNodes(pipeline: Pipeline, workflow: Workflow) {
       }
     }
 
-    // Create task — mode: 'shell' runs raw command, 'claude' runs claude -p
+    // ── Plugin mode: execute plugin action directly ──
+    if (nodeDef.mode === 'plugin' && nodeDef.plugin) {
+      nodeState.status = 'running';
+      nodeState.startedAt = new Date().toISOString();
+      savePipeline(pipeline);
+      notifyStep(pipeline, nodeId, 'running');
+
+      try {
+        const { getInstalledPlugin } = await import('./plugins/registry');
+        const { executePluginWithWait } = await import('./plugins/executor');
+
+        const inst = getInstalledPlugin(nodeDef.plugin);
+        if (!inst) throw new Error(`Plugin "${nodeDef.plugin}" not installed`);
+        if (!inst.enabled) throw new Error(`Plugin "${nodeDef.plugin}" is disabled`);
+
+        // Resolve template params
+        const resolvedParams: Record<string, any> = {};
+        for (const [k, v] of Object.entries(nodeDef.pluginParams || {})) {
+          resolvedParams[k] = typeof v === 'string' ? resolveTemplate(v, ctx) : v;
+        }
+
+        const actionName = nodeDef.pluginAction || inst.definition.defaultAction || Object.keys(inst.definition.actions)[0];
+        const result = await executePluginWithWait(inst, actionName, resolvedParams, nodeDef.pluginWait);
+
+        if (result.ok) {
+          nodeState.status = 'done';
+          nodeState.completedAt = new Date().toISOString();
+          // Store plugin outputs
+          for (const [name, value] of Object.entries(result.output)) {
+            nodeState.outputs[name] = typeof value === 'string' ? value : JSON.stringify(value);
+          }
+          savePipeline(pipeline);
+          notifyStep(pipeline, nodeId, 'done');
+          console.log(`[pipeline] Plugin ${nodeDef.plugin}.${actionName}: done (${result.duration}ms)`);
+        } else {
+          throw new Error(result.error || 'Plugin action failed');
+        }
+      } catch (err: any) {
+        nodeState.status = 'failed';
+        nodeState.error = err.message;
+        nodeState.completedAt = new Date().toISOString();
+        savePipeline(pipeline);
+        notifyStep(pipeline, nodeId, 'failed', err.message);
+        console.error(`[pipeline] Plugin ${nodeDef.plugin}: failed — ${err.message}`);
+      }
+      continue;
+    }
+
+    // ── Shell/Agent mode: create task ──
     const taskMode = nodeDef.mode === 'shell' ? 'shell' : 'prompt';
     const task = createTask({
       projectName: projectInfo.name,

package/lib/plugins/executor.ts

@@ -0,0 +1,347 @@
+/**
+ * Plugin Executor — runs plugin actions (http, poll, shell, script).
+ *
+ * Resolves templates ({{config.x}}, {{params.x}}) and executes the action.
+ */
+
+import { spawn } from 'node:child_process';
+import type { PluginAction, PluginActionResult, InstalledPlugin } from './types';
+
+// ─── Template Resolution ─────────────────────────────────
+
+function resolveTemplate(template: string, ctx: Record<string, any>): string {
+  return template.replace(/\{\{(\w+)\.(\w+)\}\}/g, (_, scope, key) => {
+    return ctx[scope]?.[key] ?? '';
+  }).replace(/\{\{(\w+)\s*\|\s*json\}\}/g, (_, scope) => {
+    return JSON.stringify(ctx[scope] || {});
+  });
+}
+
+function resolveObject(obj: Record<string, string> | undefined, ctx: Record<string, any>): Record<string, string> {
+  if (!obj) return {};
+  const result: Record<string, string> = {};
+  for (const [k, v] of Object.entries(obj)) {
+    result[k] = resolveTemplate(v, ctx);
+  }
+  return result;
+}
+
+// ─── JSONPath-like extraction ────────────────────────────
+
+function extractValue(data: any, path: string): any {
+  if (path === '$body' || path === '$stdout') return typeof data === 'string' ? data : JSON.stringify(data);
+  if (path.startsWith('$.')) {
+    const keys = path.slice(2).split('.');
+    let current = data;
+    for (const key of keys) {
+      if (current == null) return undefined;
+      current = current[key];
+    }
+    return current;
+  }
+  return data;
+}
+
+function extractOutputs(data: any, outputSpec: Record<string, string> | undefined): Record<string, any> {
+  if (!outputSpec) return { result: data };
+  const result: Record<string, any> = {};
+  for (const [name, path] of Object.entries(outputSpec)) {
+    result[name] = extractValue(data, path);
+  }
+  return result;
+}
+
+// ─── Executors ───────────────────────────────────────────
+
+async function executeHttp(action: PluginAction, ctx: Record<string, any>): Promise<PluginActionResult> {
+  const url = resolveTemplate(action.url || '', ctx);
+  const method = (action.method || 'GET').toUpperCase();
+  const headers = resolveObject(action.headers, ctx);
+  const body = action.body ? resolveTemplate(action.body, ctx) : undefined;
+
+  const startTime = Date.now();
+  try {
+    const res = await fetch(url, {
+      method,
+      headers: { 'Content-Type': 'application/json', ...headers },
+      body: method !== 'GET' ? body : undefined,
+    });
+
+    let data: any;
+    const contentType = res.headers.get('content-type') || '';
+    if (contentType.includes('json')) {
+      data = await res.json();
+    } else {
+      data = await res.text();
+    }
+
+    return {
+      ok: res.ok,
+      output: extractOutputs(data, action.output),
+      rawResponse: typeof data === 'string' ? data : JSON.stringify(data),
+      duration: Date.now() - startTime,
+    };
+  } catch (err: any) {
+    return { ok: false, output: {}, error: err.message, duration: Date.now() - startTime };
+  }
+}
+
+async function executePoll(action: PluginAction, ctx: Record<string, any>): Promise<PluginActionResult> {
+  const url = resolveTemplate(action.url || '', ctx);
+  const headers = resolveObject(action.headers, ctx);
+  const interval = (action.interval || 30) * 1000;
+  const timeout = (action.timeout || 1800) * 1000;
+  const untilExpr = action.until || '$.result != null';
+
+  const startTime = Date.now();
+
+  while (Date.now() - startTime < timeout) {
+    try {
+      const res = await fetch(url, { headers });
+      const data = await res.json();
+
+      // Evaluate condition
+      const conditionMet = evaluateCondition(data, untilExpr);
+      if (conditionMet) {
+        return {
+          ok: true,
+          output: extractOutputs(data, action.output),
+          rawResponse: JSON.stringify(data),
+          duration: Date.now() - startTime,
+        };
+      }
+    } catch {}
+
+    // Wait before next poll
+    await new Promise(r => setTimeout(r, interval));
+  }
+
+  return { ok: false, output: {}, error: 'Poll timeout', duration: Date.now() - startTime };
+}
+
+function evaluateCondition(data: any, expr: string): boolean {
+  // Simple condition parser: "$.field != null", "$.field == value"
+  const match = expr.match(/^(\$\.[.\w]+)\s*(==|!=|>|<)\s*(.+)$/);
+  if (!match) return false;
+  const [, path, op, expected] = match;
+  const actual = extractValue(data, path);
+  const exp = expected === 'null' ? null : expected === 'true' ? true : expected === 'false' ? false : expected;
+
+  switch (op) {
+    case '==': return actual == exp;
+    case '!=': return actual != exp;
+    case '>': return Number(actual) > Number(exp);
+    case '<': return Number(actual) < Number(exp);
+    default: return false;
+  }
+}
+
+async function executeShell(action: PluginAction, ctx: Record<string, any>): Promise<PluginActionResult> {
+  const command = resolveTemplate(action.command || '', ctx);
+  const rawCwd = action.cwd ? resolveTemplate(action.cwd, ctx) : '';
+  const cwd = rawCwd || undefined;
+
+  const startTime = Date.now();
+  const timeout = (action.timeout || 300) * 1000;
+
+  return new Promise((resolve) => {
+    let resolved = false;
+    const done = (result: PluginActionResult) => {
+      if (resolved) return;
+      resolved = true;
+      resolve(result);
+    };
+
+    try {
+      // Use spawn with detached: true so the child gets its own process group.
+      // This prevents crashes/signals in the child (e.g., Playwright browser crash)
+      // from propagating to Forge's process group and killing sibling services.
+      const child = spawn('/bin/sh', ['-c', command], {
+        cwd,
+        stdio: ['ignore', 'pipe', 'pipe'],
+        env: { ...process.env, FORCE_COLOR: '0' },
+        detached: true,
+      });
+
+      let stdout = '';
+      let stderr = '';
+
+      child.stdout?.on('data', (chunk: Buffer) => {
+        stdout += chunk.toString('utf-8');
+        // Cap buffer to prevent memory issues
+        if (stdout.length > 10 * 1024 * 1024) {
+          stdout = stdout.slice(-5 * 1024 * 1024);
+        }
+      });
+      child.stderr?.on('data', (chunk: Buffer) => {
+        stderr += chunk.toString('utf-8');
+        if (stderr.length > 10 * 1024 * 1024) {
+          stderr = stderr.slice(-5 * 1024 * 1024);
+        }
+      });
+
+      console.log(`[plugin-shell] pid=${child.pid} pgid=new command=${command.slice(0, 80)}`);
+
+      child.on('error', (e) => {
+        console.log(`[plugin-shell] pid=${child.pid} error: ${e.message}`);
+        done({
+          ok: false,
+          output: {},
+          error: `Process error: ${e.message}`,
+          duration: Date.now() - startTime,
+        });
+      });
+
+      // Use 'close' instead of 'exit' to ensure all stdout/stderr data is collected
+      child.on('close', (code, signal) => {
+        child.unref();
+        console.log(`[plugin-shell] pid=${child.pid} closed code=${code} signal=${signal} stdout=${stdout.length}b stderr=${stderr.length}b`);
+        const combined = (stdout || stderr || '').trim();
+        // Treat SIGTERM (143) with output as a normal completion — many test runners
+        // and complex commands send SIGTERM to their process group during cleanup,
+        // which kills the shell wrapper but doesn't indicate a real failure.
+        const killedBySignal = code === null || code === 143 || code === 130;
+        const hasOutput = combined.length > 0;
+        const effectiveOk = code === 0 || (killedBySignal && hasOutput);
+
+        done({
+          ok: effectiveOk,
+          output: extractOutputs(combined, action.output),
+          error: effectiveOk ? undefined : (signal ? `Killed by ${signal}` : `Exit code ${code}`),
+          rawResponse: combined.slice(0, 5000),
+          duration: Date.now() - startTime,
+        });
+      });
+
+      // Timeout: kill the child's process group
+      const timer = setTimeout(() => {
+        try { process.kill(-child.pid!, 'SIGTERM'); } catch {}
+        setTimeout(() => {
+          try { process.kill(-child.pid!, 'SIGKILL'); } catch {}
+        }, 3000);
+        done({
+          ok: false,
+          output: {},
+          error: `Command timed out after ${timeout / 1000}s`,
+          rawResponse: (stderr || stdout || '').slice(0, 5000),
+          duration: Date.now() - startTime,
+        });
+      }, timeout);
+      // Don't let the timer keep the process alive
+      timer.unref();
+
+      child.on('exit', () => clearTimeout(timer));
+    } catch (e: any) {
+      done({
+        ok: false,
+        output: {},
+        error: `Failed to spawn: ${e.message}`,
+        duration: Date.now() - startTime,
+      });
+    }
+  });
+}
+
+// ─── Public API ──────────────────────────────────────────
+
+/**
+ * Execute a plugin action.
+ * @param plugin - Installed plugin instance
+ * @param actionName - Action to execute (e.g., 'trigger', 'wait')
+ * @param params - Per-use parameters
+ */
+export async function executePluginAction(
+  plugin: InstalledPlugin,
+  actionName: string,
+  params: Record<string, any> = {},
+): Promise<PluginActionResult> {
+  // Auto-resolve action by config.mode prefix: "test" → "docker_test" if mode=docker
+  let action = plugin.definition.actions[actionName];
+  if (!action && plugin.config.mode) {
+    const modeAction = `${plugin.config.mode}_${actionName}`;
+    action = plugin.definition.actions[modeAction];
+  }
+  if (!action) {
+    return { ok: false, output: {}, error: `Action "${actionName}" not found in plugin "${plugin.id}"` };
+  }
+
+  // Fill missing config values with definition defaults (handles plugins installed before defaults were added)
+  const configWithDefaults = { ...plugin.config };
+  if (plugin.definition.config) {
+    for (const [k, fieldDef] of Object.entries(plugin.definition.config)) {
+      if (configWithDefaults[k] == null && (fieldDef as any).default != null) {
+        configWithDefaults[k] = (fieldDef as any).default;
+      }
+    }
+  }
+
+  // params can override config values — supports multi-instance scenarios
+  // e.g., different Jenkins URLs per pipeline node via params.jenkins_url
+  const mergedConfig = { ...configWithDefaults };
+  const remainingParams = { ...params };
+  for (const k of Object.keys(params)) {
+    if (k in plugin.definition.config && params[k] != null) {
+      mergedConfig[k] = params[k];
+      delete remainingParams[k];
+    }
+  }
+
+  // Config fields named "default_xxx" provide fallback for params.xxx
+  for (const [k, v] of Object.entries(mergedConfig)) {
+    if (k.startsWith('default_')) {
+      const paramKey = k.slice(8); // "default_job" → "job"
+      if (remainingParams[paramKey] == null && v != null) {
+        remainingParams[paramKey] = v;
+      }
+    }
+  }
+
+  const ctx = {
+    config: mergedConfig,
+    params: remainingParams,
+  };
+
+  console.log(`[plugin] ${plugin.id}.${actionName}: executing (${action.run})`);
+
+  switch (action.run) {
+    case 'http':
+      return executeHttp(action, ctx);
+    case 'poll':
+      return executePoll(action, ctx);
+    case 'shell':
+      return executeShell(action, ctx);
+    case 'script':
+      // TODO: implement script execution
+      return { ok: false, output: {}, error: 'Script execution not yet implemented' };
+    default:
+      return { ok: false, output: {}, error: `Unknown action type: ${action.run}` };
+  }
+}
+
+/**
+ * Execute a plugin with auto-wait.
+ * Runs the specified action, then if wait=true, runs the 'wait' action.
+ */
+export async function executePluginWithWait(
+  plugin: InstalledPlugin,
+  actionName: string,
+  params: Record<string, any> = {},
+  wait: boolean = false,
+): Promise<PluginActionResult> {
+  const result = await executePluginAction(plugin, actionName, params);
+  if (!result.ok || !wait) return result;
+
+  // Auto-wait: if plugin has a 'wait' action, run it
+  if (plugin.definition.actions['wait']) {
+    const waitResult = await executePluginAction(plugin, 'wait', params);
+    return {
+      ok: waitResult.ok,
+      output: { ...result.output, ...waitResult.output },
+      rawResponse: waitResult.rawResponse,
+      duration: (result.duration || 0) + (waitResult.duration || 0),
+      error: waitResult.error,
+    };
+  }
+
+  return result;
+}

package/lib/plugins/registry.ts

@@ -0,0 +1,228 @@
+/**
+ * Plugin Registry — load, install, uninstall, list plugins.
+ *
+ * Plugins are stored as YAML files:
+ * - Built-in: lib/builtin-plugins/*.yaml
+ * - User-installed: ~/.forge/plugins/<id>/plugin.yaml
+ *
+ * Installed plugin configs are stored in:
+ * - ~/.forge/data/plugin-configs.json
+ */
+
+import { existsSync, readdirSync, readFileSync, writeFileSync, mkdirSync, rmSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { homedir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import YAML from 'yaml';
+import type { PluginDefinition, InstalledPlugin, PluginSource } from './types';
+
+const _filename = typeof __filename !== 'undefined' ? __filename : fileURLToPath(import.meta.url);
+const _dirname = typeof __dirname !== 'undefined' ? __dirname : dirname(_filename);
+
+const BUILTIN_DIR_COMPILED = join(_dirname, '..', 'builtin-plugins');
+const BUILTIN_DIR_SOURCE = join(process.cwd(), 'lib', 'builtin-plugins');
+const BUILTIN_DIR = existsSync(BUILTIN_DIR_COMPILED) ? BUILTIN_DIR_COMPILED : BUILTIN_DIR_SOURCE;
+const USER_PLUGINS_DIR = join(homedir(), '.forge', 'plugins');
+const CONFIGS_FILE = join(homedir(), '.forge', 'data', 'plugin-configs.json');
+
+// ─── Load Plugin Definition ──────────────────────────────
+
+function loadPluginYaml(filePath: string): PluginDefinition | null {
+  try {
+    const raw = readFileSync(filePath, 'utf-8');
+    const def = YAML.parse(raw) as PluginDefinition;
+    if (!def.id || !def.name || !def.actions) return null;
+    // Defaults
+    if (!def.config) def.config = {};
+    if (!def.params) def.params = {};
+    if (!def.icon) def.icon = '🔌';
+    if (!def.version) def.version = '0.0.1';
+    return def;
+  } catch {
+    return null;
+  }
+}
+
+// ─── Config Storage ──────────────────────────────────────
+
+function loadConfigs(): Record<string, { config: Record<string, any>; installedAt: string; enabled: boolean }> {
+  try {
+    if (existsSync(CONFIGS_FILE)) {
+      return JSON.parse(readFileSync(CONFIGS_FILE, 'utf-8'));
+    }
+  } catch {}
+  return {};
+}
+
+function saveConfigs(configs: Record<string, any>): void {
+  const dir = dirname(CONFIGS_FILE);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(CONFIGS_FILE, JSON.stringify(configs, null, 2));
+}
+
+// ─── Public API ──────────────────────────────────────────
+
+/** List all available plugins (built-in + user-installed) */
+export function listPlugins(): PluginSource[] {
+  const sources: PluginSource[] = [];
+  const configs = loadConfigs();
+
+  // Check if any config entry references this plugin (base install or instance)
+  const isInstalledOrHasInstance = (id: string) =>
+    Object.entries(configs).some(([key, cfg]) => key === id || (cfg as any).source === id);
+
+  // Built-in plugins
+  if (existsSync(BUILTIN_DIR)) {
+    for (const file of readdirSync(BUILTIN_DIR).filter(f => f.endsWith('.yaml') || f.endsWith('.yml'))) {
+      const def = loadPluginYaml(join(BUILTIN_DIR, file));
+      if (def) {
+        sources.push({
+          id: def.id,
+          name: def.name,
+          icon: def.icon,
+          version: def.version,
+          author: def.author || 'forge',
+          description: def.description || '',
+          source: 'builtin',
+          installed: isInstalledOrHasInstance(def.id),
+          configCount: Object.keys(def.config).length,
+        });
+      }
+    }
+  }
+
+  // User-installed plugins
+  mkdirSync(USER_PLUGINS_DIR, { recursive: true });
+  for (const dir of readdirSync(USER_PLUGINS_DIR, { withFileTypes: true })) {
+    if (!dir.isDirectory()) continue;
+    const yamlPath = join(USER_PLUGINS_DIR, dir.name, 'plugin.yaml');
+    const ymlPath = join(USER_PLUGINS_DIR, dir.name, 'plugin.yml');
+    const filePath = existsSync(yamlPath) ? yamlPath : existsSync(ymlPath) ? ymlPath : null;
+    if (!filePath) continue;
+    const def = loadPluginYaml(filePath);
+    if (def) {
+      // Don't duplicate if also built-in
+      if (sources.some(s => s.id === def.id)) continue;
+      sources.push({
+        id: def.id,
+        name: def.name,
+        icon: def.icon,
+        version: def.version,
+        author: def.author || 'local',
+        description: def.description || '',
+        source: 'local',
+        installed: isInstalledOrHasInstance(def.id),
+        configCount: Object.keys(def.config).length,
+      });
+    }
+  }
+
+  return sources;
+}
+
+/** Get a plugin definition by ID */
+export function getPlugin(id: string): PluginDefinition | null {
+  // Check built-in first
+  if (existsSync(BUILTIN_DIR)) {
+    for (const file of readdirSync(BUILTIN_DIR).filter(f => f.endsWith('.yaml') || f.endsWith('.yml'))) {
+      const def = loadPluginYaml(join(BUILTIN_DIR, file));
+      if (def?.id === id) return def;
+    }
+  }
+
+  // Check user plugins
+  const yamlPath = join(USER_PLUGINS_DIR, id, 'plugin.yaml');
+  const ymlPath = join(USER_PLUGINS_DIR, id, 'plugin.yml');
+  if (existsSync(yamlPath)) return loadPluginYaml(yamlPath);
+  if (existsSync(ymlPath)) return loadPluginYaml(ymlPath);
+
+  return null;
+}
+
+/** Get an installed plugin with its config */
+export function getInstalledPlugin(id: string): InstalledPlugin | null {
+  const configs = loadConfigs();
+  const cfg = configs[id] as any;
+  if (!cfg) return null;
+  // Resolve definition: use source field for instances, fallback to id
+  const sourceId = cfg.source || id;
+  const def = getPlugin(sourceId);
+  if (!def) return null;
+  return {
+    id,
+    definition: def,
+    config: cfg.config || {},
+    installedAt: cfg.installedAt || new Date().toISOString(),
+    enabled: cfg.enabled !== false,
+    instanceName: cfg.name,
+    source: sourceId !== id ? sourceId : undefined,
+  };
+}
+
+/** List all installed plugins (including instances) */
+export function listInstalledPlugins(): InstalledPlugin[] {
+  const configs = loadConfigs();
+  const installed: InstalledPlugin[] = [];
+  for (const [id, cfg] of Object.entries(configs)) {
+    const sourceId = (cfg as any).source || id;
+    const def = getPlugin(sourceId);
+    if (def) {
+      installed.push({
+        id,
+        definition: def,
+        config: (cfg as any).config || {},
+        installedAt: (cfg as any).installedAt || '',
+        enabled: (cfg as any).enabled !== false,
+        instanceName: (cfg as any).name,
+        source: sourceId !== id ? sourceId : undefined,
+      });
+    }
+  }
+  return installed;
+}
+
+/** Install a plugin or create an instance */
+export function installPlugin(id: string, config: Record<string, any>, opts?: { source?: string; name?: string }): boolean {
+  const sourceId = opts?.source || id;
+  const def = getPlugin(sourceId);
+  if (!def) return false;
+  const configs = loadConfigs();
+  configs[id] = {
+    config,
+    installedAt: new Date().toISOString(),
+    enabled: true,
+    ...(opts?.source ? { source: opts.source } : {}),
+    ...(opts?.name ? { name: opts.name } : {}),
+  };
+  saveConfigs(configs);
+  console.log(`[plugins] Installed: ${opts?.name || def.name} (${id}${opts?.source ? ' ← ' + opts.source : ''})`);
+  return true;
+}
+
+/** Uninstall a plugin or instance */
+export function uninstallPlugin(id: string): boolean {
+  const configs = loadConfigs();
+  if (!configs[id]) return false;
+  delete configs[id];
+  saveConfigs(configs);
+  console.log(`[plugins] Uninstalled: ${id}`);
+  return true;
+}
+
+/** Update plugin config */
+export function updatePluginConfig(id: string, config: Record<string, any>): boolean {
+  const configs = loadConfigs();
+  if (!configs[id]) return false;
+  (configs[id] as any).config = config;
+  saveConfigs(configs);
+  return true;
+}
+
+/** Enable/disable a plugin */
+export function setPluginEnabled(id: string, enabled: boolean): boolean {
+  const configs = loadConfigs();
+  if (!configs[id]) return false;
+  (configs[id] as any).enabled = enabled;
+  saveConfigs(configs);
+  return true;
+}