goatcode-sh 0.0.1 → 0.1.2

package/src/registry/plugin-registry.test.ts

@@ -0,0 +1,56 @@
+import { describe, expect, test } from "bun:test";
+
+import type { PluginAgentContribution } from "../types/agent";
+import type { PluginDefinition, PluginHookHandler } from "../types/plugin";
+import type { PluginToolContribution } from "../types/tool";
+
+import { PluginRegistry } from "./plugin-registry";
+
+function makePlugin(name: string, deps: string[] = []): PluginDefinition {
+  return { name, dependencies: deps };
+}
+
+function makeToolContribution(): PluginToolContribution {
+  return { execute: async () => "ok" } as unknown as PluginToolContribution;
+}
+
+function makeAgentContribution(): PluginAgentContribution {
+  return { instructions: "test", model: "model" } as unknown as PluginAgentContribution;
+}
+
+describe("PluginRegistry", () => {
+  test("registers a plugin", () => {
+    const registry = new PluginRegistry();
+    registry.register(makePlugin("test"));
+    expect(registry.size).toBe(1);
+    expect(registry.registeredNames).toContain("test");
+  });
+
+  test("throws on duplicate plugin names", () => {
+    const registry = new PluginRegistry();
+    registry.register(makePlugin("test"));
+    expect(() => registry.register(makePlugin("test"))).toThrow("already registered");
+  });
+
+  test("resolves and aggregates hooks tools and agents", () => {
+    const handler: PluginHookHandler = async () => {};
+    const registry = new PluginRegistry();
+    registry.register({ name: "a", tools: { tool_a: makeToolContribution() } });
+    registry.register({ name: "b", agents: { agent_b: makeAgentContribution() } });
+    registry.register({ name: "c", hooks: { "tool.execute.before": handler } });
+
+    const resolved = registry.resolve();
+    const aggregated = registry.aggregate(resolved);
+
+    expect(Object.keys(aggregated.tools)).toContain("tool_a");
+    expect(Object.keys(aggregated.agents)).toContain("agent_b");
+    expect(aggregated.hooks.get("tool.execute.before")).toHaveLength(1);
+  });
+
+  test("propagates cycle detection from resolver", () => {
+    const registry = new PluginRegistry();
+    registry.register(makePlugin("x", ["y"]));
+    registry.register(makePlugin("y", ["x"]));
+    expect(() => registry.resolve()).toThrow("Circular dependency");
+  });
+});

package/src/registry/plugin-registry.ts

@@ -0,0 +1,82 @@
+import { log } from "../shared/logger";
+import type { AggregatedPlugins, OpenCodeContext, PluginDefinition } from "../types/plugin";
+
+import { aggregateAgents } from "./agent-aggregator";
+import { resolvePluginOrder } from "./dependency-resolver";
+import { aggregateHooks } from "./hook-aggregator";
+import { aggregateTools } from "./tool-aggregator";
+
+export interface AggregateOptions {
+  disabledAgents?: string[];
+  disabledHooks?: string[];
+  disabledTools?: string[];
+}
+
+export class PluginRegistry {
+  private readonly plugins = new Map<string, PluginDefinition>();
+
+  register(plugin: PluginDefinition): void {
+    if (this.plugins.has(plugin.name)) {
+      throw new Error(`Plugin "${plugin.name}" is already registered`);
+    }
+    this.plugins.set(plugin.name, plugin);
+    log(`[PluginRegistry] Registered plugin: ${plugin.name}`);
+  }
+
+  resolve(): PluginDefinition[] {
+    const result = resolvePluginOrder([...this.plugins.values()]);
+    log(`[PluginRegistry] Resolved ${result.order.length} plugins`);
+    return result.order;
+  }
+
+  aggregate(resolvedOrder: PluginDefinition[], options?: AggregateOptions): AggregatedPlugins {
+    return {
+      hooks: aggregateHooks(resolvedOrder, options?.disabledHooks),
+      tools: aggregateTools(resolvedOrder, options?.disabledTools),
+      agents: aggregateAgents(resolvedOrder, options?.disabledAgents),
+    };
+  }
+
+  async setup(
+    resolvedOrder: PluginDefinition[],
+    ctx: OpenCodeContext,
+  ): Promise<PluginDefinition[]> {
+    const successful: PluginDefinition[] = [];
+    for (const plugin of resolvedOrder) {
+      if (!plugin.setup) {
+        successful.push(plugin);
+        continue;
+      }
+
+      try {
+        await plugin.setup(ctx);
+        successful.push(plugin);
+      } catch (error) {
+        log(`[PluginRegistry] Setup failed for plugin: ${plugin.name}`, { error });
+      }
+    }
+    return successful;
+  }
+
+  async teardown(resolvedOrder: PluginDefinition[]): Promise<void> {
+    for (const plugin of [...resolvedOrder].reverse()) {
+      if (!plugin.teardown) {
+        continue;
+      }
+
+      try {
+        await plugin.teardown();
+      } catch (error) {
+        log(`[PluginRegistry] Teardown failed for plugin: ${plugin.name}`, { error });
+      }
+    }
+  }
+
+  get registeredNames(): string[] {
+    return [...this.plugins.keys()];
+  }
+
+  get size(): number {
+    return this.plugins.size;
+  }
+}

package/src/registry/tool-aggregator.ts

@@ -0,0 +1,13 @@
+import type { PluginDefinition } from "../types/plugin";
+import type { PluginToolContribution } from "../types/tool";
+import { aggregateContributions } from "./contribution-aggregator";
+
+export function aggregateTools(
+  plugins: PluginDefinition[],
+  disabledTools?: string[],
+): Record<string, PluginToolContribution> {
+  return aggregateContributions<"tools", PluginToolContribution>(plugins, "tools", {
+    disabled: disabledTools,
+    onConflict: "replace",
+  });
+}

package/src/registry/types.ts

@@ -0,0 +1,11 @@
+import type { PluginDefinition } from "../types/plugin";
+
+export interface ResolvedPlugin {
+  plugin: PluginDefinition;
+  order: number;
+}
+
+export interface ResolutionResult {
+  order: PluginDefinition[];
+  map: Map<string, ResolvedPlugin>;
+}

package/src/runtime/index.ts

@@ -0,0 +1,43 @@
+export {
+  POLLING_INTERVAL_MS,
+  STABILITY_REQUIRED_POLLS,
+  createPollState,
+  checkStability,
+  pollUntilStable,
+  initBackgroundAgent,
+  getBackgroundAgent,
+  resetBackgroundAgent,
+  BackgroundAgentManager,
+} from "../features/background-agent";
+
+export type {
+  BackgroundTask,
+  BackgroundTaskStatus,
+  LaunchInput,
+} from "../features/background-agent";
+export type { PollState, PollSnapshot } from "../features/background-agent/poller";
+
+export {
+  setSessionState,
+  getSessionState,
+  deleteSessionState,
+  clearSessionStore,
+  consumeNewMessages,
+  resetMessageCursor,
+  setSessionTools,
+  getSessionTools,
+  deleteSessionTools,
+  clearSessionTools,
+} from "../features/session-state";
+
+export type { SessionState, CursorMessage } from "../features/session-state";
+
+export {
+  DEFAULT_CATEGORIES,
+  DEFAULT_CATEGORY_DEFINITIONS,
+  CategoryResolver,
+  resolveCategory,
+  CATEGORY_PROMPT_APPENDS,
+} from "../features/categories";
+
+export type { CategoryDefinition, CategoryName, CategoryOverrides } from "../features/categories";

package/src/shared/data-path.ts

@@ -0,0 +1,18 @@
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+export function getDataDir(): string {
+  return process.env.XDG_DATA_HOME ?? join(homedir(), ".local", "share");
+}
+
+export function getCacheDir(): string {
+  return process.env.XDG_CACHE_HOME ?? join(homedir(), ".cache");
+}
+
+export function getOpenCodeStorageDir(): string {
+  return join(getDataDir(), "opencode", "storage");
+}
+
+export function getGoatCodeCacheDir(): string {
+  return join(getCacheDir(), "goatcode-sh");
+}

package/src/shared/deep-merge.test.ts

@@ -0,0 +1,36 @@
+import { describe, test, expect } from "bun:test";
+import { deepMerge } from "./deep-merge";
+
+describe("deepMerge", () => {
+  describe("with nested objects", () => {
+    test("merges nested keys without losing siblings", () => {
+      //#given
+      const base = { a: 1, b: { c: 2, d: 3 } };
+      const override = { b: { c: 10 }, e: 5 };
+      //#when
+      const result = deepMerge(base, override);
+      //#then
+      expect(result).toEqual({ a: 1, b: { c: 10, d: 3 }, e: 5 });
+    });
+
+    test("override wins for scalar values", () => {
+      //#given
+      const base = { x: "original" };
+      const override = { x: "updated" };
+      //#when
+      const result = deepMerge(base, override);
+      //#then
+      expect(result?.x).toBe("updated");
+    });
+
+    test("undefined override values do not overwrite base", () => {
+      //#given
+      const base = { a: "keep" };
+      const override = { a: undefined };
+      //#when
+      const result = deepMerge(base, override as typeof base);
+      //#then
+      expect(result?.a).toBe("keep");
+    });
+  });
+});

package/src/shared/deep-merge.ts

@@ -0,0 +1,61 @@
+const DANGEROUS_KEYS = new Set(["__proto__", "constructor", "prototype"]);
+const MAX_DEPTH = 50;
+
+export function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    !Array.isArray(value) &&
+    Object.prototype.toString.call(value) === "[object Object]"
+  );
+}
+
+/**
+ * Deep merges two objects, with override values taking precedence.
+ * - Objects are recursively merged
+ * - Arrays are replaced (not concatenated)
+ * - undefined values in override do not overwrite base values
+ *
+ * @example
+ * deepMerge({ a: 1, b: { c: 2, d: 3 } }, { b: { c: 10 }, e: 5 })
+ * // => { a: 1, b: { c: 10, d: 3 }, e: 5 }
+ */
+export function deepMerge<T extends Record<string, unknown>>(
+  base: T,
+  override: Partial<T>,
+  depth?: number,
+): T;
+export function deepMerge<T extends Record<string, unknown>>(
+  base: T | undefined,
+  override: T | undefined,
+  depth?: number,
+): T | undefined;
+export function deepMerge<T extends Record<string, unknown>>(
+  base: T | undefined,
+  override: T | undefined,
+  depth = 0,
+): T | undefined {
+  if (!base && !override) return undefined;
+  if (!base) return override;
+  if (!override) return base;
+  if (depth > MAX_DEPTH) return override ?? base;
+
+  const result = { ...base } as Record<string, unknown>;
+
+  for (const key of Object.keys(override)) {
+    if (DANGEROUS_KEYS.has(key)) continue;
+
+    const baseValue = base[key];
+    const overrideValue = override[key];
+
+    if (overrideValue === undefined) continue;
+
+    if (isPlainObject(baseValue) && isPlainObject(overrideValue)) {
+      result[key] = deepMerge(baseValue, overrideValue, depth + 1);
+    } else {
+      result[key] = overrideValue;
+    }
+  }
+
+  return result as T;
+}

package/src/shared/fallback-chain.ts

@@ -0,0 +1,8 @@
+export function buildFallbackChain(
+  configFallbacks: string | string[] | undefined,
+  defaultChain: string[],
+): string[] {
+  if (!configFallbacks) return defaultChain;
+  const overrides = Array.isArray(configFallbacks) ? configFallbacks : [configFallbacks];
+  return [...overrides, ...defaultChain.filter((m) => !overrides.includes(m))];
+}

package/src/shared/index.ts

@@ -0,0 +1,59 @@
+export { log, getLogFilePath } from "./logger";
+export { deepMerge, isPlainObject } from "./deep-merge";
+export { toSnakeCase } from "./snake-case";
+export { truncateDescription } from "./truncate-description";
+export { getDataDir, getCacheDir, getOpenCodeStorageDir, getGoatCodeCacheDir } from "./data-path";
+export { safeCreateHook } from "./safe-create-hook";
+export { normalizeModel, parseModelId, normalizeAndQualifyModel } from "./model-normalization";
+export { isModelAvailable } from "./model-availability";
+export { buildFallbackChain } from "./fallback-chain";
+export { resolveModel } from "./model-resolution-pipeline";
+export type {
+  ModelResolutionInput,
+  ModelResolutionSource,
+  ModelResolutionResult,
+} from "./model-resolution-pipeline";
+export {
+  toPlatformModel,
+  toCanonicalModel,
+  registerPlatformMappings,
+  getKnownPlatforms,
+} from "./model-prefix-map";
+export type { PlatformId, BuiltinPlatformId } from "./model-prefix-map";
+export {
+  resolveProvider,
+  qualifyModel,
+  isQualifiedModel,
+  findProvidersForModel,
+  setProviderPriority,
+  getProviderPriority,
+  setDefaultPreferredProvider,
+  getDefaultPreferredProvider,
+  registerProviderModelMap,
+  unregisterProviderModelMap,
+  resetProviderRegistry,
+} from "./provider-registry";
+export type { ProviderResolutionResult } from "./provider-registry";
+export {
+  buildDiscoveryIndex,
+  initializeDiscovery,
+  getDiscovery,
+  resetDiscovery,
+} from "./provider-discovery";
+export type {
+  ProviderListResponse,
+  ProviderModelEntry,
+  DiscoveryResult,
+} from "./provider-discovery";
+export {
+  buildModelsDevIndex,
+  fetchModelsDevData,
+  resolveWithModelsDevData,
+  createModelsDevCache,
+} from "./models-dev";
+export type {
+  ModelsDevModel,
+  ModelsDevProvider,
+  ModelsDevIndex,
+  ModelsDevCache,
+} from "./models-dev";

package/src/shared/logger.ts

@@ -0,0 +1,54 @@
+import { appendFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const LOG_FILE = join(tmpdir(), "goatcode.log");
+const BUFFER_SIZE_LIMIT = 50;
+const FLUSH_INTERVAL_MS = 500;
+
+let buffer: string[] = [];
+let flushTimer: ReturnType<typeof setTimeout> | null = null;
+
+function flush(): void {
+  if (buffer.length === 0) return;
+  const data = buffer.join("");
+  buffer = [];
+  try {
+    appendFileSync(LOG_FILE, data);
+  } catch {
+    // Ignore log write failures - never crash the plugin for logging
+  }
+}
+
+// Flush buffer on process exit to avoid losing buffered log entries
+process.on("exit", flush);
+process.on("beforeExit", flush);
+
+function scheduleFlush(): void {
+  if (flushTimer) return;
+  flushTimer = setTimeout(() => {
+    flushTimer = null;
+    flush();
+  }, FLUSH_INTERVAL_MS);
+}
+
+/** Write a structured log entry to the goatcode log file. */
+export function log(message: string, data?: unknown): void {
+  try {
+    const timestamp = new Date().toISOString();
+    const logEntry = `[${timestamp}] ${message} ${data !== undefined ? JSON.stringify(data) : ""}\n`;
+    buffer.push(logEntry);
+    if (buffer.length >= BUFFER_SIZE_LIMIT) {
+      flush();
+    } else {
+      scheduleFlush();
+    }
+  } catch {
+    // Never throw from logger
+  }
+}
+
+/** Returns the absolute path to the log file. */
+export function getLogFilePath(): string {
+  return LOG_FILE;
+}

package/src/shared/model-availability.ts

@@ -0,0 +1,18 @@
+export function isModelAvailable(model: string, availableModels: Set<string>): boolean {
+  if (availableModels.size === 0) return true;
+  const normalized = model.toLowerCase().trim();
+  if (availableModels.has(normalized)) return true;
+
+  for (const available of availableModels) {
+    const longer = available.length > normalized.length ? available : normalized;
+    const shorter = available.length <= normalized.length ? available : normalized;
+    if (
+      longer.startsWith(shorter) &&
+      (longer.length === shorter.length || /[/\-.]/.test(longer[shorter.length]!))
+    ) {
+      return true;
+    }
+  }
+
+  return false;
+}

package/src/shared/model-normalization.test.ts

@@ -0,0 +1,75 @@
+import { describe, expect, it } from "bun:test";
+import { normalizeModel, parseModelId } from "./model-normalization";
+
+describe("normalizeModel", () => {
+  describe("given undefined input", () => {
+    it("returns undefined", () => {
+      expect(normalizeModel(undefined)).toBeUndefined();
+    });
+  });
+
+  describe("given empty string", () => {
+    it("returns undefined", () => {
+      expect(normalizeModel("")).toBeUndefined();
+    });
+  });
+
+  describe("given whitespace-only string", () => {
+    it("returns undefined", () => {
+      expect(normalizeModel("   ")).toBeUndefined();
+    });
+  });
+
+  describe("given model with leading/trailing whitespace", () => {
+    it("trims whitespace", () => {
+      expect(normalizeModel("  openai/gpt-4  ")).toBe("openai/gpt-4");
+    });
+  });
+
+  describe("given model with uppercase letters", () => {
+    it("lowercases the result", () => {
+      expect(normalizeModel("OpenAI/GPT-4")).toBe("openai/gpt-4");
+    });
+  });
+
+  describe("given already normalized model", () => {
+    it("returns unchanged", () => {
+      expect(normalizeModel("anthropic/claude-3")).toBe("anthropic/claude-3");
+    });
+  });
+});
+
+describe("parseModelId", () => {
+  describe("given model without slash", () => {
+    it("returns undefined", () => {
+      expect(parseModelId("gpt-4")).toBeUndefined();
+    });
+  });
+
+  describe("given empty string", () => {
+    it("returns undefined", () => {
+      expect(parseModelId("")).toBeUndefined();
+    });
+  });
+
+  describe("given valid provider/model format", () => {
+    it("splits on first slash", () => {
+      expect(parseModelId("openai/gpt-4")).toEqual({ provider: "openai", modelId: "gpt-4" });
+    });
+  });
+
+  describe("given model with multiple slashes", () => {
+    it("splits on first slash only", () => {
+      expect(parseModelId("openai/gpt-4/turbo")).toEqual({
+        provider: "openai",
+        modelId: "gpt-4/turbo",
+      });
+    });
+  });
+
+  describe("given model with uppercase", () => {
+    it("normalizes before parsing", () => {
+      expect(parseModelId("OpenAI/GPT-4")).toEqual({ provider: "openai", modelId: "gpt-4" });
+    });
+  });
+});

package/src/shared/model-normalization.ts

@@ -0,0 +1,28 @@
+import { qualifyModel } from "./provider-registry";
+
+export function normalizeModel(model: string | undefined): string | undefined {
+  if (!model) return undefined;
+  const trimmed = model.trim();
+  if (!trimmed) return undefined;
+  return trimmed.toLowerCase();
+}
+
+export function parseModelId(model: string): { provider: string; modelId: string } | undefined {
+  const normalized = normalizeModel(model);
+  if (!normalized) return undefined;
+  const slashIndex = normalized.indexOf("/");
+  if (slashIndex === -1) return undefined;
+  return {
+    provider: normalized.slice(0, slashIndex),
+    modelId: normalized.slice(slashIndex + 1),
+  };
+}
+
+export function normalizeAndQualifyModel(
+  model: string | undefined,
+  preferredProvider?: string,
+): string | undefined {
+  const normalized = normalizeModel(model);
+  if (!normalized) return undefined;
+  return qualifyModel(normalized, preferredProvider);
+}

package/src/shared/model-prefix-map.test.ts

@@ -0,0 +1,75 @@
+import { describe, it, expect } from "bun:test";
+import { toPlatformModel, toCanonicalModel } from "./model-prefix-map";
+
+describe("model prefix map", () => {
+  describe("#given direct platform", () => {
+    describe("#when converting to platform model", () => {
+      it("#then returns the model unchanged", () => {
+        expect(toPlatformModel("anthropic/claude-opus-4-6", "direct")).toBe(
+          "anthropic/claude-opus-4-6",
+        );
+      });
+    });
+
+    describe("#when converting to canonical model", () => {
+      it("#then returns the model unchanged", () => {
+        expect(toCanonicalModel("anthropic/claude-opus-4-6", "direct")).toBe(
+          "anthropic/claude-opus-4-6",
+        );
+      });
+    });
+  });
+
+  describe("#given zen platform", () => {
+    describe("#when converting anthropic model to platform", () => {
+      it("#then adds zen- prefix", () => {
+        expect(toPlatformModel("anthropic/claude-opus-4-6", "zen")).toBe(
+          "zen-anthropic/claude-opus-4-6",
+        );
+      });
+    });
+
+    describe("#when converting openai model to platform", () => {
+      it("#then adds zen- prefix", () => {
+        expect(toPlatformModel("openai/gpt-5.4", "zen")).toBe("zen-openai/gpt-5.4");
+      });
+    });
+
+    describe("#when converting google model to platform", () => {
+      it("#then adds zen- prefix", () => {
+        expect(toPlatformModel("google/gemini-2.5-flash", "zen")).toBe(
+          "zen-google/gemini-2.5-flash",
+        );
+      });
+    });
+
+    describe("#when converting zen-prefixed model back to canonical", () => {
+      it("#then strips zen- prefix", () => {
+        expect(toCanonicalModel("zen-anthropic/claude-opus-4-6", "zen")).toBe(
+          "anthropic/claude-opus-4-6",
+        );
+        expect(toCanonicalModel("zen-openai/gpt-5.4", "zen")).toBe("openai/gpt-5.4");
+        expect(toCanonicalModel("zen-google/gemini-2.5-flash", "zen")).toBe(
+          "google/gemini-2.5-flash",
+        );
+      });
+    });
+
+    describe("#when converting an unknown provider", () => {
+      it("#then returns the model unchanged", () => {
+        expect(toPlatformModel("mistral/mistral-large", "zen")).toBe("mistral/mistral-large");
+      });
+    });
+  });
+
+  describe("#given roundtrip conversion", () => {
+    describe("#when converting to platform then back to canonical", () => {
+      it("#then returns the original model", () => {
+        const original = "anthropic/claude-sonnet-4-6";
+        const platform = toPlatformModel(original, "zen");
+        const canonical = toCanonicalModel(platform, "zen");
+        expect(canonical).toBe(original);
+      });
+    });
+  });
+});