synapsexcoder 6.0.0

package/dist/plugins/plugin-system.js

@@ -0,0 +1,707 @@
+/** Plugin System */
+import { createRequire } from "module";
+import { existsSync, mkdirSync, readFileSync, readdirSync } from "fs";
+import { join, resolve } from "path";
+export class BasePlugin {
+    context;
+    constructor(context) {
+        this.context = context;
+    }
+}
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+/**
+ * Validate that a loaded module exports the mandatory plugin contract
+ * (`activate` and `deactivate` functions).  Returns the cast module on
+ * success, throws a descriptive error otherwise.
+ */
+function assertPluginModule(mod, entryPath) {
+    if (mod === null || typeof mod !== "object") {
+        throw new Error(`Plugin entry point "${entryPath}" did not export an object.`);
+    }
+    const candidate = mod;
+    // Support both CommonJS default exports and ES module default re-exports
+    const target = candidate["default"] !== undefined &&
+        typeof candidate["default"] === "object" &&
+        candidate["default"] !== null
+        ? candidate["default"]
+        : candidate;
+    if (typeof target["activate"] !== "function") {
+        throw new Error(`Plugin entry point "${entryPath}" is missing an exported "activate" function.`);
+    }
+    if (typeof target["deactivate"] !== "function") {
+        throw new Error(`Plugin entry point "${entryPath}" is missing an exported "deactivate" function.`);
+    }
+    return target;
+}
+/**
+ * Synchronously load a plugin module from the given absolute path using
+ * `createRequire` (works in both CJS and ESM host contexts).
+ */
+function loadPluginModule(entryPath) {
+    // createRequire lets us use require() semantics from an ESM context.
+    const _require = createRequire(import.meta.url);
+    const raw = _require(entryPath);
+    return assertPluginModule(raw, entryPath);
+}
+// ---------------------------------------------------------------------------
+// PluginManager
+// ---------------------------------------------------------------------------
+export class PluginManager {
+    pluginsDir;
+    plugins = new Map();
+    constructor(projectRoot, _masterAgent) {
+        this.pluginsDir = join(projectRoot, "plugins");
+        if (!existsSync(this.pluginsDir))
+            mkdirSync(this.pluginsDir, { recursive: true });
+        this.loadPluginFiles();
+    }
+    loadPluginFiles() {
+        if (!existsSync(this.pluginsDir))
+            return;
+        for (const dirent of readdirSync(this.pluginsDir, {
+            withFileTypes: true,
+        }).filter((d) => d.isDirectory())) {
+            const pluginDir = join(this.pluginsDir, dirent.name);
+            const manifestPath = join(pluginDir, "manifest.json");
+            if (!existsSync(manifestPath))
+                continue;
+            let manifest;
+            try {
+                manifest = JSON.parse(readFileSync(manifestPath, "utf-8"));
+            }
+            catch (parseErr) {
+                // Malformed manifest — skip without polluting the registry.
+                console.warn(`[PluginManager] Skipping "${dirent.name}": invalid manifest.json — ${String(parseErr)}`);
+                continue;
+            }
+            // Resolve the entry point relative to the plugin's own directory.
+            const resolvedEntryPoint = resolve(pluginDir, manifest.entryPoint);
+            let instance = null;
+            let state = "loaded";
+            let loadError;
+            if (!existsSync(resolvedEntryPoint)) {
+                state = "error";
+                loadError = `Entry point not found: "${resolvedEntryPoint}"`;
+                console.error(`[PluginManager] Failed to load plugin "${manifest.id}": ${loadError}`);
+            }
+            else {
+                try {
+                    instance = loadPluginModule(resolvedEntryPoint);
+                    console.info(`[PluginManager] Loaded plugin "${manifest.id}" v${manifest.version} from "${resolvedEntryPoint}"`);
+                }
+                catch (loadErr) {
+                    state = "error";
+                    loadError = String(loadErr);
+                    console.error(`[PluginManager] Failed to load plugin "${manifest.id}": ${loadError}`);
+                }
+            }
+            this.plugins.set(manifest.id, {
+                manifest,
+                instance,
+                enabled: state === "loaded",
+                loadedAt: Date.now(),
+                state,
+                ...(loadError !== undefined ? { loadError } : {}),
+            });
+        }
+    }
+    listPlugins() {
+        return [...this.plugins.values()];
+    }
+    getPlugin(pluginId) {
+        return this.plugins.get(pluginId);
+    }
+    enablePlugin(pluginId) {
+        const p = this.plugins.get(pluginId);
+        if (!p)
+            return false;
+        p.enabled = true;
+        return true;
+    }
+    disablePlugin(pluginId) {
+        const p = this.plugins.get(pluginId);
+        if (!p)
+            return false;
+        p.enabled = false;
+        return true;
+    }
+    getStats() {
+        const all = [...this.plugins.values()];
+        const byType = {};
+        for (const p of all)
+            byType[p.manifest.type] = (byType[p.manifest.type] || 0) + 1;
+        return {
+            total: all.length,
+            enabled: all.filter((p) => p.enabled).length,
+            disabled: all.filter((p) => !p.enabled).length,
+            errored: all.filter((p) => p.state === "error").length,
+            byType,
+        };
+    }
+    // -------------------------------------------------------------------------
+    // Template & scaffold generation
+    // -------------------------------------------------------------------------
+    /**
+     * Return a complete, valid TypeScript plugin template for the given type.
+     *
+     * Every template:
+     *  - Implements the `PluginModule` interface contract
+     *  - Includes JSDoc on every method
+     *  - Has realistic example logic for the type's primary hook
+     *  - Ends with an `export default` statement
+     */
+    createPluginTemplate(type) {
+        // Shared header used by every template.
+        const header = (hookComment) => `/**
+ * SynapseXcoder Plugin — type: "${type}"
+ *
+ * ${hookComment}
+ *
+ * Generated by SynapseXcoder PluginManager.
+ * Implement the hooks below to integrate with the pipeline.
+ */
+
+import type { PluginContext } from "SynapseXcoder/plugins";
+
+// Stored reference to the plugin context, set during activate().
+let _context: PluginContext | null = null;
+`;
+        switch (type) {
+            // ------------------------------------------------------------------
+            // agent — handles raw prompts and returns augmented/alternate responses
+            // ------------------------------------------------------------------
+            case "agent":
+                return (header("Agent plugins intercept prompts and return processed responses.") +
+                    `
+/** Called once when the plugin is enabled. Use this to set up resources. */
+export function activate(context: PluginContext): void {
+  _context = context;
+  _context.logger(\`[${type}-plugin] activated\`);
+}
+
+/** Called once when the plugin is disabled or the host shuts down. */
+export function deactivate(): void {
+  _context?.logger(\`[${type}-plugin] deactivated\`);
+  _context = null;
+}
+
+/**
+ * Handle a prompt string.
+ *
+ * @param prompt - The raw user or pipeline prompt.
+ * @returns A modified or augmented prompt/response string.
+ */
+export function handlePrompt(prompt: string): string {
+  // Example: prefix every prompt with additional context.
+  const prefix = "[agent-plugin context] ";
+  const processed = \`\${prefix}\${prompt}\`;
+  _context?.logger(\`[${type}-plugin] handlePrompt called (${"\${prompt.length}"} chars)\`);
+  return processed;
+}
+
+export default { activate, deactivate, handlePrompt };
+`);
+            // ------------------------------------------------------------------
+            // command — registers named CLI/chat commands into the pipeline
+            // ------------------------------------------------------------------
+            case "command":
+                return (header("Command plugins register named handlers into the pipeline.") +
+                    `
+/** Called once when the plugin is enabled. Registers all commands. */
+export function activate(context: PluginContext): void {
+  _context = context;
+  _context.logger(\`[${type}-plugin] activated\`);
+
+  // Register each command this plugin provides.
+  _context.registerCommand?.("my-command", handleMyCommand);
+}
+
+/** Called once when the plugin is disabled or the host shuts down. */
+export function deactivate(): void {
+  _context?.logger(\`[${type}-plugin] deactivated\`);
+  _context = null;
+}
+
+/**
+ * Example command handler.
+ *
+ * @param args - Positional arguments passed to the command.
+ * @returns The command result that will be surfaced to the caller.
+ */
+function handleMyCommand(...args: unknown[]): string {
+  _context?.logger(\`[${type}-plugin] my-command invoked with \${args.length} args\`);
+  return \`my-command executed with args: \${JSON.stringify(args)}\`;
+}
+
+/** Expose the commands map for direct introspection. */
+export const commands: Record<string, (...args: unknown[]) => unknown> = {
+  "my-command": handleMyCommand,
+};
+
+export default { activate, deactivate, commands };
+`);
+            // ------------------------------------------------------------------
+            // tool — contributes named tools to the tool registry
+            // ------------------------------------------------------------------
+            case "tool":
+                return (header("Tool plugins expose named tools to the agent tool registry.") +
+                    `
+/** Example tool implementation. */
+const myTool = {
+  /** Human-readable description used by the planner when selecting tools. */
+  description: "An example tool contributed by this plugin.",
+
+  /**
+   * Execute the tool.
+   *
+   * @param input - Arbitrary input data for the tool.
+   * @returns The tool result.
+   */
+  execute(input: unknown): unknown {
+    _context?.logger(\`[${type}-plugin] myTool.execute called\`);
+    // Plugin tool execution: passes input through with metadata
+    return { result: "ok", echo: input, executedAt: new Date().toISOString() };
+  },
+};
+
+/** Called once when the plugin is enabled. Registers all tools. */
+export function activate(context: PluginContext): void {
+  _context = context;
+  _context.logger(\`[${type}-plugin] activated\`);
+  _context.registerTool?.("my-tool", myTool);
+}
+
+/** Called once when the plugin is disabled or the host shuts down. */
+export function deactivate(): void {
+  _context?.logger(\`[${type}-plugin] deactivated\`);
+  _context = null;
+}
+
+/** Expose the tools map for direct introspection. */
+export const tools: Record<string, unknown> = {
+  "my-tool": myTool,
+};
+
+export default { activate, deactivate, tools };
+`);
+            // ------------------------------------------------------------------
+            // context — injects additional context into the execution pipeline
+            // ------------------------------------------------------------------
+            case "context":
+                return (header("Context plugins inject supplemental context into the execution pipeline.") +
+                    `
+/** Called once when the plugin is enabled. */
+export function activate(context: PluginContext): void {
+  _context = context;
+  _context.logger(\`[${type}-plugin] activated\`);
+}
+
+/** Called once when the plugin is disabled or the host shuts down. */
+export function deactivate(): void {
+  _context?.logger(\`[${type}-plugin] deactivated\`);
+  _context = null;
+}
+
+/**
+ * Return additional context key/value pairs to inject into the pipeline.
+ *
+ * @returns A plain object whose keys will be merged into the execution context.
+ */
+export function getContext(): Record<string, unknown> {
+  _context?.logger(\`[${type}-plugin] getContext called\`);
+  return {
+    pluginProvidedAt: new Date().toISOString(),
+    environment: process.env["NODE_ENV"] ?? "development",
+    // Plugin context keys available for execution
+    pluginName: type,
+  };
+}
+
+export default { activate, deactivate, getContext };
+`);
+            // ------------------------------------------------------------------
+            // knowledge — answers domain-specific knowledge queries
+            // ------------------------------------------------------------------
+            case "knowledge":
+                return (header("Knowledge plugins answer domain-specific queries from the pipeline.") +
+                    `
+// Simple in-memory knowledge base.  Replace with a real data source.
+const KB: Record<string, string> = {
+  "what is synapsexcoder": "SynapseXcoder is a multi-agent AI coding assistant.",
+  // Add more entries as needed.
+};
+
+/** Called once when the plugin is enabled. */
+export function activate(context: PluginContext): void {
+  _context = context;
+  _context.logger(\`[${type}-plugin] activated (${"\${Object.keys(KB).length}"} KB entries)\`);
+}
+
+/** Called once when the plugin is disabled or the host shuts down. */
+export function deactivate(): void {
+  _context?.logger(\`[${type}-plugin] deactivated\`);
+  _context = null;
+}
+
+/**
+ * Answer a knowledge query.
+ *
+ * @param query - A natural-language question or lookup key.
+ * @returns A string answer, or an empty string when no match is found.
+ */
+export function queryKnowledge(query: string): string {
+  _context?.logger(\`[${type}-plugin] queryKnowledge: "\${query}"\`);
+  const key = query.toLowerCase().trim();
+  return KB[key] ?? "";
+}
+
+export default { activate, deactivate, queryKnowledge };
+`);
+            // ------------------------------------------------------------------
+            // mixed — combines multiple hook types in a single plugin
+            // ------------------------------------------------------------------
+            case "mixed":
+            default:
+                return (header("Mixed plugins combine multiple hook types (agent, command, tool, context, knowledge) in a single module.") +
+                    `
+/** Called once when the plugin is enabled. Wire up every capability here. */
+export function activate(context: PluginContext): void {
+  _context = context;
+  _context.logger(\`[${type}-plugin] activated\`);
+
+  // Register any commands this plugin provides.
+  _context.registerCommand?.("mixed-command", (...args: unknown[]) => {
+    _context?.logger(\`[${type}-plugin] mixed-command called\`);
+    return args;
+  });
+
+  // Register any tools this plugin provides.
+  _context.registerTool?.("mixed-tool", {
+    description: "A multi-purpose tool from the mixed plugin.",
+    execute: (input: unknown) => ({ result: "ok", input }),
+  });
+}
+
+/** Called once when the plugin is disabled or the host shuts down. */
+export function deactivate(): void {
+  _context?.logger(\`[${type}-plugin] deactivated\`);
+  _context = null;
+}
+
+/**
+ * Optional: handle a prompt.
+ *
+ * @param prompt - The incoming prompt string.
+ * @returns The processed prompt.
+ */
+export function handlePrompt(prompt: string): string {
+  return prompt; // Pass-through by default; replace with real logic.
+}
+
+/**
+ * Optional: supply additional context.
+ *
+ * @returns Key/value pairs merged into the execution context.
+ */
+export function getContext(): Record<string, unknown> {
+  return { mixedPluginActive: true };
+}
+
+export default { activate, deactivate, handlePrompt, getContext };
+`);
+        }
+    }
+    /**
+     * Generate a complete plugin scaffold for a new plugin.
+     *
+     * Returns every file needed to publish and use the plugin:
+     * - `code`        — the plugin's main TypeScript entry point
+     * - `packageJson` — a ready-to-publish `package.json` object
+     * - `readme`      — a Markdown README
+     * - `testFile`    — a Vitest test stub covering activate/deactivate
+     * - `tsConfig`    — a minimal `tsconfig.json` for building the plugin
+     * - `manifest`    — the `PluginManifest` object (also written to disk)
+     */
+    createPluginScaffold(type, name) {
+        // Derive a safe npm-compatible package name and a PascalCase class name.
+        const safeName = name
+            .toLowerCase()
+            .replace(/[^a-z0-9]+/g, "-")
+            .replace(/^-+|-+$/g, "");
+        const pluginPackageName = `synapsexcoder-plugin-${safeName}`;
+        const manifest = {
+            id: `${safeName}-${Date.now()}`,
+            name,
+            version: "1.0.0",
+            description: `A SynapseXcoder ${type} plugin — ${name}`,
+            author: "Developer",
+            type,
+            entryPoint: "dist/index.js",
+            dependencies: [],
+            permissions: [],
+            config: {},
+        };
+        // ── code ────────────────────────────────────────────────────────────────
+        // Use createPluginTemplate as the base, then inject the plugin name.
+        const baseTemplate = this.createPluginTemplate(type);
+        const code = baseTemplate.replace(/SynapseXcoder Plugin — type: "([^"]+)"/, `SynapseXcoder Plugin — ${name} (type: "${type}")`);
+        // ── package.json ────────────────────────────────────────────────────────
+        const packageJson = {
+            name: pluginPackageName,
+            version: "1.0.0",
+            description: `A SynapseXcoder ${type} plugin — ${name}`,
+            type: "module",
+            main: "dist/index.js",
+            types: "dist/index.d.ts",
+            files: ["dist", "manifest.json"],
+            scripts: {
+                build: "tsc",
+                test: "vitest run",
+                prepublishOnly: "npm run build",
+            },
+            keywords: ["synapsexcoder-plugin", `synapsexcoder-${type}`, "synapsexcoder"],
+            license: "MIT",
+            peerDependencies: {
+                "SynapseXcoder": ">=1.0.0.0",
+            },
+            peerDependenciesMeta: {
+                "SynapseXcoder": { optional: false },
+            },
+            devDependencies: {
+                typescript: "^5.5.4",
+                vitest: "^4.1.2",
+                "SynapseXcoder": ">=1.0.0.0",
+            },
+        };
+        // ── README ───────────────────────────────────────────────────────────────
+        const readme = `# ${name}
+
+> A SynapseXcoder **${type}** plugin.
+
+## Description
+
+${name} integrates with the SynapseXcoder pipeline as a \`${type}\` plugin, providing
+${type === "agent" ? "custom prompt-handling logic" : ""}${type === "command" ? "named command handlers" : ""}${type === "tool" ? "named tools for the agent tool registry" : ""}${type === "context" ? "additional context injection" : ""}${type === "knowledge" ? "domain-specific knowledge querying" : ""}${type === "mixed" ? "a combination of hooks (prompt, command, tool, context)" : ""}.
+
+## Installation
+
+\`\`\`bash
+npm install ${pluginPackageName}
+\`\`\`
+
+Then place a \`manifest.json\` (see below) inside your SynapseXcoder project's
+\`plugins/${safeName}/\` directory and rebuild the project.
+
+## manifest.json
+
+\`\`\`json
+{
+  "id": "${manifest.id}",
+  "name": "${name}",
+  "version": "1.0.0",
+  "description": "${manifest.description}",
+  "author": "Developer",
+  "type": "${type}",
+  "entryPoint": "dist/index.js",
+  "dependencies": [],
+  "permissions": [],
+  "config": {}
+}
+\`\`\`
+
+## Configuration
+
+Edit \`config\` in \`manifest.json\` to pass options to the plugin at load time.
+They are available as \`context.config\` inside \`activate()\`.
+
+## Development
+
+\`\`\`bash
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Run tests
+npm test
+\`\`\`
+
+## Plugin Contract
+
+| Export | Required | Description |
+|---|---|---|
+| \`activate(context)\` | ✅ | Called when the plugin is enabled |
+| \`deactivate()\` | ✅ | Called when the plugin is disabled |
+${type === "agent" || type === "mixed" ? "| `handlePrompt(prompt)` | optional | Process a prompt string |\n" : ""}${type === "command" || type === "mixed" ? "| `commands` | optional | Map of command name → handler |\n" : ""}${type === "tool" || type === "mixed" ? "| `tools` | optional | Map of tool name → implementation |\n" : ""}${type === "context" || type === "mixed" ? "| `getContext()` | optional | Returns key/value pairs injected as context |\n" : ""}${type === "knowledge" ? "| `queryKnowledge(query)` | optional | Answers a knowledge query |\n" : ""}
+## License
+
+MIT
+`;
+        // ── test file ────────────────────────────────────────────────────────────
+        const testFile = `/**
+ * ${name} — Plugin Lifecycle Tests
+ *
+ * Covers the mandatory activate/deactivate contract and the primary
+ * type-specific hook for the "${type}" plugin type.
+ */
+
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import type { PluginContext } from "SynapseXcoder/plugins";
+import plugin from "../src/index.js";
+
+// ---------------------------------------------------------------------------
+// Shared test context fixture
+// ---------------------------------------------------------------------------
+
+function makeContext(overrides: Partial<PluginContext> = {}): PluginContext {
+  return {
+    masterAgent: null,
+    config: {},
+    logger: vi.fn(),
+    registerCommand: vi.fn(),
+    registerAgent: vi.fn(),
+    registerTool: vi.fn(),
+    ...overrides,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Lifecycle tests
+// ---------------------------------------------------------------------------
+
+describe("${name} plugin lifecycle", () => {
+  let ctx: PluginContext;
+
+  beforeEach(() => {
+    ctx = makeContext();
+  });
+
+  it("exports activate as a function", () => {
+    expect(typeof plugin.activate).toBe("function");
+  });
+
+  it("exports deactivate as a function", () => {
+    expect(typeof plugin.deactivate).toBe("function");
+  });
+
+  it("activate() runs without throwing", () => {
+    expect(() => plugin.activate(ctx)).not.toThrow();
+  });
+
+  it("activate() calls context.logger at least once", () => {
+    plugin.activate(ctx);
+    expect(ctx.logger).toHaveBeenCalled();
+  });
+
+  it("deactivate() runs without throwing after activate()", () => {
+    plugin.activate(ctx);
+    expect(() => plugin.deactivate()).not.toThrow();
+  });
+
+  it("deactivate() can be called safely without a prior activate()", () => {
+    // Should not throw even if called before activate.
+    expect(() => plugin.deactivate()).not.toThrow();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Type-specific hook tests
+// ---------------------------------------------------------------------------
+${type === "agent" || type === "mixed"
+            ? `
+describe("${name} plugin — handlePrompt", () => {
+  it("handlePrompt returns a string", () => {
+    const ctx = makeContext();
+    const plug = plugin as { handlePrompt?: (p: string) => string };
+    if (typeof plug.handlePrompt !== "function") return; // optional hook
+
+    plug.activate?.(ctx);
+    const result = plug.handlePrompt("test prompt");
+    expect(typeof result).toBe("string");
+  });
+});
+`
+            : ""}${type === "command" || type === "mixed"
+            ? `
+describe("${name} plugin — commands", () => {
+  it("commands map is an object", () => {
+    const plug = plugin as { commands?: Record<string, unknown> };
+    if (!plug.commands) return; // optional
+    expect(typeof plug.commands).toBe("object");
+  });
+});
+`
+            : ""}${type === "tool" || type === "mixed"
+            ? `
+describe("${name} plugin — tools", () => {
+  it("tools map is an object", () => {
+    const plug = plugin as { tools?: Record<string, unknown> };
+    if (!plug.tools) return; // optional
+    expect(typeof plug.tools).toBe("object");
+  });
+});
+`
+            : ""}${type === "context" || type === "mixed"
+            ? `
+describe("${name} plugin — getContext", () => {
+  it("getContext returns a plain object", () => {
+    const ctx = makeContext();
+    const plug = plugin as { getContext?: () => Record<string, unknown> };
+    if (typeof plug.getContext !== "function") return; // optional
+
+    plug.activate?.(ctx);
+    const result = plug.getContext();
+    expect(result).toBeDefined();
+    expect(typeof result).toBe("object");
+  });
+});
+`
+            : ""}${type === "knowledge"
+            ? `
+describe("${name} plugin — queryKnowledge", () => {
+  it("queryKnowledge returns a string", () => {
+    const ctx = makeContext();
+    const plug = plugin as { queryKnowledge?: (q: string) => string };
+    if (typeof plug.queryKnowledge !== "function") return; // optional
+
+    plug.activate?.(ctx);
+    const result = plug.queryKnowledge("what is synapsexcoder");
+    expect(typeof result).toBe("string");
+  });
+});
+`
+            : ""}`;
+        // ── tsconfig.json ─────────────────────────────────────────────────────────
+        const tsConfig = {
+            compilerOptions: {
+                target: "ES2022",
+                module: "ESNext",
+                moduleResolution: "bundler",
+                lib: ["ES2022"],
+                outDir: "./dist",
+                rootDir: "./src",
+                declaration: true,
+                declarationMap: true,
+                sourceMap: true,
+                strict: true,
+                esModuleInterop: true,
+                skipLibCheck: true,
+                forceConsistentCasingInFileNames: true,
+                noUnusedLocals: true,
+                noUnusedParameters: true,
+                noImplicitReturns: true,
+                types: ["node"],
+            },
+            include: ["src/**/*"],
+            exclude: ["node_modules", "dist", "**/*.test.ts"],
+        };
+        return { manifest, code, packageJson, readme, testFile, tsConfig };
+    }
+}
+export function createPluginManager(projectRoot, masterAgent) {
+    return new PluginManager(projectRoot, masterAgent);
+}
+//# sourceMappingURL=plugin-system.js.map