@wntic/ocm 0.1.0

package/loader/discovery.js

@@ -0,0 +1,162 @@
+import { existsSync, readdirSync, readFileSync, realpathSync, statSync } from "node:fs"
+import { join } from "node:path"
+import { isRecord } from "./registry.js"
+
+// plugin names become command/agent namespaces and file-name prefixes, so
+// they must be lowercase kebab
+export const PLUGIN_NAME_RE = /^[a-z0-9]+(-[a-z0-9]+)*$/
+
+// `commands` and `command` (likewise agents, skills) are both opencode-valid
+// source directories, so both are discovered
+function listMdFiles(pluginDir, dirs) {
+  const names = new Set()
+  for (const dir of dirs) {
+    try {
+      for (const file of readdirSync(join(pluginDir, dir))) if (file.endsWith(".md")) names.add(file)
+    } catch {}
+  }
+  return [...names].sort()
+}
+
+function listSkillDirs(pluginDir, dirs) {
+  const found = new Set()
+  const seen = new Set()
+  const walk = (dir, rel) => {
+    let real
+    try {
+      real = realpathSync(dir)
+    } catch {
+      return
+    }
+    if (seen.has(real)) return
+    seen.add(real)
+    let entries
+    try {
+      entries = readdirSync(dir)
+    } catch {
+      return
+    }
+    for (const entry of entries) {
+      const child = join(dir, entry)
+      let isDir = false
+      try {
+        isDir = statSync(child).isDirectory()
+      } catch {}
+      if (!isDir) continue
+      const childRel = rel ? `${rel}/${entry}` : entry
+      if (existsSync(join(child, "SKILL.md"))) found.add(childRel)
+      walk(child, childRel)
+    }
+  }
+  for (const dir of dirs) walk(join(pluginDir, dir), "")
+  return [...found].sort()
+}
+
+// `plugin` and `plugins` are both opencode-valid source directories for
+// server plugin modules (spec 06)
+function listJsFiles(pluginDir, dirs) {
+  const names = new Set()
+  for (const dir of dirs) {
+    try {
+      for (const file of readdirSync(join(pluginDir, dir))) {
+        if (file.endsWith(".js") || file.endsWith(".ts")) names.add(file)
+      }
+    } catch {}
+  }
+  return [...names].sort()
+}
+
+// mcp.json holds opencode's mcp entry shape; the server names are its keys
+function listMcpServers(pluginDir) {
+  try {
+    const parsed = JSON.parse(readFileSync(join(pluginDir, "mcp.json"), "utf8"))
+    if (isRecord(parsed)) return Object.keys(parsed).sort()
+  } catch {}
+  return []
+}
+
+// the mcp source file: the marketplace entry's mcpServers path when it
+// declares one, else the plugin directory's own mcp.json (spec 06)
+export function mcpSourceFile(dir, entry, plugin) {
+  const declared = entry?.plugins?.[plugin.name]?.manifest?.mcpServers
+  return typeof declared === "string" ? join(dir, declared) : join(plugin.dir, "mcp.json")
+}
+
+// a name defined in both the singular and plural form of a component
+// directory is a clash add refuses rather than guess (spec 06)
+export function dirClashes(pluginDir) {
+  const clashes = []
+  const pairs = [
+    ["commands", "command", listMdFiles],
+    ["agents", "agent", listMdFiles],
+    ["skills", "skill", listSkillDirs],
+    ["plugin", "plugins", listJsFiles],
+  ]
+  for (const [a, b, list] of pairs) {
+    const other = list(pluginDir, [b])
+    for (const name of list(pluginDir, [a])) {
+      if (other.includes(name)) clashes.push(`${name} in both "${a}" and "${b}"`)
+    }
+  }
+  return clashes
+}
+
+// does this directory hold a SKILL.md at any depth? such entries get their
+// own mirror, so they must never be linked into a sibling mirror
+export function containsSkillMd(dir, seen = new Set()) {
+  let real
+  try {
+    real = realpathSync(dir)
+  } catch {
+    return false
+  }
+  if (seen.has(real)) return false
+  seen.add(real)
+  let entries
+  try {
+    entries = readdirSync(dir)
+  } catch {
+    return false
+  }
+  for (const entry of entries) {
+    if (entry === "SKILL.md") return true
+    const child = join(dir, entry)
+    let isDir = false
+    try {
+      isDir = statSync(child).isDirectory()
+    } catch {}
+    if (isDir && containsSkillMd(child, seen)) return true
+  }
+  return false
+}
+
+export function discoverPlugins(marketplaceDir) {
+  const plugins = []
+  const collect = (pluginDir) => {
+    const components = {}
+    const commands = listMdFiles(pluginDir, ["commands", "command"])
+    if (commands.length) components.command = commands
+    const agents = listMdFiles(pluginDir, ["agents", "agent"])
+    if (agents.length) components.agent = agents
+    const skills = listSkillDirs(pluginDir, ["skills", "skill"])
+    if (skills.length) components.skill = skills
+    const pluginFiles = listJsFiles(pluginDir, ["plugin", "plugins"])
+    if (pluginFiles.length) components.plugin = pluginFiles
+    const mcpServers = listMcpServers(pluginDir)
+    if (mcpServers.length) components.mcp = mcpServers
+    if (!Object.keys(components).length) return
+    const name = pluginDir.replace(/\/+$/, "").split("/").pop()
+    plugins.push({ name: name.toLowerCase(), dir: pluginDir, components })
+  }
+  const pluginsDir = join(marketplaceDir, "plugins")
+  if (existsSync(pluginsDir)) {
+    for (const entry of readdirSync(pluginsDir).sort()) {
+      const dir = join(pluginsDir, entry)
+      try {
+        if (statSync(dir).isDirectory()) collect(dir)
+      } catch {}
+    }
+  }
+  if (!plugins.length) collect(marketplaceDir)
+  return plugins
+}

package/loader/links.js

@@ -0,0 +1,193 @@
+import {
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  readlinkSync,
+  renameSync,
+  rmSync,
+  symlinkSync,
+  writeFileSync,
+} from "node:fs"
+import { dirname, join, relative } from "node:path"
+import { containsSkillMd } from "./discovery.js"
+
+const RENDERED_MARKER = "ocm: rendered from "
+
+// raw-string prefix compare only: a raw target must never be compared against
+// a realpath'd directory (macOS puts temp dirs behind /var -> /private/var)
+function insideDir(target, dir) {
+  return target === dir || target.startsWith(dir + "/")
+}
+
+function targetsInside(target, dirs) {
+  return dirs.some((dir) => insideDir(target, dir))
+}
+
+function owningPlugin(target) {
+  const match = target.match(/\/plugins\/([^/]+)\//)
+  return match ? match[1] : null
+}
+
+// --force takes over an unowned path by moving it under the displaced dir,
+// never deleting: a mistake stays recoverable and the path is reported
+function takeOver(dest, ctx) {
+  if (!ctx.force) {
+    ctx.warnings.push(`skipped ${dest}: not managed by ocm`)
+    return false
+  }
+  const target = join(ctx.displacedDir, dest)
+  try {
+    mkdirSync(dirname(target), { recursive: true })
+    renameSync(dest, target)
+  } catch (err) {
+    ctx.warnings.push(`failed to displace ${dest}: ${err instanceof Error ? err.message : String(err)}`)
+    return false
+  }
+  ctx.warnings.push(`displaced ${dest} -> ${target}`)
+  return true
+}
+
+export function isRenderedFile(path) {
+  try {
+    return readFileSync(path, "utf8").includes(RENDERED_MARKER)
+  } catch {
+    return false
+  }
+}
+
+// link: dest is owned iff it is a symlink whose target resolves inside a
+// managed marketplace directory
+export function link(source, dest, ctx, plugin, component) {
+  let existing
+  try {
+    existing = readlinkSync(dest)
+  } catch {}
+  if (existing === source) return "ok"
+  let stat
+  try {
+    stat = lstatSync(dest)
+  } catch {}
+  if (stat && !stat.isSymbolicLink()) {
+    if (!takeOver(dest, ctx)) return "skipped"
+  }
+  if (existing !== undefined && existsSync(dest)) {
+    if (!targetsInside(existing, ctx.managed)) {
+      if (!takeOver(dest, ctx)) return "skipped"
+    } else {
+      const owner = owningPlugin(existing) ?? ctx.name
+      if (owner !== plugin || !insideDir(existing, ctx.dir)) {
+        ctx.warnings.push(`${plugin}:${component} conflicts with ${owner}:${component}`)
+        return "refused"
+      }
+    }
+  }
+  if (stat) {
+    try {
+      rmSync(dest, { force: true, recursive: true })
+    } catch {}
+  }
+  try {
+    symlinkSync(source, dest)
+    return "created"
+  } catch (err) {
+    ctx.warnings.push(`failed ${dest}: ${err instanceof Error ? err.message : String(err)}`)
+    return "skipped"
+  }
+}
+
+// render: dest is owned iff it carries the rendered marker
+function render(source, dest, transform, ctx) {
+  let output
+  try {
+    const body = transform(readFileSync(source, "utf8"))
+    if (body === null || body === undefined) return "skipped"
+    output = body.endsWith("\n") ? body : `${body}\n`
+    output += `<!-- ${RENDERED_MARKER}${relative(ctx.dir, source)} @ ${ctx.revision} -->\n`
+  } catch (err) {
+    ctx.warnings.push(`failed ${source}: ${err instanceof Error ? err.message : String(err)}`)
+    return "skipped"
+  }
+  let stat
+  try {
+    stat = lstatSync(dest)
+  } catch {}
+  if (stat) {
+    if (stat.isSymbolicLink()) {
+      if (existsSync(dest)) {
+        if (!takeOver(dest, ctx)) return "skipped"
+      }
+      try {
+        rmSync(dest, { force: true })
+      } catch {}
+    } else if (!stat.isFile()) {
+      if (!takeOver(dest, ctx)) return "skipped"
+    } else {
+      let current
+      try {
+        current = readFileSync(dest, "utf8")
+      } catch {}
+      if (current === output) return "ok"
+      if (current === undefined || !current.includes(RENDERED_MARKER)) {
+        if (!takeOver(dest, ctx)) return "skipped"
+      }
+    }
+  }
+  try {
+    writeFileSync(dest, output)
+    return "created"
+  } catch (err) {
+    ctx.warnings.push(`failed ${dest}: ${err instanceof Error ? err.message : String(err)}`)
+    return "skipped"
+  }
+}
+
+// remove owned entries not in the desired set; a symlink is ours iff it
+// points into the current marketplace, anything else iff `extra` proves it.
+// `scope` restricts the pass to one plugin's entries (plugin-scoped update).
+export function gcTargets(dir, desired, ctx, extra, scope) {
+  let removed = 0
+  let entries
+  try {
+    entries = readdirSync(dir)
+  } catch {
+    return 0
+  }
+  for (const entry of entries) {
+    if (desired.has(entry)) continue
+    if (scope !== undefined && !entry.startsWith(scope)) continue
+    const path = join(dir, entry)
+    let target
+    try {
+      target = readlinkSync(path)
+    } catch {}
+    const owned = target !== undefined ? insideDir(target, ctx.dir) : extra ? extra(path) : false
+    if (!owned) continue
+    try {
+      rmSync(path, { force: true, recursive: true })
+      removed += 1
+    } catch {}
+  }
+  return removed
+}
+
+// mirror: a real directory whose entries are link() or render()
+export function mirror(sourceDir, destDir, plan, ctx, plugin, component) {
+  mkdirSync(destDir, { recursive: true })
+  let entries
+  try {
+    entries = readdirSync(sourceDir)
+  } catch {
+    entries = []
+  }
+  const desired = new Set()
+  for (const entry of entries) {
+    if (containsSkillMd(join(sourceDir, entry))) continue
+    desired.add(entry)
+    const transform = plan[entry]
+    if (transform) render(join(sourceDir, entry), join(destDir, entry), transform, ctx)
+    else link(join(sourceDir, entry), join(destDir, entry), ctx, plugin, component)
+  }
+  return gcTargets(destDir, desired, ctx, isRenderedFile)
+}

package/loader/lint.js

@@ -0,0 +1,83 @@
+import { existsSync, readFileSync } from "node:fs"
+import { join, relative } from "node:path"
+import { discoverPlugins } from "./discovery.js"
+
+// spec 11: the portable skill frontmatter subset. opencode tolerates extras
+// today, so this is a lint, not a rule — it exists so a plugin does not
+// become a liability if that tolerance regresses.
+const PORTABLE_KEYS = new Set(["name", "description", "license", "compatibility", "metadata"])
+
+// top-level keys only: an indented line belongs to the value above it
+function frontmatterKeys(content) {
+  if (!content.startsWith("---\n")) return []
+  const close = content.indexOf("\n---\n", 3)
+  if (close === -1) return []
+  const keys = []
+  for (const line of content.slice(4, close).split("\n")) {
+    const match = line.match(/^[^\s:]+(?=:)/)
+    if (match) keys.push(match[0])
+  }
+  return keys
+}
+
+// `commands` and `command` (likewise the other types) are both opencode-valid
+// source directories, so both are searched
+function sourceFile(pluginDir, dirs, name) {
+  for (const dir of dirs) {
+    const file = join(pluginDir, dir, name)
+    if (existsSync(file)) return file
+  }
+  return null
+}
+
+// CLAUDE_PLUGIN_ROOT is the marketplace root, so a reference resolves only
+// when the plugins/<name>/ segment is written out (spec 11)
+function lintPluginRootRefs(plugin, dirs, files, marketplaceDir, warnings) {
+  for (const name of files ?? []) {
+    const file = sourceFile(plugin.dir, dirs, name)
+    if (!file) continue
+    let content
+    try {
+      content = readFileSync(file, "utf8")
+    } catch {
+      continue
+    }
+    for (const match of content.matchAll(/\$\{CLAUDE_PLUGIN_ROOT\}([^"\s]*)/g)) {
+      if (!match[1].startsWith("/plugins/")) {
+        warnings.push(
+          `${relative(marketplaceDir, file)}: \${CLAUDE_PLUGIN_ROOT}${match[1]} will not resolve` +
+            " — CLAUDE_PLUGIN_ROOT is the marketplace root, write the plugins/<name>/ segment out",
+        )
+      }
+    }
+  }
+}
+
+// spec 11 phase 1: the cross-tool lint that `ocm validate` (spec 12) renders.
+// Warnings only — an install never fails on a finding.
+export function lintCrossTool(marketplaceDir) {
+  const warnings = []
+  for (const plugin of discoverPlugins(marketplaceDir)) {
+    for (const rel of plugin.components.skill ?? []) {
+      const file = sourceFile(plugin.dir, ["skills", "skill"], join(rel, "SKILL.md"))
+      if (!file) continue
+      let content
+      try {
+        content = readFileSync(file, "utf8")
+      } catch {
+        continue
+      }
+      for (const key of frontmatterKeys(content)) {
+        if (!PORTABLE_KEYS.has(key)) {
+          warnings.push(
+            `${relative(marketplaceDir, file)}: non-portable frontmatter "${key}"` +
+              " — outside the portable subset (name, description, license, compatibility, metadata)",
+          )
+        }
+      }
+    }
+    lintPluginRootRefs(plugin, ["commands", "command"], plugin.components.command, marketplaceDir, warnings)
+    lintPluginRootRefs(plugin, ["agents", "agent"], plugin.components.agent, marketplaceDir, warnings)
+  }
+  return warnings
+}

package/loader/manifest.js

@@ -0,0 +1,158 @@
+import { existsSync, readFileSync } from "node:fs"
+import { join } from "node:path"
+import { dirClashes, discoverPlugins } from "./discovery.js"
+import { isRecord } from "./registry.js"
+
+function readJsonRecord(file) {
+  if (!existsSync(file)) return undefined
+  try {
+    const parsed = JSON.parse(readFileSync(file, "utf8"))
+    if (isRecord(parsed)) return parsed
+  } catch {}
+  return undefined
+}
+
+// a `source` or `mcpServers` path: ./-relative and inside the marketplace
+function relativePath(source) {
+  if (!source.startsWith("./") || source.split("/").includes("..")) return null
+  return source.slice(2)
+}
+
+// the metadata fields plugin.json and a marketplace entry share; the entry
+// wins because it is the more specific declaration (spec 06)
+function metadataFrom(raw) {
+  const manifest = {}
+  if (!raw) return manifest
+  if (typeof raw.description === "string") manifest.description = raw.description
+  if (typeof raw.category === "string") manifest.category = raw.category
+  if (typeof raw.version === "string") manifest.version = raw.version
+  if (typeof raw.homepage === "string") manifest.homepage = raw.homepage
+  if (typeof raw.license === "string") manifest.license = raw.license
+  if (Array.isArray(raw.tags) && raw.tags.every((tag) => typeof tag === "string")) manifest.tags = raw.tags
+  if (Array.isArray(raw.keywords) && raw.keywords.every((keyword) => typeof keyword === "string")) {
+    manifest.keywords = raw.keywords
+  }
+  return manifest
+}
+
+// spec 06: a plugin.json name that disagrees with the directory name is a
+// warning; the directory name wins because that is what the materializer
+// namespaces from
+export function nameDisagreement(pluginDir, pluginName) {
+  const raw = readJsonRecord(join(pluginDir, "plugin.json"))
+  if (typeof raw?.name !== "string" || raw.name === pluginName) return null
+  return (
+    `plugin "${pluginName}": plugin.json name "${raw.name}" disagrees with the directory name "${pluginName}"; ` +
+    "the directory name wins — rename the directory or fix plugin.json"
+  )
+}
+
+function readEntries(marketplaceDir) {
+  const entries = new Map()
+  const raw = readJsonRecord(join(marketplaceDir, "marketplace.json"))
+  if (!Array.isArray(raw?.plugins)) return entries
+  for (const entry of raw.plugins) {
+    if (isRecord(entry) && typeof entry.name === "string") entries.set(entry.name, entry)
+  }
+  return entries
+}
+
+export function discoverMarketplace(marketplaceDir) {
+  const warnings = []
+  const entries = readEntries(marketplaceDir)
+  const plugins = new Map()
+  for (const plugin of discoverPlugins(marketplaceDir)) {
+    const entry = entries.get(plugin.name)
+    const disagreement = nameDisagreement(plugin.dir, plugin.name)
+    if (disagreement) warnings.push(disagreement)
+    const fromPlugin = metadataFrom(readJsonRecord(join(plugin.dir, "plugin.json")))
+    const fromEntry = metadataFrom(entry)
+    const manifest = { ...fromPlugin, ...fromEntry }
+    // the disagreement is cached so info can annotate it from the registry
+    // alone, with the marketplace directory deleted (spec 09)
+    const conflicts = Object.keys(fromEntry).filter(
+      (key) => key in fromPlugin && JSON.stringify(fromPlugin[key]) !== JSON.stringify(fromEntry[key]),
+    )
+    if (conflicts.length) manifest.conflicts = conflicts.sort()
+    const components = { ...plugin.components }
+    if (typeof entry?.defaultEnabled === "boolean") manifest.defaultEnabled = entry.defaultEnabled
+    if (typeof entry?.mcpServers === "string") {
+      const rel = relativePath(entry.mcpServers)
+      const servers = rel === null ? undefined : readJsonRecord(join(marketplaceDir, rel))
+      if (servers) {
+        manifest.mcpServers = entry.mcpServers
+        components.mcp = Object.keys(servers).sort()
+      } else {
+        warnings.push(`plugin "${plugin.name}": mcpServers path "${entry.mcpServers}" is not a JSON object in ${marketplaceDir}`)
+      }
+    }
+    plugins.set(plugin.name, {
+      name: plugin.name,
+      dir: plugin.dir,
+      source: plugin.dir,
+      components,
+      manifest,
+    })
+  }
+  // a bad source is a warning, never a failure: the plugin directory is
+  // still discovered by the scan (spec 06)
+  for (const [name, entry] of entries) {
+    const rel = typeof entry.source === "string" ? relativePath(entry.source) : null
+    if (rel === null || !existsSync(join(marketplaceDir, rel))) {
+      warnings.push(`plugin "${name}" source ${JSON.stringify(entry.source ?? null)} not found in ${marketplaceDir}; the entry is skipped`)
+    }
+  }
+  return { plugins, warnings }
+}
+
+// add refuses a marketplace whose singular and plural component directories
+// define the same name, or that ships a tui plugin (spec 06)
+export function discoveryError(plugins) {
+  for (const plugin of plugins) {
+    const clashes = dirClashes(plugin.dir)
+    if (clashes.length) {
+      return (
+        `plugin "${plugin.name}" has a component name clash: ${clashes.join("; ")}\n` +
+        "  remove one directory of each clashing pair; ocm refuses to guess"
+      )
+    }
+    const tui = tuiModule(plugin)
+    if (tui) {
+      return (
+        `plugin "${plugin.name}" ships a tui plugin (${tui}): tui plugins are not supported\n` +
+        "  shipping one would edit tui.json on behalf of third-party code; ship a server plugin ({ id, server }) instead"
+      )
+    }
+  }
+  return null
+}
+
+// a static check: a module default-exporting a tui member is a tui plugin
+function tuiModule(plugin) {
+  for (const file of plugin.components.plugin ?? []) {
+    for (const dir of ["plugin", "plugins"]) {
+      let content
+      try {
+        content = readFileSync(join(plugin.dir, dir, file), "utf8")
+      } catch {
+        continue
+      }
+      if (/\btui\s*:/.test(content)) return `${dir}/${file}`
+    }
+  }
+  return null
+}
+
+export function readManifest(marketplaceDir) {
+  const file = join(marketplaceDir, "marketplace.json")
+  if (!existsSync(file)) return {}
+  try {
+    const parsed = JSON.parse(readFileSync(file, "utf8"))
+    return {
+      name: isRecord(parsed) && typeof parsed.name === "string" ? parsed.name : undefined,
+      description: isRecord(parsed) && typeof parsed.description === "string" ? parsed.description : undefined,
+    }
+  } catch {
+    return {}
+  }
+}