fix(opencode): normalize command names before dedup to prevent cross-form collisions

Deduplication was comparing raw name strings, so an explicit command
'foo:bar' would not block a skill stub named 'foo/bar' — both resolve
to commands/foo/bar.md on disk, causing the stub to silently overwrite
the explicit command.

Fix: extract commandNameToRelativePath() into src/utils/files.ts and
use it in both the converter's dedup set and the writer's path
resolution, so the same normalized key is used everywhere.

Addresses second review comment on PR #776.

Author: lucabattistini

src/converters/claude-to-opencode.ts

@@ -1,5 +1,6 @@
 import { formatFrontmatter } from "../utils/frontmatter"
 import { normalizeModelWithProvider } from "../utils/model"
+import { commandNameToRelativePath } from "../utils/files"
 import {
   type ClaudeAgent,
   type ClaudeCommand,
@@ -90,10 +91,13 @@ export function convertClaudeToOpenCode(
   const openCodeSkills = filterSkillsByPlatform(plugin.skills, "opencode")
   // Commands from the plugin's commands/ directory take priority; skill stubs
   // are only appended for names that don't already have an explicit command.
+  // Dedup uses the normalized path key (colons → slashes) to match the writer's
+  // on-disk layout — "foo:bar" and a skill named "foo/bar" both resolve to
+  // commands/foo/bar.md, so they must be treated as the same command here.
   const explicitCommands = convertCommands(plugin.commands)
-  const explicitCommandNames = new Set(explicitCommands.map((c) => c.name))
+  const explicitCommandPaths = new Set(explicitCommands.map((c) => commandNameToRelativePath(c.name)))
   const skillStubs = convertSkillsToCommands(openCodeSkills).filter(
-    (stub) => !explicitCommandNames.has(stub.name),
+    (stub) => !explicitCommandPaths.has(commandNameToRelativePath(stub.name)),
   )
   const cmdFiles = [...explicitCommands, ...skillStubs]
   const mcp = plugin.mcpServers ? convertMcp(plugin.mcpServers) : undefined

src/targets/opencode.ts

@@ -1,5 +1,5 @@
 import path from "path"
-import { backupFile, copySkillDir, ensureDir, pathExists, readJson, sanitizePathName, writeJson, writeText } from "../utils/files"
+import { backupFile, commandNameToRelativePath, copySkillDir, ensureDir, pathExists, readJson, sanitizePathName, writeJson, writeText } from "../utils/files"
 import { transformSkillContentForOpenCode } from "../converters/claude-to-opencode"
 import type { OpenCodeBundle, OpenCodeConfig } from "../types/opencode"
 import { getLegacyOpenCodeArtifacts } from "../data/plugin-legacy-artifacts"
@@ -70,7 +70,7 @@ export async function writeOpenCodeBundle(
     ? await readManagedInstallManifestWithLegacyFallback(openCodePaths.managedDir, pluginName)
     : null
   const currentAgents = bundle.agents.map((agent) => `${sanitizePathName(agent.name)}.md`)
-  const currentCommands = bundle.commandFiles.map((commandFile) => `${commandFile.name.split(":").join("/")}.md`)
+  const currentCommands = bundle.commandFiles.map((commandFile) => `${commandNameToRelativePath(commandFile.name)}.md`)
   const currentPlugins = bundle.plugins.map((plugin) => plugin.name)
   const currentSkills = bundle.skillDirs.map((skill) => sanitizePathName(skill.name))
 
@@ -103,7 +103,7 @@ export async function writeOpenCodeBundle(
   }
 
   for (const commandFile of bundle.commandFiles) {
-    const dest = path.join(openCodePaths.commandDir, ...commandFile.name.split(":")) + ".md"
+    const dest = path.join(openCodePaths.commandDir, ...commandNameToRelativePath(commandFile.name).split("/")) + ".md"
     const cmdBackupPath = await backupFile(dest)
     if (cmdBackupPath) {
       console.log(`Backed up existing command file to ${cmdBackupPath}`)

src/utils/files.ts

@@ -122,6 +122,17 @@ export function isSafeManagedPath(rootDir: string, candidate: unknown): candidat
   return true
 }
 
+/**
+ * Normalizes a command name to the relative path key used by the OpenCode writer,
+ * without touching the filesystem. Colons become path separators, matching the
+ * `name.split(":")` logic in `writeOpenCodeBundle`.
+ *
+ * Example: `"foo:bar"` → `"foo/bar"`
+ */
+export function commandNameToRelativePath(name: string): string {
+  return name.split(":").join("/")
+}
+
 /**
  * Resolve a colon-separated command name into a filesystem path.
  * e.g. resolveCommandPath("/commands", "ce:plan", ".md") -> "/commands/ce/plan.md"

tests/converter.test.ts

@@ -76,6 +76,39 @@ describe("convertClaudeToOpenCode", () => {
     expect(names.length).toBe(uniqueNames.size)
   })
 
+  test("explicit command foo:bar blocks skill stub foo/bar from being emitted", async () => {
+    // "foo:bar" (explicit command) and "foo/bar" (skill name) both normalize to
+    // the same on-disk path commands/foo/bar.md — the skill stub must be dropped.
+    const plugin: ClaudePlugin = {
+      manifest: { name: "test-plugin", version: "1.0.0", description: "" },
+      agents: [],
+      commands: [{ name: "foo:bar", description: "explicit", body: "explicit body" }],
+      skills: [
+        {
+          name: "foo/bar",
+          description: "skill",
+          sourceDir: "/tmp/fake-skill",
+          platforms: [],
+        },
+      ],
+      mcpServers: undefined,
+      hooks: undefined,
+    }
+    const bundle = convertClaudeToOpenCode(plugin, {
+      agentMode: "subagent",
+      inferTemperature: false,
+      permissions: "none",
+    })
+
+    const fooBarCommands = bundle.commandFiles.filter((f) =>
+      f.name === "foo:bar" || f.name === "foo/bar",
+    )
+    // Only the explicit command should survive
+    expect(fooBarCommands).toHaveLength(1)
+    expect(fooBarCommands[0].name).toBe("foo:bar")
+    expect(fooBarCommands[0].content).toContain("explicit body")
+  })
+
   test("from-command mode: map allowedTools to global permission block", async () => {
     const plugin = await loadClaudePlugin(fixtureRoot)
     const bundle = convertClaudeToOpenCode(plugin, {