@wntic/ocm 0.1.0

package/src/loader.ts

@@ -0,0 +1,185 @@
+import { createHash } from "node:crypto"
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs"
+import { dirname, join } from "node:path"
+import { fileURLToPath } from "node:url"
+import { OCM_DIR, OCM_LEGACY_REGISTRY_FILE, OCM_LOADER_NAME, OPENCODE_GLOBAL_DIR, OPENCODE_PLUGINS_DIR } from "./paths"
+
+const TUI_CONFIG_FILE = join(OPENCODE_GLOBAL_DIR, "tui.json")
+const TUI_PLUGIN_ENTRY = "./ocm/ui.js"
+const LEGACY_TUI_PLUGIN_ENTRY = "./plugins/ocm-ui.js"
+const LEGACY_PLUGIN_FILES = ["ocm-core.js", "ocm-ui.js", "ocm-core.d.ts"]
+
+// only a subset proves a candidate is the loader source dir; the full install
+// list is derived from the directory itself (spec 01, Installation set)
+const REQUIRED_LOADER_FILES = [OCM_LOADER_NAME, "core.js", "ui.js"]
+
+function loaderSourceDir(): string {
+  const here = dirname(fileURLToPath(import.meta.url))
+  const candidates = [
+    join(here, "..", "..", "loader"),
+    join(here, "..", "loader"),
+    join(here, "loader"),
+    here,
+  ]
+  for (const candidate of candidates) {
+    if (REQUIRED_LOADER_FILES.every((name) => existsSync(join(candidate, name)))) return candidate
+  }
+  throw new Error(`loader files not found (${REQUIRED_LOADER_FILES.join(", ")})`)
+}
+
+// the installed set is the loader directory by definition: ocm-loader.js to
+// plugins/, every other *.js / *.d.ts to ocm/; the filter keeps editor junk
+// (e.g. .DS_Store) out of the install
+function loaderFiles(sourceDir: string): { source: string; target: string }[] {
+  return readdirSync(sourceDir)
+    .filter((name) => /\.(js|d\.ts)$/.test(name))
+    .sort()
+    .map((name) => ({
+      source: name,
+      target: join(name === OCM_LOADER_NAME ? OPENCODE_PLUGINS_DIR : OCM_DIR, name),
+    }))
+}
+
+function packageVersion(): string {
+  const here = dirname(fileURLToPath(import.meta.url))
+  const parsed = JSON.parse(readFileSync(join(here, "..", "package.json"), "utf8")) as { version?: unknown }
+  return typeof parsed.version === "string" ? parsed.version : "0"
+}
+
+function stamped(source: string): string {
+  const content = readFileSync(source, "utf8")
+  const hash = createHash("sha256").update(content).digest("hex").slice(0, 8)
+  return `${content.trimEnd()}\n// ocm-version: ${packageVersion()} ${hash}\n`
+}
+
+function readTuiConfig(): Record<string, unknown> | undefined {
+  if (!existsSync(TUI_CONFIG_FILE)) return {}
+  try {
+    const parsed = JSON.parse(readFileSync(TUI_CONFIG_FILE, "utf8")) as unknown
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) return parsed as Record<string, unknown>
+  } catch {}
+  return undefined
+}
+
+function writeTuiConfig(config: Record<string, unknown>): void {
+  const tmp = `${TUI_CONFIG_FILE}.ocm-tmp`
+  writeFileSync(tmp, `${JSON.stringify(config, null, 2)}\n`)
+  renameSync(tmp, TUI_CONFIG_FILE)
+}
+
+function warnTuiManual(reason: string): void {
+  console.error(`warning: ${TUI_CONFIG_FILE} ${reason}, left untouched`)
+  console.error(`warning: add "${TUI_PLUGIN_ENTRY}" to its "plugin" array manually for the /ocm TUI command`)
+}
+
+function ensureTuiPluginEntry(): void {
+  const config = readTuiConfig()
+  if (!config) {
+    warnTuiManual("is not valid JSON or not a JSON object")
+    return
+  }
+  const plugin = config.plugin
+  if (plugin !== undefined && !Array.isArray(plugin)) {
+    warnTuiManual('has a "plugin" key that is not an array')
+    return
+  }
+  const entries = Array.isArray(plugin) ? plugin : []
+  if (entries.includes(TUI_PLUGIN_ENTRY)) return
+  config.plugin = [...entries, TUI_PLUGIN_ENTRY]
+  writeTuiConfig(config)
+}
+
+function removeTuiPluginEntry(): void {
+  const config = readTuiConfig()
+  if (!config) return
+  const plugin = config.plugin
+  if (!Array.isArray(plugin)) return
+  const filtered = plugin.filter((entry) => entry !== TUI_PLUGIN_ENTRY)
+  if (filtered.length === plugin.length) return
+  config.plugin = filtered
+  writeTuiConfig(config)
+}
+
+function rewriteLegacyTuiPluginEntry(): void {
+  const config = readTuiConfig()
+  if (!config) {
+    warnTuiManual("is not valid JSON or not a JSON object")
+    return
+  }
+  const plugin = config.plugin
+  if (!Array.isArray(plugin) || !plugin.includes(LEGACY_TUI_PLUGIN_ENTRY)) return
+  config.plugin = plugin.map((entry) => (entry === LEGACY_TUI_PLUGIN_ENTRY ? TUI_PLUGIN_ENTRY : entry))
+  writeTuiConfig(config)
+}
+
+function installFiles(sourceDir: string): void {
+  if (existsSync(OCM_DIR) && !statSync(OCM_DIR).isDirectory()) {
+    throw new Error(`${OCM_DIR} exists but is not a directory; remove it or move it aside, then re-run ocm init`)
+  }
+  mkdirSync(OPENCODE_PLUGINS_DIR, { recursive: true })
+  mkdirSync(OCM_DIR, { recursive: true })
+  for (const file of loaderFiles(sourceDir)) {
+    const content = stamped(join(sourceDir, file.source))
+    let current: string | undefined
+    try {
+      current = readFileSync(file.target, "utf8")
+    } catch {
+      current = undefined
+    }
+    if (current === content) continue
+    writeFileSync(file.target, content)
+  }
+  ensureTuiPluginEntry()
+}
+
+// spec 12 doctor: the installed state of every loader file, by version
+// comment — a stale core silently no-ops, so drift is worth naming
+export interface LoaderFileStatus {
+  file: string
+  state: "current" | "stale" | "missing"
+}
+
+export function loaderStatus(): LoaderFileStatus[] {
+  const sourceDir = loaderSourceDir()
+  return loaderFiles(sourceDir).map((file) => {
+    let state: LoaderFileStatus["state"]
+    try {
+      state = readFileSync(file.target, "utf8") === stamped(join(sourceDir, file.source)) ? "current" : "stale"
+    } catch {
+      state = "missing"
+    }
+    return { file: file.source, state }
+  })
+}
+
+export function migrateLegacyLayout(): void {
+  const triggered = ["ocm-core.js", "ocm-ui.js"].some((name) => existsSync(join(OPENCODE_PLUGINS_DIR, name)))
+  if (!triggered) return
+  mkdirSync(OCM_DIR, { recursive: true })
+  if (existsSync(OCM_LEGACY_REGISTRY_FILE)) {
+    renameSync(OCM_LEGACY_REGISTRY_FILE, join(OCM_DIR, "registry.json"))
+  }
+  for (const name of LEGACY_PLUGIN_FILES) {
+    rmSync(join(OPENCODE_PLUGINS_DIR, name), { force: true })
+  }
+  rewriteLegacyTuiPluginEntry()
+  installFiles(loaderSourceDir())
+  // spec 01 migration step 5 pins this line to stdout
+  console.log(`migrated ocm registry to ${join(OCM_DIR, "registry.json")}`)
+}
+
+export function installLoader(): void {
+  migrateLegacyLayout()
+  installFiles(loaderSourceDir())
+  console.error(`installed auto-sync loader (${join(OPENCODE_PLUGINS_DIR, OCM_LOADER_NAME)})`)
+  console.error(`installed TUI plugin (/ocm in the opencode TUI, restart opencode to activate)`)
+}
+
+export function uninstallLoader(): void {
+  for (const name of [OCM_LOADER_NAME, ...LEGACY_PLUGIN_FILES]) {
+    rmSync(join(OPENCODE_PLUGINS_DIR, name), { force: true })
+  }
+  rmSync(OCM_DIR, { recursive: true, force: true })
+  removeTuiPluginEntry()
+  console.log("removed auto-sync loader")
+}

package/src/manifest-lint.ts

@@ -0,0 +1,189 @@
+// Hand-rolled validator for marketplace.json / plugin.json / mcp.json,
+// implementing the same rules as schema/*-v1.json (spec 12: no runtime
+// dependency; the schema files exist for editors).
+import { existsSync, readFileSync } from "node:fs"
+import { join, relative } from "node:path"
+import { readRegistry } from "../loader/core.js"
+import { error, warning, type Finding } from "./findings"
+
+export const NAME_RE = /^[a-z0-9]+(-[a-z0-9]+)*$/
+
+const STRING_FIELDS = ["description", "version", "category", "homepage", "repository", "license"]
+const ARRAY_FIELDS = ["tags", "keywords"]
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+}
+
+// bun's JSON.parse errors carry line/column properties but no position in
+// the message itself
+function jsonPosition(err: unknown): string {
+  const { line, column } = err as { line?: unknown; column?: unknown }
+  return typeof line === "number" && typeof column === "number" ? `${line}:${column}` : "0"
+}
+
+function parseJson(file: string, rel: string, findings: Finding[]): Record<string, unknown> | undefined {
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(readFileSync(file, "utf8"))
+  } catch (err) {
+    findings.push(error(`${rel}: invalid JSON at position ${jsonPosition(err)}`))
+    return undefined
+  }
+  if (!isRecord(parsed)) {
+    findings.push(error(`${rel}: must be a JSON object`))
+    return undefined
+  }
+  return parsed
+}
+
+function lintFields(rel: string, record: Record<string, unknown>, findings: Finding[]): void {
+  for (const key of STRING_FIELDS) {
+    if (record[key] !== undefined && typeof record[key] !== "string") {
+      findings.push(error(`${rel}: "${key}" must be a string`))
+    }
+  }
+  for (const key of ARRAY_FIELDS) {
+    const value = record[key]
+    if (value !== undefined && (!Array.isArray(value) || !value.every((item) => typeof item === "string"))) {
+      findings.push(error(`${rel}: "${key}" must be an array of strings`))
+    }
+  }
+}
+
+function lintName(rel: string, name: string, pluginName: string | undefined, findings: Finding[]): void {
+  if (!NAME_RE.test(name)) {
+    findings.push(error(`${rel}: name "${name}" must match ${NAME_RE}`))
+  } else if (name.length > 64) {
+    findings.push(error(`${rel}: name "${name}" is longer than 64 characters`))
+  } else if (pluginName !== undefined && name !== pluginName) {
+    findings.push(error(`${rel}: name "${name}" disagrees with the directory name "${pluginName}"`))
+  }
+}
+
+function lintSource(rel: string, entry: Record<string, unknown>, root: string, findings: Finding[]): void {
+  const name = typeof entry.name === "string" ? entry.name : "(unnamed)"
+  const source = entry.source
+  if (typeof source !== "string") {
+    findings.push(error(`${rel}: plugins[] entry "${name}" needs a "source"`))
+    return
+  }
+  if (source.split("/").includes("..")) {
+    findings.push(error(`${rel}: plugins[] entry "${name}" source "${source}" escapes the marketplace`))
+  } else if (!source.startsWith("./")) {
+    findings.push(error(`${rel}: plugins[] entry "${name}" source "${source}" must be ./-relative`))
+  } else if (!existsSync(join(root, source.slice(2)))) {
+    findings.push(error(`${rel}: plugins[] entry "${name}" source "${source}" does not resolve`))
+  }
+}
+
+// the plugins[]-entry fields beyond the shared string/array ones, per
+// schema/marketplace-v1.json
+function lintEntryFields(rel: string, entry: Record<string, unknown>, findings: Finding[]): void {
+  if (entry.author !== undefined && !isRecord(entry.author)) {
+    findings.push(error(`${rel}: "author" must be an object`))
+  }
+  if (entry.defaultEnabled !== undefined && typeof entry.defaultEnabled !== "boolean") {
+    findings.push(error(`${rel}: "defaultEnabled" must be a boolean`))
+  }
+  if (entry.mcpServers !== undefined && (typeof entry.mcpServers !== "string" || !entry.mcpServers.startsWith("./"))) {
+    findings.push(error(`${rel}: "mcpServers" must be a ./-relative path`))
+  }
+}
+
+function lintPlugins(
+  rel: string,
+  plugins: unknown,
+  root: string,
+  manifest: MarketplaceManifest,
+  findings: Finding[],
+): void {
+  if (!Array.isArray(plugins)) {
+    findings.push(error(`${rel}: "plugins" must be an array`))
+    return
+  }
+  for (const entry of plugins) {
+    if (!isRecord(entry)) {
+      findings.push(error(`${rel}: every plugins[] entry must be an object`))
+      continue
+    }
+    lintFields(rel, entry, findings)
+    lintEntryFields(rel, entry, findings)
+    if (typeof entry.name !== "string") {
+      findings.push(error(`${rel}: plugins[] entry needs a "name"`))
+    } else {
+      lintName(rel, entry.name, undefined, findings)
+      manifest.entries.set(entry.name, entry)
+    }
+    lintSource(rel, entry, root, findings)
+  }
+}
+
+export interface MarketplaceManifest {
+  name?: string
+  entries: Map<string, Record<string, unknown>>
+}
+
+export function lintMarketplaceJson(root: string, findings: Finding[]): MarketplaceManifest {
+  const manifest: MarketplaceManifest = { entries: new Map() }
+  const file = join(root, "marketplace.json")
+  if (!existsSync(file)) return manifest
+  const rel = relative(root, file)
+  const parsed = parseJson(file, rel, findings)
+  if (!parsed) return manifest
+  lintFields(rel, parsed, findings)
+  if (parsed.owner !== undefined && !isRecord(parsed.owner)) {
+    findings.push(error(`${rel}: "owner" must be an object`))
+  }
+  if (parsed.renames !== undefined &&
+    (!isRecord(parsed.renames) || !Object.values(parsed.renames).every((value) => typeof value === "string" || value === null))) {
+    findings.push(error(`${rel}: "renames" must be an object of string or null`))
+  }
+  if (parsed.name !== undefined && typeof parsed.name !== "string") {
+    findings.push(error(`${rel}: "name" must be a string`))
+  }
+  if (typeof parsed.name === "string") {
+    manifest.name = parsed.name
+    if (readRegistry().marketplaces[parsed.name]) {
+      findings.push(warning(`${rel}: name "${parsed.name}" is already added on this machine`))
+    }
+  }
+  if (parsed.plugins !== undefined) lintPlugins(rel, parsed.plugins, root, manifest, findings)
+  return manifest
+}
+
+// returns the parsed record so the caller can compare versions across manifests
+export function lintPluginJson(
+  root: string,
+  pluginDir: string,
+  pluginName: string,
+  findings: Finding[],
+): Record<string, unknown> | undefined {
+  const file = join(pluginDir, "plugin.json")
+  if (!existsSync(file)) return undefined
+  const rel = relative(root, file)
+  const parsed = parseJson(file, rel, findings)
+  if (!parsed) return undefined
+  lintFields(rel, parsed, findings)
+  if (parsed.author !== undefined && !isRecord(parsed.author)) {
+    findings.push(error(`${rel}: "author" must be an object`))
+  }
+  if (parsed.name !== undefined && typeof parsed.name !== "string") {
+    findings.push(error(`${rel}: "name" must be a string`))
+  }
+  if (typeof parsed.name === "string") lintName(rel, parsed.name, pluginName, findings)
+  return parsed
+}
+
+export function lintMcpJson(root: string, pluginDir: string, findings: Finding[]): void {
+  const file = join(pluginDir, "mcp.json")
+  if (!existsSync(file)) return
+  const rel = relative(root, file)
+  const parsed = parseJson(file, rel, findings)
+  if (!parsed) return
+  for (const [server, value] of Object.entries(parsed)) {
+    if (!isRecord(value) || value.type === undefined) {
+      findings.push(error(`${rel}: entry "${server}" is missing "type"`))
+    }
+  }
+}

package/src/migrate.ts

@@ -0,0 +1,117 @@
+// spec 13: the second half of the one-shot migration, run by every ocm command
+// before dispatch. The file moves live in migrateLegacyLayout (spec 01) and
+// stay byte-preserving so a programmatic installLoader keeps its spec 01
+// semantics; this half upgrades what later specs changed in place — the
+// registry schema (02), the sync stamp (08) and the skill link layout (03) —
+// and is deliberately not called from installLoader.
+import { existsSync, readFileSync, readdirSync, readlinkSync, rmSync } from "node:fs"
+import { join } from "node:path"
+import { componentRoot, enabledPlugins, materialize } from "../loader/core.js"
+import { OCM_LINKS_DIR, OCM_REGISTRY_FILE, OCM_STAMP_FILE, OPENCODE_AGENTS_DIR, OPENCODE_COMMANDS_DIR } from "./paths"
+import { loadRegistry, loadRegistryForWrite, saveRegistry } from "./registry"
+import { reportUpgrade, reportWarnings } from "./report"
+import type { Registry } from "./types"
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+}
+
+// registry version 1 → 2 on disk: normalization fills the v2 defaults and
+// rewrites absolute sources marketplace-relative (spec 02)
+function upgradeRegistry(): void {
+  const { registry, wasV1 } = loadRegistryForWrite()
+  if (!wasV1) return
+  saveRegistry(registry)
+  reportUpgrade(true)
+}
+
+// the pre-08 global throttle stamp folds into per-marketplace lastSync (spec 08)
+function foldSyncStamp(): void {
+  let at: string | null = null
+  try {
+    const stamp: unknown = JSON.parse(readFileSync(OCM_STAMP_FILE, "utf8"))
+    if (isRecord(stamp) && typeof stamp.at === "string") at = stamp.at
+  } catch {
+    return
+  }
+  let raw: unknown
+  try {
+    raw = JSON.parse(readFileSync(OCM_REGISTRY_FILE, "utf8"))
+  } catch {
+    return
+  }
+  const entries = isRecord(raw) && isRecord(raw.marketplaces) ? Object.values(raw.marketplaces).filter(isRecord) : []
+  const open = entries.filter((entry) => entry.lastSync == null)
+  rmSync(OCM_STAMP_FILE, { force: true })
+  if (!at || !open.length) return
+  for (const entry of open) entry.lastSync = { at, ok: true, error: null }
+  saveRegistry(raw as Registry)
+  console.log(`folded ${OCM_STAMP_FILE} into per-marketplace lastSync`)
+}
+
+// a top-level symlink in the skills dir is the pre-spec-03 whole-dir form; it
+// is ours iff it points into this marketplace (raw prefix compare — a realpath
+// must never be compared against a non-canonical directory)
+function legacySkillLinks(skillsDir: string, root: string): string[] {
+  let entries: string[]
+  try {
+    entries = readdirSync(skillsDir)
+  } catch {
+    return []
+  }
+  const legacy: string[] = []
+  for (const entry of entries) {
+    let target: string | undefined
+    try {
+      target = readlinkSync(join(skillsDir, entry))
+    } catch {
+      continue
+    }
+    if (target === root || target.startsWith(`${root}/`)) legacy.push(entry)
+  }
+  return legacy
+}
+
+// the old → new names for one plugin's relinked skills, read back from the
+// rendered mirrors materialize just wrote
+function skillMapping(skillsDir: string, plugin: string): string[] {
+  let entries: string[]
+  try {
+    entries = readdirSync(skillsDir)
+  } catch {
+    return []
+  }
+  const lines: string[] = []
+  for (const entry of entries) {
+    if (!entry.startsWith(`${plugin}--`)) continue
+    let name: string | undefined
+    try {
+      name = readFileSync(join(skillsDir, entry, "SKILL.md"), "utf8").match(/^name: "(.+)"$/m)?.[1]
+    } catch {}
+    if (name) lines.push(`relinked skill ${name.slice(plugin.length + 1)} -> ${name}`)
+  }
+  return lines.sort()
+}
+
+// whole-dir skill symlinks and ocm--<mp> containers both predate spec 03; one
+// materialize pass — the same code path an ocm update runs — replaces them
+// with the current layout
+function relinkSkills(): void {
+  for (const [name, entry] of Object.entries(loadRegistry().marketplaces)) {
+    const root = componentRoot(entry)
+    const skillsDir = join(OCM_LINKS_DIR, name, "skills")
+    const legacy = legacySkillLinks(skillsDir, root)
+    const container =
+      existsSync(join(OPENCODE_COMMANDS_DIR, `ocm--${name}`)) || existsSync(join(OPENCODE_AGENTS_DIR, `ocm--${name}`))
+    if (!legacy.length && !container) continue
+    const links = materialize(name, root, { enabled: enabledPlugins(entry, root) })
+    reportWarnings(links.warnings.map((warning) => `${name}: ${warning}`))
+    for (const plugin of legacy) for (const line of skillMapping(skillsDir, plugin)) console.log(line)
+  }
+}
+
+export function migrateInstallation(): void {
+  upgradeRegistry()
+  foldSyncStamp()
+  relinkSkills()
+}

package/src/paths.ts

@@ -0,0 +1,22 @@
+import { homedir } from "node:os"
+import { join } from "node:path"
+
+export const HOME = homedir()
+
+export const OPENCODE_GLOBAL_DIR = join(HOME, ".config", "opencode")
+export const OPENCODE_GLOBAL_CONFIG = join(OPENCODE_GLOBAL_DIR, "opencode.json")
+export const OPENCODE_COMMANDS_DIR = join(OPENCODE_GLOBAL_DIR, "commands")
+export const OPENCODE_AGENTS_DIR = join(OPENCODE_GLOBAL_DIR, "agents")
+export const OPENCODE_PLUGINS_DIR = join(OPENCODE_GLOBAL_DIR, "plugins")
+
+export const OCM_CACHE_DIR = join(HOME, ".cache", "ocm")
+export const OCM_MARKETPLACES_DIR = join(OCM_CACHE_DIR, "marketplaces")
+export const OCM_LINKS_DIR = join(OCM_CACHE_DIR, "links")
+// pre-08 global sync stamp, folded into per-marketplace lastSync by the migration
+export const OCM_STAMP_FILE = join(OCM_CACHE_DIR, "last-sync.json")
+
+export const OCM_DIR = join(OPENCODE_GLOBAL_DIR, "ocm")
+export const OCM_REGISTRY_FILE = join(OCM_DIR, "registry.json")
+export const OCM_LEGACY_REGISTRY_FILE = join(OPENCODE_PLUGINS_DIR, "ocm-registry.json")
+
+export const OCM_LOADER_NAME = "ocm-loader.js"

package/src/probe.ts

@@ -0,0 +1,52 @@
+import { spawnSync } from "node:child_process"
+import { cpSync, existsSync, mkdtempSync, rmSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+import { OPENCODE_GLOBAL_DIR } from "./paths"
+
+// Ask the real opencode binary which of its plugins failed to load, keeping
+// only errors attributable to ocm files. The probe runs against a throwaway
+// copy of the config directory under a scratch HOME: opencode rewrites
+// opencode.json on load (it adds $schema) and creates files under HOME, so
+// probing the real directory would mutate the user's config. OCM_SYNC_DISABLE
+// keeps the copied loader's startup sync inert as well. Never throws — a
+// failed probe reports nothing, it does not take doctor down with it.
+export function ocmPluginErrors(): string[] {
+  if (!existsSync(OPENCODE_GLOBAL_DIR)) return []
+  let scratch: string | undefined
+  try {
+    scratch = mkdtempSync(join(tmpdir(), "ocm-doctor-"))
+    const configDir = join(scratch, "config")
+    cpSync(OPENCODE_GLOBAL_DIR, configDir, { recursive: true })
+    const env: NodeJS.ProcessEnv = {
+      ...process.env,
+      HOME: join(scratch, "home"),
+      OPENCODE_CONFIG_DIR: configDir,
+      OCM_SYNC_DISABLE: "1",
+    }
+    // an XDG override would point opencode back at the real global config
+    delete env.XDG_CONFIG_HOME
+    const run = spawnSync("opencode", ["debug", "skill", "--print-logs", "--log-level", "ERROR"], {
+      env,
+      encoding: "utf8",
+      timeout: 180_000,
+    })
+    if (run.status !== 0) return []
+    const output = `${run.stdout ?? ""}\n${run.stderr ?? ""}`
+    return output
+      .split("\n")
+      .filter((line) => /level=ERROR.*failed to load plugin/.test(line))
+      .filter((line) => line.includes("/ocm--") || line.includes("/ocm-loader.js"))
+      .map((line) => line.trim())
+  } catch {
+    return []
+  } finally {
+    if (scratch !== undefined) {
+      // opencode leaves background writers in the scratch dir; a leftover
+      // temp directory is harmless, a crashed doctor is not
+      try {
+        rmSync(scratch, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 })
+      } catch {}
+    }
+  }
+}

package/src/registry.ts

@@ -0,0 +1,25 @@
+import {
+  loadRegistryForWrite as coreLoadRegistryForWrite,
+  normalizeRegistry as coreNormalizeRegistry,
+  readRegistry,
+  saveRegistry as coreSaveRegistry,
+} from "../loader/core.js"
+import type { Registry } from "./types"
+
+// thin facade over the core registry: the CLI keeps its typed surface, the
+// canonical atomic save lives in the core (spec 10a)
+export function loadRegistry(): Registry {
+  return readRegistry()
+}
+
+export function loadRegistryForWrite(): { registry: Registry; wasV1: boolean } {
+  return coreLoadRegistryForWrite()
+}
+
+export function normalizeRegistry(raw: unknown): Registry {
+  return coreNormalizeRegistry(raw)
+}
+
+export function saveRegistry(registry: Registry): void {
+  coreSaveRegistry(registry)
+}

package/src/renames.ts

@@ -0,0 +1,83 @@
+import { incumbentMarketplace } from "./install"
+import type { DiscoveredPlugin, MarketplaceEntry, MarketplacePlugin, Registry } from "./types"
+
+export interface RenameResult {
+  renamed: { from: string; to: string }[]
+  removed: string[]
+  refused: { from: string; to: string; incumbent: string }[]
+  // rename targets refused for colliding with another marketplace's plugin
+  // name: excluded from registration so the incumbent keeps the name
+  excluded: Set<string>
+  // records a refusal kept at their old name, re-added after registration
+  kept: Record<string, MarketplacePlugin>
+}
+
+// spec 08 rename chains: walk each source while its target is itself a
+// source. A walk that revisits a name is a cycle — reported by the caller
+// and ignored, so its keys stay unresolved.
+export function resolveChains(renames: Record<string, string | null>): {
+  resolved: Record<string, string | null>
+  cycles: string[][]
+} {
+  const resolved: Record<string, string | null> = {}
+  const cycles: string[][] = []
+  const reported = new Set<string>()
+  for (const start of Object.keys(renames)) {
+    if (start in resolved) continue
+    const path: string[] = []
+    const visited = new Set<string>()
+    let current: string | null = start
+    let cyclic = false
+    while (current !== null && current in renames) {
+      if (visited.has(current)) {
+        const cycle = path.slice(path.indexOf(current))
+        const id = [...cycle].sort().join("\u0000")
+        if (!reported.has(id)) {
+          reported.add(id)
+          cycles.push(cycle)
+        }
+        cyclic = true
+        break
+      }
+      visited.add(current)
+      path.push(current)
+      current = renames[current] ?? null
+    }
+    if (!cyclic) for (const key of path) resolved[key] = current
+  }
+  return { resolved, cycles }
+}
+
+// applied after discovery, before registration: migrate records along the
+// resolved renames, drop removals, refuse cross-marketplace collisions
+export function applyRenames(
+  registry: Registry,
+  name: string,
+  entry: MarketplaceEntry,
+  discovered: Map<string, DiscoveredPlugin>,
+  resolved: Record<string, string | null>,
+): RenameResult {
+  const result: RenameResult = { renamed: [], removed: [], refused: [], excluded: new Set(), kept: {} }
+  for (const [from, to] of Object.entries(resolved)) {
+    const record = entry.plugins[from]
+    if (!record) continue
+    if (to === null) {
+      delete entry.plugins[from]
+      result.removed.push(from)
+      continue
+    }
+    const incumbent = incumbentMarketplace(registry, name, to)
+    if (incumbent) {
+      result.refused.push({ from, to, incumbent })
+      result.excluded.add(to)
+      result.kept[from] = record
+      continue
+    }
+    // the target is not shipped (yet): the record dangles rather than moves
+    if (!discovered.has(to)) continue
+    entry.plugins[to] = record
+    delete entry.plugins[from]
+    result.renamed.push({ from, to })
+  }
+  return result
+}