@wntic/ocm 0.1.0

package/src/commands/plugins.ts

@@ -0,0 +1,127 @@
+import { existsSync, mkdtempSync, readlinkSync, rmSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+import { isGitUrl, parseSource, resolvePlugin, setEnabled } from "../../loader/core.js"
+import type { CorePluginComponents } from "../../loader/core.js"
+import { OPENCODE_AGENTS_DIR, OPENCODE_COMMANDS_DIR, OPENCODE_GLOBAL_CONFIG, OPENCODE_PLUGINS_DIR } from "../paths"
+import { loadRegistry, loadRegistryForWrite, saveRegistry } from "../registry"
+import { discoverMarketplace } from "../discovery"
+import { clone } from "../git"
+import { reportRestart, reportUpgrade, reportWarnings } from "../report"
+
+function componentSummary(components: CorePluginComponents): string {
+  const parts: string[] = []
+  for (const [type, files] of Object.entries(components)) {
+    if (files?.length) parts.push(`${files.length} ${type}${files.length === 1 ? "" : "s"}`)
+  }
+  return parts.join(", ")
+}
+
+// spec 05 install: the core flips the record, saves and materializes; the
+// CLI renders — disagreement first, then the upgrade, then the links report
+export function install(arg: string, force = false): void {
+  const result = setEnabled(arg, true, { force })
+  if (result.disagreement) reportWarnings([result.disagreement])
+  reportUpgrade(result.wasV1)
+  reportWarnings(result.report.warnings)
+  console.log(`installed ${result.plugin}@${result.marketplace} (${componentSummary(result.components)})`)
+  reportRestart(result.report.created)
+}
+
+export function uninstall(arg: string): void {
+  const result = setEnabled(arg, false)
+  reportUpgrade(result.wasV1)
+  reportWarnings(result.report.warnings)
+  reportRestart(result.report.removed)
+  console.log(`uninstalled ${result.plugin}@${result.marketplace}`)
+}
+
+export function setMode(name: string, mode: string): void {
+  if (mode !== "auto" && mode !== "explicit") {
+    throw new Error(`unknown mode "${mode}" (expected "auto" or "explicit")`)
+  }
+  const { registry, wasV1 } = loadRegistryForWrite()
+  const entry = registry.marketplaces[name]
+  if (!entry) throw new Error(`marketplace "${name}" not found (ocm list)`)
+  entry.mode = mode
+  saveRegistry(registry)
+  reportUpgrade(wasV1)
+  console.log(`marketplace "${name}" mode: ${mode}`)
+}
+
+// a plugin arg is a bare name or name@marketplace; anything with a url
+// scheme or a slash is a source
+function isPluginArg(source: string): boolean {
+  if (isGitUrl(source) || source.includes("/")) return false
+  return /^[a-z0-9]+(-[a-z0-9]+)*(@[a-z0-9]+(-[a-z0-9]+)*)?$/.test(source)
+}
+
+export function scan(source: string): void {
+  if (isPluginArg(source) && !existsSync(source)) {
+    scanPlugin(source)
+    return
+  }
+  const parsed = parseSource(source)
+  let dir = parsed.url
+  let temp: string | null = null
+  if (parsed.isGit) {
+    // scan never writes outside its temp directory (spec 05): the clone
+    // lives in the os temp dir, not the marketplaces store
+    temp = mkdtempSync(join(tmpdir(), "ocm-scan-"))
+    console.log(`cloning ${parsed.url}...`)
+    try {
+      clone(parsed.url, temp, parsed.ref)
+    } catch (err) {
+      rmSync(temp, { recursive: true, force: true })
+      throw err
+    }
+    dir = parsed.subdir ? join(temp, parsed.subdir) : temp
+  }
+  try {
+    const discovered = discoverMarketplace(dir)
+    reportWarnings(discovered.warnings)
+    const plugins = [...discovered.plugins.values()]
+    if (!plugins.length) {
+      console.log(`no plugins found in ${source}`)
+      return
+    }
+    console.log(`${plugins.length} plugin(s) would be installed from ${parsed.url}:`)
+    for (const plugin of plugins) {
+      console.log(`  ${plugin.name} (${componentSummary(plugin.components)})`)
+    }
+  } finally {
+    if (temp) rmSync(temp, { recursive: true, force: true })
+  }
+}
+
+function scanPlugin(arg: string): void {
+  const { marketplace, plugin, entry } = resolvePlugin(loadRegistry(), arg)
+  const record = entry.plugins[plugin]!
+  console.log(`installing ${plugin}@${marketplace} would materialize:`)
+  for (const file of record.components.command ?? []) {
+    reportScanDest(join(OPENCODE_COMMANDS_DIR, `${plugin}:${file}`), entry.dir)
+  }
+  for (const file of record.components.agent ?? []) {
+    reportScanDest(join(OPENCODE_AGENTS_DIR, `${plugin}:${file}`), entry.dir)
+  }
+  for (const rel of record.components.skill ?? []) {
+    console.log(`  skill ${plugin}:${rel}`)
+  }
+  for (const file of record.components.plugin ?? []) {
+    console.log(`  plugin ${join(OPENCODE_PLUGINS_DIR, `ocm--${plugin}--${file}`)}`)
+  }
+  for (const server of record.components.mcp ?? []) {
+    console.log(`  mcp ocm--${plugin}--${server} (${OPENCODE_GLOBAL_CONFIG})`)
+  }
+}
+
+// a dest that exists but is not a symlink into this marketplace is a
+// collision install would refuse (or --force displace)
+function reportScanDest(dest: string, marketplaceDir: string): void {
+  let target
+  try {
+    target = readlinkSync(dest)
+  } catch {}
+  const owned = target !== undefined && (target === marketplaceDir || target.startsWith(`${marketplaceDir}/`))
+  console.log(`  ${dest}${owned ? "" : " (collision: install would refuse without --force)"}`)
+}

package/src/commands/search.ts

@@ -0,0 +1,86 @@
+import { DEFAULT_SYNC_INTERVAL_MS, searchPlugins } from "../../loader/core.js"
+import type { CoreSearchMatch } from "../../loader/core.js"
+import { loadRegistry } from "../registry"
+import type { MarketplaceEntry, MarketplacePlugin } from "../types"
+
+export interface SearchOptions {
+  enabledOnly?: boolean
+  json?: boolean
+}
+
+// blocked is a trust state, not an enabled state: executable components of
+// an untrusted marketplace stay listed, just not linked (spec 07)
+function isBlocked(entry: MarketplaceEntry, record: MarketplacePlugin): boolean {
+  if (entry.trust.code === "granted") return false
+  return Boolean(record.components.plugin?.length || record.components.mcp?.length)
+}
+
+// the names the summary line prints: commands and agents drop their .md
+function bareComponents(components: Partial<Record<string, string[]>>): Partial<Record<string, string[]>> {
+  const out: Partial<Record<string, string[]>> = {}
+  for (const type of ["command", "agent"] as const) {
+    if (components[type]?.length) out[type] = components[type]!.map((file) => file.replace(/\.md$/, ""))
+  }
+  for (const type of ["skill", "plugin", "mcp"] as const) {
+    if (components[type]?.length) out[type] = [...components[type]!]
+  }
+  return out
+}
+
+const LABELS: Record<string, string> = { command: "commands", agent: "agents", skill: "skills", plugin: "plugins", mcp: "mcp" }
+
+function componentSummary(components: Partial<Record<string, string[]>>): string {
+  return Object.entries(bareComponents(components))
+    .map(([type, names]) => `${LABELS[type]}: ${names!.join(", ")}`)
+    .join(" · ")
+}
+
+// a stale or failed sync is a common cause of a plugin appearing not to exist
+function staleSync(entry: MarketplaceEntry): boolean {
+  const sync = entry.lastSync
+  if (!sync || !sync.ok) return true
+  const at = Date.parse(sync.at)
+  if (Number.isNaN(at)) return true
+  return Date.now() - at >= (entry.syncIntervalMs ?? DEFAULT_SYNC_INTERVAL_MS)
+}
+
+export function search(queryArg: string, options: SearchOptions = {}): void {
+  const matches = searchPlugins(queryArg, { enabledOnly: options.enabledOnly })
+  if (!matches.length) {
+    const registry = loadRegistry()
+    const hint = Object.values(registry.marketplaces).some(staleSync)
+      ? "\n  a marketplace sync is stale or failed; run ocm update"
+      : ""
+    throw new Error(`no matches for "${queryArg}"${hint}`)
+  }
+  if (options.json) {
+    console.log(JSON.stringify(matches.map((match: CoreSearchMatch) => ({
+      plugin: match.plugin,
+      marketplace: match.marketplace,
+      version: match.record.version,
+      category: match.record.manifest.category ?? null,
+      description: match.record.manifest.description ?? null,
+      enabled: match.record.enabled,
+      blocked: isBlocked(match.entry, match.record),
+      matched: match.matched.length ? match.matched : null,
+      components: bareComponents(match.record.components),
+    })), null, 2))
+    return
+  }
+  for (const match of matches) {
+    const head = [
+      `${match.plugin}@${match.marketplace}`,
+      match.record.version,
+      match.record.manifest.category,
+      match.record.manifest.description,
+    ].filter(Boolean).join("  ")
+    const markers = `${!match.record.enabled ? " (disabled)" : ""}${isBlocked(match.entry, match.record) ? " (blocked)" : ""}`
+    console.log(`${head}${markers}`)
+    if (match.matched.length) {
+      for (const component of match.matched) console.log(`  matched: ${component}`)
+    } else {
+      const summary = componentSummary(match.record.components)
+      if (summary) console.log(`  ${summary}`)
+    }
+  }
+}

package/src/commands/trust.ts

@@ -0,0 +1,146 @@
+import { denyEntry, denyTrust, executableComponents, grantEntry, grantTrust, trustFingerprint } from "../../loader/core.js"
+import type { CoreExecutableComponent } from "../../loader/core.js"
+import { componentRoot, materializeLinks } from "../install"
+import { loadRegistryForWrite, saveRegistry } from "../registry"
+import { reportRestart, reportUpgrade, reportWarnings } from "../report"
+import type { MarketplaceEntry } from "../types"
+
+// the block every trust decision prints before asking: what runs, where it
+// lives, and what it can do (spec 07)
+function printTrustBlock(name: string, dir: string, components: CoreExecutableComponent[]): void {
+  console.error(`marketplace "${name}" ships code that opencode will execute:`)
+  for (const component of components) {
+    if (component.kind === "plugin") {
+      console.error(`  plugin  ${component.plugin}/${component.name.replace(/\.[jt]s$/, "")} (${component.rel})`)
+    } else {
+      const value = component.value as Record<string, unknown> | undefined
+      const detail =
+        value && typeof value.url === "string"
+          ? `remote server: ${value.url}`
+          : `local server: ${Array.isArray(value?.command) ? (value.command as string[]).join(" ") : ""}`
+      console.error(`  mcp     ${component.plugin}/${component.name} (${detail})`)
+    }
+  }
+  console.error("this code runs with your shell's permissions on every opencode start.")
+  console.error(`review it at ${dir}`)
+  console.error("trust this marketplace to run code? [y/N/skip]")
+}
+
+async function readAnswer(): Promise<string> {
+  const { createInterface } = await import("node:readline/promises")
+  const rl = createInterface({ input: process.stdin, output: process.stdout })
+  try {
+    return (await rl.question("")).trim().toLowerCase()
+  } finally {
+    rl.close()
+  }
+}
+
+// the prompt half of a trust decision: renders the block and reads the
+// answer. The mutation is the caller's — the core never prompts (spec 10a)
+export async function promptTrust(
+  name: string,
+  dir: string,
+  components: CoreExecutableComponent[],
+): Promise<"granted" | "denied" | "skipped"> {
+  printTrustBlock(name, dir, components)
+  if (!process.stdin.isTTY) return "skipped"
+  const answer = await readAnswer()
+  if (answer === "y" || answer === "yes") return "granted"
+  if (answer === "skip") return "skipped"
+  return "denied"
+}
+
+// the update-time decision, applied in memory: the update engine saves the
+// registry after reconcile, so a mid-update core call would be overwritten
+// by that later save
+async function decideTrust(name: string, entry: MarketplaceEntry, root: string, flag?: boolean): Promise<boolean> {
+  const components = executableComponents(root, entry)
+  if (!components.length) return false
+  if (flag === true) {
+    grantEntry(entry, components)
+    return true
+  }
+  if (flag === false) {
+    denyEntry(entry)
+    return false
+  }
+  const decision = await promptTrust(name, entry.dir, components)
+  if (decision === "granted") {
+    grantEntry(entry, components)
+    return true
+  }
+  if (decision === "denied") denyEntry(entry)
+  return false
+}
+
+function reportChanged(name: string, entry: MarketplaceEntry, components: CoreExecutableComponent[]): void {
+  const recorded = entry.trust.components ?? {}
+  const current = new Map(components.map((c) => [c.rel, c.hash]))
+  const added = components.filter((c) => !(c.rel in recorded)).map((c) => c.rel)
+  const removed = Object.keys(recorded).filter((rel) => !current.has(rel))
+  const modified = components.filter((c) => c.rel in recorded && recorded[c.rel] !== c.hash).map((c) => c.rel)
+  console.error(`marketplace "${name}" shipped code that changed since you trusted it:`)
+  for (const rel of added) console.error(`  added: ${rel}`)
+  for (const rel of removed) console.error(`  removed: ${rel}`)
+  for (const rel of modified) console.error(`  modified: ${rel}`)
+}
+
+// the update-time decision: an unchanged or denied grant stands; a drifted
+// one reports the diff and re-prompts (spec 07)
+export async function decideUpdateTrust(
+  name: string,
+  entry: MarketplaceEntry,
+  root: string,
+  flag?: boolean,
+): Promise<boolean> {
+  const components = executableComponents(root, entry)
+  if (!components.length || entry.trust.code === "denied") return false
+  if (entry.trust.code === "granted" && entry.trust.fingerprint === trustFingerprint(components)) return false
+  if (entry.trust.code === "granted") reportChanged(name, entry, components)
+  return decideTrust(name, entry, root, flag)
+}
+
+export async function trust(name: string): Promise<void> {
+  const { registry, wasV1 } = loadRegistryForWrite()
+  const entry = registry.marketplaces[name]
+  if (!entry) throw new Error(`marketplace "${name}" not found (ocm list)`)
+  const root = componentRoot(entry)
+  const components = executableComponents(root, entry)
+  if (!components.length) {
+    console.log(`marketplace "${name}" ships no code; nothing to trust`)
+    return
+  }
+  const decision = await promptTrust(name, entry.dir, components)
+  if (decision === "granted") {
+    const result = grantTrust(name)
+    if (result.report) {
+      reportWarnings(result.report.warnings)
+      reportRestart(result.report.created)
+    }
+    console.log(`marketplace "${name}" trusted to run code`)
+    reportUpgrade(result.wasV1)
+    return
+  }
+  if (decision === "denied") {
+    const result = denyTrust(name)
+    reportWarnings(result.report.warnings)
+    reportRestart(result.report.created)
+    reportUpgrade(result.wasV1)
+    return
+  }
+  // skipped: the registry is still saved (a v1 migration) and materialized
+  saveRegistry(registry)
+  const links = materializeLinks(name, entry)
+  reportWarnings(links.warnings)
+  reportRestart(links.created)
+  reportUpgrade(wasV1)
+}
+
+export async function untrust(name: string): Promise<void> {
+  const result = denyTrust(name)
+  reportWarnings(result.report.warnings)
+  reportRestart(result.report.removed)
+  console.log(`marketplace "${name}" no longer trusted; executable components removed`)
+  reportUpgrade(result.wasV1)
+}

package/src/commands/update-report.ts

@@ -0,0 +1,123 @@
+import { relative } from "node:path"
+import { git } from "../git"
+import type { DiscoveredPlugin, MarketplaceEntry, MarketplacePlugin } from "../types"
+
+export interface FileChange {
+  mark: "+" | "~" | "-"
+  path: string
+}
+
+export interface PluginReport {
+  name: string
+  fresh: boolean
+  from: string | null
+  to: string | null
+  files: FileChange[]
+  note: string | null
+}
+
+export interface MarketplaceReport {
+  name: string
+  ok: boolean
+  error: string | null
+  note: string | null
+  before: string | null
+  after: string | null
+  changed: boolean
+  renamed: { from: string; to: string }[]
+  removed: string[]
+  pruned: string[]
+  refused: { from: string; to: string; incumbent: string }[]
+  plugins: PluginReport[]
+  warnings: string[]
+  materialized: { created: number; removed: number; skipped: number } | null
+}
+
+// spec 08: the per-plugin file list is git's own answer — diff the revision
+// pair and filter to the plugin's source prefix
+export function pluginFileChanges(
+  entry: MarketplaceEntry,
+  before: string | null,
+  after: string | null,
+  plugins: DiscoveredPlugin[],
+): Map<string, FileChange[]> {
+  const changes = new Map<string, FileChange[]>()
+  if (!before || !after || before === after) return changes
+  const diff = git(["diff", "--name-status", before, after], entry.dir)
+  if (!diff.ok) return changes
+  for (const line of diff.stdout.split("\n")) {
+    const [status, ...paths] = line.split("\t")
+    if (!status || !paths.length) continue
+    const mark = status.startsWith("A") ? "+" : status.startsWith("D") ? "-" : "~"
+    // R lines carry old and new; the new path is what ships now
+    const path = paths[paths.length - 1]!
+    for (const plugin of plugins) {
+      const prefix = `${relative(entry.dir, plugin.dir)}/`
+      if (path.startsWith(prefix)) {
+        const list = changes.get(plugin.name) ?? []
+        list.push({ mark, path: path.slice(prefix.length) })
+        changes.set(plugin.name, list)
+      }
+    }
+  }
+  return changes
+}
+
+export function pluginReports(
+  plugins: DiscoveredPlugin[],
+  records: Record<string, MarketplacePlugin>,
+  versions: Map<string, string | null>,
+  known: Set<string>,
+  files: Map<string, FileChange[]>,
+): PluginReport[] {
+  const reports: PluginReport[] = []
+  for (const plugin of plugins) {
+    const record = records[plugin.name]
+    if (!record) continue
+    const from = versions.get(plugin.name) ?? null
+    const fresh = !known.has(plugin.name)
+    const pluginFiles = files.get(plugin.name) ?? []
+    if (!fresh && from === record.version && !pluginFiles.length) continue
+    const note = record.collision
+      ? `not installed (name provided by ${record.collision})`
+      : fresh
+        ? "installed (auto)"
+        : null
+    reports.push({ name: plugin.name, fresh, from, to: record.version, files: pluginFiles, note })
+  }
+  return reports
+}
+
+export function renderMarketplace(report: MarketplaceReport, quiet: boolean): void {
+  if (quiet && report.ok && !report.changed) return
+  console.log(`updating ${report.name}...`)
+  for (const warning of report.warnings) console.error(`  warning: ${warning}`)
+  if (report.note) {
+    console.error(`marketplace "${report.name}" ${report.note}`)
+    return
+  }
+  if (!report.ok) {
+    console.error(`  failed: ${report.error}`)
+    return
+  }
+  if (report.before && report.after) {
+    console.log(report.before === report.after ? "  already up to date" : `  ${report.before.slice(0, 7)} → ${report.after.slice(0, 7)}`)
+  } else if (report.materialized) {
+    // no revision pair (local marketplace, re-clone): the materializer's own
+    // counts are the report (spec 08)
+    const m = report.materialized
+    console.log(`  ${m.created} created, ${m.removed} removed, ${m.skipped} skipped`)
+  }
+  for (const rename of report.renamed) console.log(`  renamed ${rename.from} → ${rename.to}`)
+  for (const name of report.removed) console.log(`  removed ${name}`)
+  for (const name of report.pruned) console.log(`  ${name} removed (no longer in the marketplace)`)
+  for (const refusal of report.refused) {
+    console.log(`  refused rename ${refusal.from} → ${refusal.to}: "${refusal.to}" is already provided by marketplace "${refusal.incumbent}"`)
+  }
+  for (const plugin of report.plugins) {
+    const detail = plugin.note ?? (plugin.from === plugin.to ? null : `${plugin.from ?? "?"} → ${plugin.to ?? "?"}`)
+    console.log(`  ${plugin.name}${detail ? `   ${detail}` : ""}`)
+    for (const file of plugin.files) console.log(`    ${file.mark} ${file.path}`)
+  }
+  if (report.materialized && report.materialized.created > 0) console.log("  restart opencode to activate")
+}

package/src/commands/update.ts

@@ -0,0 +1,160 @@
+import { existsSync, mkdirSync } from "node:fs"
+import { dirname } from "node:path"
+import { pullRepo } from "../../loader/core.js"
+import { componentRoot, materializeLinks, registerPlugins, removeMcpKeys } from "../install"
+import { discoverMarketplace, readRenames } from "../discovery"
+import { applyRenames, resolveChains } from "../renames"
+import { clone, git } from "../git"
+import { loadRegistryForWrite, saveRegistry } from "../registry"
+import { installLoader } from "../loader"
+import { reportUpgrade } from "../report"
+import type { MarketplaceEntry, Registry } from "../types"
+import { decideUpdateTrust } from "./trust"
+import { pluginFileChanges, pluginReports, renderMarketplace } from "./update-report"
+import type { MarketplaceReport } from "./update-report"
+
+export interface UpdateOptions {
+  quiet?: boolean
+  json?: boolean
+  trust?: boolean
+}
+
+// `ocm update` takes a marketplace, a plugin@marketplace, or nothing
+function resolveTarget(registry: Registry, target?: string): { names: string[]; plugin?: string } {
+  if (!target) return { names: Object.keys(registry.marketplaces) }
+  const at = target.indexOf("@")
+  if (at === -1) {
+    if (!registry.marketplaces[target]) throw new Error(`marketplace "${target}" not found (ocm list)`)
+    return { names: [target] }
+  }
+  const plugin = target.slice(0, at)
+  const name = target.slice(at + 1)
+  const entry = registry.marketplaces[name]
+  if (!entry) throw new Error(`marketplace "${name}" not found (ocm list)`)
+  if (!entry.plugins[plugin]) {
+    throw new Error(`plugin "${plugin}" not found in marketplace "${name}" (ocm list --all)`)
+  }
+  return { names: [name], plugin }
+}
+
+export async function update(target?: string, options: UpdateOptions = {}): Promise<void> {
+  const { registry, wasV1 } = loadRegistryForWrite()
+  const { names, plugin } = resolveTarget(registry, target)
+  if (!names.length) {
+    if (options.json) console.log(JSON.stringify({ marketplaces: [] }, null, 2))
+    else console.log("no marketplaces added yet (ocm add <url|path>)")
+    return
+  }
+  const reports: MarketplaceReport[] = []
+  let installedLoader = false
+  for (const name of names) {
+    const report = await updateOne(registry, name, options.trust, plugin)
+    reports.push(report)
+    if (!options.json) renderMarketplace(report, options.quiet === true)
+    if (report.ok && !installedLoader) {
+      installLoader()
+      installedLoader = true
+    }
+  }
+  if (options.json) console.log(JSON.stringify({ marketplaces: reports }, null, 2))
+  reportUpgrade(wasV1)
+  const failed = reports.filter((report) => !report.ok).map((report) => report.name)
+  if (failed.length) {
+    throw new Error(`update failed for ${failed.length} marketplace(s): ${failed.join(", ")}`)
+  }
+}
+
+// pull, or re-clone a cleared cache (spec 08 edge cases); the revision
+// pair and the re-clone note land on the report
+async function pullMarketplace(entry: MarketplaceEntry, report: MarketplaceReport): Promise<void> {
+  if (entry.local) {
+    // a local directory is the user's: reported and skipped, never re-created
+    if (!existsSync(entry.dir)) report.note = `directory missing (${entry.dir}), skipping`
+  } else if (existsSync(entry.dir)) {
+    const pull = await pullRepo(entry.dir, entry.ref)
+    if (!pull.ok) throw new Error(pull.output)
+    report.before = pull.before
+    report.after = pull.after
+    if (pull.dirty) report.warnings.push(`${entry.dir} has local changes; discarded (the cache is not an editing surface)`)
+  } else {
+    if (!entry.url) throw new Error(`clone directory missing (${entry.dir}) and no url recorded; remove and re-add the marketplace`)
+    console.error(`clone directory missing, re-cloning ${entry.url}...`)
+    mkdirSync(dirname(entry.dir), { recursive: true })
+    clone(entry.url, entry.dir, entry.ref)
+    report.after = git(["rev-parse", "HEAD"], entry.dir).stdout
+  }
+}
+
+// one marketplace, wrapped: a failure records lastSync.ok = false and moves
+// on, never touching this marketplace's links (spec 08)
+async function updateOne(registry: Registry, name: string, trust?: boolean, plugin?: string): Promise<MarketplaceReport> {
+  const entry = registry.marketplaces[name]!
+  const report: MarketplaceReport = {
+    name, ok: true, error: null, note: null, before: null, after: null, changed: false,
+    renamed: [], removed: [], pruned: [], refused: [], plugins: [], warnings: [], materialized: null,
+  }
+  try {
+    await pullMarketplace(entry, report)
+    if (!report.note) {
+      reconcile(registry, name, report, plugin)
+      await decideUpdateTrust(name, entry, componentRoot(entry), trust)
+      if (report.after) entry.revision = report.after
+      entry.lastSync = { at: new Date().toISOString(), ok: true, error: null }
+      saveRegistry(registry)
+      const links = materializeLinks(name, entry, false, plugin)
+      report.warnings.push(...links.warnings)
+      report.materialized = { created: links.created, removed: links.removed, skipped: links.skipped }
+      report.changed =
+        report.before !== report.after ||
+        report.renamed.length > 0 ||
+        report.removed.length > 0 ||
+        report.pruned.length > 0 ||
+        report.refused.length > 0 ||
+        report.plugins.length > 0 ||
+        links.created > 0
+    }
+  } catch (err) {
+    report.ok = false
+    report.error = err instanceof Error ? err.message : String(err)
+    entry.lastSync = { at: new Date().toISOString(), ok: false, error: report.error }
+    try {
+      saveRegistry(registry)
+    } catch {}
+  }
+  return report
+}
+
+// discover, apply renames, reconcile against the registry (spec 08 step 4)
+function reconcile(registry: Registry, name: string, report: MarketplaceReport, plugin?: string): void {
+  const entry = registry.marketplaces[name]!
+  const root = componentRoot(entry)
+  const discovered = discoverMarketplace(root)
+  report.warnings.push(...discovered.warnings)
+  const plugins = [...discovered.plugins.values()]
+  const renames = readRenames(root, plugins)
+  const { resolved, cycles } = resolveChains(renames)
+  for (const cycle of cycles) report.warnings.push(`rename cycle ignored: ${cycle.join(" → ")} → ${cycle[0]}`)
+  const applied = applyRenames(registry, name, entry, discovered.plugins, resolved)
+  const pruned: string[] = []
+  for (const pluginName of Object.keys(entry.plugins)) {
+    if (!discovered.plugins.has(pluginName) && !(pluginName in resolved)) {
+      delete entry.plugins[pluginName]
+      pruned.push(pluginName)
+    }
+  }
+  const mcpWarning = removeMcpKeys([...applied.removed, ...applied.renamed.map((rename) => rename.from), ...pruned])
+  if (mcpWarning) report.warnings.push(mcpWarning)
+  const versions = new Map(Object.entries(entry.plugins).map(([pluginName, plugin]) => [pluginName, plugin.version]))
+  const known = new Set(Object.keys(entry.plugins))
+  let registrable = plugins.filter((candidate) => !applied.excluded.has(candidate.name))
+  // a plugin-scoped update registers no newly shipped plugin: auto-install
+  // is the full pass's job, not this one's (spec 08)
+  if (plugin) registrable = registrable.filter((candidate) => candidate.name in entry.plugins)
+  registerPlugins(registry, name, registrable)
+  Object.assign(entry.plugins, applied.kept)
+  report.renamed = applied.renamed
+  report.removed = applied.removed
+  report.pruned = pruned
+  report.refused = applied.refused
+  report.plugins = pluginReports(plugins, entry.plugins, versions, known, pluginFileChanges(entry, report.before, report.after, plugins))
+}