goatcode-sh 0.0.1 → 0.1.3

package/src/hooks/workflow-reminders.test.ts

@@ -0,0 +1,187 @@
+declare const require: (name: string) => any;
+
+const { describe, expect, it, mock } = require("bun:test");
+
+import { createForegroundFallbackHandler, foregroundFallbackPlugin } from "./foreground-fallback";
+import { createPhaseReminderHandler, phaseReminderPlugin, PHASE_REMINDER } from "./phase-reminder";
+import {
+  createPostReadNudgeHandler,
+  postReadNudgePlugin,
+  POST_READ_NUDGE,
+} from "./post-read-nudge";
+
+describe("foreground-fallback", () => {
+  describe("#given a session.error with rate-limit signal", () => {
+    describe("#when the handler receives a fallback chain", () => {
+      it("#then switches to the next model and requests retry", async () => {
+        const sessionModels = new Map<string, string>([["ses-foreground", "openai/gpt-5"]]);
+        const onFallbackApplied = mock(() => undefined);
+        const onRetryRequested = mock(() => undefined);
+
+        const handler = createForegroundFallbackHandler({
+          getCurrentModel: (sessionID) => sessionModels.get(sessionID),
+          setCurrentModel: (sessionID, model) => {
+            sessionModels.set(sessionID, model);
+          },
+          onFallbackApplied,
+          onRetryRequested,
+        });
+
+        const payload = {
+          event: {
+            type: "session.error",
+            properties: {
+              sessionID: "ses-foreground",
+              model: "openai/gpt-5",
+              error: { statusCode: 429, message: "Too many requests" },
+              fallbackChain: ["openai/gpt-5", "openai/gpt-4.1-mini", "anthropic/claude-3.7-sonnet"],
+            },
+          },
+        };
+
+        await handler(payload as unknown as Parameters<typeof handler>[0]);
+
+        expect(sessionModels.get("ses-foreground")).toBe("openai/gpt-4.1-mini");
+        const properties = payload.event.properties as Record<string, unknown>;
+        expect(properties.retryRequested).toBe(true);
+        expect(properties.retryWithModel).toBe("openai/gpt-4.1-mini");
+        expect(onFallbackApplied).toHaveBeenCalledTimes(1);
+        expect(onRetryRequested).toHaveBeenCalledTimes(1);
+      });
+    });
+  });
+
+  describe("#given duplicated rate-limit events in a short window", () => {
+    describe("#when the handler receives two events within 5 seconds", () => {
+      it("#then deduplicates fallback attempts", async () => {
+        const sessionModels = new Map<string, string>([["ses-dedup", "openai/gpt-5"]]);
+        const onFallbackApplied = mock(() => undefined);
+        const now = mock(() => 1_000);
+
+        const handler = createForegroundFallbackHandler({
+          getCurrentModel: (sessionID) => sessionModels.get(sessionID),
+          setCurrentModel: (sessionID, model) => {
+            sessionModels.set(sessionID, model);
+          },
+          onFallbackApplied,
+          now,
+        });
+
+        const first = {
+          event: {
+            type: "session.error",
+            properties: {
+              sessionID: "ses-dedup",
+              model: "openai/gpt-5",
+              error: { message: "rate limit" },
+              fallbackChain: ["openai/gpt-5", "openai/gpt-4.1-mini", "openai/gpt-4.1-nano"],
+            },
+          },
+        };
+
+        const second = {
+          event: {
+            type: "session.error",
+            properties: {
+              sessionID: "ses-dedup",
+              model: "openai/gpt-4.1-mini",
+              error: { message: "rate limit" },
+              fallbackChain: ["openai/gpt-5", "openai/gpt-4.1-mini", "openai/gpt-4.1-nano"],
+            },
+          },
+        };
+
+        await handler(first as unknown as Parameters<typeof handler>[0]);
+        await handler(second as unknown as Parameters<typeof handler>[0]);
+
+        expect(onFallbackApplied).toHaveBeenCalledTimes(1);
+      });
+    });
+  });
+
+  it("#then plugin registers an event hook", () => {
+    expect(typeof foregroundFallbackPlugin.hooks?.event).toBe("function");
+  });
+});
+
+describe("phase-reminder", () => {
+  describe("#given an orchestrator user message", () => {
+    describe("#when transform runs", () => {
+      it("#then prepends the workflow reminder", async () => {
+        const handler = createPhaseReminderHandler();
+        const output = {
+          messages: [
+            {
+              info: { role: "user", agent: "orchestrator" },
+              parts: [{ type: "text", text: "Implement this task" }],
+            },
+          ],
+        };
+
+        await handler({}, output as unknown as Parameters<typeof handler>[1]);
+
+        const text = output.messages[0].parts[0].text;
+        expect(text.startsWith(PHASE_REMINDER)).toBe(true);
+      });
+    });
+  });
+
+  describe("#given a subagent user message", () => {
+    describe("#when transform runs", () => {
+      it("#then does not inject the reminder", async () => {
+        const handler = createPhaseReminderHandler();
+        const output = {
+          messages: [
+            {
+              info: { role: "user", agent: "explore" },
+              parts: [{ type: "text", text: "Search for files" }],
+            },
+          ],
+        };
+
+        await handler({}, output as unknown as Parameters<typeof handler>[1]);
+
+        const text = output.messages[0].parts[0].text;
+        expect(text).toBe("Search for files");
+      });
+    });
+  });
+
+  it("#then plugin registers a messages transform hook", () => {
+    expect(typeof phaseReminderPlugin.hooks?.["experimental.chat.messages.transform"]).toBe(
+      "function",
+    );
+  });
+});
+
+describe("post-read-nudge", () => {
+  describe("#given a Read tool call", () => {
+    describe("#when tool.execute.after runs", () => {
+      it("#then appends the nudge", async () => {
+        const handler = createPostReadNudgeHandler();
+        const output = { title: "read", output: "file content", metadata: {} };
+
+        await handler({ tool: "Read", sessionID: "s1", callID: "c1", args: {} }, output);
+
+        expect(output.output.endsWith(POST_READ_NUDGE)).toBe(true);
+      });
+    });
+  });
+
+  describe("#given a non-read tool call", () => {
+    describe("#when tool.execute.after runs", () => {
+      it("#then leaves output unchanged", async () => {
+        const handler = createPostReadNudgeHandler();
+        const output = { title: "bash", output: "command output", metadata: {} };
+
+        await handler({ tool: "Bash", sessionID: "s1", callID: "c1", args: {} }, output);
+
+        expect(output.output).toBe("command output");
+      });
+    });
+  });
+
+  it("#then plugin registers tool.execute.after", () => {
+    expect(typeof postReadNudgePlugin.hooks?.["tool.execute.after"]).toBe("function");
+  });
+});

package/src/hooks/write-file-guard/handler.test.ts

@@ -0,0 +1,107 @@
+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 { createWriteFileGuardHandler, BLOCK_MESSAGE } from "./handler";
+
+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(), "wfg-handler-test-"));
+  });
+
+  afterEach(() => {
+    rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  describe("#given a handler instance", () => {
+    describe("#when writing to an existing file without prior read", () => {
+      it("#then throws a block error", async () => {
+        const handler = createWriteFileGuardHandler(tempDir);
+        const existingFile = createFile("no-read.txt");
+
+        await expect(
+          invokePreToolUse(handler, { tool: "write", filePath: existingFile }),
+        ).rejects.toThrow(BLOCK_MESSAGE);
+      });
+    });
+
+    describe("#when writing to a file that was read first", () => {
+      it("#then allows the write", async () => {
+        const handler = createWriteFileGuardHandler(tempDir);
+        const existingFile = createFile("read-first.txt");
+        const sessionID = "ses_read_write";
+
+        await invokePreToolUse(handler, { tool: "read", sessionID, filePath: existingFile });
+
+        await expect(
+          invokePreToolUse(handler, { tool: "write", sessionID, filePath: existingFile }),
+        ).resolves.toBeUndefined();
+      });
+    });
+
+    describe("#when session.deleted event fires after a read", () => {
+      it("#then clears session data and blocks subsequent write", async () => {
+        const handler = createWriteFileGuardHandler(tempDir);
+        const existingFile = createFile("cleanup.txt");
+        const sessionID = "ses_to_delete";
+
+        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("#when the tool is neither write nor read", () => {
+      it("#then does nothing", async () => {
+        const handler = createWriteFileGuardHandler(tempDir);
+        const existingFile = createFile("ignored.txt");
+
+        await expect(
+          invokePreToolUse(handler, { tool: "bash", filePath: existingFile }),
+        ).resolves.toBeUndefined();
+      });
+    });
+
+    describe("#when writing to a file that does not exist", () => {
+      it("#then allows the write (new file creation)", async () => {
+        const handler = createWriteFileGuardHandler(tempDir);
+        const newFile = join(tempDir, "brand-new.txt");
+
+        await expect(
+          invokePreToolUse(handler, { tool: "write", filePath: newFile }),
+        ).resolves.toBeUndefined();
+      });
+    });
+  });
+});

package/src/hooks/write-file-guard/handler.ts

@@ -0,0 +1,166 @@
+import type { PluginHookHandler } from "../../types/plugin";
+import { existsSync } from "node:fs";
+import { isAbsolute, normalize, resolve } from "node:path";
+import { log } from "../../shared/logger";
+
+const MAX_TRACKED_SESSIONS = 256;
+const MAX_PATHS_PER_SESSION = 1024;
+const BLOCK_MESSAGE = "File already exists. Read the file before writing to it.";
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+function getFilePath(args: Record<string, unknown>): string | undefined {
+  const p = args.filePath ?? args.file_path ?? args.path;
+  return typeof p === "string" ? p : undefined;
+}
+
+function resolvePath(filePath: string, directory: string): string {
+  const abs = isAbsolute(filePath) ? filePath : resolve(directory, filePath);
+  return normalize(abs);
+}
+
+export function createWriteFileGuardHandler(directory: string): {
+  preToolUse: PluginHookHandler;
+  event: PluginHookHandler;
+} {
+  const readsBySession = new Map<string, Set<string>>();
+  const sessionAccess = new Map<string, number>();
+
+  function touchSession(sessionId: string): void {
+    sessionAccess.set(sessionId, Date.now());
+  }
+
+  function evictOldestSession(): void {
+    let oldest: string | undefined;
+    let oldestTime = Number.POSITIVE_INFINITY;
+    for (const [id, time] of sessionAccess.entries()) {
+      if (time < oldestTime) {
+        oldestTime = time;
+        oldest = id;
+      }
+    }
+    if (oldest) {
+      readsBySession.delete(oldest);
+      sessionAccess.delete(oldest);
+    }
+  }
+
+  function getOrCreateReadSet(sessionId: string): Set<string> {
+    let set = readsBySession.get(sessionId);
+    if (!set) {
+      if (readsBySession.size >= MAX_TRACKED_SESSIONS) {
+        evictOldestSession();
+      }
+      set = new Set<string>();
+      readsBySession.set(sessionId, set);
+    }
+    touchSession(sessionId);
+    return set;
+  }
+
+  function trimReadSet(set: Set<string>): void {
+    while (set.size > MAX_PATHS_PER_SESSION) {
+      const first = set.values().next().value;
+      if (first === undefined) break;
+      set.delete(first);
+    }
+  }
+
+  function registerRead(sessionId: string, canonicalPath: string): void {
+    const set = getOrCreateReadSet(sessionId);
+    set.delete(canonicalPath);
+    set.add(canonicalPath);
+    trimReadSet(set);
+  }
+
+  function consumeRead(sessionId: string, canonicalPath: string): boolean {
+    const set = readsBySession.get(sessionId);
+    if (!set || !set.has(canonicalPath)) {
+      return false;
+    }
+    set.delete(canonicalPath);
+    touchSession(sessionId);
+    return true;
+  }
+
+  const preToolUse: PluginHookHandler = async (input: unknown, output: unknown) => {
+    if (!isRecord(input) || !isRecord(output)) {
+      return;
+    }
+
+    const tool = input.tool;
+    if (typeof tool !== "string") {
+      return;
+    }
+
+    const toolLower = tool.toLowerCase();
+    if (toolLower !== "write" && toolLower !== "read") {
+      return;
+    }
+
+    const args = isRecord(output.args) ? output.args : output;
+    const rawPath = getFilePath(args);
+    if (!rawPath) {
+      return;
+    }
+
+    const sessionId = typeof input.sessionID === "string" ? input.sessionID : undefined;
+    const canonicalPath = resolvePath(rawPath, directory);
+
+    if (toolLower === "read") {
+      if (!existsSync(canonicalPath) || !sessionId) {
+        return;
+      }
+      registerRead(sessionId, canonicalPath);
+      return;
+    }
+
+    if (!existsSync(canonicalPath)) {
+      return;
+    }
+
+    if (canonicalPath.includes("/.sisyphus/")) {
+      log("[write-file-guard] allowing .sisyphus/** overwrite", { sessionId, canonicalPath });
+      return;
+    }
+
+    if (sessionId && consumeRead(sessionId, canonicalPath)) {
+      log("[write-file-guard] allowing write after read", { sessionId, canonicalPath });
+      return;
+    }
+
+    log("[write-file-guard] blocking write to existing file without prior read", {
+      sessionId,
+      canonicalPath,
+    });
+
+    throw new Error(BLOCK_MESSAGE);
+  };
+
+  const event: PluginHookHandler = async (input: unknown) => {
+    if (!isRecord(input)) {
+      return;
+    }
+
+    const evt = isRecord(input.event) ? input.event : input;
+    if (evt.type !== "session.deleted") {
+      return;
+    }
+
+    const props = isRecord(evt.properties) ? evt.properties : undefined;
+    const info = isRecord(props?.info) ? props.info : undefined;
+    const sessionId = typeof info?.id === "string" ? info.id : undefined;
+    if (!sessionId) {
+      return;
+    }
+
+    readsBySession.delete(sessionId);
+    sessionAccess.delete(sessionId);
+  };
+
+  return { preToolUse, event };
+}
+
+export { BLOCK_MESSAGE };

package/src/hooks/write-file-guard/index.ts

@@ -0,0 +1,2 @@
+export { writeFileGuardPlugin } from "./plugin";
+export { createWriteFileGuardHandler, BLOCK_MESSAGE } from "./handler";

package/src/hooks/write-file-guard/plugin.ts

@@ -0,0 +1,23 @@
+import type { OpenCodeContext } from "../../types/plugin";
+import { definePlugin } from "../../plugin-api/define-plugin";
+import { createWriteFileGuardHandler } from "./handler";
+
+let handlers: ReturnType<typeof createWriteFileGuardHandler> | null = null;
+
+export const writeFileGuardPlugin = definePlugin({
+  name: "write-file-guard",
+  version: "0.1.0",
+  setup(ctx: OpenCodeContext) {
+    handlers = createWriteFileGuardHandler(ctx.directory);
+  },
+  hooks: {
+    "tool.execute.before": async (input: unknown, output: unknown) => {
+      if (!handlers) return;
+      await handlers.preToolUse(input, output);
+    },
+    event: async (input: unknown) => {
+      if (!handlers) return;
+      await handlers.event(input);
+    },
+  },
+});

package/src/index.ts

@@ -0,0 +1,8 @@
+import type { Plugin } from "@opencode-ai/plugin";
+import { bootstrap } from "./bootstrap";
+
+const GoatCodePlugin: Plugin = (ctx) => bootstrap(ctx);
+
+export default GoatCodePlugin;
+export { definePlugin } from "./plugin-api";
+export { defineConfig, defineConfigAsync } from "./config";

package/src/plugin/compositor.ts

@@ -0,0 +1,99 @@
+import type { Hooks } from "@opencode-ai/plugin";
+import type { AggregatedPlugins, PluginHookHandler } from "../types/plugin";
+import { log } from "../shared/logger";
+import { qualifyModel } from "../shared/provider-registry";
+import { HOOK_EVENT_NAMES } from "../types/hook";
+import { getBuiltinSkillsDir } from "../features/skills";
+
+const FUNCTION_HOOK_SLOTS = HOOK_EVENT_NAMES.filter(
+  (name): name is Exclude<(typeof HOOK_EVENT_NAMES)[number], "tool"> => name !== "tool",
+) as readonly Exclude<(typeof HOOK_EVENT_NAMES)[number], "tool">[];
+
+function buildSlotHandler(handlers: PluginHookHandler[]): PluginHookHandler {
+  if (handlers.length === 0) {
+    return async () => {};
+  }
+  return async (input: unknown, output: unknown) => {
+    for (const handler of handlers) {
+      try {
+        await handler(input, output);
+      } catch (err) {
+        log(`[compositor] Handler error: ${err instanceof Error ? err.message : String(err)}`);
+      }
+    }
+  };
+}
+
+/**
+ * Compose aggregated plugin contributions into a complete OpenCode Hooks instance.
+ * Produces all handler slots (1 tool record + function hooks).
+ * The `config` slot injects agents before delegating to registered hooks.
+ * Slots without registered handlers are defined as no-ops.
+ */
+export function compose(aggregated: AggregatedPlugins): Hooks {
+  const hooks: Hooks = {};
+
+  // Shallow-copy the tools record. structuredClone cannot clone the execute
+  // functions inside each ToolDefinition and would throw at runtime.
+  hooks.tool = { ...aggregated.tools };
+
+  const configHandlers = aggregated.hooks.get("config") ?? [];
+  hooks.config = async (input) => {
+    if (!input.agent) {
+      input.agent = {};
+    }
+
+    for (const [name, agentConfig] of Object.entries(aggregated.agents)) {
+      if (!input.agent[name]) {
+        input.agent[name] = {
+          ...agentConfig,
+          ...(agentConfig.tools ? { tools: { ...agentConfig.tools } } : {}),
+        };
+      }
+    }
+
+    for (const agentConfig of Object.values(input.agent)) {
+      if (agentConfig?.model && !agentConfig.model.includes("/")) {
+        agentConfig.model = qualifyModel(agentConfig.model);
+      }
+    }
+
+    if (input.agent.build === undefined) {
+      input.agent.build = { disable: true };
+    }
+    if (input.agent.plan === undefined) {
+      input.agent.plan = { disable: true };
+    }
+
+    const configRecord = input as Record<string, unknown>;
+    if (!configRecord["default_agent"]) {
+      configRecord["default_agent"] = "orchestrator";
+    }
+
+    const skills = (configRecord["skills"] ?? {}) as Record<string, unknown>;
+    const existingPaths = (skills["paths"] ?? []) as string[];
+    const builtinDir = getBuiltinSkillsDir();
+    if (builtinDir && !existingPaths.includes(builtinDir)) {
+      skills["paths"] = [...existingPaths, builtinDir];
+      configRecord["skills"] = skills;
+    }
+
+    for (const handler of configHandlers) {
+      await handler(input);
+    }
+  };
+
+  for (const key of FUNCTION_HOOK_SLOTS) {
+    if (key === "config") continue;
+    const handlers = aggregated.hooks.get(key) ?? [];
+    (hooks as Record<typeof key, PluginHookHandler>)[key] = buildSlotHandler(handlers);
+  }
+
+  const toolCount = Object.keys(aggregated.tools).length;
+  const agentCount = Object.keys(aggregated.agents).length;
+  log(
+    `[compositor] Composed plugin: ${toolCount} tools, ${agentCount} agents, ${HOOK_EVENT_NAMES.length} handler slots`,
+  );
+
+  return hooks;
+}

package/src/plugin/index.ts

@@ -0,0 +1 @@
+export { compose } from "./compositor";

package/src/plugin-api/define-plugin.test.ts

@@ -0,0 +1,66 @@
+import { describe, test, expect } from "bun:test";
+
+import { definePlugin } from "./define-plugin";
+import { HOOK_EVENT_NAMES } from "./types";
+
+describe("definePlugin", () => {
+  describe("with minimal plugin", () => {
+    test("returns the definition unchanged", () => {
+      //#given
+      const definition = { name: "test-plugin" };
+      //#when
+      const result = definePlugin(definition);
+      //#then
+      expect(result).toBe(definition);
+    });
+  });
+
+  describe("with full plugin", () => {
+    test("preserves all fields", () => {
+      //#given
+      const handler = async () => {};
+      const definition = {
+        name: "full-plugin",
+        version: "1.0.0",
+        dependencies: ["other-plugin"],
+        hooks: { "tool.execute.before": handler },
+      };
+      //#when
+      const result = definePlugin(definition);
+      //#then
+      expect(result.name).toBe("full-plugin");
+      expect(result.version).toBe("1.0.0");
+      expect(result.dependencies).toEqual(["other-plugin"]);
+      expect(result.hooks?.["tool.execute.before"]).toBe(handler);
+    });
+  });
+});
+
+describe("HOOK_EVENT_NAMES", () => {
+  test("contains all OpenCode hook handler names", () => {
+    //#given
+    const expected = [
+      "tool",
+      "config",
+      "chat.message",
+      "chat.params",
+      "chat.headers",
+      "event",
+      "tool.execute.before",
+      "tool.execute.after",
+      "experimental.chat.messages.transform",
+      "experimental.chat.system.transform",
+      "tool.definition",
+      "permission.ask",
+      "command.execute.before",
+      "shell.env",
+      "experimental.session.compacting",
+      "experimental.text.complete",
+    ];
+    //#when / #then
+    expect(HOOK_EVENT_NAMES).toHaveLength(16);
+    for (const name of expected) {
+      expect(HOOK_EVENT_NAMES).toContain(name);
+    }
+  });
+});