goatcode-sh 0.0.1 → 0.1.2

package/src/registry/contribution-conflicts.integration.test.ts

@@ -0,0 +1,186 @@
+import { describe, expect, it, mock } from "bun:test";
+
+import type { PluginAgentContribution } from "../types/agent";
+import type { PluginDefinition, PluginHookHandler } from "../types/plugin";
+import type { PluginToolContribution } from "../types/tool";
+
+const logSpy = mock(() => {});
+
+mock.module("../shared/logger", () => ({
+  log: logSpy,
+}));
+
+import { wrapSafely } from "../hooks/safe-hook-wrapper";
+import { aggregateAgents } from "./agent-aggregator";
+import { aggregateHooks } from "./hook-aggregator";
+import { aggregateTools } from "./tool-aggregator";
+
+function makeToolContribution(id: string): PluginToolContribution {
+  return {
+    execute: async () => id,
+  } as unknown as PluginToolContribution;
+}
+
+function makeAgentContribution(model: string): PluginAgentContribution {
+  return {
+    instructions: "integration-test",
+    model,
+  } as unknown as PluginAgentContribution;
+}
+
+describe("aggregateTools", () => {
+  describe("#given two plugins that register the same tool name", () => {
+    describe("#when aggregateTools runs in replace conflict mode", () => {
+      it("#then the last plugin tool wins and a conflict warning is logged", () => {
+        const toolA = makeToolContribution("plugin-a");
+        const toolB = makeToolContribution("plugin-b");
+        const plugins: PluginDefinition[] = [
+          { name: "plugin-a", tools: { search: toolA } },
+          { name: "plugin-b", tools: { search: toolB } },
+        ];
+        const callsBefore = logSpy.mock.calls.length;
+
+        const aggregated = aggregateTools(plugins);
+
+        expect(aggregated.search).toBe(toolB);
+        expect(aggregated.search).not.toBe(toolA);
+        expect(logSpy.mock.calls.length).toBeGreaterThan(callsBefore);
+        expect(
+          logSpy.mock.calls
+            .slice(callsBefore)
+            .some(
+              (call) =>
+                typeof call[0] === "string" &&
+                call[0].includes("CONFLICT") &&
+                call[0].includes('"search"'),
+            ),
+        ).toBe(true);
+      });
+    });
+  });
+});
+
+describe("aggregateAgents", () => {
+  describe("#given two plugins that register the same agent name", () => {
+    describe("#when aggregateAgents runs in replace conflict mode", () => {
+      it("#then the second plugin agent overwrites the first", () => {
+        const firstAgent = makeAgentContribution("model-a");
+        const secondAgent = makeAgentContribution("model-b");
+        const plugins: PluginDefinition[] = [
+          { name: "plugin-a", agents: { advisor: firstAgent } },
+          { name: "plugin-b", agents: { advisor: secondAgent } },
+        ];
+
+        const aggregated = aggregateAgents(plugins);
+
+        expect(aggregated.advisor).toBe(secondAgent);
+        expect(aggregated.advisor).not.toBe(firstAgent);
+      });
+    });
+  });
+});
+
+describe("aggregateHooks", () => {
+  describe("#given two plugins that register the same hook event", () => {
+    describe("#when aggregateHooks runs in append conflict mode", () => {
+      it("#then both handlers are collected in plugin order", () => {
+        type ToolExecuteBeforeHandler = NonNullable<
+          PluginDefinition["hooks"]
+        >["tool.execute.before"];
+        const first: ToolExecuteBeforeHandler = async () => {};
+        const second: ToolExecuteBeforeHandler = async () => {};
+        const plugins: PluginDefinition[] = [
+          { name: "plugin-a", hooks: { "tool.execute.before": first } },
+          { name: "plugin-b", hooks: { "tool.execute.before": second } },
+        ];
+
+        const aggregated = aggregateHooks(plugins);
+
+        expect(aggregated.get("tool.execute.before")).toEqual([first, second]);
+      });
+    });
+  });
+});
+
+describe("wrapSafely", () => {
+  describe("#given a hook handler partially mutates output before throwing", () => {
+    describe("#when the wrapped handler executes", () => {
+      it("#then the throw is swallowed and partial mutation remains", async () => {
+        const handler: PluginHookHandler = async (_input, output) => {
+          const mutableOutput = output as { output: string };
+          mutableOutput.output = "partial";
+          throw new Error("boom");
+        };
+        const wrapped = wrapSafely("test", handler);
+        const output = { output: "" };
+
+        await expect(wrapped({}, output)).resolves.toBeUndefined();
+        expect(output.output).toBe("partial");
+      });
+    });
+  });
+
+  describe("#given handlers that throw non-Error values", () => {
+    describe("#when each handler is wrapped and executed", () => {
+      it("#then string, number, and object throws are all swallowed", async () => {
+        const nonErrorThrows = ["string error", 42, { code: "ERR_CUSTOM" }] as const;
+
+        for (const thrownValue of nonErrorThrows) {
+          const handler: PluginHookHandler = async () => {
+            throw thrownValue;
+          };
+          const wrapped = wrapSafely("non-error", handler);
+
+          await expect(wrapped({}, {})).resolves.toBeUndefined();
+        }
+      });
+    });
+  });
+});
+
+describe("disabled contributions", () => {
+  describe("#given hook, tool, and agent entries that are disabled by name", () => {
+    describe("#when each aggregator runs with disabled arrays", () => {
+      it("#then disabled entries are excluded from aggregated output", () => {
+        const hooksPlugins: PluginDefinition[] = [
+          {
+            name: "hooks-plugin",
+            hooks: {
+              "comment-checker": async () => {},
+              "tool.execute.before": async () => {},
+            } as unknown as NonNullable<PluginDefinition["hooks"]>,
+          },
+        ];
+        const toolsPlugins: PluginDefinition[] = [
+          {
+            name: "tools-plugin",
+            tools: {
+              grep: makeToolContribution("grep"),
+              safe_tool: makeToolContribution("safe-tool"),
+            },
+          },
+        ];
+        const agentsPlugins: PluginDefinition[] = [
+          {
+            name: "agents-plugin",
+            agents: {
+              advisor: makeAgentContribution("model-advisor"),
+              worker: makeAgentContribution("model-worker"),
+            },
+          },
+        ];
+
+        const hooks = aggregateHooks(hooksPlugins, ["comment-checker"]);
+        const tools = aggregateTools(toolsPlugins, ["grep"]);
+        const agents = aggregateAgents(agentsPlugins, ["advisor"]);
+
+        expect(hooks.has("comment-checker")).toBe(false);
+        expect(hooks.has("tool.execute.before")).toBe(true);
+        expect(tools.grep).toBeUndefined();
+        expect(tools.safe_tool).toBeDefined();
+        expect(agents.advisor).toBeUndefined();
+        expect(agents.worker).toBeDefined();
+      });
+    });
+  });
+});

package/src/registry/dependency-resolver.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, test } from "bun:test";
+
+import type { PluginDefinition } from "../types/plugin";
+
+import { resolvePluginOrder } from "./dependency-resolver";
+
+function makePlugin(name: string, deps: string[] = []): PluginDefinition {
+  return { name, dependencies: deps };
+}
+
+describe("resolvePluginOrder", () => {
+  test("returns all plugins in registration order when no dependencies", () => {
+    const plugins = [makePlugin("a"), makePlugin("b"), makePlugin("c")];
+    const { order } = resolvePluginOrder(plugins);
+    expect(order.map((plugin) => plugin.name)).toEqual(["a", "b", "c"]);
+  });
+
+  test("orders dependencies before dependents", () => {
+    const plugins = [makePlugin("c", ["b"]), makePlugin("b", ["a"]), makePlugin("a")];
+    const { order } = resolvePluginOrder(plugins);
+    const names = order.map((plugin) => plugin.name);
+    expect(names.indexOf("a")).toBeLessThan(names.indexOf("b"));
+    expect(names.indexOf("b")).toBeLessThan(names.indexOf("c"));
+  });
+
+  test("throws on circular dependencies", () => {
+    const plugins = [makePlugin("a", ["b"]), makePlugin("b", ["a"])];
+    expect(() => resolvePluginOrder(plugins)).toThrow("Circular dependency");
+  });
+
+  test("throws on unknown dependency", () => {
+    const plugins = [makePlugin("a", ["unknown"])];
+    expect(() => resolvePluginOrder(plugins)).toThrow('unknown plugin "unknown"');
+  });
+});

package/src/registry/dependency-resolver.ts

@@ -0,0 +1,64 @@
+import type { PluginDefinition } from "../types/plugin";
+
+import type { ResolvedPlugin, ResolutionResult } from "./types";
+
+export function resolvePluginOrder(plugins: PluginDefinition[]): ResolutionResult {
+  const pluginMap = new Map(plugins.map((plugin) => [plugin.name, plugin]));
+  const inDegree = new Map<string, number>();
+  const dependents = new Map<string, string[]>();
+
+  for (const plugin of plugins) {
+    inDegree.set(plugin.name, inDegree.get(plugin.name) ?? 0);
+    for (const dep of plugin.dependencies ?? []) {
+      if (!pluginMap.has(dep)) {
+        throw new Error(`Plugin "${plugin.name}" depends on unknown plugin "${dep}"`);
+      }
+
+      inDegree.set(plugin.name, (inDegree.get(plugin.name) ?? 0) + 1);
+      const list = dependents.get(dep) ?? [];
+      list.push(plugin.name);
+      dependents.set(dep, list);
+    }
+  }
+
+  const queue = plugins
+    .filter((plugin) => (inDegree.get(plugin.name) ?? 0) === 0)
+    .map((plugin) => plugin.name);
+  const order: PluginDefinition[] = [];
+
+  while (queue.length > 0) {
+    const name = queue.shift();
+    if (!name) {
+      break;
+    }
+
+    const plugin = pluginMap.get(name);
+    if (!plugin) {
+      continue;
+    }
+    order.push(plugin);
+
+    for (const dependent of dependents.get(name) ?? []) {
+      const next = (inDegree.get(dependent) ?? 0) - 1;
+      inDegree.set(dependent, next);
+      if (next === 0) {
+        queue.push(dependent);
+      }
+    }
+  }
+
+  if (order.length !== plugins.length) {
+    const resolvedNames = new Set(order.map((plugin) => plugin.name));
+    const remaining = plugins
+      .filter((plugin) => !resolvedNames.has(plugin.name))
+      .map((plugin) => plugin.name);
+    throw new Error(`Circular dependency detected among plugins: ${remaining.join(", ")}`);
+  }
+
+  const resultMap = new Map<string, ResolvedPlugin>();
+  order.forEach((plugin, orderIndex) => {
+    resultMap.set(plugin.name, { plugin, order: orderIndex });
+  });
+
+  return { order, map: resultMap };
+}

package/src/registry/hook-aggregator.test.ts

@@ -0,0 +1,78 @@
+import { describe, expect, it } from "bun:test";
+import { withPriority } from "../hooks/hook-ordering";
+import type { PluginDefinition } from "../types/plugin";
+import { aggregateHooks } from "./hook-aggregator";
+
+describe("aggregateHooks", () => {
+  it("orders handlers by explicit priority", async () => {
+    const execution: string[] = [];
+
+    const low = withPriority(async () => {
+      execution.push("low");
+    }, 20);
+
+    const high = withPriority(async () => {
+      execution.push("high");
+    }, -20);
+
+    const pluginA: PluginDefinition = {
+      name: "plugin-a",
+      hooks: {
+        "tool.execute.after": low,
+      },
+    };
+
+    const pluginB: PluginDefinition = {
+      name: "plugin-b",
+      hooks: {
+        "tool.execute.after": high,
+      },
+    };
+
+    const map = aggregateHooks([pluginA, pluginB]);
+    const handlers = map.get("tool.execute.after");
+
+    expect(handlers).toBeDefined();
+    for (const handler of handlers ?? []) {
+      await handler({}, {});
+    }
+
+    expect(execution).toEqual(["high", "low"]);
+  });
+
+  it("keeps registration order when priorities are equal", async () => {
+    const execution: string[] = [];
+
+    const first = async () => {
+      execution.push("first");
+    };
+
+    const second = async () => {
+      execution.push("second");
+    };
+
+    const pluginA: PluginDefinition = {
+      name: "plugin-a",
+      hooks: {
+        "chat.message": first,
+      },
+    };
+
+    const pluginB: PluginDefinition = {
+      name: "plugin-b",
+      hooks: {
+        "chat.message": second,
+      },
+    };
+
+    const map = aggregateHooks([pluginA, pluginB]);
+    const handlers = map.get("chat.message");
+
+    expect(handlers).toBeDefined();
+    for (const handler of handlers ?? []) {
+      await handler({}, {});
+    }
+
+    expect(execution).toEqual(["first", "second"]);
+  });
+});

package/src/registry/hook-aggregator.ts

@@ -0,0 +1,63 @@
+import type { PluginDefinition, PluginHookHandler } from "../types/plugin";
+import { log } from "../shared/logger";
+import { HOOK_TIERS, type HookTier } from "../hooks/hook-types";
+import { getHookPriority, sortByPriority } from "../hooks/hook-ordering";
+
+const TIER_PRIORITIES: Record<HookTier, number> = {
+  config: 0,
+  message: 10,
+  transform: 20,
+  event: 30,
+  tool: 40,
+};
+
+export function aggregateHooks(
+  plugins: PluginDefinition[],
+  disabledHooks?: string[],
+): Map<string, PluginHookHandler[]> {
+  const disabled = new Set(disabledHooks ?? []);
+  const hookMap = new Map<string, PluginHookHandler[]>();
+  const skippedHooks: string[] = [];
+
+  for (const plugin of plugins) {
+    if (!plugin.hooks) {
+      continue;
+    }
+
+    for (const [eventName, handler] of Object.entries(plugin.hooks)) {
+      if (handler === undefined) {
+        continue;
+      }
+      if (disabled.has(eventName)) {
+        skippedHooks.push(eventName);
+        continue;
+      }
+
+      const handlers = hookMap.get(eventName) ?? [];
+      // Type cast is necessary: TypeScript cannot narrow the union type HookHandlerFor<Name>
+      // in a generic loop. The cast is safe because each handler is registered under its
+      // correct event name and will be called with the appropriate arguments by the compositor.
+      handlers.push(handler as PluginHookHandler);
+      hookMap.set(eventName, handlers);
+    }
+  }
+
+  for (const [eventName, handlers] of hookMap.entries()) {
+    const tier = HOOK_TIERS[eventName as keyof typeof HOOK_TIERS];
+    const tierPriority = tier ? TIER_PRIORITIES[tier] : 100;
+    const prioritized = handlers.map((handler, order) => ({
+      handler,
+      priority: tierPriority + getHookPriority(handler),
+      order,
+    }));
+    hookMap.set(eventName, sortByPriority(prioritized));
+  }
+
+  if (skippedHooks.length > 0) {
+    log(
+      `[hook-aggregator] Skipped ${skippedHooks.length} disabled hook(s): ${skippedHooks.join(", ")}`,
+    );
+  }
+
+  return hookMap;
+}

package/src/registry/index.ts

@@ -0,0 +1,6 @@
+export { aggregateAgents } from "./agent-aggregator";
+export { resolvePluginOrder } from "./dependency-resolver";
+export { aggregateHooks } from "./hook-aggregator";
+export { PluginRegistry } from "./plugin-registry";
+export { aggregateTools } from "./tool-aggregator";
+export type { ResolutionResult, ResolvedPlugin } from "./types";

package/src/registry/plugin-lifecycle.integration.test.ts

@@ -0,0 +1,94 @@
+import { describe, expect, it, mock } from "bun:test";
+import { createMockPluginContext } from "../test-utils/mock-plugin-context";
+import type { PluginDefinition } from "../types/plugin";
+import type { PluginToolContribution } from "../types/tool";
+import { PluginRegistry } from "./plugin-registry";
+
+function makeTool(): PluginToolContribution {
+  return { execute: async () => "ok" } as unknown as PluginToolContribution;
+}
+
+describe("plugin lifecycle integration", () => {
+  it("resolves, sets up, aggregates, and composes a valid plugin graph", async () => {
+    const setupCore = mock(async () => {});
+    const setupAddon = mock(async () => {});
+
+    const core: PluginDefinition = {
+      name: "core",
+      setup: setupCore,
+      tools: { core_tool: makeTool() },
+    };
+
+    const addon: PluginDefinition = {
+      name: "addon",
+      dependencies: ["core"],
+      setup: setupAddon,
+      hooks: {
+        "tool.execute.before": async () => {},
+      },
+    };
+
+    const registry = new PluginRegistry();
+    registry.register(addon);
+    registry.register(core);
+
+    const resolved = registry.resolve();
+    expect(resolved.map((plugin) => plugin.name)).toEqual(["core", "addon"]);
+
+    const initialized = await registry.setup(resolved, createMockPluginContext());
+    expect(initialized.map((plugin) => plugin.name)).toEqual(["core", "addon"]);
+    expect(setupCore).toHaveBeenCalledTimes(1);
+    expect(setupAddon).toHaveBeenCalledTimes(1);
+
+    const aggregated = registry.aggregate(initialized);
+    expect(Object.keys(aggregated.tools)).toContain("core_tool");
+    expect(aggregated.hooks.get("tool.execute.before")?.length).toBe(1);
+
+    expect(aggregated.tools.core_tool).toBeDefined();
+    expect(aggregated.hooks.get("tool.execute.before")?.length).toBe(1);
+  });
+
+  it("fails resolution when a dependency is missing", () => {
+    const registry = new PluginRegistry();
+    registry.register({ name: "feature", dependencies: ["missing"] });
+
+    expect(() => registry.resolve()).toThrow("depends on unknown plugin");
+  });
+
+  it("fails resolution when dependencies are circular", () => {
+    const registry = new PluginRegistry();
+    registry.register({ name: "a", dependencies: ["b"] });
+    registry.register({ name: "b", dependencies: ["a"] });
+
+    expect(() => registry.resolve()).toThrow("Circular dependency");
+  });
+
+  it("continues setup when one plugin setup fails", async () => {
+    const registry = new PluginRegistry();
+    const badSetup = mock(async () => {
+      throw new Error("setup failed");
+    });
+    const goodSetup = mock(async () => {});
+
+    registry.register({
+      name: "bad",
+      setup: badSetup,
+      tools: { bad_tool: makeTool() },
+    });
+    registry.register({
+      name: "good",
+      setup: goodSetup,
+      tools: { good_tool: makeTool() },
+    });
+
+    const resolved = registry.resolve();
+    const initialized = await registry.setup(resolved, createMockPluginContext());
+
+    expect(initialized.map((plugin) => plugin.name)).toEqual(["good"]);
+    expect(goodSetup).toHaveBeenCalledTimes(1);
+
+    const aggregated = registry.aggregate(initialized);
+    expect(Object.keys(aggregated.tools)).toContain("good_tool");
+    expect(Object.keys(aggregated.tools)).not.toContain("bad_tool");
+  });
+});

package/src/registry/plugin-overrides.integration.test.ts

@@ -0,0 +1,140 @@
+import { describe, expect, it } from "bun:test";
+import { buildAgent } from "../agents/agent-builder";
+import type { AgentConfig, AgentFactory } from "../types/agent";
+import type { PluginDefinition } from "../types/plugin";
+import type { PluginToolContribution } from "../types/tool";
+import { aggregateAgents } from "./agent-aggregator";
+import { aggregateHooks } from "./hook-aggregator";
+import { PluginRegistry } from "./plugin-registry";
+import { aggregateTools } from "./tool-aggregator";
+
+function makeTool(): PluginToolContribution {
+  return { execute: async () => "ok" } as unknown as PluginToolContribution;
+}
+
+function makeAgent(overrides: Partial<AgentConfig> = {}): AgentConfig {
+  return {
+    instructions: "test agent",
+    model: "test-model",
+    temperature: 0.5,
+    ...overrides,
+  } as AgentConfig;
+}
+
+describe("plugin overrides integration", () => {
+  describe("aggregateAgents", () => {
+    describe("#given a plugin contributing an agent named 'advisor'", () => {
+      describe("#when aggregated with disabledAgents containing 'advisor'", () => {
+        it("#then 'advisor' is not present in the aggregated output", () => {
+          const plugin: PluginDefinition = {
+            name: "test-plugin",
+            agents: { advisor: makeAgent() },
+          };
+
+          const result = aggregateAgents([plugin], ["advisor"]);
+
+          expect(result).not.toHaveProperty("advisor");
+          expect(Object.keys(result)).toHaveLength(0);
+        });
+      });
+    });
+  });
+
+  describe("aggregateTools", () => {
+    describe("#given a plugin contributing a tool named 'grep'", () => {
+      describe("#when aggregated with disabledTools containing 'grep'", () => {
+        it("#then 'grep' is not present in the aggregated output", () => {
+          const plugin: PluginDefinition = {
+            name: "test-plugin",
+            tools: { grep: makeTool() },
+          };
+
+          const result = aggregateTools([plugin], ["grep"]);
+
+          expect(result).not.toHaveProperty("grep");
+          expect(Object.keys(result)).toHaveLength(0);
+        });
+      });
+    });
+  });
+
+  describe("aggregateHooks", () => {
+    describe("#given a plugin contributing a 'tool.execute.before' hook handler", () => {
+      describe("#when aggregated with disabledHooks containing 'tool.execute.before'", () => {
+        it("#then 'tool.execute.before' is absent from the result map", () => {
+          const plugin: PluginDefinition = {
+            name: "test-plugin",
+            hooks: {
+              "tool.execute.before": async () => {},
+            },
+          };
+
+          const result = aggregateHooks([plugin], ["tool.execute.before"]);
+
+          expect(result.has("tool.execute.before")).toBe(false);
+          expect(result.size).toBe(0);
+        });
+      });
+    });
+  });
+
+  describe("buildAgent", () => {
+    describe("#given an agent factory returning model 'original-model' and temperature 0.5", () => {
+      describe("#when built with overrides model 'override-model' and temperature 0.9", () => {
+        it("#then the returned config has the overridden model and temperature", () => {
+          const factory: AgentFactory = Object.assign(
+            (_model: string): AgentConfig =>
+              ({
+                instructions: "test agent",
+                model: "original-model",
+                temperature: 0.5,
+              }) as AgentConfig,
+            { mode: "all" as const },
+          );
+
+          const result = buildAgent(factory, "base-model", undefined, {
+            model: "override-model",
+            temperature: 0.9,
+          });
+
+          expect(result.model).toBe("override-model");
+          expect(result.temperature).toBe(0.9);
+          expect(result.instructions).toBe("test agent");
+        });
+      });
+    });
+  });
+
+  describe("PluginRegistry.aggregate", () => {
+    describe("#given a plugin with agent 'advisor', tool 'grep', and hook 'tool.execute.before'", () => {
+      describe("#when aggregated with disabledAgents=['advisor'] and disabledTools=['grep']", () => {
+        it("#then 'advisor' not in agents, 'grep' not in tools, but hook is still present", () => {
+          const plugin: PluginDefinition = {
+            name: "test-plugin",
+            agents: { advisor: makeAgent() },
+            tools: { grep: makeTool() },
+            hooks: {
+              "tool.execute.before": async () => {},
+            },
+          };
+
+          const registry = new PluginRegistry();
+          registry.register(plugin);
+          const resolved = registry.resolve();
+
+          const aggregated = registry.aggregate(resolved, {
+            disabledAgents: ["advisor"],
+            disabledTools: ["grep"],
+          });
+
+          expect(aggregated.agents).not.toHaveProperty("advisor");
+          expect(Object.keys(aggregated.agents)).toHaveLength(0);
+          expect(aggregated.tools).not.toHaveProperty("grep");
+          expect(Object.keys(aggregated.tools)).toHaveLength(0);
+          expect(aggregated.hooks.has("tool.execute.before")).toBe(true);
+          expect(aggregated.hooks.get("tool.execute.before")).toHaveLength(1);
+        });
+      });
+    });
+  });
+});