@soleri/core 2.10.0 → 2.12.0

package/src/plugins/plugin-loader.ts

@@ -0,0 +1,183 @@
+/**
+ * Plugin Loader — scans directories, validates manifests, loads plugins.
+ *
+ * Plugin directories (checked in order, first occurrence wins):
+ *   1. ~/.{agentId}/plugins/ (global plugins)
+ *   2. .{agentId}/plugins/  (project plugins)
+ *   3. Custom directories (via config)
+ *
+ * Each plugin is a directory containing `soleri-plugin.json`.
+ */
+
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import {
+  pluginManifestSchema,
+  type LoadedPlugin,
+  type LoadResult,
+  type PluginProvenance,
+} from './types.js';
+
+// =============================================================================
+// LOADER
+// =============================================================================
+
+const MANIFEST_FILENAME = 'soleri-plugin.json';
+
+/**
+ * Load all plugins from standard + custom directories.
+ */
+export function loadPlugins(
+  agentId: string,
+  projectPath?: string,
+  extraDirs: string[] = [],
+): LoadResult {
+  const result: LoadResult = { loaded: [], errors: [] };
+  const seen = new Set<string>();
+
+  const dirs: Array<{ path: string; provenance: PluginProvenance }> = [];
+
+  // Global: ~/.{agentId}/plugins/
+  const globalDir = join(homedir(), `.${agentId}`, 'plugins');
+  if (existsSync(globalDir)) {
+    dirs.push({ path: globalDir, provenance: 'global' });
+  }
+
+  // Project: .{agentId}/plugins/
+  if (projectPath) {
+    const projectDir = join(projectPath, `.${agentId}`, 'plugins');
+    if (existsSync(projectDir)) {
+      dirs.push({ path: projectDir, provenance: 'project' });
+    }
+  }
+
+  // Custom
+  for (const dir of extraDirs) {
+    if (existsSync(dir)) {
+      dirs.push({ path: dir, provenance: 'custom' });
+    }
+  }
+
+  for (const { path: parentDir, provenance } of dirs) {
+    try {
+      const entries = readdirSync(parentDir, { withFileTypes: true });
+      for (const entry of entries) {
+        if (!entry.isDirectory()) continue;
+
+        const pluginDir = join(parentDir, entry.name);
+        const loaded = loadSinglePlugin(pluginDir, provenance);
+
+        if (loaded.error) {
+          result.errors.push({ directory: pluginDir, error: loaded.error });
+          continue;
+        }
+
+        if (loaded.plugin) {
+          if (seen.has(loaded.plugin.manifest.id)) continue; // first wins
+          seen.add(loaded.plugin.manifest.id);
+          result.loaded.push(loaded.plugin);
+        }
+      }
+    } catch {
+      // Directory not scannable — skip
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Load a single plugin from a directory.
+ */
+function loadSinglePlugin(
+  pluginDir: string,
+  provenance: PluginProvenance,
+): { plugin?: LoadedPlugin; error?: string } {
+  const manifestPath = join(pluginDir, MANIFEST_FILENAME);
+
+  if (!existsSync(manifestPath)) {
+    return { error: `No ${MANIFEST_FILENAME} found in ${pluginDir}` };
+  }
+
+  let raw: unknown;
+  try {
+    raw = JSON.parse(readFileSync(manifestPath, 'utf-8'));
+  } catch (e) {
+    return {
+      error: `Invalid JSON in ${manifestPath}: ${e instanceof Error ? e.message : String(e)}`,
+    };
+  }
+
+  const parseResult = pluginManifestSchema.safeParse(raw);
+  if (!parseResult.success) {
+    const issues = parseResult.error.issues
+      .map((i) => `${i.path.join('.')}: ${i.message}`)
+      .join('; ');
+    return { error: `Invalid manifest in ${pluginDir}: ${issues}` };
+  }
+
+  return {
+    plugin: {
+      manifest: parseResult.data,
+      directory: pluginDir,
+      provenance,
+    },
+  };
+}
+
+// =============================================================================
+// DEPENDENCY HELPERS
+// =============================================================================
+
+/**
+ * Validate that all plugin dependencies are satisfiable.
+ */
+export function validateDependencies(
+  plugins: LoadedPlugin[],
+): Array<{ pluginId: string; missingDep: string }> {
+  const available = new Set(plugins.map((p) => p.manifest.id));
+  const errors: Array<{ pluginId: string; missingDep: string }> = [];
+
+  for (const { manifest } of plugins) {
+    for (const dep of manifest.dependencies) {
+      if (!available.has(dep)) {
+        errors.push({ pluginId: manifest.id, missingDep: dep });
+      }
+    }
+  }
+
+  return errors;
+}
+
+/**
+ * Topological sort by dependency order (no-deps first).
+ * Detects and breaks circular dependencies.
+ */
+export function sortByDependencies(plugins: LoadedPlugin[]): LoadedPlugin[] {
+  const byId = new Map(plugins.map((p) => [p.manifest.id, p]));
+  const sorted: LoadedPlugin[] = [];
+  const visited = new Set<string>();
+  const visiting = new Set<string>();
+
+  function visit(id: string): void {
+    if (visited.has(id)) return;
+    if (visiting.has(id)) return; // circular — break
+    visiting.add(id);
+    const plugin = byId.get(id);
+    if (plugin) {
+      for (const dep of plugin.manifest.dependencies) {
+        visit(dep);
+      }
+      sorted.push(plugin);
+    }
+    visiting.delete(id);
+    visited.add(id);
+  }
+
+  for (const { manifest } of plugins) {
+    visit(manifest.id);
+  }
+
+  return sorted;
+}

package/src/plugins/plugin-registry.ts

@@ -0,0 +1,187 @@
+/**
+ * Plugin Registry — tracks loaded plugins and their lifecycle.
+ *
+ * Not a singleton — lives on AgentRuntime for testability.
+ * Lifecycle: load → register → activate → (deactivate | error)
+ */
+
+import type {
+  LoadedPlugin,
+  RegisteredPlugin,
+  PluginContext,
+  PluginFacadeBuilder,
+} from './types.js';
+import type { FacadeConfig, OpDefinition } from '../facades/types.js';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+export class PluginRegistry {
+  private plugins = new Map<string, RegisteredPlugin>();
+
+  /**
+   * Register a loaded plugin. Does NOT activate it — call activate() separately.
+   */
+  register(loaded: LoadedPlugin): RegisteredPlugin {
+    const existing = this.plugins.get(loaded.manifest.id);
+    if (existing) {
+      throw new Error(`Plugin "${loaded.manifest.id}" is already registered`);
+    }
+
+    const registered: RegisteredPlugin = {
+      id: loaded.manifest.id,
+      manifest: loaded.manifest,
+      directory: loaded.directory,
+      provenance: loaded.provenance,
+      status: 'registered',
+      facades: [],
+      registeredAt: Date.now(),
+    };
+
+    this.plugins.set(registered.id, registered);
+    return registered;
+  }
+
+  /**
+   * Activate a plugin — builds facades from its manifest or JS module.
+   *
+   * If the plugin directory contains an `index.js` with a `createFacades` export,
+   * that function is called to build facades dynamically. Otherwise, facade stubs
+   * are created from the manifest's `facades` array (static ops with no-op handlers).
+   */
+  async activate(pluginId: string, ctx: PluginContext): Promise<RegisteredPlugin> {
+    const plugin = this.plugins.get(pluginId);
+    if (!plugin) throw new Error(`Plugin "${pluginId}" is not registered`);
+    if (plugin.status === 'active') return plugin;
+
+    try {
+      // Try dynamic facade builder first
+      let facades = await this.tryLoadFacadeBuilder(plugin, ctx);
+
+      // Fall back to static manifest facades
+      if (!facades) {
+        facades = this.buildStaticFacades(plugin);
+      }
+
+      plugin.facades = facades;
+      plugin.status = 'active';
+      plugin.activatedAt = Date.now();
+      plugin.error = undefined;
+    } catch (e) {
+      plugin.status = 'error';
+      plugin.error = e instanceof Error ? e.message : String(e);
+    }
+
+    return plugin;
+  }
+
+  /**
+   * Deactivate a plugin — removes its facades from the runtime.
+   */
+  deactivate(pluginId: string): boolean {
+    const plugin = this.plugins.get(pluginId);
+    if (!plugin) return false;
+
+    plugin.status = 'deactivated';
+    plugin.facades = [];
+    return true;
+  }
+
+  /**
+   * Unregister a plugin completely.
+   */
+  unregister(pluginId: string): boolean {
+    const plugin = this.plugins.get(pluginId);
+    if (!plugin) return false;
+
+    if (plugin.status === 'active') {
+      this.deactivate(pluginId);
+    }
+
+    return this.plugins.delete(pluginId);
+  }
+
+  /**
+   * Get a registered plugin by ID.
+   */
+  get(pluginId: string): RegisteredPlugin | undefined {
+    return this.plugins.get(pluginId);
+  }
+
+  /**
+   * List all registered plugins.
+   */
+  list(): RegisteredPlugin[] {
+    return Array.from(this.plugins.values());
+  }
+
+  /**
+   * Get all active facades from all active plugins.
+   */
+  getActiveFacades(): FacadeConfig[] {
+    const facades: FacadeConfig[] = [];
+    for (const plugin of this.plugins.values()) {
+      if (plugin.status === 'active') {
+        facades.push(...plugin.facades);
+      }
+    }
+    return facades;
+  }
+
+  /**
+   * Get all active ops (flattened from all active plugin facades).
+   */
+  getActiveOps(): OpDefinition[] {
+    return this.getActiveFacades().flatMap((f) => f.ops);
+  }
+
+  // ─── Private ────────────────────────────────────────────────────────
+
+  /**
+   * Try to load a JS module with `createFacades` export from the plugin directory.
+   * Returns null if no module found or no export.
+   */
+  private async tryLoadFacadeBuilder(
+    plugin: RegisteredPlugin,
+    ctx: PluginContext,
+  ): Promise<FacadeConfig[] | null> {
+    const moduleFile = join(plugin.directory, 'index.js');
+    if (!existsSync(moduleFile)) {
+      return null;
+    }
+
+    try {
+      // Dynamic import of plugin's index.js
+      const mod = (await import(pathToFileURL(moduleFile).href)) as {
+        createFacades?: PluginFacadeBuilder;
+      };
+      if (typeof mod.createFacades === 'function') {
+        return mod.createFacades(ctx);
+      }
+      throw new Error(`Plugin module "${moduleFile}" must export createFacades(ctx)`);
+    } catch (e) {
+      throw new Error(
+        `Failed to load plugin module "${moduleFile}": ${e instanceof Error ? e.message : String(e)}`, { cause: e },
+      );
+    }
+  }
+
+  /**
+   * Build facade configs from the manifest's static facade definitions.
+   * These have no-op handlers — useful for schema discovery and documentation.
+   */
+  private buildStaticFacades(plugin: RegisteredPlugin): FacadeConfig[] {
+    return plugin.manifest.facades.map((f) => ({
+      name: f.name,
+      description: f.description,
+      ops: f.ops.map((op) => ({
+        name: op.name,
+        description: op.description,
+        auth: op.auth as 'read' | 'write' | 'admin',
+        handler: async () => ({
+          error: `Op "${op.name}" is a static plugin op — no handler implementation provided. Add an index.js with createFacades() to ${plugin.directory}`,
+        }),
+      })),
+    }));
+  }
+}

package/src/plugins/types.ts

@@ -0,0 +1,119 @@
+/**
+ * Plugin System — Types & Manifest Schema
+ *
+ * A plugin is a directory containing a `soleri-plugin.json` manifest
+ * and optionally additional intelligence data. Plugins register
+ * OpDefinition[] (facades) dynamically without re-scaffolding.
+ */
+
+import { z } from 'zod';
+import type { FacadeConfig } from '../facades/types.js';
+
+// =============================================================================
+// MANIFEST SCHEMA (validated at load time)
+// =============================================================================
+
+export const pluginManifestSchema = z.object({
+  id: z.string().regex(/^[a-z0-9-]+$/, 'Plugin ID must be lowercase alphanumeric with hyphens'),
+  name: z.string().min(1),
+  version: z.string().regex(/^\d+\.\d+\.\d+$/, 'Version must be semver (x.y.z)'),
+  description: z.string().optional().default(''),
+  /** Domain this plugin provides knowledge/ops for */
+  domain: z.string().optional(),
+  /** Plugin IDs this plugin depends on (must be loaded first) */
+  dependencies: z.array(z.string()).optional().default([]),
+  /** Facade definitions — each becomes an MCP tool */
+  facades: z
+    .array(
+      z.object({
+        name: z.string(),
+        description: z.string().optional().default(''),
+        ops: z.array(
+          z.object({
+            name: z.string(),
+            description: z.string().optional().default(''),
+            auth: z.enum(['read', 'write', 'admin']).optional().default('read'),
+          }),
+        ),
+      }),
+    )
+    .optional()
+    .default([]),
+  /** Intelligence entries to seed into the vault */
+  intelligence: z
+    .array(
+      z.object({
+        id: z.string(),
+        type: z.string(),
+        domain: z.string().optional(),
+        title: z.string(),
+        severity: z.enum(['critical', 'warning', 'suggestion']).optional(),
+        description: z.string(),
+        tags: z.array(z.string()).optional().default([]),
+      }),
+    )
+    .optional()
+    .default([]),
+});
+
+export type PluginManifest = z.infer<typeof pluginManifestSchema>;
+
+// =============================================================================
+// PLUGIN TYPES
+// =============================================================================
+
+export type PluginStatus = 'registered' | 'active' | 'error' | 'deactivated';
+export type PluginProvenance = 'global' | 'project' | 'custom';
+
+/**
+ * A loaded plugin — manifest validated, ready for activation.
+ */
+export interface LoadedPlugin {
+  manifest: PluginManifest;
+  directory: string;
+  provenance: PluginProvenance;
+}
+
+/**
+ * A registered plugin in the runtime — tracks lifecycle state.
+ */
+export interface RegisteredPlugin {
+  id: string;
+  manifest: PluginManifest;
+  directory: string;
+  provenance: PluginProvenance;
+  status: PluginStatus;
+  error?: string;
+  facades: FacadeConfig[];
+  activatedAt?: number;
+  registeredAt: number;
+}
+
+/**
+ * Plugin facade builder — plugins provide this function to create ops
+ * that have access to the agent runtime.
+ *
+ * Plugin JS modules export: `export function createFacades(ctx): FacadeConfig[]`
+ */
+export type PluginFacadeBuilder = (ctx: PluginContext) => FacadeConfig[];
+
+/**
+ * Context passed to plugin facade builders during activation.
+ */
+export interface PluginContext {
+  /** The agent runtime — full access to vault, brain, planner, etc. */
+  runtime: unknown; // AgentRuntime — kept as unknown to avoid circular deps
+  /** The plugin's own manifest */
+  manifest: PluginManifest;
+  /** The plugin's directory on disk */
+  directory: string;
+}
+
+// =============================================================================
+// LOAD RESULT
+// =============================================================================
+
+export interface LoadResult {
+  loaded: LoadedPlugin[];
+  errors: Array<{ directory: string; error: string }>;
+}