@wntic/ocm 0.1.0

package/src/commands/doctor-links.ts

@@ -0,0 +1,170 @@
+// spec 12 doctor: the link-layer checks — stray ocm files, broken symlinks,
+// drifted materialization and paths under directories ocm never owns. Every
+// removal proves ownership first; an unowned path is reported, never touched.
+import { existsSync, readFileSync, readdirSync, readlinkSync, rmSync } from "node:fs"
+import { dirname, join } from "node:path"
+import { componentRoot, discoverPlugins, enabledPlugins } from "../../loader/core.js"
+import type { CoreRegistry } from "../../loader/core.js"
+import { materializeLinks } from "../install"
+import { HOME, OCM_LINKS_DIR, OPENCODE_AGENTS_DIR, OPENCODE_COMMANDS_DIR, OPENCODE_PLUGINS_DIR } from "../paths"
+import { error, fixed, type Finding } from "../findings"
+
+function errText(err: unknown): string {
+  return err instanceof Error ? err.message : String(err)
+}
+
+// raw-string prefix compare only: a raw symlink target must never be compared
+// against a realpath'd directory (macOS puts temp dirs behind /var)
+function insideDir(target: string, dir: string): boolean {
+  return target === dir || target.startsWith(dir + "/")
+}
+
+function managedRoots(registry: CoreRegistry): string[] {
+  return Object.values(registry.marketplaces).map((entry) => componentRoot(entry))
+}
+
+function removePath(path: string, findings: Finding[]): void {
+  try {
+    rmSync(path, { force: true, recursive: true })
+    findings.push(fixed(`${path}: removed`))
+  } catch (err) {
+    findings.push(error(`${path}: cannot remove — ${errText(err)}`))
+  }
+}
+
+// spec 01: no ocm file other than ocm-loader.js may live in plugins/
+export function checkStrays(registry: CoreRegistry, findings: Finding[], fix: boolean): void {
+  const claimed = new Set<string>()
+  for (const entry of Object.values(registry.marketplaces)) {
+    for (const [name, plugin] of Object.entries(entry.plugins ?? {})) {
+      for (const file of plugin.components?.plugin ?? []) claimed.add(`ocm--${name}--${file}`)
+    }
+  }
+  let entries: string[]
+  try {
+    entries = readdirSync(OPENCODE_PLUGINS_DIR)
+  } catch {
+    return
+  }
+  for (const name of entries) {
+    if (!name.startsWith("ocm--") || claimed.has(name)) continue
+    const path = join(OPENCODE_PLUGINS_DIR, name)
+    if (fix) removePath(path, findings)
+    else findings.push(error(`${path}: stray ocm file — no registry entry owns it`))
+  }
+}
+
+export function checkBrokenLinks(registry: CoreRegistry, findings: Finding[], fix: boolean): void {
+  const managed = managedRoots(registry)
+  for (const dir of [OPENCODE_COMMANDS_DIR, OPENCODE_AGENTS_DIR, OPENCODE_PLUGINS_DIR]) {
+    let entries: string[]
+    try {
+      entries = readdirSync(dir)
+    } catch {
+      continue
+    }
+    for (const name of entries) {
+      const path = join(dir, name)
+      let target: string
+      try {
+        target = readlinkSync(path)
+      } catch {
+        continue
+      }
+      if (existsSync(path)) continue
+      if (!managed.some((root) => insideDir(target, root))) {
+        findings.push(error(`${path}: broken symlink → ${target} (not ocm's, left in place)`))
+      } else if (fix) {
+        removePath(path, findings)
+      } else {
+        findings.push(error(`${path}: broken symlink → ${target}`))
+      }
+    }
+  }
+}
+
+// a skill mirror exists only when the source SKILL.md renders (has a name in
+// its frontmatter); one that does not is legitimately skipped by materialize
+function skillRenders(source: string): boolean {
+  try {
+    const content = readFileSync(join(source, "SKILL.md"), "utf8")
+    if (!content.startsWith("---\n")) return false
+    const close = content.indexOf("\n---\n", 3)
+    if (close === -1) return false
+    return /^name:[^\n]*\S/m.test(content.slice(4, close))
+  } catch {
+    return false
+  }
+}
+
+// plugin-js links and mcp keys are trust-gated, so their absence is not drift
+export function checkMaterialized(registry: CoreRegistry, findings: Finding[], fix: boolean): void {
+  for (const [name, entry] of Object.entries(registry.marketplaces)) {
+    const root = componentRoot(entry)
+    if (!existsSync(root)) continue
+    const enabled = enabledPlugins(entry, root)
+    let missing = 0
+    for (const plugin of discoverPlugins(root)) {
+      if (enabled !== null && !enabled.has(plugin.name)) continue
+      if (entry.plugins[plugin.name]?.collision) continue
+      for (const file of plugin.components.command ?? []) {
+        if (!existsSync(join(OPENCODE_COMMANDS_DIR, `${plugin.name}:${file}`))) missing += 1
+      }
+      for (const file of plugin.components.agent ?? []) {
+        if (!existsSync(join(OPENCODE_AGENTS_DIR, `${plugin.name}:${file}`))) missing += 1
+      }
+      for (const rel of plugin.components.skill ?? []) {
+        const source = ["skills", "skill"].map((dir) => join(plugin.dir, dir, rel)).find((path) => existsSync(path))
+        const mirror = join(OCM_LINKS_DIR, name, "skills", `${plugin.name}--${rel.split("/").join("-")}`)
+        if (source && skillRenders(source) && !existsSync(join(mirror, "SKILL.md"))) missing += 1
+      }
+    }
+    if (!missing) continue
+    if (!fix) {
+      findings.push(error(`marketplace "${name}": ${missing} materialized component(s) missing (ocm update)`))
+      continue
+    }
+    materializeLinks(name, entry)
+    findings.push(fixed(`marketplace "${name}": re-materialized ${missing} component(s) (restart opencode to activate)`))
+  }
+}
+
+// spec 04: ocm never writes under ~/.claude or ~/.agents; an ocm-created
+// symlink there should be impossible, so it is reported loudly
+// spec 00: opencode also scans .claude / .agents directories walking up
+// from cwd, so those bases are checked alongside the home ones
+function forbiddenBases(): Set<string> {
+  const bases = new Set([join(HOME, ".claude"), join(HOME, ".agents")])
+  let dir = process.cwd()
+  for (;;) {
+    bases.add(join(dir, ".claude"))
+    bases.add(join(dir, ".agents"))
+    const parent = dirname(dir)
+    if (parent === dir) return bases
+    dir = parent
+  }
+}
+
+export function checkForbiddenPaths(registry: CoreRegistry, findings: Finding[]): void {
+  const managed = [...managedRoots(registry), OCM_LINKS_DIR]
+  for (const base of forbiddenBases()) {
+    let paths: string[]
+    try {
+      paths = readdirSync(base, { recursive: true }) as string[]
+    } catch {
+      continue
+    }
+    for (const rel of paths) {
+      const path = join(base, rel)
+      let target: string
+      try {
+        target = readlinkSync(path)
+      } catch {
+        continue
+      }
+      if (managed.some((root) => insideDir(target, root))) {
+        findings.push(error(`${path}: ocm-created path under a directory ocm never owns — report this bug`))
+      }
+    }
+  }
+}

package/src/commands/doctor.ts

@@ -0,0 +1,144 @@
+// spec 12 `ocm doctor`: read-mostly diagnosis of an installation. The probe
+// runs last, after any fixes, so its report reflects the repaired state.
+import { spawnSync } from "node:child_process"
+import { existsSync, readFileSync } from "node:fs"
+import { componentRoot, isGitRepo, readRegistry } from "../../loader/core.js"
+import type { CoreRegistry } from "../../loader/core.js"
+import { installLoader, loaderStatus, type LoaderFileStatus } from "../loader"
+import { OCM_LEGACY_REGISTRY_FILE, OCM_LOADER_NAME, OCM_REGISTRY_FILE } from "../paths"
+import { error, fixed, reportFindings, warning, type Finding } from "../findings"
+import { ocmPluginErrors } from "../probe"
+import { checkConfig } from "./doctor-config"
+import { checkBrokenLinks, checkForbiddenPaths, checkMaterialized, checkStrays } from "./doctor-links"
+
+function errText(err: unknown): string {
+  return err instanceof Error ? err.message : String(err)
+}
+
+export function doctor(fix: boolean): void {
+  console.log("doctor")
+  const findings: Finding[] = []
+  const registry = readRegistry()
+  checkGitPath(findings)
+  checkLoader(findings, fix)
+  // a registry that cannot be honored must never be read as "nothing owns
+  // these files": the stray and MCP fixes stay report-only until it is
+  // fixed, or --fix would uninstall everything at once
+  const registryUsable = checkRegistryFile(findings)
+  checkStrays(registry, findings, fix && registryUsable)
+  checkMarketplaces(registry, findings)
+  checkBrokenLinks(registry, findings, fix)
+  checkConfig(findings, registry, fix, registryUsable)
+  checkMaterialized(registry, findings, fix)
+  checkForbiddenPaths(registry, findings)
+  for (const line of ocmPluginErrors()) findings.push(error(`${line} (ocm update)`))
+  if (reportFindings(findings)) process.exitCode = 1
+}
+
+function checkGitPath(findings: Finding[]): void {
+  const run = spawnSync("git", ["--version"], { encoding: "utf8", timeout: 10_000 })
+  if (run.error || run.status !== 0) {
+    findings.push(warning("git is not on PATH — ocm update and the loader's sync need it"))
+  }
+}
+
+// the report names the loader trio; the remaining installed files surface
+// only when broken
+function checkLoader(findings: Finding[], fix: boolean): void {
+  let files: LoaderFileStatus[]
+  try {
+    files = loaderStatus()
+  } catch (err) {
+    findings.push(error(`cannot check the loader — ${errText(err)}`))
+    return
+  }
+  for (const file of files) {
+    if ([OCM_LOADER_NAME, "core.js", "ui.js"].includes(file.file)) {
+      console.log(`  loader  ${file.file} (${file.state})`)
+    }
+  }
+  const broken = files.filter((file) => file.state !== "current")
+  if (!broken.length) return
+  if (fix) {
+    try {
+      installLoader()
+      findings.push(fixed(`reinstalled ${broken.length} loader file(s) (restart opencode to activate)`))
+    } catch (err) {
+      findings.push(error(`cannot reinstall the loader — ${errText(err)}`))
+    }
+    return
+  }
+  for (const file of broken) {
+    findings.push(error(file.state === "missing"
+      ? `${file.file}: not installed (ocm init)`
+      : `${file.file}: stale version comment — a stale core silently no-ops (ocm update)`))
+  }
+}
+
+// returns whether the on-disk registry can be honored; a missing file is a
+// genuinely empty registry, but an unusable one must gate the fixes that
+// trust its ownership records
+function checkRegistryFile(findings: Finding[]): boolean {
+  let raw: string
+  try {
+    raw = readFileSync(OCM_REGISTRY_FILE, "utf8")
+  } catch {
+    return checkLegacyRegistryFile(findings)
+  }
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(raw)
+  } catch {
+    findings.push(error(`${OCM_REGISTRY_FILE}: not valid JSON (ocm update)`))
+    return false
+  }
+  if (typeof parsed !== "object" || parsed === null || (parsed as Record<string, unknown>).version !== 2) {
+    findings.push(error(`${OCM_REGISTRY_FILE}: not a current v2 registry (ocm update)`))
+    return false
+  }
+  return true
+}
+
+// readRegistry falls back to the pre-02 plugins/ocm-registry.json when the
+// v2 file is absent and silently swallows a parse failure — the same
+// lost-ownership failure mode, so it gates the registry-trusting fixes too
+function checkLegacyRegistryFile(findings: Finding[]): boolean {
+  let raw: string
+  try {
+    raw = readFileSync(OCM_LEGACY_REGISTRY_FILE, "utf8")
+  } catch {
+    return true
+  }
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(raw)
+  } catch {
+    findings.push(error(`${OCM_LEGACY_REGISTRY_FILE}: not valid JSON (ocm update)`))
+    return false
+  }
+  if (typeof parsed !== "object" || parsed === null) {
+    findings.push(error(`${OCM_LEGACY_REGISTRY_FILE}: not a JSON object (ocm update)`))
+    return false
+  }
+  return true
+}
+
+function checkMarketplaces(registry: CoreRegistry, findings: Finding[]): void {
+  for (const [name, entry] of Object.entries(registry.marketplaces)) {
+    const root = componentRoot(entry)
+    if (!existsSync(root)) {
+      findings.push(error(`marketplace "${name}": directory missing (${root}) — ocm update re-clones`))
+      continue
+    }
+    if (!entry.local && !isGitRepo(entry.dir)) {
+      findings.push(error(`marketplace "${name}": not a git repository (ocm update)`))
+    }
+    const lastSync = entry.lastSync
+    if (lastSync?.ok === false) {
+      const age = Date.now() - Date.parse(lastSync.at)
+      const minutes = Number.isFinite(age) ? Math.max(0, Math.round(age / 60_000)) : 0
+      const first = lastSync.error?.split("\n").map((line) => line.trim()).find(Boolean) ?? "unknown error"
+      findings.push(error(`marketplace "${name}": last sync failed ${minutes}m ago: ${first}`))
+    }
+  }
+}

package/src/commands/info.ts

@@ -0,0 +1,159 @@
+import { join } from "node:path"
+import { OCM_LINKS_DIR, OPENCODE_AGENTS_DIR, OPENCODE_COMMANDS_DIR, OPENCODE_GLOBAL_CONFIG, OPENCODE_PLUGINS_DIR } from "../paths"
+import { loadRegistry } from "../registry"
+import type { MarketplaceEntry, MarketplacePlugin, PluginManifest, Registry } from "../types"
+
+export interface InfoOptions {
+  json?: boolean
+}
+
+interface Resolved {
+  marketplace: string
+  plugin: string
+  entry: MarketplaceEntry
+  record: MarketplacePlugin
+}
+
+// resolution never touches the marketplace directory: info answers from the
+// registry cache and works for disabled and blocked plugins (spec 09)
+function resolve(registry: Registry, arg: string): Resolved {
+  const at = arg.indexOf("@")
+  const plugin = at === -1 ? arg : arg.slice(0, at)
+  const wanted = at === -1 ? null : arg.slice(at + 1)
+  if (!plugin) throw new Error(`missing plugin name in "${arg}" (ocm search <query>)`)
+  const providers = Object.entries(registry.marketplaces).filter(
+    ([name, entry]) => entry.plugins[plugin] && (wanted === null || name === wanted),
+  )
+  if (!providers.length) {
+    throw new Error(`plugin "${plugin}" not found in any marketplace (ocm search <query>, or ocm update)`)
+  }
+  if (providers.length > 1) {
+    const names = providers.map(([name]) => name).join(", ")
+    throw new Error(`plugin "${plugin}" is provided by more than one marketplace: ${names} (use ${plugin}@<marketplace>)`)
+  }
+  const [marketplace, entry] = providers[0]!
+  return { marketplace, plugin, entry, record: entry.plugins[plugin]! }
+}
+
+interface ResultingComponent {
+  type: string
+  name: string
+  source: string
+  target: string
+}
+
+// the resulting opencode names, not the source filenames: "what do I type to
+// use this" is the question info exists to answer (spec 09)
+function resultingComponents(marketplace: string, plugin: string, record: MarketplacePlugin): ResultingComponent[] {
+  const out: ResultingComponent[] = []
+  for (const file of record.components.command ?? []) {
+    out.push({
+      type: "command",
+      name: `${plugin}:${file.replace(/\.md$/, "")}`,
+      source: join(record.source, "commands", file),
+      target: join(OPENCODE_COMMANDS_DIR, `${plugin}:${file}`),
+    })
+  }
+  for (const file of record.components.agent ?? []) {
+    out.push({
+      type: "agent",
+      name: `${plugin}:${file.replace(/\.md$/, "")}`,
+      source: join(record.source, "agents", file),
+      target: join(OPENCODE_AGENTS_DIR, `${plugin}:${file}`),
+    })
+  }
+  for (const rel of record.components.skill ?? []) {
+    out.push({
+      type: "skill",
+      name: `${plugin}:${rel}`,
+      source: join(record.source, "skills", rel, "SKILL.md"),
+      target: join(OCM_LINKS_DIR, marketplace, "skills", `${plugin}--${rel.split("/").join("-")}`, "SKILL.md"),
+    })
+  }
+  for (const file of record.components.plugin ?? []) {
+    out.push({
+      type: "plugin",
+      name: `ocm--${plugin}--${file}`,
+      source: join(record.source, "plugin", file),
+      target: join(OPENCODE_PLUGINS_DIR, `ocm--${plugin}--${file}`),
+    })
+  }
+  for (const server of record.components.mcp ?? []) {
+    out.push({
+      type: "mcp",
+      name: `ocm--${plugin}--${server}`,
+      source: join(record.source, "mcp.json"),
+      target: `${OPENCODE_GLOBAL_CONFIG} (mcp)`,
+    })
+  }
+  return out
+}
+
+// origin is debugging information, not decoration: annotated only where the
+// two manifests disagreed, and the marketplace entry won by precedence
+function origin(manifest: PluginManifest, field: string): string | undefined {
+  return manifest.conflicts?.includes(field) ? "marketplace.json" : undefined
+}
+
+function field(label: string, value: string | undefined, note?: string): void {
+  if (value === undefined) return
+  console.log(`  ${label.padEnd(13)}${value}${note ? `  (${note})` : ""}`)
+}
+
+function age(iso: string): string {
+  const ms = Date.now() - Date.parse(iso)
+  if (Number.isNaN(ms) || ms < 60_000) return "just now"
+  const minutes = Math.floor(ms / 60_000)
+  if (minutes < 60) return `${minutes}m ago`
+  const hours = Math.floor(minutes / 60)
+  return hours < 24 ? `${hours}h ago` : `${Math.floor(hours / 24)}d ago`
+}
+
+export function info(arg: string, options: InfoOptions = {}): void {
+  const { marketplace, plugin, entry, record } = resolve(loadRegistry(), arg)
+  const manifest = record.manifest
+  if (options.json) {
+    console.log(JSON.stringify({
+      plugin,
+      marketplace,
+      description: manifest.description ?? null,
+      version: record.version,
+      category: manifest.category ?? null,
+      tags: manifest.tags ?? null,
+      keywords: manifest.keywords ?? null,
+      homepage: manifest.homepage ?? null,
+      license: manifest.license ?? null,
+      enabled: record.enabled,
+      installedAt: record.installedAt,
+      url: entry.url,
+      ref: entry.ref,
+      revision: entry.revision,
+      trust: entry.trust.code,
+      lastSync: entry.lastSync,
+      components: resultingComponents(marketplace, plugin, record),
+    }, null, 2))
+    return
+  }
+  console.log(`${plugin} @ ${marketplace}`)
+  field("description", manifest.description, origin(manifest, "description"))
+  field("version", record.version ?? undefined, origin(manifest, "version"))
+  field("category", manifest.category, origin(manifest, "category"))
+  field("tags", manifest.tags?.join(", "))
+  field("homepage", manifest.homepage)
+  field("license", manifest.license)
+  field("enabled", record.enabled ? "yes" : "no")
+  field("installed", record.installedAt ?? undefined)
+  field("marketplace", `${entry.url}${entry.ref ? `  @ ${entry.ref}` : ""}`)
+  if (entry.revision) {
+    const synced = entry.lastSync ? `  (synced ${age(entry.lastSync.at)})` : ""
+    field("revision", `${entry.revision.slice(0, 7)}${synced}`)
+  }
+  field("trust", entry.trust.code)
+  const components = resultingComponents(marketplace, plugin, record)
+  if (components.length) {
+    console.log("  components")
+    for (const component of components) {
+      console.log(`    ${component.type.padEnd(8)}${component.name}  → ${component.target}`)
+    }
+  }
+}

package/src/commands/list.ts

@@ -0,0 +1,44 @@
+import { loadRegistry } from "../registry"
+
+export interface ListOptions {
+  all?: boolean
+  json?: boolean
+}
+
+export function list(options: ListOptions = {}): void {
+  const registry = loadRegistry()
+  if (options.json) {
+    console.log(JSON.stringify(registry, null, 2))
+    return
+  }
+  const entries = Object.entries(registry.marketplaces)
+  if (!entries.length) {
+    console.log("no marketplaces added yet (ocm add <url|path>)")
+    return
+  }
+  for (const [name, entry] of entries) {
+    console.log(`${name}${options.all ? ` (${entry.mode})` : ""}`)
+    console.log(`  source: ${entry.url}`)
+    // display shortens; the registry keeps the full sha (spec 08)
+    const short = entry.revision ? entry.revision.slice(0, 7) : null
+    if (short) console.log(`  revision: ${short}`)
+    if (options.all && entry.lastSync && !entry.lastSync.ok) {
+      console.log(`  \x1b[31mlast sync failed: ${entry.lastSync.error}\x1b[0m`)
+    }
+    for (const [pluginName, plugin] of Object.entries(entry.plugins)) {
+      if (!options.all && !plugin.enabled) continue
+      const parts: string[] = []
+      if (plugin.components.agent) parts.push(`agents: ${plugin.components.agent.join(", ")}`)
+      if (plugin.components.command) parts.push(`commands: ${plugin.components.command.join(", ")}`)
+      if (plugin.components.skill) parts.push(`skills: ${plugin.components.skill.join(", ")}`)
+      if (plugin.components.plugin) parts.push(`plugins: ${plugin.components.plugin.join(", ")}`)
+      if (plugin.components.mcp) parts.push(`mcp: ${plugin.components.mcp.join(", ")}`)
+      // the marketplace revision is the implicit version of a versionless
+      // plugin (spec 08)
+      const version = plugin.version ?? (short ? `@${short}` : null)
+      const markers = `${version ? ` (${version})` : ""}${options.all && !plugin.enabled ? " (disabled)" : ""}`
+      console.log(`  ${pluginName}${markers}`)
+      for (const part of parts) console.log(`    ${part}`)
+    }
+  }
+}

package/src/commands/marketplace.ts

@@ -0,0 +1,99 @@
+import { addMarketplace, denyTrust, grantTrust, isGitUrl, normaliseMarketplaceName, parseSource, pinMarketplace, readRegistry, removeMarketplace } from "../../loader/core.js"
+import type { CoreAddResult } from "../../loader/core.js"
+import { installLoader } from "../loader"
+import { reportRestart, reportUpgrade, reportWarnings } from "../report"
+import { promptTrust } from "./trust"
+
+export interface AddOptions {
+  explicit?: boolean
+  name?: string
+  ref?: string
+  trust?: boolean
+}
+
+// spec 05 add, minus the dialog: the core registers, decides trust from the
+// flag, saves and materializes; the CLI renders and prompts (spec 10a)
+export async function add(source: string, options: AddOptions = {}): Promise<void> {
+  // the clone line must not state a false fact: the core refuses an
+  // already-added name before it clones
+  if (isGitUrl(source)) {
+    const parsed = parseSource(source)
+    const wanted = options.name ? normaliseMarketplaceName(options.name) : parsed.name
+    if (!readRegistry().marketplaces[wanted]) console.log(`cloning ${parsed.url}...`)
+  }
+  let result: CoreAddResult
+  try {
+    result = await addMarketplace(source, options)
+  } catch (err) {
+    // a refused add still owes the user the diagnostics behind the refusal
+    // (spec 06); they ride the error as data — the core never prints
+    const warnings = (err as { warnings?: unknown }).warnings
+    if (Array.isArray(warnings)) reportWarnings(warnings)
+    throw err
+  }
+  reportWarnings(result.warnings)
+  // a prompted decision re-materializes: the two passes are reported as one —
+  // created links sum, warnings union. A grant makes pass 1's "blocked
+  // (untrusted)" lines false, so they do not carry over
+  let created = result.report.created
+  let warnings = result.report.warnings
+  if (result.trustComponents.length && options.trust === undefined) {
+    const decision = await promptTrust(result.name, result.dir, result.trustComponents)
+    if (decision === "granted" || decision === "denied") {
+      const second = decision === "granted" ? await grantTrust(result.name) : await denyTrust(result.name)
+      if (second.report) {
+        created += second.report.created
+        const carry = decision === "granted"
+          ? warnings.filter((warning) => !warning.startsWith("blocked (untrusted): "))
+          : warnings
+        warnings = [...new Set([...carry, ...second.report.warnings])]
+      }
+    }
+  }
+  reportWarnings(warnings)
+  reportRestart(created)
+  installLoader()
+  reportUpgrade(result.wasV1)
+  reportAdded(result)
+}
+
+function reportAdded(result: CoreAddResult): void {
+  console.log(`added marketplace "${result.name}"`)
+  for (const plugin of result.plugins) {
+    const parts: string[] = []
+    if (plugin.components.agent) parts.push(`${plugin.components.agent.length} agents`)
+    if (plugin.components.command) parts.push(`${plugin.components.command.length} commands`)
+    if (plugin.components.skill) parts.push(`${plugin.components.skill.length} skills`)
+    if (plugin.components.plugin) parts.push(`${plugin.components.plugin.length} plugins`)
+    if (plugin.components.mcp) parts.push(`${plugin.components.mcp.length} mcp servers`)
+    const available = result.mode === "explicit" ? " — available, not installed" : ""
+    console.log(`  ${plugin.name} (${parts.join(", ")})${available}`)
+  }
+  console.log("commands and agents are available as /<plugin>:<name> in every project")
+}
+
+export function remove(name: string): void {
+  const result = removeMarketplace(name)
+  reportWarnings(result.warnings)
+  reportUpgrade(result.wasV1)
+  console.log(`removed marketplace "${result.name}"`)
+  for (const plugin of result.owned) {
+    const parts: string[] = []
+    if (plugin.components.agent) parts.push(`${plugin.components.agent.length} agents`)
+    if (plugin.components.command) parts.push(`${plugin.components.command.length} commands`)
+    if (plugin.components.skill) parts.push(`${plugin.components.skill.length} skills`)
+    if (plugin.components.plugin) parts.push(`${plugin.components.plugin.length} plugins`)
+    if (plugin.components.mcp) parts.push(`${plugin.components.mcp.length} mcp servers`)
+    console.log(`  ${plugin.name}: ${parts.join(", ")} removed`)
+  }
+}
+
+// spec 08: pinning is branch- and tag-following, never commit-freezing; the
+// core validates the ref by fetching it before saving it
+export async function pin(name: string, ref?: string, clear = false): Promise<void> {
+  const result = await pinMarketplace(name, clear ? null : ref)
+  reportUpgrade(result.wasV1)
+  console.log(clear
+    ? `marketplace "${name}" unpinned (following the default branch)`
+    : `marketplace "${name}" pinned to ${ref}`)
+}