@koriit/opencode-claude-bridge 0.1.11 → 0.1.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@koriit/opencode-claude-bridge",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "description": "An OpenCode plugin that bridges enabled Claude Code plugins (commands, agents, skills, MCP, LSP) into OpenCode at runtime, namespaced so they never shadow your existing items.",
   "type": "module",
   "license": "MIT",

package/src/index.ts

@@ -68,6 +68,7 @@ export const server: Plugin = async (_input, options) => {
 
         // §6.1 commands, §6.2 agents — inline injection into the shared cfg.
         const cmdAgentSummary = await injectCommandsAndAgents(selected, cfg, logger)
+        const { commandAllocator } = cmdAgentSummary
 
         // §6.3 skills — cfg.skills.paths injection (with bridge-cache copy on collision).
         const home = os.homedir()
@@ -85,6 +86,7 @@ export const server: Plugin = async (_input, options) => {
           home,
           projectDir: _input.directory,
           cacheRoot: process.env["OPENCODE_CLAUDE_BRIDGE_CACHE_ROOT"],
+          commandAllocator,
         }, logger)
 
         // §6.4 MCP — cfg.mcp injection (opt-in via allowMcp).
@@ -96,7 +98,7 @@ export const server: Plugin = async (_input, options) => {
         // §10 concise per-run summary.
         const renamed = cmdAgentSummary.renamed + skillSummary.renamed + mcpSummary.renamed + lspSummary.renamed
         const summaryParts: string[] = [
-          `injected ${cmdAgentSummary.commands} command(s), ${cmdAgentSummary.agents} agent(s), ${skillSummary.skills} skill(s), ${mcpSummary.servers} MCP server(s), ${lspSummary.servers} LSP server(s)`,
+          `injected ${cmdAgentSummary.commands + skillSummary.commandsAdded} command(s), ${cmdAgentSummary.agents} agent(s), ${skillSummary.skills} skill(s), ${mcpSummary.servers} MCP server(s), ${lspSummary.servers} LSP server(s)`,
         ]
         if (renamed > 0) summaryParts.push(`renamed ${renamed} (collision)`)
         if (mcpSummary.skippedPolicy > 0) summaryParts.push(`skipped ${mcpSummary.skippedPolicy} MCP (policy)`)

package/src/inject.ts

@@ -80,6 +80,11 @@ export interface InjectionSummary {
   renamed: number
 }
 
+/** Full result of {@link injectCommandsAndAgents}, including the populated command allocator. */
+export interface InjectionResult extends InjectionSummary {
+  commandAllocator: NameAllocator
+}
+
 // ── File collection helpers ────────────────────────────────────────────────────
 
 /**
@@ -405,6 +410,41 @@ export function sanitizeAgentColor(value: string): string | null {
   return null
 }
 
+// ── Single-entry command injection ───────────────────────────────────────────
+
+/**
+ * Insert one command entry into `cfg.command` using the allocator, appending `[pluginId]`
+ * to the description. Returns the allocated name and whether it was renamed.
+ *
+ * The `entry.template` must already be fully resolved by the caller (e.g. via
+ * `resolvePluginRoot` for commands from the plugin's commands/ dir, or verbatim for
+ * skill-derived commands whose body does not use `${CLAUDE_PLUGIN_ROOT}`).
+ */
+export function injectCommandEntry(
+  bareName: string,
+  entry: CommandEntry,
+  cfg: InjectableConfig,
+  allocator: NameAllocator,
+  pluginId: string,
+  logger: Logger,
+): { allocatedName: string; renamed: boolean } {
+  if (cfg.command === undefined || cfg.command === null || typeof cfg.command !== "object") {
+    cfg.command = {}
+  }
+
+  const { name: allocatedName, renamed } = allocator.claim(pluginId, bareName)
+
+  const rawDescription = entry.description
+  const tracedDescription = rawDescription
+    ? `${rawDescription} [${pluginId}]`
+    : `${bareName} [${pluginId}]`
+
+  warnUnsupportedPlaceholders(entry.template, allocatedName, pluginId, logger)
+
+  cfg.command[allocatedName] = { ...entry, description: tracedDescription }
+  return { allocatedName, renamed }
+}
+
 // ── Command injection for one plugin ─────────────────────────────────────────
 
 /**
@@ -666,11 +706,8 @@ export async function injectCommandsAndAgents(
   plugins: ClaudePlugin[],
   cfg: Config,
   logger: Logger,
-): Promise<InjectionSummary> {
+): Promise<InjectionResult> {
   const mutableCfg = cfg as unknown as InjectableConfig
-  const summary: InjectionSummary = { commands: 0, agents: 0, renamed: 0 }
-
-  if (plugins.length === 0) return summary
 
   // Seed the command allocator with existing cfg keys ∪ built-in command names.
   const existingCommands = new Set<string>([
@@ -679,6 +716,10 @@ export async function injectCommandsAndAgents(
   ])
   const commandAlloc = new NameAllocator(existingCommands)
 
+  const summary: InjectionSummary = { commands: 0, agents: 0, renamed: 0 }
+
+  if (plugins.length === 0) return { ...summary, commandAllocator: commandAlloc }
+
   // Seed the agent allocator with existing cfg keys ∪ built-in agent names.
   const existingAgents = new Set<string>([
     ...BUILTIN_AGENT_NAMES,
@@ -691,5 +732,5 @@ export async function injectCommandsAndAgents(
     await injectPluginAgents(plugin, mutableCfg, agentAlloc, summary, logger)
   }
 
-  return summary
+  return { ...summary, commandAllocator: commandAlloc }
 }

package/src/logger.ts

@@ -24,48 +24,28 @@ export interface Logger {
   hadWarnings(): boolean
 }
 
-/**
- * Minimal duck-type for the OpenCode core logger service we resolve at runtime.
- * `@opencode-ai/core` is private/unpublished; we access it via dynamic import
- * against the Bun module registry that the host worker already populated.
- */
-interface CoreLog {
-  create(tags?: Record<string, unknown>): {
-    info(msg: string): void
-    warn(msg: string): void
-  }
-}
-
 /**
  * Resolve the core log module at runtime by hitting Bun's module registry.
- * The Bun Worker that hosts plugins already executed
- *   `import * as Log from "@opencode-ai/core/util/log"`
- * and called `Log.init({ print: ... })`, so the registry holds a fully
- * configured instance. A dynamic import of the same specifier returns it.
  *
- * Falls back to a plain stderr writer if the import fails (tests, non-OpenCode
- * environments) — in that case output is always emitted so tests can capture it.
+ * @opencode-ai/core is private and not on npm, but the host Bun Worker already
+ * executed `import * as Log from "@opencode-ai/core/util/log"` and called
+ * `Log.init({ print: ... })`. A dynamic import of the same specifier returns
+ * the cached, fully-configured instance — so output correctly goes to stderr
+ * (with --print-logs) or the log file (default), with no argv check needed.
+ *
+ * Falls back to direct stderr writes when the import fails (tests, or if the
+ * module path changes in a future OpenCode version).
  */
-async function resolveCoreLog(): Promise<CoreLog | null> {
+async function resolveCoreLog() {
   try {
-    // @opencode-ai/core is a private package bundled into the OpenCode binary.
-    // The dynamic import resolves against Bun's module registry at runtime —
-    // the host worker already loaded and initialized it.
-    // eslint-disable-next-line @typescript-eslint/ban-ts-comment
-    // @ts-ignore — not in node_modules; resolved from the Bun bundle at runtime
-    return await import("@opencode-ai/core/util/log") as CoreLog
+    return await import("@opencode-ai/core/util/log")
   } catch {
     return null
   }
 }
 
-// Kick off resolution immediately so it's ready before the first log call.
 const coreLogPromise = resolveCoreLog()
 
-/**
- * Fallback writer used when the core log module is unavailable.
- * Always writes to stderr — correct for test environments.
- */
 function fallbackWrite(level: "INFO" | "WARN", msg: string): void {
   const ts = new Date().toISOString().split(".")[0]
   process.stderr.write(`${level.padEnd(5)} ${ts} service=opencode-claude-bridge ${msg}\n`)

package/src/opencode-core.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Type declarations for @opencode-ai/core — a private package bundled into the
+ * OpenCode binary and not published to npm. Only the subset the bridge actually
+ * uses is declared here; the full API is larger.
+ *
+ * Resolved at runtime via dynamic import against Bun's module registry, which
+ * already holds the host worker's pre-initialized instance.
+ */
+declare module "@opencode-ai/core/util/log" {
+  export interface Logger {
+    debug(message?: unknown, extra?: Record<string, unknown>): void
+    info(message?: unknown, extra?: Record<string, unknown>): void
+    warn(message?: unknown, extra?: Record<string, unknown>): void
+    error(message?: unknown, extra?: Record<string, unknown>): void
+  }
+
+  export function create(tags?: Record<string, unknown>): Logger
+}

package/src/skill-inject.ts

@@ -29,6 +29,8 @@ import path from "node:path"
 import type { Config } from "@opencode-ai/plugin"
 import { extractSkillName } from "./skill-scan.js"
 import { NameAllocator, splitPluginId } from "./naming.js"
+import { parseFrontmatter, FRONTMATTER_PARSE_ERROR } from "./frontmatter.js"
+import { injectCommandEntry } from "./inject.js"
 import type { Logger } from "./logger.js"
 import type { ClaudePlugin } from "./types.js"
 
@@ -55,6 +57,7 @@ interface NormalizedSkillsConfig {
 
 interface InjectableConfig {
   skills?: SkillsConfig | boolean | undefined
+  command?: Record<string, unknown> | undefined
 }
 
 /**
@@ -317,14 +320,20 @@ export function patchSkillName(content: string, newName: string): string {
 
 /**
  * Scan `<installPath>/skills/` for skill subdirectories and inject each one into
- * `cfg.skills.paths`, performing a cache copy + frontmatter patch on collision.
+ * `cfg.skills.paths` and/or `cfg.command` based on the skill's frontmatter flags.
  *
- * @returns the number of skills injected and collisions renamed.
+ * Routing table (from `user-invocable` and `disable-model-invocation` frontmatter):
+ *   - neither flag      → inject as skill AND command
+ *   - user-invocable: false → inject as skill only (no command)
+ *   - disable-model-invocation: true → inject as command only (no skill)
+ *   - both flags set    → skip entirely with a WARN
  */
 async function injectPluginSkills(
   plugin: ClaudePlugin,
   skillsCfg: NormalizedSkillsConfig,
-  allocator: NameAllocator,
+  mutableCfg: InjectableConfig,
+  skillAllocator: NameAllocator,
+  commandAllocator: NameAllocator,
   cacheRoot: string,
   summary: SkillInjectionSummary,
   logger: Logger,
@@ -363,36 +372,81 @@ async function injectPluginSkills(
       )
     }
 
-    const { name: allocatedName, renamed } = allocator.claim(plugin.id, bareName)
-
-    if (!renamed) {
-      // No collision — point OpenCode directly at the plugin's skill dir.
-      skillsCfg.paths.push(skillDir)
-      summary.skills++
-    } else {
-      // Collision — copy the skill dir into the bridge cache and patch the name.
-      const cachedSkillDir = cacheDirForSkill(cacheRoot, plugin, allocatedName)
-      const cachedSkillMd = path.join(cachedSkillDir, "SKILL.md")
-
-      const stale = await isCacheStale(skillMdPath, cachedSkillMd)
-      if (stale) {
-        try {
-          await copyDirRecursive(skillDir, cachedSkillDir, logger)
-          // Patch using the content already in memory (read above for extractSkillName)
-          // rather than re-reading the just-copied file — same bytes, avoids a round-trip.
-          const patched = patchSkillName(content, allocatedName)
-          await fs.writeFile(cachedSkillMd, patched, "utf8")
-        } catch (err) {
-          logger.warn(
-            `failed to create bridge-cache copy for skill "${bareName}" from plugin "${plugin.id}" (${err instanceof Error ? err.message : String(err)}); skipping`,
-          )
-          continue
+    // Parse additional frontmatter flags that control injection routing.
+    const parsed = parseFrontmatter(content)
+    let userInvocable = true
+    let disableModelInvocation = false
+    let description: string | undefined
+    let body = ""
+
+    if (parsed !== null && parsed !== FRONTMATTER_PARSE_ERROR) {
+      const fm = parsed.data
+      if (fm["user-invocable"] === false) userInvocable = false
+      if (fm["disable-model-invocation"] === true) disableModelInvocation = true
+      if (typeof fm["description"] === "string") description = fm["description"]
+      body = parsed.body
+    }
+
+    const asSkill = !disableModelInvocation
+    const asCommand = userInvocable
+
+    if (!asSkill && !asCommand) {
+      logger.warn(
+        `skill "${bareName}" from plugin "${plugin.id}" has both "disable-model-invocation: true" and "user-invocable: false"; skipping`,
+        { fatalInStrict: false },
+      )
+      continue
+    }
+
+    if (asSkill) {
+      const { name: allocatedName, renamed } = skillAllocator.claim(plugin.id, bareName)
+
+      if (!renamed) {
+        // No collision — point OpenCode directly at the plugin's skill dir.
+        skillsCfg.paths.push(skillDir)
+        summary.skills++
+      } else {
+        // Collision — copy the skill dir into the bridge cache and patch the name.
+        const cachedSkillDir = cacheDirForSkill(cacheRoot, plugin, allocatedName)
+        const cachedSkillMd = path.join(cachedSkillDir, "SKILL.md")
+
+        const stale = await isCacheStale(skillMdPath, cachedSkillMd)
+        if (stale) {
+          try {
+            await copyDirRecursive(skillDir, cachedSkillDir, logger)
+            // Patch using the content already in memory (read above for extractSkillName)
+            // rather than re-reading the just-copied file — same bytes, avoids a round-trip.
+            const patched = patchSkillName(content, allocatedName)
+            await fs.writeFile(cachedSkillMd, patched, "utf8")
+          } catch (err) {
+            logger.warn(
+              `failed to create bridge-cache copy for skill "${bareName}" from plugin "${plugin.id}" (${err instanceof Error ? err.message : String(err)}); skipping`,
+            )
+            continue
+          }
         }
+
+        skillsCfg.paths.push(cachedSkillDir)
+        summary.skills++
+        summary.renamed++
       }
+    }
 
-      skillsCfg.paths.push(cachedSkillDir)
-      summary.skills++
-      summary.renamed++
+    if (asCommand) {
+      if (!body) continue
+      const fmData = (parsed !== null && parsed !== FRONTMATTER_PARSE_ERROR) ? parsed.data : {}
+      const modelRaw = fmData["model"]
+      const model = typeof modelRaw === "string" && modelRaw.includes("/") ? modelRaw : undefined
+      const { renamed } = injectCommandEntry(
+        bareName,
+        { template: body, description, model },
+        mutableCfg as unknown as { command?: Record<string, import("./inject.js").CommandEntry> },
+        commandAllocator,
+        plugin.id,
+        logger,
+      )
+      summary.commandsAdded++
+      if (renamed) summary.renamed++
     }
   }
 }
@@ -403,6 +457,7 @@ async function injectPluginSkills(
 export interface SkillInjectionSummary {
   skills: number
   renamed: number
+  commandsAdded: number
 }
 
 /**
@@ -424,6 +479,13 @@ export interface SkillInjectOptions {
    * to `~/.cache/opencode-claude-bridge/skills/`.
    */
   cacheRoot?: string
+  /**
+   * The fully-populated command name allocator from `injectCommandsAndAgents`.
+   * Required to participate in the same command namespace so skill-derived
+   * commands never collide with plugin commands or built-in commands.
+   * When omitted (e.g. in legacy callers), a fresh allocator is created.
+   */
+  commandAllocator?: NameAllocator
 }
 
 /**
@@ -451,7 +513,7 @@ export async function injectSkills(
   logger: Logger,
 ): Promise<SkillInjectionSummary> {
   const mutableCfg = cfg as unknown as InjectableConfig
-  const summary: SkillInjectionSummary = { skills: 0, renamed: 0 }
+  const summary: SkillInjectionSummary = { skills: 0, renamed: 0, commandsAdded: 0 }
 
   if (plugins.length === 0) return summary
 
@@ -469,13 +531,17 @@ export async function injectSkills(
   const cacheRoot =
     opts.cacheRoot ?? path.join(opts.home, ".cache", "opencode-claude-bridge", "skills")
 
-  // Seed the allocator with every name OpenCode already knows about (native + built-ins).
+  // Seed the skill allocator with every name OpenCode already knows about (native + built-ins).
   // `existingSkillNames` is provided by the caller (from `collectExistingSkillNames`) to
   // avoid calling the Skill service from the hook.
-  const allocator = new NameAllocator(existingSkillNames)
+  const skillAllocator = new NameAllocator(existingSkillNames)
+
+  // Use the caller-provided command allocator so skill-derived commands share the
+  // same namespace as plugin commands. Fall back to a fresh one if not provided.
+  const commandAllocator = opts.commandAllocator ?? new NameAllocator(new Set<string>())
 
   for (const plugin of plugins) {
-    await injectPluginSkills(plugin, skillsCfg, allocator, cacheRoot, summary, logger)
+    await injectPluginSkills(plugin, skillsCfg, mutableCfg, skillAllocator, commandAllocator, cacheRoot, summary, logger)
   }
 
   return summary