@koriit/opencode-claude-bridge 0.1.0

package/src/mcp-inject.ts

@@ -0,0 +1,381 @@
+/**
+ * MCP injection from enabled Claude plugins into OpenCode's flat `cfg.mcp` record.
+ *
+ * Only runs when the global `allowMcp` toggle is on (safe-by-default off per §8).
+ *
+ * Source: each plugin's top-level `<installPath>/.mcp.json` — the canonical Claude
+ * MCP location (verified against real installed plugins: slack, atlassian, zoom).
+ * `plugin.json` holds metadata only and never contains `mcpServers`.
+ *
+ * Mapping (Claude → OpenCode V1 flat shape):
+ *   - `type:"http"` (remote) → `{ type:"remote", url, headers?, oauth? }`
+ *   - stdio/command (no type, or `type:"stdio"`) → `{ type:"local", command:[cmd, ...args], environment? }`
+ *   - `${CLAUDE_PLUGIN_ROOT}` resolved to `installPath` in all string fields
+ *
+ * oauth: OpenCode V1 uses the same camelCase field names as Claude's `.mcp.json`
+ * (`clientId`, `clientSecret`, `scope`, `callbackPort`, `redirectUri`). No rename
+ * is needed — the fields are passed through directly. (Appendix B open item resolved.)
+ *
+ * Naming: base name `<plugin>-<server>`, then apply the §7 NameAllocator collision
+ * rules vs existing `cfg.mcp` keys.
+ *
+ * Skip-and-warn (§10): unreadable/unparseable `.mcp.json` or a malformed server
+ * entry logs a warning and that item is skipped; the hook does not throw in non-strict
+ * mode.
+ */
+
+import fs from "node:fs/promises"
+import path from "node:path"
+import type { Config } from "@opencode-ai/plugin"
+import { NameAllocator, splitPluginId } from "./naming.js"
+import type { Logger } from "./logger.js"
+import type { ClaudePlugin } from "./types.js"
+
+// ── OpenCode V1 MCP entry shapes ──────────────────────────────────────────────
+
+/**
+ * OpenCode V1 oauth configuration shape (same field names as Claude's `.mcp.json`).
+ * Verified against OpenCode v1.15.x packages/core/src/v1/config/mcp.ts:
+ * `clientId`, `clientSecret`, `scope`, `callbackPort`, `redirectUri`.
+ */
+export interface McpOauth {
+  clientId?: string
+  clientSecret?: string
+  scope?: string
+  callbackPort?: number
+  redirectUri?: string
+}
+
+/** OpenCode V1 local MCP entry (`type:"local"`). */
+export interface McpLocalEntry {
+  type: "local"
+  command: string[]
+  environment?: Record<string, string>
+  enabled?: boolean
+  timeout?: number
+}
+
+/** OpenCode V1 remote MCP entry (`type:"remote"`). */
+export interface McpRemoteEntry {
+  type: "remote"
+  url: string
+  headers?: Record<string, string>
+  oauth?: McpOauth | false
+  enabled?: boolean
+  timeout?: number
+}
+
+export type McpEntry = McpLocalEntry | McpRemoteEntry
+
+// ── Config shape guard ────────────────────────────────────────────────────────
+
+interface InjectableMcpConfig {
+  mcp?: Record<string, McpEntry> | undefined
+}
+
+function guardMcpConfig(cfg: InjectableMcpConfig): Record<string, McpEntry> {
+  if (cfg.mcp === undefined || cfg.mcp === null || typeof cfg.mcp !== "object") {
+    cfg.mcp = {}
+  }
+  return cfg.mcp
+}
+
+// ── Claude .mcp.json schema ───────────────────────────────────────────────────
+
+/**
+ * Claude's MCP server entry as it appears in `.mcp.json`.
+ * Verified against real installed plugins (slack, atlassian, zoom-skills).
+ */
+interface ClaudeMcpOauthObject {
+  clientId?: string
+  clientSecret?: string
+  scope?: string
+  callbackPort?: number
+  redirectUri?: string
+  [key: string]: unknown
+}
+
+interface ClaudeMcpServer {
+  type?: "http" | "stdio" | string
+  url?: string
+  command?: string
+  args?: string[]
+  env?: Record<string, string>
+  headers?: Record<string, string>
+  /** Claude oauth may be an object or `false` (to disable OAuth auto-detection). */
+  oauth?: ClaudeMcpOauthObject | false
+  [key: string]: unknown
+}
+
+interface ClaudeMcpJson {
+  mcpServers?: Record<string, ClaudeMcpServer>
+}
+
+// ── Resolution helpers ────────────────────────────────────────────────────────
+
+/**
+ * Resolve `${CLAUDE_PLUGIN_ROOT}` in a string to the absolute `installPath`.
+ */
+function resolvePluginRoot(text: string, installPath: string): string {
+  return text.replaceAll("${CLAUDE_PLUGIN_ROOT}", installPath)
+}
+
+/**
+ * Resolve `${CLAUDE_PLUGIN_ROOT}` in all string values of a record.
+ *
+ * Non-string values (e.g. a numeric header or env value from a loose JSON file)
+ * are silently dropped rather than reaching `String.prototype.replaceAll` and
+ * throwing a TypeError that would kill the whole hook run (§10).
+ */
+function resolveRecordValues(
+  record: Record<string, unknown>,
+  installPath: string,
+): Record<string, string> {
+  const out: Record<string, string> = {}
+  for (const [k, v] of Object.entries(record)) {
+    if (typeof v === "string") out[k] = resolvePluginRoot(v, installPath)
+    // Non-string values are dropped — they cannot be path-resolved and are
+    // not valid in the target OpenCode string-record fields (headers, env).
+  }
+  return out
+}
+
+// ── Claude → OpenCode mapping ─────────────────────────────────────────────────
+
+/**
+ * Map a Claude `.mcp.json` server entry to an OpenCode V1 MCP entry.
+ *
+ * - `type:"http"` → `{ type:"remote", url, headers?, oauth? }`
+ * - everything else (stdio, absent) → `{ type:"local", command:[cmd,...args], environment? }`
+ * - `${CLAUDE_PLUGIN_ROOT}` resolved in all string fields
+ * - oauth fields passed through with same camelCase names (OpenCode V1 matches Claude exactly)
+ *
+ * Returns `null` if the entry is malformed and should be skipped.
+ */
+export function mapClaudeMcpServer(
+  server: ClaudeMcpServer,
+  installPath: string,
+): McpEntry | null {
+  if (server.type === "http") {
+    // Remote entry
+    if (!server.url || typeof server.url !== "string") return null
+    const url = resolvePluginRoot(server.url, installPath)
+
+    const entry: McpRemoteEntry = { type: "remote", url }
+
+    if (server.headers && typeof server.headers === "object") {
+      entry.headers = resolveRecordValues(server.headers, installPath)
+    }
+
+    if (server.oauth !== undefined) {
+      if (server.oauth === false) {
+        entry.oauth = false
+      } else if (typeof server.oauth === "object") {
+        // Pass through camelCase oauth fields verbatim — OpenCode V1 uses the
+        // same field names as Claude: clientId, clientSecret, scope, callbackPort,
+        // redirectUri. Verified against OpenCode src/v1/config/mcp.ts.
+        const oauth: McpOauth = {}
+        if (typeof server.oauth.clientId === "string") oauth.clientId = server.oauth.clientId
+        if (typeof server.oauth.clientSecret === "string") oauth.clientSecret = server.oauth.clientSecret
+        if (typeof server.oauth.scope === "string") oauth.scope = server.oauth.scope
+        if (typeof server.oauth.callbackPort === "number") oauth.callbackPort = server.oauth.callbackPort
+        if (typeof server.oauth.redirectUri === "string") oauth.redirectUri = server.oauth.redirectUri
+        entry.oauth = oauth
+      }
+    }
+
+    return entry
+  }
+
+  // Local / stdio entry
+  if (!server.command || typeof server.command !== "string") return null
+  const cmd = resolvePluginRoot(server.command, installPath)
+  const args = Array.isArray(server.args)
+    ? server.args.map((a) => (typeof a === "string" ? resolvePluginRoot(a, installPath) : String(a)))
+    : []
+
+  const entry: McpLocalEntry = { type: "local", command: [cmd, ...args] }
+
+  if (server.env && typeof server.env === "object") {
+    entry.environment = resolveRecordValues(
+      server.env as Record<string, unknown>,
+      installPath,
+    )
+  }
+
+  return entry
+}
+
+// ── Per-plugin injection ──────────────────────────────────────────────────────
+
+/**
+ * Read and parse `<installPath>/.mcp.json`. Returns the parsed object or `null`
+ * if the file is absent or unreadable (caller logs and skips).
+ */
+async function readMcpJson(
+  installPath: string,
+  pluginId: string,
+  logger: Logger,
+): Promise<ClaudeMcpJson | null> {
+  const mcpPath = path.join(installPath, ".mcp.json")
+  let raw: string
+  try {
+    raw = await fs.readFile(mcpPath, "utf8")
+  } catch (err) {
+    const code = (err as NodeJS.ErrnoException).code
+    if (code === "ENOENT") return null // no MCP for this plugin — silent
+    logger.warn(
+      `could not read ".mcp.json" from plugin "${pluginId}" (${err instanceof Error ? err.message : String(err)}); skipping MCP for this plugin`,
+    )
+    return null
+  }
+
+  try {
+    const parsed = JSON.parse(raw) as unknown
+    if (
+      typeof parsed !== "object" ||
+      parsed === null ||
+      Array.isArray(parsed)
+    ) {
+      logger.warn(
+        `".mcp.json" from plugin "${pluginId}" is not a JSON object; skipping MCP for this plugin`,
+      )
+      return null
+    }
+    return parsed as ClaudeMcpJson
+  } catch (err) {
+    logger.warn(
+      `could not parse ".mcp.json" from plugin "${pluginId}" (${err instanceof Error ? err.message : String(err)}); skipping MCP for this plugin`,
+    )
+    return null
+  }
+}
+
+/**
+ * Inject MCP servers from one plugin's `.mcp.json` into `mcpCfg`.
+ */
+async function injectPluginMcp(
+  plugin: ClaudePlugin,
+  mcpCfg: Record<string, McpEntry>,
+  allocator: NameAllocator,
+  summary: McpInjectionSummary,
+  logger: Logger,
+): Promise<void> {
+  const parsed = await readMcpJson(plugin.installPath, plugin.id, logger)
+  if (parsed === null) return
+
+  const servers = parsed.mcpServers
+  if (!servers || typeof servers !== "object" || Array.isArray(servers)) {
+    // .mcp.json exists but has no mcpServers — not an error, just nothing to inject.
+    return
+  }
+
+  // pluginPart is loop-invariant — hoist outside the per-server loop.
+  const pluginPart = splitPluginId(plugin.id).plugin
+
+  for (const [serverName, serverDef] of Object.entries(servers)) {
+    if (typeof serverDef !== "object" || serverDef === null || Array.isArray(serverDef)) {
+      logger.warn(
+        `MCP server "${serverName}" in plugin "${plugin.id}" is not a valid object; skipping`,
+      )
+      continue
+    }
+
+    const mapped = mapClaudeMcpServer(serverDef as ClaudeMcpServer, plugin.installPath)
+    if (mapped === null) {
+      logger.warn(
+        `MCP server "${serverName}" in plugin "${plugin.id}" is missing required fields (url for http, command for local); skipping`,
+      )
+      continue
+    }
+
+    // Base name is always "<plugin>-<server>" per §6.4 — the plugin prefix is intentional
+    // (every bridge-injected MCP name starts with the plugin name). On collision the
+    // NameAllocator ladder escalates from this already-prefixed base, so a double-prefix
+    // on collision (e.g. "<plugin>-<plugin>-<server>") is correct, not a bug.
+    // pluginPart is hoisted outside the loop (splitPluginId is loop-invariant).
+    const baseName = `${pluginPart}-${serverName}`
+    const { name, renamed } = allocator.claim(plugin.id, baseName)
+
+    mcpCfg[name] = mapped
+    summary.servers++
+    if (renamed) summary.renamed++
+  }
+}
+
+// ── Public API ────────────────────────────────────────────────────────────────
+
+/** Summary counters for MCP injection collected across all plugins. */
+export interface McpInjectionSummary {
+  servers: number
+  renamed: number
+  skippedPolicy: number
+}
+
+/**
+ * Count MCP servers in a plugin's `.mcp.json` without any validation or warnings.
+ * Used only for the policy-gate summary when `allowMcp` is off — a user who opted out
+ * should not see per-entry warnings from plugins they never enabled.
+ * Returns 0 if the file is absent, unreadable, or malformed.
+ */
+async function countMcpServersQuiet(installPath: string): Promise<number> {
+  const mcpPath = path.join(installPath, ".mcp.json")
+  try {
+    const raw = await fs.readFile(mcpPath, "utf8")
+    const parsed = JSON.parse(raw) as unknown
+    if (typeof parsed === "object" && parsed !== null && "mcpServers" in parsed) {
+      const servers = (parsed as { mcpServers?: unknown }).mcpServers
+      if (typeof servers === "object" && servers !== null && !Array.isArray(servers)) {
+        return Object.keys(servers).length
+      }
+    }
+    return 0
+  } catch {
+    return 0
+  }
+}
+
+/**
+ * Inject MCP servers from all `plugins` into the mutable `cfg`.
+ *
+ * When `allowMcp` is false, logs a policy summary and injects nothing.
+ * Builds one `NameAllocator` seeded with existing `cfg.mcp` keys.
+ * Processes plugins in the order given (caller passes sorted-by-id order).
+ */
+export async function injectMcp(
+  plugins: ClaudePlugin[],
+  cfg: Config,
+  allowMcp: boolean,
+  logger: Logger,
+): Promise<McpInjectionSummary> {
+  const summary: McpInjectionSummary = { servers: 0, renamed: 0, skippedPolicy: 0 }
+
+  if (!allowMcp) {
+    // Policy gate: count potential servers without per-entry validation — a user who
+    // opted out of MCP should not see MCP-config warnings from plugins they never enabled.
+    let totalServers = 0
+    for (const plugin of plugins) {
+      totalServers += await countMcpServersQuiet(plugin.installPath)
+    }
+    summary.skippedPolicy = totalServers
+    if (totalServers > 0) {
+      logger.info(`skipped ${totalServers} MCP server(s) (policy: allowMcp is off)`)
+    }
+    return summary
+  }
+
+  if (plugins.length === 0) return summary
+
+  const mutableCfg = cfg as unknown as InjectableMcpConfig
+  const mcpCfg = guardMcpConfig(mutableCfg)
+
+  // Seed the allocator with existing cfg.mcp keys.
+  const existingMcp = new Set<string>(Object.keys(mcpCfg))
+  const allocator = new NameAllocator(existingMcp)
+
+  for (const plugin of plugins) {
+    await injectPluginMcp(plugin, mcpCfg, allocator, summary, logger)
+  }
+
+  return summary
+}

package/src/naming.ts

@@ -0,0 +1,122 @@
+import { createHash } from "node:crypto"
+
+/**
+ * The result of a name-claim operation.
+ *
+ * @property name - The final allocated name (may be prefixed if the bare name collided).
+ * @property renamed - `true` when the bare name was not available and a prefix was applied.
+ */
+export interface ClaimResult {
+  readonly name: string
+  readonly renamed: boolean
+}
+
+/**
+ * A family-agnostic name allocator that enforces the §7 no-shadowing invariant.
+ *
+ * Seed it with the set of already-existing names (native config items + built-ins + any
+ * names already registered by earlier allocator instances), then call `claim` for each
+ * component in the id-sorted plugin order that `selectEnabledPlugins` produces. The
+ * allocator accumulates claimed names so that later claims in the same run see all prior
+ * allocations — giving deterministic first-wins-by-id semantics across plugins.
+ *
+ * The rename ladder (§7), tried in order until a free slot is found:
+ *   1. `bareName`
+ *   2. `<plugin>-<bareName>`
+ *   3. `<marketplace>-<plugin>-<bareName>`
+ *   4. `<marketplace>-<plugin>-<bareName>-<shortHash>` (deterministic tiebreak)
+ *
+ * `<plugin>` and `<marketplace>` are derived by splitting the plugin id `name@marketplace`.
+ * The short hash is the first 8 hex characters of a SHA-256 over
+ * `${marketplace}/${plugin}/${bareName}`, so it is deterministic across runs for the same
+ * triple — a collision at rung 3 always resolves to the same name.
+ *
+ * Native/existing items are never renamed — only the bridge's claimant is prefixed.
+ */
+export class NameAllocator {
+  /** All names currently considered taken (native + previously claimed). */
+  private readonly taken: Set<string>
+
+  /**
+   * @param existing - Names already in use (native config keys + built-in lists).
+   *   A snapshot is taken; mutations to the passed set after construction are ignored.
+   */
+  constructor(existing: ReadonlySet<string> | Iterable<string>) {
+    this.taken = new Set(existing)
+  }
+
+  /**
+   * Attempt to allocate `bareName` on behalf of `pluginId`.
+   *
+   * `pluginId` must be in `name@marketplace` format. If the bare name is already taken,
+   * the rename ladder is walked until a free slot is found (the hash rung is the final
+   * fallback and always produces a unique name). The winning name is recorded as taken so
+   * subsequent claims see it.
+   */
+  claim(pluginId: string, bareName: string): ClaimResult {
+    const { plugin, marketplace } = splitPluginId(pluginId)
+
+    // Rung 1: bare name
+    if (!this.taken.has(bareName)) {
+      this.taken.add(bareName)
+      return { name: bareName, renamed: false }
+    }
+
+    // Rung 2: <plugin>-<bareName>
+    const rung2 = `${plugin}-${bareName}`
+    if (!this.taken.has(rung2)) {
+      this.taken.add(rung2)
+      return { name: rung2, renamed: true }
+    }
+
+    // Rung 3: <marketplace>-<plugin>-<bareName>
+    const rung3 = `${marketplace}-${plugin}-${bareName}`
+    if (!this.taken.has(rung3)) {
+      this.taken.add(rung3)
+      return { name: rung3, renamed: true }
+    }
+
+    // Rung 4: <marketplace>-<plugin>-<bareName>-<shortHash> (deterministic final tiebreak)
+    const hash = shortHash(marketplace, plugin, bareName)
+    const rung4 = `${marketplace}-${plugin}-${bareName}-${hash}`
+    this.taken.add(rung4)
+    return { name: rung4, renamed: true }
+  }
+
+  /**
+   * Return a snapshot of all currently-taken names, including everything registered
+   * by prior `claim` calls. Useful for seeding a child allocator or for inspection.
+   */
+  snapshot(): ReadonlySet<string> {
+    return new Set(this.taken)
+  }
+}
+
+/**
+ * Split a plugin id of the form `name@marketplace` into its two parts.
+ *
+ * If the id is malformed (no `@`), the whole string is used as the plugin part
+ * and marketplace defaults to `"unknown"` — matching how the bridge logs unknown
+ * marketplace entries rather than hard-failing.
+ */
+export function splitPluginId(pluginId: string): { plugin: string; marketplace: string } {
+  const at = pluginId.indexOf("@")
+  if (at === -1) return { plugin: pluginId, marketplace: "unknown" }
+  return {
+    plugin: pluginId.slice(0, at),
+    marketplace: pluginId.slice(at + 1),
+  }
+}
+
+/**
+ * Compute the 8-hex-character short hash used in rung-4 tiebreak names.
+ *
+ * Deterministic: for the same `(marketplace, plugin, bareName)` triple this always
+ * returns the same string, across runs and machines. Uses SHA-256 from `node:crypto`.
+ */
+export function shortHash(marketplace: string, plugin: string, bareName: string): string {
+  return createHash("sha256")
+    .update(`${marketplace}/${plugin}/${bareName}`)
+    .digest("hex")
+    .slice(0, 8)
+}

package/src/opencode-builtins.ts

@@ -0,0 +1,98 @@
+/**
+ * Version-pinned OpenCode built-in name lists and skill-discovery constants.
+ *
+ * The runtime OpenCode version verified by the spec is **1.15.10**; the source
+ * checkout on this machine is **1.15.13**. The constants were re-confirmed
+ * unchanged against the 1.15.13 source — the cited line numbers and values are
+ * identical in both versions. The pin below records the runtime version (what
+ * users run and what the spec validated against); re-validate on the next upgrade.
+ *
+ * MUST be re-validated on every OpenCode upgrade — these are part of what the
+ * §9 compatibility check guards.
+ *
+ * Source locations (all in `packages/opencode/src/`):
+ *   - Built-in agents:   `agent/agent.ts:127-248`
+ *   - Built-in commands: `command/index.ts:53-110` (`Default.INIT`, `Default.REVIEW`)
+ *   - Built-in skills:   `skill/index.ts:33`
+ *   - Skill scan dirs:   `skill/index.ts:22-26, 173-233`
+ */
+
+// The single source of truth for the verified OpenCode version is VERIFIED_OPENCODE_VERSION
+// in src/version.ts. Re-export it here so callers in this module don't need a cross-module
+// import, and so the value is never duplicated.
+export { VERIFIED_OPENCODE_VERSION as PINNED_OPENCODE_VERSION } from "./version.js"
+
+// ── Built-in agents ─────────────────────────────────────────────────────────
+//
+// Registered as hard-coded entries in the `agents` object before `cfg.agent`
+// is merged in (`agent/agent.ts:127-248`). They are NOT present in `cfg.agent`
+// at hook time, so the bridge must treat them as already-taken names.
+
+/** Built-in OpenCode agent names (not present in cfg at hook time). */
+export const BUILTIN_AGENT_NAMES: ReadonlySet<string> = new Set([
+  "build",       // agent/agent.ts:128
+  "plan",        // agent/agent.ts:143
+  "general",     // agent/agent.ts:166
+  "explore",     // agent/agent.ts:180
+  "compaction",  // agent/agent.ts:203 (hidden/internal)
+  "title",       // agent/agent.ts:218 (hidden/internal)
+  "summary",     // agent/agent.ts:234 (hidden/internal)
+])
+
+// ── Built-in commands ────────────────────────────────────────────────────────
+//
+// Registered before `cfg.command` entries are merged in (`command/index.ts:53-110`).
+// `Default.INIT = "init"`, `Default.REVIEW = "review"`.
+
+/** Built-in OpenCode command names (not present in cfg at hook time). */
+export const BUILTIN_COMMAND_NAMES: ReadonlySet<string> = new Set([
+  "init",    // command/index.ts:53-55, 77-85
+  "review",  // command/index.ts:53-55, 86-95
+])
+
+// ── Built-in skills ──────────────────────────────────────────────────────────
+//
+// The only built-in skill is defined at `skill/index.ts:33`.
+// Unlike agents/commands, a file-based skill of the same name *overrides* the
+// built-in (not the other way around), but the bridge still avoids shadowing it.
+
+/** Built-in OpenCode skill names (not present in cfg.skills.paths at hook time). */
+export const BUILTIN_SKILL_NAMES: ReadonlySet<string> = new Set([
+  "customize-opencode",  // skill/index.ts:33
+])
+
+// ── Skill-discovery dir specs ────────────────────────────────────────────────
+//
+// OpenCode discovers SKILL.md files from two families of roots:
+//
+//   1. External roots (`.claude` + `.agents`): global home dirs + project-upward walk
+//      Pattern: `skills/**/SKILL.md`   (`skill/index.ts:24`)
+//   2. OpenCode config dirs:             global XDG config + project-upward `.opencode`
+//      Pattern: `{skill,skills}/**/SKILL.md` (`skill/index.ts:25`)
+//   3. `cfg.skills.paths` entries:       explicit user-specified paths
+//      Pattern: `**/SKILL.md`           (`skill/index.ts:26, 219`)
+//
+// The `.agents` root is for skills only — `.opencode/agents` is NOT a skill dir.
+// Source: `skill/index.ts:22-26, 173-233`
+
+/** Glob pattern used under `.claude` and `.agents` external roots. */
+export const EXTERNAL_SKILL_GLOB = "skills/**/SKILL.md"
+
+/** Glob pattern used under OpenCode config dirs (`.opencode`, `~/.config/opencode`). */
+export const OPENCODE_SKILL_GLOB = "{skill,skills}/**/SKILL.md"
+
+/** Glob pattern used under explicit `cfg.skills.paths` entries. */
+export const PATHS_SKILL_GLOB = "**/SKILL.md"
+
+/**
+ * External root dir names walked from `$HOME` and project-upward.
+ * Source: `skill/index.ts:22-24, 185-201`
+ */
+export const EXTERNAL_SKILL_ROOTS = [".claude", ".agents"] as const
+
+/**
+ * OpenCode config dir name walked project-upward (and from `$HOME`).
+ * Also used as part of the global XDG config path (`~/.config/opencode`).
+ * Source: `skill/index.ts:205-207`, `config/paths.ts:23-41`
+ */
+export const OPENCODE_CONFIG_DIR_NAME = ".opencode"