goatcode-sh 0.0.1 → 0.1.2

package/src/hooks/hook-composer.test.ts

@@ -0,0 +1,52 @@
+import { describe, expect, it } from "bun:test";
+
+import type { PluginHookHandler } from "../types/plugin";
+import { composeHooks } from "./hook-composer";
+
+describe("composeHooks", () => {
+  describe("#given 3 handlers", () => {
+    describe("#when composed and called", () => {
+      it("#then all 3 fire in order", async () => {
+        const calls: number[] = [];
+        const handler1: PluginHookHandler = async () => {
+          calls.push(1);
+        };
+        const handler2: PluginHookHandler = async () => {
+          calls.push(2);
+        };
+        const handler3: PluginHookHandler = async () => {
+          calls.push(3);
+        };
+
+        const composed = composeHooks("event", [handler1, handler2, handler3]);
+
+        await composed({}, {});
+
+        expect(calls).toEqual([1, 2, 3]);
+      });
+    });
+  });
+
+  describe("#given one handler throws", () => {
+    describe("#when composed with safe=true and called", () => {
+      it("#then other handlers still fire", async () => {
+        const calls: string[] = [];
+        const first: PluginHookHandler = async () => {
+          calls.push("first");
+        };
+        const failing: PluginHookHandler = async () => {
+          throw new Error("boom");
+        };
+        const last: PluginHookHandler = async () => {
+          calls.push("last");
+        };
+
+        const composed = composeHooks("event", [first, failing, last], { safe: true });
+
+        await composed({}, {});
+
+        expect(calls).toEqual(["first", "last"]);
+      });
+    });
+  });
+});

package/src/hooks/hook-composer.ts

@@ -0,0 +1,17 @@
+import type { PluginHookHandler } from "../types/plugin";
+import { wrapSafely } from "./safe-hook-wrapper";
+
+export function composeHooks(
+  eventName: string,
+  handlers: PluginHookHandler[],
+  options?: { safe?: boolean },
+): PluginHookHandler {
+  const wrapped =
+    options?.safe !== false ? handlers.map((h) => wrapSafely(eventName, h)) : handlers;
+
+  return async (input: unknown, output: unknown) => {
+    for (const handler of wrapped) {
+      await handler(input, output);
+    }
+  };
+}

package/src/hooks/hook-composition.integration.test.ts

@@ -0,0 +1,274 @@
+import { describe, expect, it } from "bun:test";
+
+import { EDIT_ERROR_RECOVERY_MESSAGE } from "./edit-error/handler";
+import { composeHooks } from "./hook-composer";
+import { withPriority } from "./hook-ordering";
+import { HOOK_TIERS, type HookTier } from "./hook-types";
+import { clearSessionMode, createKeywordDetectorHandler } from "./keyword-detector/handler";
+import { createThinkModeHandler } from "./think-mode/handler";
+import { aggregateHooks } from "../registry/hook-aggregator";
+import type { PluginDefinition, PluginHookHandler } from "../types/plugin";
+
+const TIER_PRIORITIES: Record<HookTier, number> = {
+  config: 0,
+  message: 10,
+  transform: 20,
+  event: 30,
+  tool: 40,
+};
+
+function getTierPriority(eventName: string): number {
+  const tier = HOOK_TIERS[eventName as keyof typeof HOOK_TIERS];
+  return tier ? TIER_PRIORITIES[tier] : 100;
+}
+
+async function runAggregatedHooksByTier(
+  hookMap: Map<string, PluginHookHandler[]>,
+  ioByEvent: Record<string, { input: unknown; output: unknown }>,
+): Promise<void> {
+  const orderedEvents = [...hookMap.entries()].sort(
+    ([eventA], [eventB]) => getTierPriority(eventA) - getTierPriority(eventB),
+  );
+
+  for (const [eventName, handlers] of orderedEvents) {
+    const composed = composeHooks(eventName, handlers);
+    const io = ioByEvent[eventName] ?? { input: {}, output: {} };
+    await composed(io.input, io.output);
+  }
+}
+
+describe("hook composition integration", () => {
+  describe("#given hooks across config/message/tool tiers", () => {
+    describe("#when hooks are aggregated and executed by tier priority", () => {
+      it("#then config fires before message, and message before tool", async () => {
+        const calls: string[] = [];
+
+        const plugins: PluginDefinition[] = [
+          {
+            name: "config-plugin",
+            hooks: {
+              config: async () => {
+                calls.push("config");
+              },
+            },
+          },
+          {
+            name: "message-plugin",
+            hooks: {
+              "chat.message": async () => {
+                calls.push("message");
+              },
+            },
+          },
+          {
+            name: "tool-plugin",
+            hooks: {
+              "tool.execute.before": async () => {
+                calls.push("tool");
+              },
+            },
+          },
+        ];
+
+        const aggregated = aggregateHooks(plugins);
+        await runAggregatedHooksByTier(aggregated, {
+          config: { input: {}, output: {} },
+          "chat.message": { input: {}, output: {} },
+          "tool.execute.before": { input: {}, output: {} },
+        });
+
+        expect(calls).toEqual(["config", "message", "tool"]);
+      });
+    });
+  });
+
+  describe("#given two handlers in the same tier and event", () => {
+    describe("#when one handler has lower explicit priority", () => {
+      it("#then the lower-priority-number handler fires first", async () => {
+        const calls: string[] = [];
+
+        const earlyHandler = withPriority(async () => {
+          calls.push("early");
+        }, -1);
+
+        const aggregated = aggregateHooks([
+          {
+            name: "normal-message-plugin",
+            hooks: {
+              "chat.message": async () => {
+                calls.push("normal");
+              },
+            },
+          },
+          {
+            name: "early-message-plugin",
+            hooks: { "chat.message": earlyHandler },
+          },
+        ]);
+
+        const handlers = aggregated.get("chat.message") ?? [];
+        const composed = composeHooks("chat.message", handlers);
+
+        await composed({}, {});
+
+        expect(calls).toEqual(["early", "normal"]);
+      });
+    });
+  });
+
+  describe("#given multiple hooks mutating the same output field", () => {
+    describe("#when both handlers append to output.output", () => {
+      it("#then both mutations are accumulated in sequence", async () => {
+        const plugins: PluginDefinition[] = [
+          {
+            name: "append-a",
+            hooks: {
+              "tool.execute.after": async (_input, output) => {
+                if (typeof output === "object" && output !== null && "output" in output) {
+                  const current = output.output;
+                  if (typeof current === "string") {
+                    output.output = `${current}\n[A]`;
+                  }
+                }
+              },
+            },
+          },
+          {
+            name: "append-b",
+            hooks: {
+              "tool.execute.after": async (_input, output) => {
+                if (typeof output === "object" && output !== null && "output" in output) {
+                  const current = output.output;
+                  if (typeof current === "string") {
+                    output.output = `${current}\n[B]`;
+                  }
+                }
+              },
+            },
+          },
+        ];
+
+        const aggregated = aggregateHooks(plugins);
+        const handlers = aggregated.get("tool.execute.after") ?? [];
+        const composed = composeHooks("tool.execute.after", handlers);
+
+        const input = {
+          tool: "bash",
+          sessionID: "ses_accumulate",
+          callID: "call_accumulate",
+          args: {},
+        };
+        const output = { output: "base", title: "tool execution", metadata: {} };
+        await composed(input, output);
+
+        expect(output.output).toBe("base\n[A]\n[B]");
+      });
+    });
+  });
+
+  describe("#given keyword-detector and think-mode handlers", () => {
+    describe("#when a message enables think mode for a session", () => {
+      it("#then chat.params composition reads shared session state and injects thinking", async () => {
+        const sessionID = "ses_hook_chain";
+        clearSessionMode(sessionID);
+
+        const keywordHandler = createKeywordDetectorHandler();
+        const thinkModeHandler = createThinkModeHandler();
+
+        const messageInput = { sessionID };
+        const messageOutput = {
+          message: {},
+          parts: [{ type: "text", text: "Please deep-think this architecture change." }],
+        };
+
+        await keywordHandler(messageInput, messageOutput);
+
+        const paramsInput = {
+          sessionID,
+          agent: "sisyphus",
+          model: {
+            providerID: "anthropic",
+            modelID: "claude-3-7-sonnet",
+          },
+          provider: { id: "anthropic" },
+          message: {},
+        };
+        const paramsOutput = {
+          temperature: 0.1,
+          topP: 1,
+          topK: 0,
+          options: {},
+        };
+
+        await thinkModeHandler(paramsInput, paramsOutput);
+
+        expect(paramsOutput.options).toEqual({
+          thinking: {
+            type: "enabled",
+            budget_tokens: 10000,
+          },
+        });
+
+        clearSessionMode(sessionID);
+      });
+    });
+  });
+
+  describe("#given two hooks that both append guidance to tool output", () => {
+    describe("#when composed handlers run on an edit failure payload", () => {
+      it("#then truncation notice and edit recovery guidance are both preserved", async () => {
+        const plugins: PluginDefinition[] = [
+          {
+            name: "tool-output-truncator-like",
+            hooks: {
+              "tool.execute.after": async (_input, output) => {
+                if (typeof output === "object" && output !== null && "output" in output) {
+                  const current = output.output;
+                  if (typeof current === "string") {
+                    output.output = `${current}\n[Output truncated: synthetic notice for integration test.]`;
+                  }
+                }
+              },
+            },
+          },
+          {
+            name: "edit-error-like",
+            hooks: {
+              "tool.execute.after": async (_input, output) => {
+                if (typeof output === "object" && output !== null && "output" in output) {
+                  const current = output.output;
+                  if (typeof current === "string" && /oldstring not found/i.test(current)) {
+                    output.output = `${current}\n${EDIT_ERROR_RECOVERY_MESSAGE}`;
+                  }
+                }
+              },
+            },
+          },
+        ];
+
+        const handlers = aggregateHooks(plugins).get("tool.execute.after") ?? [];
+        const composed = composeHooks("tool.execute.after", handlers);
+
+        const input = {
+          tool: "edit",
+          sessionID: "ses_dual_mutation",
+          callID: "call_dual_mutation",
+          args: {},
+        };
+        const output = {
+          output: "oldString not found while applying patch",
+          title: "tool execution",
+          metadata: {},
+        };
+
+        await composed(input, output);
+
+        expect(typeof output.output).toBe("string");
+        expect(output.output).toContain(
+          "[Output truncated: synthetic notice for integration test.]",
+        );
+        expect(output.output).toContain(EDIT_ERROR_RECOVERY_MESSAGE);
+      });
+    });
+  });
+});

package/src/hooks/hook-ordering.ts

@@ -0,0 +1,41 @@
+import type { PluginHookHandler } from "../types/plugin";
+
+const HOOK_PRIORITY_SYMBOL = Symbol.for("goatcode.hookPriority");
+
+export type PrioritizedHandler = {
+  handler: PluginHookHandler;
+  priority: number;
+  order: number;
+};
+
+export function sortByPriority(handlers: PrioritizedHandler[]): PluginHookHandler[] {
+  return [...handlers]
+    .sort((a, b) => {
+      if (a.priority !== b.priority) {
+        return a.priority - b.priority;
+      }
+      return a.order - b.order;
+    })
+    .map((h) => h.handler);
+}
+
+export function getHookPriority(handler: PluginHookHandler): number {
+  const value = (handler as PluginHookHandler & { [HOOK_PRIORITY_SYMBOL]?: unknown })[
+    HOOK_PRIORITY_SYMBOL
+  ];
+  return typeof value === "number" ? value : 0;
+}
+
+export function withPriority<T extends PluginHookHandler>(handler: T, priority: number): T {
+  const wrapped = function (this: unknown, ...args: unknown[]) {
+    return (handler as (...args: unknown[]) => unknown).apply(this, args);
+  } as T;
+
+  Object.defineProperty(wrapped, HOOK_PRIORITY_SYMBOL, {
+    configurable: false,
+    enumerable: false,
+    writable: false,
+    value: priority,
+  });
+  return wrapped;
+}

package/src/hooks/hook-types.ts

@@ -0,0 +1,22 @@
+import type { HookEventName } from "../types/hook";
+
+export type HookTier = "message" | "tool" | "transform" | "event" | "config";
+
+export const HOOK_TIERS: Record<HookEventName, HookTier> = {
+  tool: "tool",
+  "chat.message": "message",
+  "chat.params": "message",
+  "chat.headers": "message",
+  "tool.execute.before": "tool",
+  "tool.execute.after": "tool",
+  "tool.definition": "tool",
+  "permission.ask": "event",
+  "command.execute.before": "event",
+  "shell.env": "event",
+  "experimental.chat.messages.transform": "transform",
+  "experimental.chat.system.transform": "transform",
+  "experimental.session.compacting": "transform",
+  "experimental.text.complete": "transform",
+  event: "event",
+  config: "config",
+};

package/src/hooks/index.ts

@@ -0,0 +1,6 @@
+export { composeHooks } from "./hook-composer";
+export { wrapSafely } from "./safe-hook-wrapper";
+export { HOOK_TIERS } from "./hook-types";
+export { sortByPriority, withPriority } from "./hook-ordering";
+export type { HookTier } from "./hook-types";
+export type { PrioritizedHandler } from "./hook-ordering";

package/src/hooks/json-error/handler.test.ts

@@ -0,0 +1,95 @@
+import { describe, expect, it } from "bun:test";
+
+import { createJsonErrorHandler, JSON_ERROR_RECOVERY_MESSAGE } from "./handler";
+
+type UnknownHandler = (input: unknown, output: unknown) => Promise<void>;
+
+describe("createJsonErrorHandler", () => {
+  describe("#given a handler instance", () => {
+    const handler = createJsonErrorHandler() as unknown as UnknownHandler;
+
+    describe("#when output contains a JSON error pattern", () => {
+      it("#then appends JSON_ERROR_RECOVERY_MESSAGE", async () => {
+        const input = {};
+        const output = { output: "JSON parse error: unexpected token at position 5" };
+        await handler(input, output);
+        expect(output.output).toContain("[JSON ERROR RECOVERY]");
+        expect(output.output).toContain("JSON parse error: unexpected token at position 5");
+      });
+    });
+
+    describe("#when output looks like malformed JSON and json is expected via metadata", () => {
+      it("#then appends recovery message", async () => {
+        const input = {};
+        const output = {
+          output: '{ "key": "value", }',
+          metadata: { format: "json" },
+        };
+        await handler(input, output);
+        expect(output.output).toContain("[JSON ERROR RECOVERY]");
+      });
+    });
+
+    describe("#when output is valid JSON", () => {
+      it("#then output remains unchanged", async () => {
+        const input = {};
+        const output = {
+          output: '{"key": "value"}',
+          metadata: { format: "json" },
+        };
+        await handler(input, output);
+        expect(output.output).toBe('{"key": "value"}');
+      });
+    });
+
+    describe("#when output already contains recovery marker", () => {
+      it("#then does not double-append", async () => {
+        const input = {};
+        const output = {
+          output: `JSON parse error\n${JSON_ERROR_RECOVERY_MESSAGE}`,
+        };
+        const before = output.output;
+        await handler(input, output);
+        expect(output.output).toBe(before);
+      });
+    });
+
+    describe("#when output.output is not a string", () => {
+      it("#then no-op", async () => {
+        const input = {};
+        const output = { output: 123 };
+        await handler(input, output);
+        expect(output.output).toBe(123);
+      });
+    });
+
+    describe("#when output is not a record", () => {
+      it("#then no-op", async () => {
+        const output = "not-an-object";
+        await handler({}, output);
+        expect(output).toBe("not-an-object");
+      });
+    });
+
+    describe("#when output looks like JSON but json is NOT expected", () => {
+      it("#then no recovery (no error pattern, no json expectation)", async () => {
+        const input = {};
+        const output = { output: '{ "key": "value", }' };
+        await handler(input, output);
+        expect(output.output).toBe('{ "key": "value", }');
+      });
+    });
+
+    describe("#when output matches via title containing 'json'", () => {
+      it("#then appends recovery for malformed json", async () => {
+        const input = {};
+        const output = {
+          output: "[ invalid json array",
+          title: "JSON Response",
+        };
+        await handler(input, output);
+        expect(output.output).toContain("[JSON ERROR RECOVERY]");
+      });
+    });
+  });
+});

package/src/hooks/json-error/handler.ts

@@ -0,0 +1,82 @@
+import type { PluginHookContributions } from "../../types/hook";
+import { log } from "../../shared/logger";
+
+export const JSON_ERROR_PATTERNS = [
+  /json parse error/i,
+  /failed to parse json/i,
+  /invalid json/i,
+  /malformed json/i,
+  /unexpected end of json input/i,
+  /syntaxerror:\s*unexpected token.*json/i,
+] as const;
+
+const JSON_ERROR_RECOVERY_MARKER = "[JSON ERROR RECOVERY]";
+
+export const JSON_ERROR_RECOVERY_MESSAGE = `${JSON_ERROR_RECOVERY_MARKER}\nTool output appears to be malformed JSON. Re-check the response shape, validate it as strict JSON, and retry with a corrected payload or parser expectation.`;
+
+type PostToolUseHook = NonNullable<PluginHookContributions["tool.execute.after"]>;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+function looksLikeJson(text: string): boolean {
+  const trimmed = text.trim();
+  return trimmed.startsWith("{") || trimmed.startsWith("[");
+}
+
+function isValidJson(text: string): boolean {
+  try {
+    JSON.parse(text);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function isJsonExpected(output: Record<string, unknown>): boolean {
+  const title = output.title;
+  const metadata = output.metadata;
+
+  if (typeof title === "string" && /json/i.test(title)) {
+    return true;
+  }
+
+  if (!isRecord(metadata)) {
+    return false;
+  }
+
+  return (
+    metadata.format === "json" ||
+    metadata.expectedFormat === "json" ||
+    metadata.expectsJson === true
+  );
+}
+
+export function createJsonErrorHandler(): PostToolUseHook {
+  return async (_input: unknown, output: unknown) => {
+    if (!isRecord(output)) {
+      return;
+    }
+
+    const toolOutput = output.output;
+    if (typeof toolOutput !== "string") {
+      return;
+    }
+
+    if (toolOutput.includes(JSON_ERROR_RECOVERY_MARKER)) {
+      return;
+    }
+
+    const hasJsonErrorPattern = JSON_ERROR_PATTERNS.some((pattern) => pattern.test(toolOutput));
+    const malformedJson = looksLikeJson(toolOutput) && !isValidJson(toolOutput);
+    const shouldRecover = hasJsonErrorPattern || (isJsonExpected(output) && malformedJson);
+
+    if (!shouldRecover) {
+      return;
+    }
+
+    output.output = `${toolOutput}\n${JSON_ERROR_RECOVERY_MESSAGE}`;
+    log("[json-error] injected JSON recovery message");
+  };
+}

package/src/hooks/json-error/index.ts

@@ -0,0 +1,6 @@
+export { jsonErrorPlugin } from "./plugin";
+export {
+  createJsonErrorHandler,
+  JSON_ERROR_PATTERNS,
+  JSON_ERROR_RECOVERY_MESSAGE,
+} from "./handler";

package/src/hooks/json-error/plugin.ts

@@ -0,0 +1,15 @@
+import { definePlugin } from "../../plugin-api/define-plugin";
+import { safeCreateHook } from "../../shared/safe-create-hook";
+import { createJsonErrorHandler } from "./handler";
+
+const toolExecuteAfterHook = safeCreateHook("json-error", createJsonErrorHandler);
+
+export const jsonErrorPlugin = definePlugin({
+  name: "json-error",
+  version: "0.1.0",
+  hooks: toolExecuteAfterHook
+    ? {
+        "tool.execute.after": toolExecuteAfterHook,
+      }
+    : {},
+});