goatcode-sh 0.0.1 → 0.1.3

package/src/tools/tool-builder.ts

@@ -0,0 +1,24 @@
+import type { ToolDefinition } from "@opencode-ai/plugin";
+
+export type ToolBuilderInput<
+  TArgs extends ToolDefinition["args"] = ToolDefinition["args"],
+  TExecuteArgs = Record<string, unknown>,
+> = {
+  description: string;
+  args: TArgs;
+  execute: (
+    args: TExecuteArgs,
+    context: Parameters<ToolDefinition["execute"]>[1],
+  ) => Promise<string>;
+};
+
+export function buildTool<
+  TArgs extends ToolDefinition["args"] = ToolDefinition["args"],
+  TExecuteArgs = Record<string, unknown>,
+>(input: ToolBuilderInput<TArgs, TExecuteArgs>): ToolDefinition {
+  return {
+    description: input.description,
+    args: input.args,
+    execute: (args, context) => input.execute(args as TExecuteArgs, context),
+  };
+}

package/src/tools/tool-registry-adapter.test.ts

@@ -0,0 +1,51 @@
+import { describe, it, expect } from "bun:test";
+import type { PluginToolContribution, ToolsRecord } from "../types/tool";
+import { adaptToolsToRegistry, mergeToolRegistries } from "./tool-registry-adapter";
+
+function makeToolContribution(): PluginToolContribution {
+  return {
+    description: "test tool",
+    args: {},
+    execute: async () => "ok",
+  };
+}
+
+describe("adaptToolsToRegistry", () => {
+  describe("#given a tools contribution record", () => {
+    describe("#when adaptToolsToRegistry is called", () => {
+      it("#then it returns a copied tools registry with the same entries", () => {
+        const tools: Record<string, PluginToolContribution> = {
+          alpha: makeToolContribution(),
+          beta: makeToolContribution(),
+        };
+
+        const result = adaptToolsToRegistry(tools);
+
+        expect(result).toEqual(tools);
+        expect(result).not.toBe(tools);
+      });
+    });
+  });
+});
+
+describe("mergeToolRegistries", () => {
+  describe("#given multiple registries with distinct tool names", () => {
+    describe("#when mergeToolRegistries is called", () => {
+      it("#then it merges all registries without collisions", () => {
+        const registryOne: ToolsRecord = {
+          alpha: makeToolContribution(),
+        };
+        const registryTwo: ToolsRecord = {
+          beta: makeToolContribution(),
+        };
+
+        const result = mergeToolRegistries(registryOne, registryTwo);
+
+        expect(result).toEqual({
+          alpha: registryOne.alpha,
+          beta: registryTwo.beta,
+        });
+      });
+    });
+  });
+});

package/src/tools/tool-registry-adapter.ts

@@ -0,0 +1,19 @@
+import type { PluginToolContribution, ToolsRecord } from "../types/tool";
+import { log } from "../shared/logger";
+
+export function adaptToolsToRegistry(tools: Record<string, PluginToolContribution>): ToolsRecord {
+  return { ...tools };
+}
+
+export function mergeToolRegistries(...registries: ToolsRecord[]): ToolsRecord {
+  const result: ToolsRecord = {};
+  for (const registry of registries) {
+    for (const [name, tool] of Object.entries(registry)) {
+      if (result[name]) {
+        log(`[tool-registry-adapter] CONFLICT: Tool "${name}" already registered, overwriting`);
+      }
+      result[name] = tool;
+    }
+  }
+  return result;
+}

package/src/types/agent.ts

@@ -0,0 +1,53 @@
+import type { AgentConfig } from "@opencode-ai/sdk";
+
+/** Re-export for convenience. */
+export type { AgentConfig };
+
+/**
+ * Agent execution mode.
+ * - "primary": Respects the user-selected UI model.
+ * - "subagent": Uses its own fallback chain and ignores UI selection.
+ * - "all": Available in both contexts.
+ */
+export type AgentMode = "primary" | "subagent" | "all";
+
+/**
+ * Factory function that creates an AgentConfig given a model string.
+ * Includes a static mode property for pre-instantiation access.
+ */
+export type AgentFactory = ((model: string) => AgentConfig) & {
+  readonly mode: AgentMode;
+};
+
+/** All built-in GoatCode agent names. */
+export type BuiltinAgentName =
+  | "orchestrator"
+  | "deep-worker"
+  | "planner"
+  | "advisor"
+  | "researcher"
+  | "explorer"
+  | "worker";
+
+/** Agent override config for user customization. */
+export interface AgentOverrideConfig {
+  /** Override model identifier. */
+  model?: string;
+  /** Override model variant. */
+  variant?: string;
+  /** Override sampling temperature. */
+  temperature?: number;
+  /** Override nucleus sampling value. */
+  top_p?: number;
+  /** Additional prompt text appended to the system prompt. */
+  prompt_append?: string;
+  /** Tool names explicitly denied for this agent. */
+  denied_tools?: string[];
+  /** Whether this agent is disabled. */
+  disable?: boolean;
+  /** Custom fallback model chain. */
+  fallback_models?: string | string[];
+}
+
+/** Agent contribution from a micro-plugin. */
+export type PluginAgentContribution = AgentConfig;

package/src/types/category.ts

@@ -0,0 +1,32 @@
+/** All built-in GoatCode category names. */
+export type BuiltinCategoryName =
+  | "visual-engineering"
+  | "ultrabrain"
+  | "deep"
+  | "artistry"
+  | "quick"
+  | "unspecified-low"
+  | "unspecified-high"
+  | "writing";
+
+/** Category configuration. */
+export interface CategoryConfig {
+  /** Model to use for this category. */
+  model?: string;
+  /** Model variant (for example: high, max, xhigh). */
+  variant?: string;
+  /** Human-readable description. */
+  description?: string;
+  /** Additional system prompt text appended for this category. */
+  prompt_append?: string;
+}
+
+/** Available category with resolved metadata. */
+export interface AvailableCategory {
+  /** Category name. */
+  name: string;
+  /** User-facing category description. */
+  description: string;
+  /** Resolved model for this category, if available. */
+  model?: string;
+}

package/src/types/config.ts

@@ -0,0 +1,26 @@
+import type { AgentOverrideConfig, BuiltinAgentName } from "./agent";
+import type { BuiltinCategoryName, CategoryConfig } from "./category";
+
+/** Partial agent overrides where each built-in agent can be partially overridden. */
+export type AgentOverrides = Partial<Record<BuiltinAgentName, AgentOverrideConfig>>;
+
+/** Partial category overrides for built-in categories. */
+export type CategoryOverrides = Partial<Record<BuiltinCategoryName, CategoryConfig>>;
+
+/**
+ * Top-level GoatCode configuration shape.
+ * Runtime validation and defaults are handled by the config schema layer.
+ */
+export interface GoatCodeConfig {
+  agents?: AgentOverrides;
+  categories?: CategoryOverrides;
+  default_temperature?: number;
+  default_provider?: string;
+  provider_priority?: string[];
+  disabled_agents?: string[];
+  disabled_hooks?: string[];
+  disabled_tools?: string[];
+  disabled_skills?: string[];
+  auto_update?: boolean;
+  plugins?: string[];
+}

package/src/types/hook.ts

@@ -0,0 +1,44 @@
+import type { Plugin } from "@opencode-ai/plugin";
+
+/** All OpenCode hook event names — single source of truth. */
+export const HOOK_EVENT_NAMES = [
+  "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",
+] as const;
+
+/** All OpenCode hook event names. */
+export type HookEventName = (typeof HOOK_EVENT_NAMES)[number];
+
+/** Generic hook handler signature fallback. */
+export type HookHandler = (input: unknown, output: unknown) => Promise<void> | void;
+
+/** Raw plugin instance shape returned to OpenCode. */
+type OpenCodePluginInstance = Awaited<ReturnType<Plugin>>;
+
+/** Resolves the concrete OpenCode hook handler type for a hook name. */
+type HookHandlerFor<Name extends HookEventName> =
+  NonNullable<OpenCodePluginInstance[Name]> extends (...args: infer Args) => infer Return
+    ? (...args: Args) => Return
+    : HookHandler;
+
+/** Hook contributions mapped by event name. */
+export type PluginHookContributions = {
+  [Name in HookEventName]: HookHandlerFor<Name>;
+};
+
+/** Priority for hook execution ordering (lower values run first). */
+export type HookPriority = number;

package/src/types/index.ts

@@ -0,0 +1,12 @@
+/** Agent types and configurations. */
+export * from "./agent";
+/** Category types and configurations. */
+export * from "./category";
+/** Configuration types for GoatCode. */
+export * from "./config";
+/** Hook types and contributions. */
+export * from "./hook";
+/** Plugin types and registry interfaces. */
+export * from "./plugin";
+/** Tool types and definitions. */
+export * from "./tool";

package/src/types/plugin.ts

@@ -0,0 +1,47 @@
+import type { Plugin } from "@opencode-ai/plugin";
+
+import type { PluginAgentContribution } from "./agent";
+import type { PluginHookContributions } from "./hook";
+import type { PluginToolContribution } from "./tool";
+
+/** The raw context passed to the plugin by OpenCode. */
+export type OpenCodeContext = Parameters<Plugin>[0];
+
+/** The raw plugin instance returned to OpenCode. */
+export type OpenCodePluginInstance = Awaited<ReturnType<Plugin>>;
+
+/** Generic plugin hook handler fallback type. */
+export type PluginHookHandler = (...args: unknown[]) => Promise<void> | void;
+
+/**
+ * A GoatCode micro-plugin definition.
+ * This is the contract used by internal and external plugins.
+ */
+export interface PluginDefinition {
+  /** Unique plugin name (kebab-case). */
+  readonly name: string;
+  /** Semantic version string. */
+  readonly version?: string;
+  /** Plugin names this depends on (must be registered first). */
+  readonly dependencies?: readonly string[];
+  /** Hook contributions keyed by OpenCode hook event name. */
+  readonly hooks?: Partial<PluginHookContributions>;
+  /** Tool contributions keyed by tool name. */
+  readonly tools?: Record<string, PluginToolContribution>;
+  /** Agent contributions keyed by agent name. */
+  readonly agents?: Record<string, PluginAgentContribution>;
+  /** Optional setup executed during registry initialization. */
+  readonly setup?: (ctx: OpenCodeContext) => Promise<void> | void;
+  /** Optional teardown executed when plugin registry is disposed. */
+  readonly teardown?: () => Promise<void> | void;
+}
+
+/** Intermediate aggregated plugin output produced by the registry. */
+export interface AggregatedPlugins {
+  /** All hook contributions keyed by hook name in execution order. */
+  hooks: Map<string, PluginHookHandler[]>;
+  /** All tool contributions merged into one record. */
+  tools: Record<string, PluginToolContribution>;
+  /** All agent contributions merged into one record. */
+  agents: Record<string, PluginAgentContribution>;
+}

package/src/types/tool.ts

@@ -0,0 +1,10 @@
+import type { ToolDefinition } from "@opencode-ai/plugin";
+
+/** Re-export for convenience. */
+export type { ToolDefinition };
+
+/** A tool contribution from a micro-plugin. */
+export type PluginToolContribution = ToolDefinition;
+
+/** Record of tools keyed by name. */
+export type ToolsRecord = Record<string, ToolDefinition>;

package/test-setup.ts

@@ -0,0 +1,8 @@
+import { beforeEach } from "bun:test"
+
+// Reset module-level state before each test to prevent test pollution.
+// Add state reset functions here as new stateful modules are added.
+beforeEach(() => {
+  // Currently no stateful module state to reset.
+  // Future stateful modules will register reset functions here.
+})

package/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "declaration": true,
+    "declarationDir": "dist",
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "lib": ["ESNext"],
+    "types": ["bun"]
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "**/*.test.ts", "src/agents/disabled/**/*"]
+}