@wntic/ocm 0.1.0

package/src/commands/validate-files.ts

@@ -0,0 +1,145 @@
+// Component-file linting for `ocm validate`: command/agent markdown, skill
+// SKILL.md files and plugin js modules. Frontmatter parsing is deliberately
+// tolerant-but-strict — no sanitizer fallback, so YAML that only survives by
+// luck is caught here instead of in the field.
+import { existsSync, readFileSync } from "node:fs"
+import { join, relative } from "node:path"
+import type { CoreDiscoveredPlugin } from "../../loader/core.js"
+import { error, warning, type Finding } from "../findings"
+
+// `commands` and `command` (likewise the other types) are both opencode-valid
+// source directories, so both are searched
+function locate(pluginDir: string, dirs: string[], name: string): string | null {
+  for (const dir of dirs) {
+    const path = join(pluginDir, dir, name)
+    if (existsSync(path)) return path
+  }
+  return null
+}
+
+function frontmatter(content: string): { fm: string; body: string } | null {
+  if (!content.startsWith("---\n")) return null
+  const close = content.indexOf("\n---\n", 3)
+  if (close === -1) return null
+  return { fm: content.slice(4, close), body: content.slice(close + 5) }
+}
+
+// strict YAML rejects a plain scalar containing ": "; opencode's sanitizer
+// rescues it, so a quoted value passes and an unquoted one is an error
+function lintStrictYaml(rel: string, fm: string, findings: Finding[]): void {
+  for (const line of fm.split("\n")) {
+    const match = line.match(/^([^\s:]+):\s*(.*)$/)
+    if (!match) continue
+    const value = match[2]!
+    if (value.includes(": ") && !/^["'[]/.test(value)) {
+      findings.push(error(`${rel}: unquoted ": " in "${match[1]}" — strict YAML would reject this; quote the value`))
+    }
+  }
+}
+
+export function lintMarkdown(
+  root: string,
+  plugin: CoreDiscoveredPlugin,
+  dirs: string[],
+  file: string,
+  kind: "command" | "agent",
+  findings: Finding[],
+): void {
+  const path = locate(plugin.dir, dirs, file)
+  if (!path) return
+  const rel = relative(root, path)
+  let content: string
+  try {
+    content = readFileSync(path, "utf8")
+  } catch {
+    return
+  }
+  const parsed = frontmatter(content)
+  if (parsed === null) {
+    findings.push(warning(`${rel}: no frontmatter — opencode requires a description`))
+    return
+  }
+  lintStrictYaml(rel, parsed.fm, findings)
+  if (!parsed.body.trim()) {
+    findings.push(error(`${rel}: empty body — opencode requires the template`))
+  }
+  if (kind === "command" && /![a-zA-Z]/.test(parsed.body)) {
+    findings.push(warning(`${rel}: "!" shell substitution — ocm info surfaces this plugin as shell-executing`))
+  }
+}
+
+function lintSkillFields(
+  rel: string,
+  plugin: CoreDiscoveredPlugin,
+  fm: string,
+  skills: Map<string, string>,
+  findings: Finding[],
+): void {
+  const values = new Map<string, string>()
+  for (const line of fm.split("\n")) {
+    const match = line.match(/^([^\s:]+):\s*(.*)$/)
+    if (match) values.set(match[1]!, match[2]!)
+  }
+  const strip = (value: string | undefined) => value?.trim().replace(/^["']|["']$/g, "")
+  const name = strip(values.get("name"))
+  const description = strip(values.get("description"))
+  if (!name) {
+    findings.push(error(`${rel}: frontmatter has no "name"`))
+  } else {
+    const namespaced = `${plugin.name}:${name}`
+    const previous = skills.get(namespaced)
+    if (previous) findings.push(error(`${previous} and ${rel}: both produce "${namespaced}"`))
+    else skills.set(namespaced, rel)
+  }
+  if (!description) {
+    findings.push(error(`${rel}: frontmatter has no "description"`))
+  } else if (description.length > 1024) {
+    findings.push(error(`${rel}: "description" must be 1-1024 characters`))
+  }
+}
+
+export function lintSkill(
+  root: string,
+  plugin: CoreDiscoveredPlugin,
+  relDir: string,
+  skills: Map<string, string>,
+  findings: Finding[],
+): void {
+  const dir = locate(plugin.dir, ["skills", "skill"], relDir)
+  if (!dir) return
+  const rel = relative(root, join(dir, "SKILL.md"))
+  let content: string
+  try {
+    content = readFileSync(join(dir, "SKILL.md"), "utf8")
+  } catch {
+    return
+  }
+  const parsed = frontmatter(content)
+  if (parsed === null) {
+    findings.push(error(`${rel}: no frontmatter — a skill without it is invisible`))
+    return
+  }
+  lintStrictYaml(rel, parsed.fm, findings)
+  lintSkillFields(rel, plugin, parsed.fm, skills, findings)
+}
+
+// static checks only: the failure mode in the field is a red line on every
+// opencode start, so a suspicious export shape is an error, not a warning
+export function lintPluginJs(root: string, plugin: CoreDiscoveredPlugin, file: string, findings: Finding[]): void {
+  const path = locate(plugin.dir, ["plugin", "plugins"], file)
+  if (!path) return
+  const rel = relative(root, path)
+  let content: string
+  try {
+    content = readFileSync(path, "utf8")
+  } catch {
+    return
+  }
+  if (/\btui\s*:/.test(content)) {
+    findings.push(error(`${rel}: exports { id, tui } — tui plugins are not supported; ship { id, server }`))
+  } else if (/\bsetup\s*:/.test(content)) {
+    findings.push(error(`${rel}: exports { id, setup } — opencode silently rejects it; ship { id, server }`))
+  } else if (!/\bserver\s*:/.test(content) && !/export\s+default\s+(async\s+)?[(f]/.test(content)) {
+    findings.push(error(`${rel}: does not default-export { id, server } or a function`))
+  }
+}

package/src/commands/validate.ts

@@ -0,0 +1,77 @@
+// spec 12 `ocm validate`: lint a marketplace repo for its author. Structure
+// checks live here; component-file checks (markdown, skills, plugin js) are in
+// validate-files.ts.
+import { existsSync, readdirSync } from "node:fs"
+import { join, relative } from "node:path"
+import { dirClashes, discoverPlugins, lintCrossTool } from "../../loader/core.js"
+import type { CoreDiscoveredPlugin } from "../../loader/core.js"
+import { error, reportFindings, warning, type Finding } from "../findings"
+import { NAME_RE, lintMarketplaceJson, lintMcpJson, lintPluginJson, type MarketplaceManifest } from "../manifest-lint"
+import { lintMarkdown, lintPluginJs, lintSkill } from "./validate-files"
+
+const TYPO_FILES = new Set(["plugin.ts", "SKILLS.md", "Skill.md"])
+
+export function validate(path?: string): void {
+  const root = path ?? process.cwd()
+  if (!existsSync(root)) throw new Error(`marketplace directory "${root}" does not exist`)
+  console.log(`validate ${root}`)
+  const findings: Finding[] = []
+  const manifest = lintMarketplaceJson(root, findings)
+  const skills = new Map<string, string>()
+  for (const plugin of discoverPlugins(root)) {
+    lintPlugin(root, plugin, manifest, skills, findings)
+  }
+  for (const message of lintCrossTool(root)) findings.push(warning(message))
+  if (reportFindings(findings)) process.exitCode = 1
+}
+
+function lintPlugin(
+  root: string,
+  plugin: CoreDiscoveredPlugin,
+  manifest: MarketplaceManifest,
+  skills: Map<string, string>,
+  findings: Finding[],
+): void {
+  const rel = relative(root, plugin.dir) || "."
+  if (!NAME_RE.test(plugin.name)) findings.push(error(`${rel}: directory name must match ${NAME_RE}`))
+  if (plugin.name.length > 64) findings.push(error(`${rel}: directory name is longer than 64 characters`))
+  for (const clash of dirClashes(plugin.dir)) {
+    findings.push(error(`${rel}: ${clash} — both produce the same materialized name`))
+  }
+  lintTypos(rel, plugin.dir, findings)
+  const record = lintPluginJson(root, plugin.dir, plugin.name, findings)
+  lintMcpJson(root, plugin.dir, findings)
+  const entry = manifest.entries.get(plugin.name)
+  const fromMarketplace = typeof entry?.version === "string" ? entry.version : undefined
+  const fromPlugin = typeof record?.version === "string" ? record.version : undefined
+  if (fromMarketplace && fromPlugin && fromMarketplace !== fromPlugin) {
+    findings.push(warning(`${rel}: version disagrees — marketplace.json ${fromMarketplace}, plugin.json ${fromPlugin}`))
+  }
+  for (const file of plugin.components.command ?? []) {
+    lintMarkdown(root, plugin, ["commands", "command"], file, "command", findings)
+  }
+  for (const file of plugin.components.agent ?? []) {
+    lintMarkdown(root, plugin, ["agents", "agent"], file, "agent", findings)
+  }
+  for (const dir of plugin.components.skill ?? []) {
+    lintSkill(root, plugin, dir, skills, findings)
+  }
+  for (const file of plugin.components.plugin ?? []) {
+    lintPluginJs(root, plugin, file, findings)
+  }
+}
+
+function lintTypos(rel: string, pluginDir: string, findings: Finding[]): void {
+  if (existsSync(join(pluginDir, "skills")) && existsSync(join(pluginDir, "skill"))) {
+    findings.push(warning(`${rel}: both "skill" and "skills" exist — one is probably a typo`))
+  }
+  let names: string[]
+  try {
+    names = readdirSync(pluginDir)
+  } catch {
+    return
+  }
+  for (const name of names) {
+    if (TYPO_FILES.has(name)) findings.push(warning(`${rel}/${name}: likely a typo — not discovered as a component`))
+  }
+}

package/src/discovery.ts

@@ -0,0 +1,36 @@
+import { existsSync, readFileSync } from "node:fs"
+import { join } from "node:path"
+import type { DiscoveredPlugin } from "./types"
+
+export { discoverMarketplace, discoveryError, nameDisagreement, readManifest } from "../loader/core.js"
+
+export type { DiscoveredPlugin }
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+}
+
+function readJsonRecord(file: string): Record<string, unknown> | undefined {
+  if (!existsSync(file)) return undefined
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(file, "utf8"))
+    if (isRecord(parsed)) return parsed
+  } catch {}
+  return undefined
+}
+
+function collectRenames(raw: Record<string, unknown> | undefined, into: Record<string, string | null>): void {
+  if (!raw || !isRecord(raw.renames)) return
+  for (const [from, to] of Object.entries(raw.renames)) {
+    if (typeof to === "string" || to === null) into[from] = to
+  }
+}
+
+// spec 08: renames come from each discovered plugin's plugin.json, with the
+// marketplace manifest winning on conflict
+export function readRenames(marketplaceDir: string, plugins: DiscoveredPlugin[]): Record<string, string | null> {
+  const renames: Record<string, string | null> = {}
+  for (const plugin of plugins) collectRenames(readJsonRecord(join(plugin.dir, "plugin.json")), renames)
+  collectRenames(readJsonRecord(join(marketplaceDir, "marketplace.json")), renames)
+  return renames
+}

package/src/findings.ts

@@ -0,0 +1,33 @@
+// The spec 12 finding format, shared by `ocm validate` and `ocm doctor`:
+// two-space indent, severity padded to 8, then the message. The summary line
+// appears only when something was found, and "fixed" never counts toward it —
+// a fully repaired `doctor --fix` exits 0.
+export interface Finding {
+  severity: "error" | "warning" | "fixed"
+  message: string
+}
+
+export function error(message: string): Finding {
+  return { severity: "error", message }
+}
+
+export function warning(message: string): Finding {
+  return { severity: "warning", message }
+}
+
+export function fixed(message: string): Finding {
+  return { severity: "fixed", message }
+}
+
+// prints the findings and the summary; returns true when any error was found
+export function reportFindings(findings: Finding[]): boolean {
+  for (const finding of findings) {
+    console.log(`  ${finding.severity.padEnd(8)}${finding.message}`)
+  }
+  const errors = findings.filter((finding) => finding.severity === "error").length
+  const warnings = findings.filter((finding) => finding.severity === "warning").length
+  if (errors + warnings > 0) {
+    console.log(`${errors} ${errors === 1 ? "error" : "errors"}, ${warnings} ${warnings === 1 ? "warning" : "warnings"}`)
+  }
+  return errors > 0
+}

package/src/git.ts

@@ -0,0 +1,24 @@
+import { spawnSync } from "node:child_process"
+
+export function git(args: string[], cwd?: string): { ok: boolean; stdout: string; stderr: string } {
+  const result = spawnSync("git", args, {
+    cwd,
+    encoding: "utf8",
+    timeout: 120_000,
+  })
+  return {
+    ok: result.status === 0,
+    stdout: (result.stdout ?? "").trim(),
+    stderr: (result.stderr ?? "").trim(),
+  }
+}
+
+export function clone(url: string, dir: string, ref?: string | null): void {
+  const args = ["clone", "--depth", "1"]
+  if (ref) args.push("--branch", ref)
+  args.push(url, dir)
+  const result = git(args)
+  if (!result.ok) {
+    throw new Error(`git clone failed: ${result.stderr || result.stdout}`)
+  }
+}

package/src/index.ts

@@ -0,0 +1,175 @@
+import { installLoader, migrateLegacyLayout, uninstallLoader } from "./loader"
+import { migrateInstallation } from "./migrate"
+import { add, pin, remove } from "./commands/marketplace"
+import { update } from "./commands/update"
+import { install, scan, setMode, uninstall } from "./commands/plugins"
+import { trust, untrust } from "./commands/trust"
+import { list } from "./commands/list"
+import { search } from "./commands/search"
+import { info } from "./commands/info"
+import { validate } from "./commands/validate"
+import { doctor } from "./commands/doctor"
+
+const HELP = `ocm - file-based plugin marketplace for opencode
+
+usage:
+  ocm init                          install auto-sync loader
+  ocm add <url|path> [--ref <ref>] [--explicit] [--name <name>] [--trust|--no-trust]
+                                     add a marketplace (github url or local dir)
+  ocm remove <name>                 remove a marketplace and its links
+  ocm update [name|plugin@mp] [--quiet] [--json] [--trust|--no-trust]
+                                     pull latest changes (all, one marketplace or one plugin's marketplace)
+  ocm pin <name> <ref>              follow a branch or tag
+  ocm pin <name> --clear            back to the default branch
+  ocm list [--all] [--json]         list marketplaces and plugins
+  ocm search <query> [--enabled-only] [--json]
+                                     search cached plugin metadata
+  ocm info <plugin>[@<marketplace>] [--json]
+                                     show a plugin's cached record
+  ocm install <plugin>[@<mp>] [--force]
+                                     enable a plugin and materialize its components
+  ocm uninstall <plugin>[@<mp>]     disable a plugin and remove its links
+  ocm enable <plugin>[@<mp>]        alias of install
+  ocm disable <plugin>[@<mp>]       alias of uninstall
+  ocm mode <name> <auto|explicit>   change when new upstream plugins install
+  ocm trust <name>                  approve a marketplace's executable components
+  ocm untrust <name>                revoke trust and remove executable components
+  ocm scan <url|path|plugin>        dry-run: show what would be installed
+  ocm validate [path]               lint a marketplace repo (default: current directory)
+  ocm doctor [--fix]                diagnose this installation; --fix applies safe fixes
+  ocm loader uninstall              remove auto-sync loader
+
+examples:
+  ocm add https://github.com/user/opencode-marketplace
+  ocm add ~/plugins/my-marketplace
+  ocm install commit-tools
+  ocm update`
+
+// flags that take a value: `--name foo` or `--name=foo`
+const VALUE_FLAGS = new Set(["name", "ref"])
+
+interface ParsedArgs {
+  positional: string[]
+  flags: Set<string>
+  values: Record<string, string>
+}
+
+function parseArgs(args: string[]): ParsedArgs {
+  const positional: string[] = []
+  const flags = new Set<string>()
+  const values: Record<string, string> = {}
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i]!
+    if (!arg.startsWith("--")) {
+      positional.push(arg)
+      continue
+    }
+    const eq = arg.indexOf("=")
+    if (eq !== -1) {
+      values[arg.slice(2, eq)] = arg.slice(eq + 1)
+    } else if (VALUE_FLAGS.has(arg.slice(2))) {
+      values[arg.slice(2)] = args[++i] ?? ""
+    } else {
+      flags.add(arg.slice(2))
+    }
+  }
+  return { positional, flags, values }
+}
+
+// `--trust` and `--no-trust` carry opposite decisions; absence means prompt
+function trustFlag(flags: Set<string>): boolean | undefined {
+  if (flags.has("trust")) return true
+  if (flags.has("no-trust")) return false
+  return undefined
+}
+
+export async function main(argv: string[]): Promise<void> {
+  migrateLegacyLayout()
+  migrateInstallation()
+  const [command, ...rest] = argv
+  const { positional, flags, values } = parseArgs(rest)
+
+  switch (command) {
+    case undefined:
+    case "help":
+    case "--help":
+    case "-h":
+      console.log(HELP)
+      break
+    case "init":
+      installLoader()
+      break
+    case "add":
+      requireArg(positional[0], "missing marketplace url or path")
+      await add(positional[0]!, { explicit: flags.has("explicit"), name: values.name, ref: values.ref, trust: trustFlag(flags) })
+      break
+    case "remove":
+      requireArg(positional[0], "missing marketplace name")
+      remove(positional[0]!)
+      break
+    case "update":
+      await update(positional[0], { quiet: flags.has("quiet"), json: flags.has("json"), trust: trustFlag(flags) })
+      break
+    case "pin":
+      requireArg(positional[0], "missing marketplace name")
+      await pin(positional[0]!, positional[1], flags.has("clear"))
+      break
+    case "list":
+      list({ all: flags.has("all"), json: flags.has("json") })
+      break
+    case "search":
+      requireArg(positional[0], "missing search query")
+      search(positional[0]!, { enabledOnly: flags.has("enabled-only"), json: flags.has("json") })
+      break
+    case "info":
+      requireArg(positional[0], "missing plugin name")
+      info(positional[0]!, { json: flags.has("json") })
+      break
+    case "install":
+    case "enable":
+      requireArg(positional[0], "missing plugin name")
+      install(positional[0]!, flags.has("force"))
+      break
+    case "uninstall":
+    case "disable":
+      requireArg(positional[0], "missing plugin name")
+      uninstall(positional[0]!)
+      break
+    case "mode":
+      requireArg(positional[0], "missing marketplace name")
+      requireArg(positional[1], "missing mode (auto or explicit)")
+      setMode(positional[0]!, positional[1]!)
+      break
+    case "trust":
+      requireArg(positional[0], "missing marketplace name")
+      await trust(positional[0]!)
+      break
+    case "untrust":
+      requireArg(positional[0], "missing marketplace name")
+      await untrust(positional[0]!)
+      break
+    case "scan":
+      requireArg(positional[0], "missing url, path or plugin")
+      scan(positional[0]!)
+      break
+    case "validate":
+      validate(positional[0])
+      break
+    case "doctor":
+      doctor(flags.has("fix"))
+      break
+    case "loader":
+      if (positional[0] === "uninstall") {
+        uninstallLoader()
+      } else {
+        throw new Error('unknown loader command, expected "ocm loader uninstall"')
+      }
+      break
+    default:
+      throw new Error(`unknown command "${command}" (ocm help)`)
+  }
+}
+
+function requireArg(arg: string | undefined, message: string): void {
+  if (!arg) throw new Error(message)
+}

package/src/install.ts

@@ -0,0 +1,15 @@
+import { componentRoot, enabledPlugins, materialize as coreMaterialize } from "../loader/core.js"
+import type { CoreMaterializeReport } from "../loader/core.js"
+import type { MarketplaceEntry } from "./types"
+
+export { componentRoot, incumbentMarketplace, registerPlugins, removeMcpKeys } from "../loader/core.js"
+
+export function materializeLinks(
+  name: string,
+  entry: MarketplaceEntry,
+  force = false,
+  plugin?: string,
+): CoreMaterializeReport {
+  const dir = componentRoot(entry)
+  return coreMaterialize(name, dir, { enabled: enabledPlugins(entry, dir), force, plugin })
+}