goatcode-sh 0.0.1 → 0.1.2

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);
+    }
+  });
+});

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

@@ -0,0 +1,36 @@
+import type { PluginDefinition } from "../types/plugin";
+
+/**
+ * Define a GoatCode micro-plugin.
+ *
+ * This is the primary authoring API for creating plugins.
+ * Both internal GoatCode plugins and external plugins use this function.
+ *
+ * @example
+ * ```typescript
+ * import { definePlugin } from "goatcode-sh"
+ *
+ * export default definePlugin({
+ *   name: "my-plugin",
+ *   version: "1.0.0",
+ *   hooks: {
+ *     "tool.execute.before": async (input, output) => {
+ *       // called before every tool execution
+ *     },
+ *   },
+ *   tools: {
+ *     my_tool: {
+ *       description: "Does something useful",
+ *       parameters: { type: "object", properties: {} },
+ *       execute: async (args) => "result",
+ *     },
+ *   },
+ * })
+ * ```
+ *
+ * @param definition - The plugin definition object
+ * @returns The definition unchanged (typed identity function for IDE autocomplete)
+ */
+export function definePlugin(definition: PluginDefinition): PluginDefinition {
+  return definition;
+}

package/src/plugin-api/index.ts

@@ -0,0 +1,26 @@
+export { definePlugin } from "./define-plugin";
+export type {
+  PluginDefinition,
+  AggregatedPlugins,
+  OpenCodeContext,
+  OpenCodePluginInstance,
+  PluginHookHandler,
+  PluginHookContributions,
+  AgentConfig,
+  AgentMode,
+  AgentFactory,
+  BuiltinAgentName,
+  AgentOverrideConfig,
+  ToolDefinition,
+  ToolsRecord,
+  HookEventName,
+  HookHandler,
+  HookPriority,
+  BuiltinCategoryName,
+  CategoryConfig,
+  AvailableCategory,
+  GoatCodeConfig,
+  AgentOverrides,
+  HookName,
+} from "./types";
+export { HOOK_EVENT_NAMES, HOOK_EVENT_NAMES as HOOK_NAMES } from "./types";

package/src/plugin-api/types.ts

@@ -0,0 +1,28 @@
+export type {
+  PluginDefinition,
+  AggregatedPlugins,
+  OpenCodeContext,
+  OpenCodePluginInstance,
+  PluginHookHandler,
+} from "../types/plugin";
+
+export type { PluginHookContributions } from "../types/hook";
+
+export type {
+  AgentConfig,
+  AgentMode,
+  AgentFactory,
+  BuiltinAgentName,
+  AgentOverrideConfig,
+} from "../types/agent";
+
+export type { ToolDefinition, ToolsRecord } from "../types/tool";
+
+export type { HookEventName, HookHandler, HookPriority } from "../types/hook";
+export { HOOK_EVENT_NAMES } from "../types/hook";
+export { HOOK_EVENT_NAMES as HOOK_NAMES } from "../types/hook";
+export type HookName = import("../types/hook").HookEventName;
+
+export type { BuiltinCategoryName, CategoryConfig, AvailableCategory } from "../types/category";
+
+export type { GoatCodeConfig, AgentOverrides } from "../types/config";

package/src/registry/agent-aggregator.ts

@@ -0,0 +1,13 @@
+import type { PluginDefinition } from "../types/plugin";
+import type { PluginAgentContribution } from "../types/agent";
+import { aggregateContributions } from "./contribution-aggregator";
+
+export function aggregateAgents(
+  plugins: PluginDefinition[],
+  disabledAgents?: string[],
+): Record<string, PluginAgentContribution> {
+  return aggregateContributions<"agents", PluginAgentContribution>(plugins, "agents", {
+    disabled: disabledAgents,
+    onConflict: "replace",
+  });
+}

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

@@ -0,0 +1,62 @@
+import { describe, expect, test } from "bun:test";
+
+import type { PluginAgentContribution } from "../types/agent";
+import type { PluginDefinition, PluginHookHandler } from "../types/plugin";
+
+import { aggregateContributions } from "./contribution-aggregator";
+
+function makeAgentContribution(model: string): PluginAgentContribution {
+  return { instructions: "test", model } as unknown as PluginAgentContribution;
+}
+
+describe("aggregateContributions", () => {
+  test("replaces conflicting entries and filters disabled names", () => {
+    const plugins: PluginDefinition[] = [
+      {
+        name: "a",
+        agents: {
+          shared: makeAgentContribution("model-a"),
+          keep: makeAgentContribution("model-a"),
+        },
+      },
+      {
+        name: "b",
+        agents: {
+          shared: makeAgentContribution("model-b"),
+          skip: makeAgentContribution("model-b"),
+        },
+      },
+    ];
+
+    const aggregated = aggregateContributions<"agents", PluginAgentContribution>(
+      plugins,
+      "agents",
+      {
+        disabled: ["skip"],
+        onConflict: "replace",
+      },
+    );
+
+    expect(Object.keys(aggregated)).toEqual(["shared", "keep"]);
+    expect(aggregated.shared.model).toBe("model-b");
+    expect(aggregated.skip).toBeUndefined();
+  });
+
+  test("appends hook handlers in plugin order", () => {
+    type ToolExecuteBeforeHandler = NonNullable<PluginDefinition["hooks"]>["tool.execute.before"];
+    const first: ToolExecuteBeforeHandler = async () => {};
+    const second: ToolExecuteBeforeHandler = async () => {};
+
+    const plugins: PluginDefinition[] = [
+      { name: "a", hooks: { "tool.execute.before": first } },
+      { name: "b", hooks: { "tool.execute.before": second } },
+    ];
+
+    const aggregated = aggregateContributions<"hooks", PluginHookHandler>(plugins, "hooks", {
+      disabled: [],
+      onConflict: "append",
+    });
+
+    expect(aggregated.get("tool.execute.before")).toEqual([first, second] as PluginHookHandler[]);
+  });
+});

package/src/registry/contribution-aggregator.ts

@@ -0,0 +1,114 @@
+import { log } from "../shared/logger";
+import type { PluginDefinition } from "../types/plugin";
+
+type ContributionKey = "agents" | "tools" | "hooks";
+type ConflictMode = "replace" | "append";
+
+type AggregateResult<K extends ContributionKey, T> = K extends "hooks"
+  ? Map<string, T[]>
+  : Record<string, T>;
+
+interface AggregateOptions {
+  disabled?: string[];
+  onConflict: ConflictMode;
+}
+
+function describeContribution(key: ContributionKey): {
+  prefix: string;
+  singular: string;
+  plural: string;
+} {
+  if (key === "agents") {
+    return { prefix: "agent-aggregator", singular: "Agent", plural: "agent" };
+  }
+
+  if (key === "tools") {
+    return { prefix: "tool-aggregator", singular: "Tool", plural: "tool" };
+  }
+
+  return { prefix: "hook-aggregator", singular: "Hook", plural: "hook" };
+}
+
+export function aggregateContributions<K extends ContributionKey, T>(
+  plugins: PluginDefinition[],
+  key: K,
+  options: AggregateOptions,
+): AggregateResult<K, T> {
+  const disabled = new Set(options.disabled ?? []);
+  const skipped: string[] = [];
+  const descriptor = describeContribution(key);
+
+  if (options.onConflict === "append") {
+    const map = new Map<string, T[]>();
+
+    for (const plugin of plugins) {
+      const contributions = plugin[key];
+      if (!contributions) {
+        continue;
+      }
+
+      for (const [name, contribution] of Object.entries(contributions)) {
+        if (contribution === undefined) {
+          continue;
+        }
+
+        if (disabled.has(name)) {
+          skipped.push(name);
+          continue;
+        }
+
+        const entries = map.get(name) ?? [];
+        entries.push(contribution as T);
+        map.set(name, entries);
+      }
+    }
+
+    if (skipped.length > 0) {
+      log(
+        `[${descriptor.prefix}] Skipped ${skipped.length} disabled ${descriptor.plural}(s): ${skipped.join(", ")}`,
+      );
+    }
+
+    return map as AggregateResult<K, T>;
+  }
+
+  const record: Record<string, T> = {};
+
+  for (const plugin of plugins) {
+    const contributions = plugin[key];
+    if (!contributions) {
+      continue;
+    }
+
+    for (const [name, contribution] of Object.entries(contributions)) {
+      if (contribution === undefined) {
+        continue;
+      }
+
+      if (disabled.has(name)) {
+        skipped.push(name);
+        continue;
+      }
+
+      if (record[name]) {
+        log(
+          `[${descriptor.prefix}] CONFLICT: ${descriptor.singular} "${name}" from plugin "${plugin.name}" overwrites existing registration. To avoid this, ensure ${descriptor.plural} names are unique across plugins.`,
+          {
+            plugin: plugin.name,
+            [descriptor.plural]: name,
+          },
+        );
+      }
+
+      record[name] = contribution as T;
+    }
+  }
+
+  if (skipped.length > 0) {
+    log(
+      `[${descriptor.prefix}] Skipped ${skipped.length} disabled ${descriptor.plural}(s): ${skipped.join(", ")}`,
+    );
+  }
+
+  return record as AggregateResult<K, T>;
+}