profclaw 0.0.1-beta.1

package/dist/plugins/registry.js

@@ -0,0 +1,352 @@
+/**
+ * profClaw Plugin Registry
+ *
+ * Manages plugin registration, instantiation, and health monitoring.
+ */
+// ============================================================================
+// Search Provider Registry
+// ============================================================================
+class SearchProviderRegistry {
+    definitions = new Map();
+    instances = new Map();
+    configs = new Map();
+    healthCache = new Map();
+    HEALTH_CACHE_TTL = 60_000; // 1 minute
+    /**
+     * Register a search provider plugin
+     */
+    register(definition) {
+        this.definitions.set(definition.metadata.id, definition);
+        console.log(`[Plugins] Registered search provider: ${definition.metadata.name}`);
+    }
+    /**
+     * Unregister a search provider
+     */
+    unregister(pluginId) {
+        this.definitions.delete(pluginId);
+        // Remove any instances using this plugin
+        for (const [configId, config] of this.configs) {
+            if (config.pluginId === pluginId) {
+                this.instances.delete(configId);
+                this.configs.delete(configId);
+            }
+        }
+    }
+    /**
+     * Create a provider instance from config
+     */
+    create(config) {
+        const definition = this.definitions.get(config.pluginId);
+        if (!definition) {
+            throw new Error(`Unknown search provider plugin: ${config.pluginId}`);
+        }
+        const instance = definition.factory(config);
+        this.instances.set(config.id, instance);
+        this.configs.set(config.id, config);
+        return instance;
+    }
+    /**
+     * Get provider by config ID
+     */
+    get(configId) {
+        return this.instances.get(configId);
+    }
+    /**
+     * Get all active (enabled) providers
+     */
+    getActive() {
+        const active = [];
+        for (const [configId, config] of this.configs) {
+            if (config.enabled) {
+                const instance = this.instances.get(configId);
+                if (instance)
+                    active.push(instance);
+            }
+        }
+        // Sort by priority (higher first)
+        return active.sort((a, b) => {
+            const configA = this.getConfigByInstance(a);
+            const configB = this.getConfigByInstance(b);
+            return (configB?.priority || 0) - (configA?.priority || 0);
+        });
+    }
+    /**
+     * Get primary (highest priority enabled) provider
+     */
+    getPrimary() {
+        const active = this.getActive();
+        return active[0];
+    }
+    /**
+     * List all registered plugin IDs
+     */
+    listRegistered() {
+        return Array.from(this.definitions.keys());
+    }
+    /**
+     * Get plugin metadata
+     */
+    getMetadata(pluginId) {
+        return this.definitions.get(pluginId)?.metadata;
+    }
+    /**
+     * Get all plugin metadata
+     */
+    getAllMetadata() {
+        return Array.from(this.definitions.values()).map((d) => d.metadata);
+    }
+    /**
+     * Get settings schema for a plugin
+     */
+    getSettingsSchema(pluginId) {
+        return this.definitions.get(pluginId)?.settingsSchema;
+    }
+    /**
+     * Get config by instance
+     */
+    getConfigByInstance(instance) {
+        for (const [configId, inst] of this.instances) {
+            if (inst === instance) {
+                return this.configs.get(configId);
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Get all configs
+     */
+    getAllConfigs() {
+        return Array.from(this.configs.values());
+    }
+    /**
+     * Update config
+     */
+    updateConfig(configId, updates) {
+        const config = this.configs.get(configId);
+        if (config) {
+            const newConfig = { ...config, ...updates };
+            this.configs.set(configId, newConfig);
+            // Recreate instance with new config
+            const definition = this.definitions.get(config.pluginId);
+            if (definition) {
+                const instance = definition.factory(newConfig);
+                this.instances.set(configId, instance);
+            }
+        }
+    }
+    /**
+     * Delete config and instance
+     */
+    deleteConfig(configId) {
+        this.instances.delete(configId);
+        this.configs.delete(configId);
+        this.healthCache.delete(configId);
+    }
+    /**
+     * Get health status (cached)
+     */
+    async getHealth(configId) {
+        const cached = this.healthCache.get(configId);
+        const now = Date.now();
+        if (cached && now - cached.timestamp < this.HEALTH_CACHE_TTL) {
+            return cached.health;
+        }
+        const instance = this.instances.get(configId);
+        if (!instance) {
+            return {
+                healthy: false,
+                lastCheck: new Date(),
+                errorMessage: 'Provider not initialized',
+            };
+        }
+        try {
+            const health = await instance.healthCheck();
+            this.healthCache.set(configId, { health, timestamp: now });
+            return health;
+        }
+        catch (error) {
+            const health = {
+                healthy: false,
+                lastCheck: new Date(),
+                errorMessage: error instanceof Error ? error.message : 'Health check failed',
+            };
+            this.healthCache.set(configId, { health, timestamp: now });
+            return health;
+        }
+    }
+    /**
+     * Search with automatic fallback
+     */
+    async search(query, options, preferredProvider) {
+        const providers = this.getActive();
+        if (providers.length === 0) {
+            throw new Error('No search providers available');
+        }
+        // Try preferred provider first
+        if (preferredProvider) {
+            const preferred = this.get(preferredProvider);
+            if (preferred) {
+                try {
+                    return await preferred.search(query, options);
+                }
+                catch (error) {
+                    console.warn(`[Plugins] Preferred provider ${preferredProvider} failed, falling back:`, error);
+                }
+            }
+        }
+        // Try providers in priority order
+        for (const provider of providers) {
+            try {
+                const isAvailable = await provider.isAvailable();
+                if (!isAvailable)
+                    continue;
+                return await provider.search(query, options);
+            }
+            catch (error) {
+                console.warn(`[Plugins] Provider ${provider.metadata.id} failed:`, error);
+                continue;
+            }
+        }
+        throw new Error('All search providers failed');
+    }
+}
+// ============================================================================
+// Tool Provider Registry
+// ============================================================================
+class ToolProviderRegistry {
+    definitions = new Map();
+    instances = new Map();
+    configs = new Map();
+    register(definition) {
+        this.definitions.set(definition.metadata.id, definition);
+        console.log(`[Plugins] Registered tool provider: ${definition.metadata.name}`);
+    }
+    unregister(pluginId) {
+        this.definitions.delete(pluginId);
+        for (const [configId, config] of this.configs) {
+            if (config.pluginId === pluginId) {
+                this.instances.delete(configId);
+                this.configs.delete(configId);
+            }
+        }
+    }
+    create(config) {
+        const definition = this.definitions.get(config.pluginId);
+        if (!definition) {
+            throw new Error(`Unknown tool provider plugin: ${config.pluginId}`);
+        }
+        const instance = definition.factory(config);
+        this.instances.set(config.id, instance);
+        this.configs.set(config.id, config);
+        return instance;
+    }
+    get(configId) {
+        return this.instances.get(configId);
+    }
+    getActive() {
+        const active = [];
+        for (const [configId, config] of this.configs) {
+            if (config.enabled) {
+                const instance = this.instances.get(configId);
+                if (instance)
+                    active.push(instance);
+            }
+        }
+        return active;
+    }
+    listRegistered() {
+        return Array.from(this.definitions.keys());
+    }
+    getMetadata(pluginId) {
+        return this.definitions.get(pluginId)?.metadata;
+    }
+    getAllMetadata() {
+        return Array.from(this.definitions.values()).map((d) => d.metadata);
+    }
+    getSettingsSchema(pluginId) {
+        return this.definitions.get(pluginId)?.settingsSchema;
+    }
+    getAllConfigs() {
+        return Array.from(this.configs.values());
+    }
+    updateConfig(configId, updates) {
+        const config = this.configs.get(configId);
+        if (config) {
+            const newConfig = { ...config, ...updates };
+            this.configs.set(configId, newConfig);
+            const definition = this.definitions.get(config.pluginId);
+            if (definition) {
+                const instance = definition.factory(newConfig);
+                this.instances.set(configId, instance);
+            }
+        }
+    }
+    deleteConfig(configId) {
+        this.instances.delete(configId);
+        this.configs.delete(configId);
+    }
+    /**
+     * Get all available tools across all providers
+     */
+    getAllTools() {
+        const tools = [];
+        for (const provider of this.getActive()) {
+            for (const tool of provider.tools) {
+                tools.push({ provider: provider.metadata.id, tool });
+            }
+        }
+        return tools;
+    }
+    /**
+     * Execute a tool by name
+     */
+    async execute(toolName, params) {
+        for (const provider of this.getActive()) {
+            const tool = provider.tools.find((t) => t.name === toolName);
+            if (tool) {
+                return provider.execute(toolName, params);
+            }
+        }
+        throw new Error(`Tool not found: ${toolName}`);
+    }
+}
+// ============================================================================
+// Global Plugin Manager
+// ============================================================================
+class PluginManager {
+    search = new SearchProviderRegistry();
+    tools = new ToolProviderRegistry();
+    /**
+     * Initialize built-in plugins
+     */
+    async initialize() {
+        // Built-in plugins will be registered here
+        // Import and register each plugin definition
+        console.log('[Plugins] Plugin manager initialized');
+    }
+    /**
+     * Get all plugin metadata across categories
+     */
+    getAllPlugins() {
+        const plugins = [];
+        for (const meta of this.search.getAllMetadata()) {
+            plugins.push({ ...meta, category: 'search' });
+        }
+        for (const meta of this.tools.getAllMetadata()) {
+            plugins.push({ ...meta, category: 'tool' });
+        }
+        return plugins;
+    }
+}
+// ============================================================================
+// Singleton Instance
+// ============================================================================
+let manager = null;
+export function getPluginManager() {
+    if (!manager) {
+        manager = new PluginManager();
+    }
+    return manager;
+}
+export { SearchProviderRegistry, ToolProviderRegistry, PluginManager };
+//# sourceMappingURL=registry.js.map

package/dist/plugins/sandbox.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Plugin Sandbox
+ *
+ * Runs plugins in isolated Node.js Worker threads with restricted access.
+ * Plugins cannot access the filesystem, network, or process directly
+ * unless explicitly granted permissions.
+ */
+import { EventEmitter } from 'node:events';
+export type PluginPermission = 'fs:read' | 'fs:write' | 'net:fetch' | 'env:read' | 'exec' | 'tools';
+export interface SandboxConfig {
+    pluginId: string;
+    pluginPath: string;
+    permissions: PluginPermission[];
+    timeout: number;
+    memoryLimit: number;
+}
+export interface SandboxMessage {
+    type: 'init' | 'call' | 'result' | 'error' | 'log' | 'register-tool';
+    id?: string;
+    payload?: unknown;
+}
+export declare class PluginSandbox extends EventEmitter {
+    private worker;
+    private config;
+    private pendingCalls;
+    private callCounter;
+    private healthy;
+    constructor(config: SandboxConfig);
+    /**
+     * Start the sandbox worker
+     */
+    start(): Promise<void>;
+    /**
+     * Call a plugin method
+     */
+    call(method: string, args?: unknown[]): Promise<unknown>;
+    /**
+     * Stop the sandbox
+     */
+    stop(): Promise<void>;
+    /**
+     * Check if sandbox is healthy
+     */
+    isHealthy(): boolean;
+    private handleMessage;
+    private handleError;
+    private handleExit;
+}
+declare class SandboxManager {
+    private sandboxes;
+    /**
+     * Create and start a sandbox for a plugin
+     */
+    create(config: SandboxConfig): Promise<PluginSandbox>;
+    /**
+     * Get a running sandbox
+     */
+    get(pluginId: string): PluginSandbox | undefined;
+    /**
+     * Stop a sandbox
+     */
+    stop(pluginId: string): Promise<void>;
+    /**
+     * Stop all sandboxes
+     */
+    stopAll(): Promise<void>;
+    /**
+     * List running sandboxes
+     */
+    list(): Array<{
+        pluginId: string;
+        healthy: boolean;
+    }>;
+}
+export declare function getSandboxManager(): SandboxManager;
+export { SandboxManager };
+//# sourceMappingURL=sandbox.d.ts.map

package/dist/plugins/sandbox.js

@@ -0,0 +1,287 @@
+/**
+ * Plugin Sandbox
+ *
+ * Runs plugins in isolated Node.js Worker threads with restricted access.
+ * Plugins cannot access the filesystem, network, or process directly
+ * unless explicitly granted permissions.
+ */
+import { Worker, isMainThread, parentPort, workerData } from 'node:worker_threads';
+import { EventEmitter } from 'node:events';
+// =============================================================================
+// Sandbox Runner (main thread)
+// =============================================================================
+export class PluginSandbox extends EventEmitter {
+    worker = null;
+    config;
+    pendingCalls = new Map();
+    callCounter = 0;
+    healthy = false;
+    constructor(config) {
+        super();
+        this.config = config;
+    }
+    /**
+     * Start the sandbox worker
+     */
+    async start() {
+        if (this.worker) {
+            throw new Error(`Sandbox for ${this.config.pluginId} is already running`);
+        }
+        this.worker = new Worker(new URL(import.meta.url), {
+            workerData: {
+                pluginPath: this.config.pluginPath,
+                permissions: this.config.permissions,
+                pluginId: this.config.pluginId,
+            },
+            resourceLimits: {
+                maxOldGenerationSizeMb: this.config.memoryLimit,
+                maxYoungGenerationSizeMb: Math.ceil(this.config.memoryLimit / 4),
+            },
+        });
+        this.worker.on('message', (msg) => this.handleMessage(msg));
+        this.worker.on('error', (err) => this.handleError(err));
+        this.worker.on('exit', (code) => this.handleExit(code));
+        // Wait for init confirmation
+        await new Promise((resolve, reject) => {
+            const timer = setTimeout(() => reject(new Error('Sandbox init timeout')), this.config.timeout);
+            const handler = (msg) => {
+                if (msg.type === 'init') {
+                    clearTimeout(timer);
+                    this.healthy = true;
+                    this.worker?.removeListener('message', handler);
+                    resolve();
+                }
+            };
+            this.worker?.on('message', handler);
+        });
+    }
+    /**
+     * Call a plugin method
+     */
+    async call(method, args = []) {
+        if (!this.worker || !this.healthy) {
+            throw new Error(`Sandbox for ${this.config.pluginId} is not running`);
+        }
+        const id = String(++this.callCounter);
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pendingCalls.delete(id);
+                reject(new Error(`Plugin call ${method} timed out after ${this.config.timeout}ms`));
+            }, this.config.timeout);
+            this.pendingCalls.set(id, { resolve, reject, timer });
+            this.worker?.postMessage({
+                type: 'call',
+                id,
+                payload: { method, args },
+            });
+        });
+    }
+    /**
+     * Stop the sandbox
+     */
+    async stop() {
+        if (!this.worker)
+            return;
+        this.healthy = false;
+        // Reject all pending calls
+        for (const [id, pending] of this.pendingCalls) {
+            clearTimeout(pending.timer);
+            pending.reject(new Error('Sandbox stopped'));
+            this.pendingCalls.delete(id);
+        }
+        await this.worker.terminate();
+        this.worker = null;
+    }
+    /**
+     * Check if sandbox is healthy
+     */
+    isHealthy() {
+        return this.healthy;
+    }
+    // ===========================================================================
+    // Private
+    // ===========================================================================
+    handleMessage(msg) {
+        switch (msg.type) {
+            case 'result': {
+                const pending = this.pendingCalls.get(msg.id);
+                if (pending) {
+                    clearTimeout(pending.timer);
+                    this.pendingCalls.delete(msg.id);
+                    pending.resolve(msg.payload);
+                }
+                break;
+            }
+            case 'error': {
+                const pendingErr = this.pendingCalls.get(msg.id);
+                if (pendingErr) {
+                    clearTimeout(pendingErr.timer);
+                    this.pendingCalls.delete(msg.id);
+                    pendingErr.reject(new Error(String(msg.payload)));
+                }
+                break;
+            }
+            case 'log': {
+                this.emit('log', msg.payload);
+                break;
+            }
+            case 'register-tool': {
+                this.emit('register-tool', msg.payload);
+                break;
+            }
+        }
+    }
+    handleError(err) {
+        this.healthy = false;
+        this.emit('error', err);
+    }
+    handleExit(code) {
+        this.healthy = false;
+        this.worker = null;
+        // Reject all pending calls
+        for (const [id, pending] of this.pendingCalls) {
+            clearTimeout(pending.timer);
+            pending.reject(new Error(`Sandbox exited with code ${code}`));
+            this.pendingCalls.delete(id);
+        }
+        this.emit('exit', code);
+    }
+}
+// =============================================================================
+// Sandbox Manager
+// =============================================================================
+class SandboxManager {
+    sandboxes = new Map();
+    /**
+     * Create and start a sandbox for a plugin
+     */
+    async create(config) {
+        if (this.sandboxes.has(config.pluginId)) {
+            throw new Error(`Sandbox already exists for ${config.pluginId}`);
+        }
+        const sandbox = new PluginSandbox(config);
+        await sandbox.start();
+        this.sandboxes.set(config.pluginId, sandbox);
+        sandbox.on('exit', () => {
+            this.sandboxes.delete(config.pluginId);
+        });
+        return sandbox;
+    }
+    /**
+     * Get a running sandbox
+     */
+    get(pluginId) {
+        return this.sandboxes.get(pluginId);
+    }
+    /**
+     * Stop a sandbox
+     */
+    async stop(pluginId) {
+        const sandbox = this.sandboxes.get(pluginId);
+        if (sandbox) {
+            await sandbox.stop();
+            this.sandboxes.delete(pluginId);
+        }
+    }
+    /**
+     * Stop all sandboxes
+     */
+    async stopAll() {
+        const promises = Array.from(this.sandboxes.values()).map((s) => s.stop());
+        await Promise.allSettled(promises);
+        this.sandboxes.clear();
+    }
+    /**
+     * List running sandboxes
+     */
+    list() {
+        return Array.from(this.sandboxes.entries()).map(([id, sb]) => ({
+            pluginId: id,
+            healthy: sb.isHealthy(),
+        }));
+    }
+}
+// =============================================================================
+// Worker Thread Entry (runs inside sandbox)
+// =============================================================================
+if (!isMainThread && parentPort && workerData) {
+    const { pluginPath, permissions, pluginId } = workerData;
+    // Create restricted API surface
+    const sandboxApi = {
+        log: (...args) => {
+            parentPort?.postMessage({
+                type: 'log',
+                payload: { pluginId, level: 'info', args: args.map(String) },
+            });
+        },
+        registerTool: (tool) => {
+            if (!permissions.includes('tools')) {
+                throw new Error('Plugin does not have "tools" permission');
+            }
+            parentPort?.postMessage({
+                type: 'register-tool',
+                payload: tool,
+            });
+        },
+        fetch: permissions.includes('net:fetch')
+            ? globalThis.fetch
+            : () => { throw new Error('Plugin does not have "net:fetch" permission'); },
+    };
+    // Load plugin
+    (async () => {
+        try {
+            const pluginModule = await import(pluginPath);
+            const plugin = pluginModule.default || pluginModule;
+            // Call onLoad if present
+            if (typeof plugin.onLoad === 'function') {
+                await plugin.onLoad(sandboxApi);
+            }
+            // Notify main thread we're ready
+            parentPort?.postMessage({ type: 'init' });
+            // Handle calls from main thread
+            parentPort?.on('message', async (msg) => {
+                if (msg.type !== 'call' || !msg.id)
+                    return;
+                const { method, args } = msg.payload;
+                try {
+                    const fn = plugin[method];
+                    if (typeof fn !== 'function') {
+                        throw new Error(`Plugin method ${method} not found`);
+                    }
+                    const result = await fn.apply(plugin, args);
+                    parentPort?.postMessage({
+                        type: 'result',
+                        id: msg.id,
+                        payload: result,
+                    });
+                }
+                catch (error) {
+                    parentPort?.postMessage({
+                        type: 'error',
+                        id: msg.id,
+                        payload: error instanceof Error ? error.message : String(error),
+                    });
+                }
+            });
+        }
+        catch (error) {
+            parentPort?.postMessage({
+                type: 'error',
+                payload: `Failed to load plugin: ${error instanceof Error ? error.message : String(error)}`,
+            });
+            process.exit(1);
+        }
+    })();
+}
+// =============================================================================
+// Singleton
+// =============================================================================
+let manager = null;
+export function getSandboxManager() {
+    if (!manager) {
+        manager = new SandboxManager();
+    }
+    return manager;
+}
+export { SandboxManager };
+//# sourceMappingURL=sandbox.js.map