goatcode-sh 0.0.1 → 0.1.3

package/src/hooks/quality.test.ts

@@ -0,0 +1,330 @@
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+
+import { createCommentCheckerHandler, EMPTY_CATCH_WARNING } from "./comment-checker/handler";
+import { createWriteFileGuardHandler, BLOCK_MESSAGE } from "./write-file-guard/handler";
+import { createThinkingBlockValidatorHandler } from "./thinking-block-validator/handler";
+
+describe("createCommentCheckerHandler", () => {
+  describe("#given a write tool call with an empty catch block", () => {
+    describe("#when the handler runs", () => {
+      it("#then injects a warning into output.output", async () => {
+        const handler = createCommentCheckerHandler();
+        const input = { tool: "write", sessionID: "ses_1", callID: "call_1" };
+        const output: Record<string, unknown> = {
+          content: `
+function foo() {
+  try {
+    doSomething()
+  } catch (e) {}
+}
+`,
+        };
+
+        await handler(input, output);
+
+        expect(typeof output.output).toBe("string");
+        expect(output.output as string).toContain(EMPTY_CATCH_WARNING);
+      });
+    });
+  });
+
+  describe("#given a write tool call with a commented catch block", () => {
+    describe("#when the handler runs", () => {
+      it("#then does not inject a warning", async () => {
+        const handler = createCommentCheckerHandler();
+        const input = { tool: "write", sessionID: "ses_1", callID: "call_1" };
+        const output: Record<string, unknown> = {
+          content: `
+function foo() {
+  try {
+    doSomething()
+  } catch (e) {
+    // ignore: expected on first run
+  }
+}
+`,
+        };
+
+        await handler(input, output);
+
+        expect(output.output).toBeUndefined();
+      });
+    });
+  });
+
+  describe("#given a non-write/edit tool call", () => {
+    describe("#when the handler runs", () => {
+      it("#then does nothing", async () => {
+        const handler = createCommentCheckerHandler();
+        const input = { tool: "bash", sessionID: "ses_1", callID: "call_1" };
+        const output: Record<string, unknown> = {
+          content: "try {} catch (e) {}",
+        };
+
+        await handler(input, output);
+
+        expect(output.output).toBeUndefined();
+      });
+    });
+  });
+
+  describe("#given an edit tool call with empty catch in newString", () => {
+    describe("#when the handler runs", () => {
+      it("#then injects a warning", async () => {
+        const handler = createCommentCheckerHandler();
+        const input = { tool: "edit", sessionID: "ses_1", callID: "call_1" };
+        const output: Record<string, unknown> = {
+          newString: "try { doThing() } catch (err) {}",
+        };
+
+        await handler(input, output);
+
+        expect(output.output as string).toContain(EMPTY_CATCH_WARNING);
+      });
+    });
+  });
+});
+
+describe("createWriteFileGuardHandler", () => {
+  let tempDir: string;
+
+  const createFile = (relativePath: string, content = "existing"): string => {
+    const abs = join(tempDir, relativePath);
+    mkdirSync(dirname(abs), { recursive: true });
+    writeFileSync(abs, content);
+    return abs;
+  };
+
+  const invokePreToolUse = async (
+    handler: ReturnType<typeof createWriteFileGuardHandler>,
+    opts: {
+      tool: string;
+      sessionID?: string;
+      filePath: string;
+    },
+  ): Promise<void> => {
+    const input = {
+      tool: opts.tool,
+      sessionID: opts.sessionID ?? "ses_default",
+      callID: "call_1",
+    };
+    const output = { args: { filePath: opts.filePath } };
+    await handler.preToolUse(input, output);
+  };
+
+  beforeEach(() => {
+    tempDir = mkdtempSync(join(tmpdir(), "write-file-guard-test-"));
+  });
+
+  afterEach(() => {
+    rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  describe("#given an existing file with no prior read", () => {
+    describe("#when write is attempted", () => {
+      it("#then throws block error", async () => {
+        const handler = createWriteFileGuardHandler(tempDir);
+        const existingFile = createFile("existing.txt");
+
+        await expect(
+          invokePreToolUse(handler, { tool: "write", filePath: existingFile }),
+        ).rejects.toThrow(BLOCK_MESSAGE);
+      });
+    });
+  });
+
+  describe("#given an existing file that was read first in the same session", () => {
+    describe("#when write is attempted", () => {
+      it("#then allows the write", async () => {
+        const handler = createWriteFileGuardHandler(tempDir);
+        const existingFile = createFile("readable.txt");
+        const sessionID = "ses_read_first";
+
+        await invokePreToolUse(handler, { tool: "read", sessionID, filePath: existingFile });
+
+        await expect(
+          invokePreToolUse(handler, { tool: "write", sessionID, filePath: existingFile }),
+        ).resolves.toBeUndefined();
+      });
+    });
+  });
+
+  describe("#given a non-existing file", () => {
+    describe("#when write is attempted", () => {
+      it("#then allows the write", async () => {
+        const handler = createWriteFileGuardHandler(tempDir);
+        const newFile = join(tempDir, "new-file.txt");
+
+        await expect(
+          invokePreToolUse(handler, { tool: "write", filePath: newFile }),
+        ).resolves.toBeUndefined();
+      });
+    });
+  });
+
+  describe("#given a read in a different session", () => {
+    describe("#when write is attempted from another session", () => {
+      it("#then blocks the write", async () => {
+        const handler = createWriteFileGuardHandler(tempDir);
+        const existingFile = createFile("cross-session.txt");
+
+        await invokePreToolUse(handler, {
+          tool: "read",
+          sessionID: "ses_reader",
+          filePath: existingFile,
+        });
+
+        await expect(
+          invokePreToolUse(handler, {
+            tool: "write",
+            sessionID: "ses_writer",
+            filePath: existingFile,
+          }),
+        ).rejects.toThrow(BLOCK_MESSAGE);
+      });
+    });
+  });
+
+  describe("#given a session that was deleted after reading", () => {
+    describe("#when write is attempted after session deletion", () => {
+      it("#then blocks the write", async () => {
+        const handler = createWriteFileGuardHandler(tempDir);
+        const existingFile = createFile("cleanup.txt");
+        const sessionID = "ses_cleanup";
+
+        await invokePreToolUse(handler, { tool: "read", sessionID, filePath: existingFile });
+
+        await handler.event({
+          event: { type: "session.deleted", properties: { info: { id: sessionID } } },
+        });
+
+        await expect(
+          invokePreToolUse(handler, { tool: "write", sessionID, filePath: existingFile }),
+        ).rejects.toThrow(BLOCK_MESSAGE);
+      });
+    });
+  });
+});
+
+describe("createThinkingBlockValidatorHandler", () => {
+  describe("#given messages with a malformed thinking block (empty thinking)", () => {
+    describe("#when the handler runs", () => {
+      it("#then strips the malformed thinking block", async () => {
+        const handler = createThinkingBlockValidatorHandler();
+        const messages = [
+          {
+            info: { role: "assistant", id: "msg_1" },
+            parts: [
+              { type: "thinking", thinking: "" },
+              { type: "text", text: "Hello" },
+            ],
+          },
+        ];
+        const output = { messages };
+
+        await handler({}, output);
+
+        expect(messages[0].parts).toHaveLength(1);
+        expect(messages[0].parts[0].type).toBe("text");
+      });
+    });
+  });
+
+  describe("#given messages with a well-formed thinking block", () => {
+    describe("#when the handler runs", () => {
+      it("#then keeps the thinking block intact", async () => {
+        const handler = createThinkingBlockValidatorHandler();
+        const messages = [
+          {
+            info: { role: "assistant", id: "msg_1" },
+            parts: [
+              { type: "thinking", thinking: "I need to think about this carefully." },
+              { type: "text", text: "Here is my answer." },
+            ],
+          },
+        ];
+        const output = { messages };
+
+        await handler({}, output);
+
+        expect(messages[0].parts).toHaveLength(2);
+        expect(messages[0].parts[0].type).toBe("thinking");
+      });
+    });
+  });
+
+  describe("#given messages with a whitespace-only thinking block", () => {
+    describe("#when the handler runs", () => {
+      it("#then strips the whitespace-only thinking block", async () => {
+        const handler = createThinkingBlockValidatorHandler();
+        const messages = [
+          {
+            info: { role: "assistant", id: "msg_1" },
+            parts: [
+              { type: "thinking", thinking: "   \n  " },
+              { type: "text", text: "Response" },
+            ],
+          },
+        ];
+        const output = { messages };
+
+        await handler({}, output);
+
+        expect(messages[0].parts).toHaveLength(1);
+        expect(messages[0].parts[0].type).toBe("text");
+      });
+    });
+  });
+
+  describe("#given messages with no thinking blocks", () => {
+    describe("#when the handler runs", () => {
+      it("#then leaves messages unchanged", async () => {
+        const handler = createThinkingBlockValidatorHandler();
+        const messages = [
+          {
+            info: { role: "assistant", id: "msg_1" },
+            parts: [{ type: "text", text: "Just text." }],
+          },
+        ];
+        const output = { messages };
+
+        await handler({}, output);
+
+        expect(messages[0].parts).toHaveLength(1);
+      });
+    });
+  });
+
+  describe("#given user messages with malformed thinking blocks", () => {
+    describe("#when the handler runs", () => {
+      it("#then does not strip from user messages", async () => {
+        const handler = createThinkingBlockValidatorHandler();
+        const messages = [
+          {
+            info: { role: "user", id: "msg_1" },
+            parts: [{ type: "thinking", thinking: "" }],
+          },
+        ];
+        const output = { messages };
+
+        await handler({}, output);
+
+        expect(messages[0].parts).toHaveLength(1);
+      });
+    });
+  });
+
+  describe("#given empty output", () => {
+    describe("#when the handler runs", () => {
+      it("#then does not throw", async () => {
+        const handler = createThinkingBlockValidatorHandler();
+
+        await expect(handler({}, {})).resolves.toBeUndefined();
+        await expect(handler({}, { messages: [] })).resolves.toBeUndefined();
+      });
+    });
+  });
+});

package/src/hooks/runtime-fallback/handler.test.ts

@@ -0,0 +1,142 @@
+import { describe, expect, it, mock } from "bun:test";
+import { createRuntimeFallbackHandler } from "./handler";
+
+describe("createRuntimeFallbackHandler", () => {
+  describe("#given a handler with a fallback chain", () => {
+    describe("#when error message contains 'model not found'", () => {
+      it("#then switches to a compatible same-provider fallback", async () => {
+        const setCurrentModel = mock((_sid: string, _model: string) => {});
+
+        const handler = createRuntimeFallbackHandler({
+          setCurrentModel,
+        });
+
+        await handler({
+          event: {
+            type: "session.error",
+            properties: {
+              sessionID: "ses-notfound",
+              model: "openai/gpt-5",
+              error: { message: "Model not found for this provider" },
+              fallbackChain: [
+                "anthropic/claude-3.7-sonnet",
+                "openai/gpt-4.1-mini",
+                "google/gemini-2.5-pro",
+              ],
+            },
+          },
+        });
+
+        expect(setCurrentModel).toHaveBeenCalledTimes(1);
+        expect(setCurrentModel).toHaveBeenCalledWith("ses-notfound", "openai/gpt-4.1-mini");
+      });
+    });
+
+    describe("#when error message contains 'context length'", () => {
+      it("#then triggers fallback for context-exceeded reason", async () => {
+        const setCurrentModel = mock((_sid: string, _model: string) => {});
+        const onFallbackApplied = mock(() => {});
+
+        const handler = createRuntimeFallbackHandler({
+          setCurrentModel,
+          onFallbackApplied,
+        });
+
+        await handler({
+          event: {
+            type: "session.error",
+            properties: {
+              sessionID: "ses-ctx",
+              model: "anthropic/claude-3-5-sonnet",
+              error: { message: "Maximum context length exceeded" },
+              fallbackChain: [
+                "anthropic/claude-3-5-sonnet",
+                "anthropic/claude-3-5-haiku",
+                "openai/gpt-4o",
+              ],
+            },
+          },
+        });
+
+        expect(setCurrentModel).toHaveBeenCalledTimes(1);
+        expect(setCurrentModel).toHaveBeenCalledWith("ses-ctx", "anthropic/claude-3-5-haiku");
+        expect(onFallbackApplied).toHaveBeenCalledTimes(1);
+      });
+    });
+
+    describe("#when error message is a generic error", () => {
+      it("#then does not trigger any fallback", async () => {
+        const setCurrentModel = mock((_sid: string, _model: string) => {});
+
+        const handler = createRuntimeFallbackHandler({
+          setCurrentModel,
+        });
+
+        await handler({
+          event: {
+            type: "session.error",
+            properties: {
+              sessionID: "ses-generic",
+              model: "openai/gpt-4o",
+              error: { message: "Something went wrong" },
+              fallbackChain: ["openai/gpt-4o", "anthropic/claude-3-5-sonnet"],
+            },
+          },
+        });
+
+        expect(setCurrentModel).not.toHaveBeenCalled();
+      });
+    });
+  });
+
+  describe("#given a handler receives non-error events", () => {
+    describe("#when event type is not session.error", () => {
+      it("#then does nothing", async () => {
+        const setCurrentModel = mock((_sid: string, _model: string) => {});
+
+        const handler = createRuntimeFallbackHandler({
+          setCurrentModel,
+        });
+
+        await handler({
+          event: {
+            type: "session.created",
+            properties: {
+              sessionID: "ses-created",
+              model: "openai/gpt-4o",
+            },
+          },
+        });
+
+        expect(setCurrentModel).not.toHaveBeenCalled();
+      });
+    });
+  });
+
+  describe("#given a handler with 'too many tokens' error", () => {
+    describe("#when error message contains 'too many tokens'", () => {
+      it("#then classifies as context-exceeded and triggers fallback", async () => {
+        const setCurrentModel = mock((_sid: string, _model: string) => {});
+
+        const handler = createRuntimeFallbackHandler({
+          setCurrentModel,
+        });
+
+        await handler({
+          event: {
+            type: "session.error",
+            properties: {
+              sessionID: "ses-tokens",
+              model: "openai/gpt-4o",
+              error: { message: "Too many tokens in the request" },
+              fallbackChain: ["openai/gpt-4o", "openai/gpt-4o-mini"],
+            },
+          },
+        });
+
+        expect(setCurrentModel).toHaveBeenCalledTimes(1);
+        expect(setCurrentModel).toHaveBeenCalledWith("ses-tokens", "openai/gpt-4o-mini");
+      });
+    });
+  });
+});

package/src/hooks/runtime-fallback/handler.ts

@@ -0,0 +1,171 @@
+import { buildFallbackChain } from "../../shared/fallback-chain";
+import { resolveModel } from "../../shared/model-resolution-pipeline";
+import { log } from "../../shared/logger";
+
+type RuntimeFallbackReason = "model-not-found" | "context-exceeded";
+
+type RuntimeFallbackEvent = {
+  event: {
+    type: string;
+    properties?: unknown;
+  };
+};
+
+type RuntimeFallbackDependencies = {
+  defaultFallbackChain?: string[];
+  getCurrentModel?: (sessionID: string) => string | undefined;
+  getAvailableModels?: (sessionID: string) => Set<string>;
+  setCurrentModel?: (sessionID: string, model: string) => void | Promise<void>;
+  onFallbackApplied?: (input: {
+    sessionID: string;
+    previousModel: string;
+    nextModel: string;
+    reason: RuntimeFallbackReason;
+  }) => void | Promise<void>;
+};
+
+function toRecord(value: unknown): Record<string, unknown> | undefined {
+  if (!value || typeof value !== "object") return undefined;
+  return value as Record<string, unknown>;
+}
+
+function getSessionID(properties: Record<string, unknown>): string | undefined {
+  const sessionID = properties["sessionID"];
+  if (typeof sessionID === "string" && sessionID.length > 0) return sessionID;
+
+  const info = toRecord(properties["info"]);
+  const infoID = info?.["id"];
+  if (typeof infoID === "string" && infoID.length > 0) return infoID;
+
+  return undefined;
+}
+
+function getErrorMessage(error: unknown): string {
+  if (typeof error === "string") return error.toLowerCase();
+  const record = toRecord(error);
+  const message = record?.["message"];
+  if (typeof message === "string") return message.toLowerCase();
+
+  const nested = toRecord(record?.["error"]);
+  const nestedMessage = nested?.["message"];
+  if (typeof nestedMessage === "string") return nestedMessage.toLowerCase();
+
+  return "";
+}
+
+function classifyRuntimeFallbackReason(error: unknown): RuntimeFallbackReason | undefined {
+  const message = getErrorMessage(error);
+  if (message.includes("model not found") || message.includes("unknown model")) {
+    return "model-not-found";
+  }
+  if (
+    message.includes("context length") ||
+    message.includes("context window") ||
+    message.includes("maximum context") ||
+    message.includes("too many tokens")
+  ) {
+    return "context-exceeded";
+  }
+  return undefined;
+}
+
+function getProvider(model: string): string | undefined {
+  const idx = model.indexOf("/");
+  if (idx <= 0) return undefined;
+  return model.slice(0, idx).toLowerCase();
+}
+
+function getNextRuntimeFallbackModel(input: {
+  currentModel: string;
+  configuredFallbacks: string | string[] | undefined;
+  defaultChain: string[];
+  availableModels: Set<string>;
+}): string | undefined {
+  const currentProvider = getProvider(input.currentModel);
+  const fullChain = buildFallbackChain(input.configuredFallbacks, input.defaultChain);
+  const currentIndex = fullChain.findIndex(
+    (model) => model.toLowerCase() === input.currentModel.toLowerCase(),
+  );
+  const remaining = currentIndex >= 0 ? fullChain.slice(currentIndex + 1) : fullChain;
+
+  const compatibleRemaining =
+    currentProvider === undefined
+      ? remaining
+      : remaining.filter((model) => getProvider(model) === currentProvider);
+
+  const compatibleResolved = resolveModel({
+    fallbackChain: compatibleRemaining,
+    availableModels: input.availableModels,
+  })?.model;
+  if (compatibleResolved) return compatibleResolved;
+
+  return resolveModel({
+    fallbackChain: remaining,
+    availableModels: input.availableModels,
+  })?.model;
+}
+
+export function createRuntimeFallbackHandler(deps: RuntimeFallbackDependencies = {}) {
+  const sessionModels = new Map<string, string>();
+  const defaultSwitch = async (sessionID: string, model: string) => {
+    sessionModels.set(sessionID, model);
+  };
+
+  return async ({ event }: RuntimeFallbackEvent): Promise<void> => {
+    if (event.type !== "session.error") return;
+
+    const properties = toRecord(event.properties);
+    if (!properties) return;
+
+    const reason = classifyRuntimeFallbackReason(properties["error"]);
+    if (!reason) return;
+
+    const sessionID = getSessionID(properties);
+    if (!sessionID) return;
+
+    const eventModel = properties["model"];
+    const currentModel =
+      (typeof eventModel === "string" && eventModel.length > 0 ? eventModel : undefined) ??
+      deps.getCurrentModel?.(sessionID) ??
+      sessionModels.get(sessionID);
+    if (!currentModel) return;
+
+    const configuredFallbacks = properties["fallbackChain"];
+    const fallbackInput =
+      typeof configuredFallbacks === "string" || Array.isArray(configuredFallbacks)
+        ? configuredFallbacks
+        : undefined;
+
+    const availableModels = deps.getAvailableModels?.(sessionID) ?? new Set<string>();
+    const nextModel = getNextRuntimeFallbackModel({
+      currentModel,
+      configuredFallbacks: fallbackInput,
+      defaultChain: deps.defaultFallbackChain ?? [],
+      availableModels,
+    });
+
+    if (!nextModel || nextModel.toLowerCase() === currentModel.toLowerCase()) {
+      log("[runtime-fallback] no compatible fallback model", { sessionID, currentModel, reason });
+      return;
+    }
+
+    const applyModel = deps.setCurrentModel ?? defaultSwitch;
+    await Promise.resolve(applyModel(sessionID, nextModel));
+
+    await Promise.resolve(
+      deps.onFallbackApplied?.({
+        sessionID,
+        previousModel: currentModel,
+        nextModel,
+        reason,
+      }),
+    );
+
+    log("[runtime-fallback] switched model", {
+      sessionID,
+      from: currentModel,
+      to: nextModel,
+      reason,
+    });
+  };
+}

package/src/hooks/runtime-fallback/index.ts

@@ -0,0 +1,2 @@
+export { createRuntimeFallbackHandler } from "./handler";
+export { runtimeFallbackPlugin } from "./plugin";

package/src/hooks/runtime-fallback/plugin.ts

@@ -0,0 +1,13 @@
+import { definePlugin } from "../../plugin-api";
+import { safeCreateHook } from "../../shared/safe-create-hook";
+import { createRuntimeFallbackHandler } from "./handler";
+
+const runtimeFallbackEventHook = safeCreateHook("runtime-fallback", () =>
+  createRuntimeFallbackHandler(),
+);
+
+export const runtimeFallbackPlugin = definePlugin({
+  name: "runtime-fallback",
+  version: "0.1.0",
+  hooks: runtimeFallbackEventHook ? { event: runtimeFallbackEventHook } : undefined,
+});

package/src/hooks/safe-hook-wrapper.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, it } from "bun:test";
+
+import type { PluginHookHandler } from "../types/plugin";
+import { wrapSafely } from "./safe-hook-wrapper";
+
+describe("wrapSafely", () => {
+  describe("#given a handler that throws", () => {
+    describe("#when wrapped and called", () => {
+      it("#then error is caught and no throw escapes", async () => {
+        const failing: PluginHookHandler = async () => {
+          throw new Error("boom");
+        };
+        const wrapped = wrapSafely("event", failing);
+
+        await expect(wrapped({}, {})).resolves.toBeUndefined();
+      });
+    });
+  });
+
+  describe("#given a handler that succeeds", () => {
+    describe("#when wrapped and called", () => {
+      it("#then it executes normally", async () => {
+        const calls: string[] = [];
+        const success: PluginHookHandler = async () => {
+          calls.push("ran");
+        };
+        const wrapped = wrapSafely("event", success);
+
+        await wrapped({}, {});
+
+        expect(calls).toEqual(["ran"]);
+      });
+    });
+  });
+});