loki-mode 5.51.0 → 5.52.1

package/src/plugins/loader.js

@@ -0,0 +1,275 @@
+'use strict';
+
+const { readFileSync, readdirSync, existsSync, statSync, watch } = require('fs');
+const { join, extname } = require('path');
+const { PluginValidator } = require('./validator');
+
+/**
+ * Simple YAML parser for plugin configs.
+ * Handles: key-value pairs, arrays (- item), multiline strings (|), booleans, numbers.
+ * This avoids requiring the js-yaml dependency.
+ */
+function parseSimpleYAML(content) {
+    const result = {};
+    const lines = content.split('\n');
+    let currentKey = null;
+    let multilineValue = null;
+    let multilineIndent = 0;
+    let arrayKey = null;
+
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+
+        // Skip empty lines and comments (unless in multiline mode)
+        if (!multilineValue && (line.trim() === '' || line.trim().startsWith('#'))) {
+            continue;
+        }
+
+        // Handle multiline string continuation
+        if (multilineValue !== null) {
+            const stripped = line;
+            const indent = stripped.length - stripped.trimStart().length;
+            if (indent >= multilineIndent && stripped.trim() !== '') {
+                if (result[currentKey] === '') {
+                    result[currentKey] = stripped.trimStart();
+                } else {
+                    result[currentKey] += '\n' + stripped.trimStart();
+                }
+                continue;
+            } else {
+                // End of multiline
+                multilineValue = null;
+                // Fall through to process this line normally
+                if (line.trim() === '') continue;
+            }
+        }
+
+        // Handle array items
+        const arrayMatch = line.match(/^(\s+)- (.+)$/);
+        if (arrayMatch && arrayKey) {
+            if (!Array.isArray(result[arrayKey])) {
+                result[arrayKey] = [];
+            }
+            result[arrayKey].push(parseYAMLValue(arrayMatch[2].trim()));
+            continue;
+        }
+
+        // Handle key-value pairs
+        const kvMatch = line.match(/^([a-z_][a-z0-9_]*)\s*:\s*(.*)$/i);
+        if (kvMatch) {
+            const key = kvMatch[1];
+            const rawValue = kvMatch[2].trim();
+
+            // Check for multiline indicator
+            if (rawValue === '|' || rawValue === '>') {
+                currentKey = key;
+                multilineValue = '';
+                multilineIndent = 2; // expect at least 2-space indent
+                result[key] = '';
+                arrayKey = null;
+                continue;
+            }
+
+            // Check if next line starts an array
+            if (rawValue === '' && i + 1 < lines.length && lines[i + 1].match(/^\s+- /)) {
+                arrayKey = key;
+                result[key] = [];
+                continue;
+            }
+
+            result[key] = parseYAMLValue(rawValue);
+            currentKey = key;
+            arrayKey = null;
+        }
+    }
+
+    return result;
+}
+
+/**
+ * Parse a single YAML value (string, number, boolean, null).
+ */
+function parseYAMLValue(raw) {
+    if (raw === '' || raw === 'null' || raw === '~') return null;
+    if (raw === 'true') return true;
+    if (raw === 'false') return false;
+
+    // Quoted strings
+    if ((raw.startsWith('"') && raw.endsWith('"')) || (raw.startsWith("'") && raw.endsWith("'"))) {
+        return raw.slice(1, -1);
+    }
+
+    // Numbers
+    if (/^-?\d+$/.test(raw)) return parseInt(raw, 10);
+    if (/^-?\d+\.\d+$/.test(raw)) return parseFloat(raw);
+
+    return raw;
+}
+
+class PluginLoader {
+    /**
+     * Create a new PluginLoader.
+     * @param {string} pluginsDir - Path to plugins directory (default: .loki/plugins)
+     * @param {string} [schemasDir] - Path to schemas directory
+     */
+    constructor(pluginsDir, schemasDir) {
+        this.pluginsDir = pluginsDir || '.loki/plugins';
+        this.validator = new PluginValidator(schemasDir);
+        this._watchers = [];
+    }
+
+    /**
+     * Discover plugin files in the plugins directory.
+     * @returns {string[]} Array of file paths
+     */
+    discover() {
+        if (!existsSync(this.pluginsDir)) {
+            return [];
+        }
+
+        try {
+            const stat = statSync(this.pluginsDir);
+            if (!stat.isDirectory()) {
+                return [];
+            }
+        } catch {
+            return [];
+        }
+
+        try {
+            const entries = readdirSync(this.pluginsDir);
+            const pluginFiles = [];
+
+            for (const entry of entries) {
+                const ext = extname(entry).toLowerCase();
+                if (ext === '.yaml' || ext === '.yml' || ext === '.json') {
+                    pluginFiles.push(join(this.pluginsDir, entry));
+                }
+            }
+
+            return pluginFiles.sort();
+        } catch {
+            return [];
+        }
+    }
+
+    /**
+     * Parse a plugin file (YAML or JSON).
+     * @param {string} filePath - Path to the plugin file
+     * @returns {object|null} Parsed config or null on error
+     */
+    _parseFile(filePath) {
+        try {
+            const content = readFileSync(filePath, 'utf8');
+            const ext = extname(filePath).toLowerCase();
+
+            if (ext === '.json') {
+                return JSON.parse(content);
+            }
+
+            // YAML parsing
+            return parseSimpleYAML(content);
+        } catch (err) {
+            return null;
+        }
+    }
+
+    /**
+     * Load all plugins from the plugins directory.
+     * @returns {{ loaded: Array<{path: string, config: object}>, failed: Array<{path: string, errors: string[]}> }}
+     */
+    loadAll() {
+        const files = this.discover();
+        const loaded = [];
+        const failed = [];
+
+        for (const filePath of files) {
+            try {
+                const config = this._parseFile(filePath);
+
+                if (!config) {
+                    failed.push({ path: filePath, errors: ['Failed to parse plugin file'] });
+                    continue;
+                }
+
+                const result = this.validator.validate(config);
+
+                if (result.valid) {
+                    loaded.push({ path: filePath, config });
+                } else {
+                    failed.push({ path: filePath, errors: result.errors });
+                }
+            } catch (err) {
+                failed.push({ path: filePath, errors: [err.message || 'Unknown error'] });
+            }
+        }
+
+        return { loaded, failed };
+    }
+
+    /**
+     * Load a single plugin file.
+     * @param {string} filePath - Path to the plugin file
+     * @returns {{ config: object|null, errors: string[] }}
+     */
+    loadOne(filePath) {
+        const config = this._parseFile(filePath);
+
+        if (!config) {
+            return { config: null, errors: ['Failed to parse plugin file'] };
+        }
+
+        const result = this.validator.validate(config);
+
+        if (result.valid) {
+            return { config, errors: [] };
+        }
+
+        return { config: null, errors: result.errors };
+    }
+
+    /**
+     * Watch the plugins directory for changes.
+     * @param {function} callback - Called with (eventType, filePath) on changes
+     * @returns {function} Cleanup function to stop watching
+     */
+    watchForChanges(callback) {
+        if (!existsSync(this.pluginsDir)) {
+            return () => {};
+        }
+
+        try {
+            const watcher = watch(this.pluginsDir, (eventType, filename) => {
+                if (!filename) return;
+
+                const ext = extname(filename).toLowerCase();
+                if (ext === '.yaml' || ext === '.yml' || ext === '.json') {
+                    const filePath = join(this.pluginsDir, filename);
+                    callback(eventType, filePath);
+                }
+            });
+
+            this._watchers.push(watcher);
+
+            return () => {
+                watcher.close();
+                const idx = this._watchers.indexOf(watcher);
+                if (idx >= 0) this._watchers.splice(idx, 1);
+            };
+        } catch {
+            return () => {};
+        }
+    }
+
+    /**
+     * Stop all file watchers.
+     */
+    stopWatching() {
+        for (const watcher of this._watchers) {
+            try { watcher.close(); } catch { /* ignore */ }
+        }
+        this._watchers = [];
+    }
+}
+
+module.exports = { PluginLoader, parseSimpleYAML, parseYAMLValue };

package/src/plugins/mcp-plugin.js

@@ -0,0 +1,190 @@
+'use strict';
+
+const { execFile } = require('child_process');
+
+// In-memory registry for custom MCP tool plugins
+const _registeredTools = new Map();
+
+class MCPPlugin {
+    /**
+     * Register a custom MCP tool plugin.
+     *
+     * @param {object} pluginConfig - Validated MCP tool plugin config
+     * @returns {{ success: boolean, error?: string }}
+     */
+    static register(pluginConfig) {
+        if (!pluginConfig || pluginConfig.type !== 'mcp_tool') {
+            return { success: false, error: 'Invalid plugin config: type must be "mcp_tool"' };
+        }
+
+        const name = pluginConfig.name;
+
+        if (_registeredTools.has(name)) {
+            return { success: false, error: `MCP tool plugin "${name}" is already registered` };
+        }
+
+        const toolDef = {
+            name: name,
+            description: pluginConfig.description,
+            command: pluginConfig.command,
+            parameters: pluginConfig.parameters || [],
+            timeout_ms: pluginConfig.timeout_ms || 30000,
+            working_directory: pluginConfig.working_directory || 'project',
+            registered_at: new Date().toISOString(),
+        };
+
+        _registeredTools.set(name, toolDef);
+        return { success: true };
+    }
+
+    /**
+     * Unregister a custom MCP tool plugin.
+     *
+     * @param {string} pluginName - Name of the tool to remove
+     * @returns {{ success: boolean, error?: string }}
+     */
+    static unregister(pluginName) {
+        if (!_registeredTools.has(pluginName)) {
+            return { success: false, error: `MCP tool plugin "${pluginName}" is not registered` };
+        }
+
+        _registeredTools.delete(pluginName);
+        return { success: true };
+    }
+
+    /**
+     * Execute an MCP tool command with parameter substitution.
+     *
+     * @param {object} pluginConfig - The MCP tool plugin config
+     * @param {object} params - Input parameters
+     * @param {string} [projectDir] - Project directory for sandbox
+     * @returns {Promise<{ success: boolean, output: string, duration_ms: number }>}
+     */
+    static async execute(pluginConfig, params, projectDir) {
+        const command = pluginConfig.command;
+        const timeoutMs = pluginConfig.timeout_ms || 30000;
+        const startTime = Date.now();
+
+        if (!command) {
+            return {
+                success: false,
+                output: 'Error: no command specified for MCP tool',
+                duration_ms: 0,
+            };
+        }
+
+        // Substitute parameters into command with shell-safe quoting
+        let resolvedCommand = command;
+        if (params && typeof params === 'object') {
+            for (const [key, value] of Object.entries(params)) {
+                const safeValue = MCPPlugin._sanitizeValue(value);
+                resolvedCommand = resolvedCommand.replace(
+                    new RegExp(`\\{\\{params\\.${key}\\}\\}`, 'g'),
+                    safeValue
+                );
+            }
+        }
+
+        return new Promise((resolve) => {
+            const cwd = projectDir || process.cwd();
+
+            execFile('/bin/sh', ['-c', resolvedCommand], {
+                cwd,
+                timeout: timeoutMs,
+                maxBuffer: 1024 * 1024, // 1MB
+                env: { ...process.env, LOKI_MCP_TOOL: pluginConfig.name || 'unknown' },
+            }, (error, stdout, stderr) => {
+                const durationMs = Date.now() - startTime;
+                const output = (stdout || '') + (stderr ? '\n' + stderr : '');
+
+                if (error) {
+                    if (error.killed) {
+                        resolve({
+                            success: false,
+                            output: `Timeout: command exceeded ${timeoutMs}ms limit`,
+                            duration_ms: durationMs,
+                        });
+                    } else {
+                        resolve({
+                            success: false,
+                            output: output.trim() || error.message || 'Command failed',
+                            duration_ms: durationMs,
+                        });
+                    }
+                } else {
+                    resolve({
+                        success: true,
+                        output: output.trim(),
+                        duration_ms: durationMs,
+                    });
+                }
+            });
+        });
+    }
+
+    /**
+     * Get the MCP tool definition in a format suitable for MCP protocol.
+     *
+     * @param {string} name - Tool name
+     * @returns {object|null} MCP-compatible tool definition
+     */
+    static getMCPDefinition(name) {
+        const tool = _registeredTools.get(name);
+        if (!tool) return null;
+
+        const inputSchema = {
+            type: 'object',
+            properties: {},
+            required: [],
+        };
+
+        for (const param of tool.parameters) {
+            inputSchema.properties[param.name] = {
+                type: param.type || 'string',
+                description: param.description || '',
+            };
+            if (param.default !== undefined) {
+                inputSchema.properties[param.name].default = param.default;
+            }
+            if (param.required) {
+                inputSchema.required.push(param.name);
+            }
+        }
+
+        return {
+            name: tool.name,
+            description: tool.description,
+            inputSchema,
+        };
+    }
+
+    /**
+     * List all registered MCP tool plugins.
+     *
+     * @returns {object[]}
+     */
+    static listRegistered() {
+        return Array.from(_registeredTools.values());
+    }
+
+    /**
+     * Shell-safe value sanitization using POSIX single-quote escaping.
+     * Wraps value in single quotes with internal single quotes escaped.
+     *
+     * @param {*} value - The value to sanitize
+     * @returns {string} Shell-safe quoted string
+     */
+    static _sanitizeValue(value) {
+        const str = String(value);
+        return "'" + str.replace(/'/g, "'\\''") + "'";
+    }
+
+    /**
+     * Clear all registered tools (primarily for testing).
+     */
+    static _clearAll() {
+        _registeredTools.clear();
+    }
+}
+
+module.exports = { MCPPlugin };

package/src/plugins/schemas/agent.json

@@ -0,0 +1,59 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Agent Plugin Schema",
+  "description": "Schema for custom agent plugins in Loki Mode",
+  "type": "object",
+  "required": ["type", "name", "description", "prompt_template"],
+  "properties": {
+    "type": {
+      "const": "agent"
+    },
+    "name": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]{2,49}$",
+      "description": "Unique agent name (lowercase, 3-50 chars, alphanumeric and hyphens)"
+    },
+    "description": {
+      "type": "string",
+      "maxLength": 500,
+      "description": "Human-readable description of the agent"
+    },
+    "trigger": {
+      "type": "string",
+      "description": "Regex pattern for when to activate this agent"
+    },
+    "prompt_template": {
+      "type": "string",
+      "maxLength": 10000,
+      "description": "Prompt template for the agent (supports {{event.*}} variables)"
+    },
+    "quality_gate": {
+      "type": "boolean",
+      "default": false,
+      "description": "Whether this agent participates in quality gate reviews"
+    },
+    "category": {
+      "type": "string",
+      "enum": [
+        "engineering",
+        "operations",
+        "business",
+        "data",
+        "product",
+        "growth",
+        "review",
+        "orchestration",
+        "custom"
+      ],
+      "description": "Swarm category for this agent"
+    },
+    "capabilities": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "List of capabilities this agent provides"
+    }
+  },
+  "additionalProperties": false
+}

package/src/plugins/schemas/integration.json

@@ -0,0 +1,62 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Integration Plugin Schema",
+  "description": "Schema for custom integration plugins in Loki Mode",
+  "type": "object",
+  "required": ["type", "name", "description", "webhook_url", "events"],
+  "properties": {
+    "type": {
+      "const": "integration"
+    },
+    "name": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]{2,49}$",
+      "description": "Unique integration name (lowercase, 3-50 chars, alphanumeric and hyphens)"
+    },
+    "description": {
+      "type": "string",
+      "maxLength": 500,
+      "description": "Human-readable description of the integration"
+    },
+    "webhook_url": {
+      "type": "string",
+      "format": "uri",
+      "description": "URL to POST event payloads to"
+    },
+    "events": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "minItems": 1,
+      "description": "List of event types to subscribe to"
+    },
+    "payload_template": {
+      "type": "string",
+      "maxLength": 5000,
+      "description": "JSON template for the webhook payload (supports {{event.*}} variables)"
+    },
+    "headers": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "string"
+      },
+      "description": "Additional HTTP headers to send with webhook requests"
+    },
+    "timeout_ms": {
+      "type": "integer",
+      "minimum": 1000,
+      "maximum": 30000,
+      "default": 5000,
+      "description": "HTTP request timeout in milliseconds"
+    },
+    "retry_count": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 3,
+      "default": 1,
+      "description": "Number of retry attempts on failure"
+    }
+  },
+  "additionalProperties": false
+}

package/src/plugins/schemas/mcp_tool.json

@@ -0,0 +1,73 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "MCP Tool Plugin Schema",
+  "description": "Schema for custom MCP tool plugins in Loki Mode",
+  "type": "object",
+  "required": ["type", "name", "description", "command"],
+  "properties": {
+    "type": {
+      "const": "mcp_tool"
+    },
+    "name": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]{2,49}$",
+      "description": "Unique tool name (lowercase, 3-50 chars, alphanumeric and hyphens)"
+    },
+    "description": {
+      "type": "string",
+      "maxLength": 500,
+      "description": "Human-readable description of the MCP tool"
+    },
+    "command": {
+      "type": "string",
+      "maxLength": 1000,
+      "description": "Command to execute when tool is invoked"
+    },
+    "parameters": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["name", "type"],
+        "properties": {
+          "name": {
+            "type": "string",
+            "description": "Parameter name"
+          },
+          "type": {
+            "type": "string",
+            "enum": ["string", "number", "boolean"],
+            "description": "Parameter type"
+          },
+          "description": {
+            "type": "string",
+            "description": "Parameter description"
+          },
+          "required": {
+            "type": "boolean",
+            "default": false,
+            "description": "Whether the parameter is required"
+          },
+          "default": {
+            "description": "Default value for the parameter"
+          }
+        },
+        "additionalProperties": false
+      },
+      "description": "Tool input parameters"
+    },
+    "timeout_ms": {
+      "type": "integer",
+      "minimum": 1000,
+      "maximum": 120000,
+      "default": 30000,
+      "description": "Maximum execution time in milliseconds"
+    },
+    "working_directory": {
+      "type": "string",
+      "enum": ["project", "plugin"],
+      "default": "project",
+      "description": "Working directory for command execution"
+    }
+  },
+  "additionalProperties": false
+}