@huynle/hub 0.7.1 → 0.7.2

package/packages/cli/src/bootstrap/adapters/opencode/config.ts

@@ -0,0 +1,212 @@
+// How the Hub plugin and the hubctl MCP server sit in an OpenCode 2 config (opencode.json / opencode.jsonc).
+//
+// OpenCode 2's config schema (@opencode/schema, Config): `plugins` is an array of package specs, each a string or
+// `{ package, options? }`; `mcp.servers` maps a server name to `{ type: "local", command: string[], environment?,
+// disabled?, … }` or `{ type: "remote", url, … }`. This module only reads: it classifies what is there and computes the
+// exact JSON-pointer sets for the lossless JSONC merge (transaction/json-merge.ts), which edits nothing else.
+//
+//   plugin   absent → append the spec to /plugins; registered (an exact or unpinned npm entry, or the user's own
+//            checkout/GitHub install) → nothing; drift (an older pin, or the legacy name @huynle/opencode-voice) →
+//            replace just that entry's spec; a duplicate, or a pin newer than this hubctl → conflict (refused).
+//   mcp      absent → add mcp.servers.hub; registered (hubctl at the stable authority) → nothing; stale (a hub/hubctl
+//            `mcp` at another path, e.g. the plugin's launcher in the hub state dir) → replace only its command;
+//            another server named hub, or hub's mcp under another name → conflict (refused).
+//   text     unparseable JSONC or duplicate keys → manual_edit_required; a shape hubctl cannot merge into → conflict.
+import { compareVersions, SEMVER, type ConfigSet, type Json } from "../../contracts/index.ts"
+import { parseJsonc } from "../../transaction/json-merge.ts"
+import { txFail, txOk, type TxResult } from "../../transaction/result.ts"
+
+/** The npm package of the Hub OpenCode plugin. */
+export const HUB_PLUGIN_PACKAGE = "@huynle/hub"
+/** The plugin's former name; its last release only re-exports @huynle/hub, so both would load the plugin twice. */
+export const LEGACY_PLUGIN_PACKAGE = "@huynle/opencode-voice"
+/** The name hubctl's MCP server is registered under. */
+export const HUB_MCP_NAME = "hub"
+/** The subcommand an MCP client runs (the command is implied by register-mcp-server, never carried by a plan). */
+export const MCP_SUBCOMMAND = "mcp"
+/** Program names that are hub's one command surface (contract COMMAND_ALIASES). */
+const HUB_PROGRAMS = new Set(["hub", "hubctl"])
+
+export interface DesiredRegistration {
+  /** The absolute path of the stable hubctl authority the MCP server runs. */
+  readonly authority: string
+  /** Pin the plugin to this exact version (this hubctl's own); unpinned when absent. */
+  readonly pluginVersion?: string
+}
+
+export type PluginSource = "npm" | "legacy" | "custom"
+
+export type PluginState =
+  | { readonly state: "absent" }
+  | { readonly state: "registered"; readonly pointer: string; readonly source: PluginSource; readonly found?: string }
+  | { readonly state: "drift"; readonly pointer: string; readonly source: PluginSource; readonly found?: string; readonly object: boolean }
+
+export type McpState = { readonly state: "absent" } | { readonly state: "registered" } | { readonly state: "stale"; readonly found: string }
+
+export type FindingCode =
+  | "plugin-unpinned"
+  | "plugin-custom-source"
+  | "plugin-legacy-name"
+  | "plugin-drift"
+  | "mcp-stale-authority"
+  | "harness-user-installed"
+  | "harness-newer-than-pin"
+
+/** Something worth telling the user that needs no refusal (secret-free: specs, versions and paths only). */
+export interface Finding {
+  readonly code: FindingCode
+  readonly message: string
+}
+
+export interface ConfigInspection {
+  readonly plugin: PluginState
+  readonly mcp: McpState
+  readonly findings: readonly Finding[]
+}
+
+type Value = null | boolean | number | string | Value[] | { [key: string]: Value }
+const isObject = (v: unknown): v is { [key: string]: Value } => typeof v === "object" && v !== null && !Array.isArray(v)
+const basename = (p: string) => p.slice(p.lastIndexOf("/") + 1)
+
+/** The desired plugin spec: `@huynle/hub`, or `@huynle/hub@<version>` when pinned. */
+export const pluginSpec = (desired: { readonly pluginVersion?: string }): string => (desired.pluginVersion ? `${HUB_PLUGIN_PACKAGE}@${desired.pluginVersion}` : HUB_PLUGIN_PACKAGE)
+
+/** What a plugin spec names: the hub plugin (from npm, by its legacy name, or a custom source) or something else. */
+export function classifyPluginSpec(spec: string): { readonly source: PluginSource; readonly version?: string } | undefined {
+  const npm = spec.startsWith("npm:") ? spec.slice(4) : spec
+  for (const [pkg, source] of [
+    [HUB_PLUGIN_PACKAGE, "npm"],
+    [LEGACY_PLUGIN_PACKAGE, "legacy"],
+  ] as const) {
+    if (npm === pkg) return { source }
+    if (npm.startsWith(`${pkg}@`)) {
+      const v = npm.slice(pkg.length + 1)
+      return SEMVER.test(v) ? { source, version: v } : { source }
+    }
+  }
+  // The user's own install of the plugin: a GitHub spec, or a checkout named hub (README: { "package": "/path/to/hub" }).
+  if (/^(?:github:|git\+https:\/\/github\.com\/|https:\/\/github\.com\/)huynle\/hub(?:\.git)?(?:#.*)?$/.test(spec)) return { source: "custom" }
+  const path = spec.startsWith("file://") ? spec.slice(7) : spec
+  if (path.startsWith("/") && basename(path.replace(/\/+$/, "")) === "hub") return { source: "custom" }
+  return undefined
+}
+
+const specOf = (entry: Value): string | undefined => (typeof entry === "string" ? entry : isObject(entry) && typeof entry.package === "string" ? entry.package : undefined)
+
+const parse = (text: string): TxResult<{ [key: string]: Value }> => {
+  const parsed = parseJsonc(text)
+  if (!parsed.ok) return txFail("manual_edit_required", `the OpenCode config cannot be edited losslessly (${parsed.message}); make the edit by hand`)
+  if (!isObject(parsed.value)) return txFail("conflict", "the OpenCode config is not a JSON object")
+  return txOk(parsed.value)
+}
+
+function inspectPlugin(config: { [key: string]: Value }, desired: DesiredRegistration, findings: Finding[]): TxResult<PluginState> {
+  const found: { pointer: string; spec: string; object: boolean; source: PluginSource; version?: string }[] = []
+  // `plugins` is OpenCode 2's key; `plugin` is OpenCode 1's, still found in older configs.
+  for (const key of ["plugins", "plugin"]) {
+    const list = config[key]
+    if (list === undefined) continue
+    if (!Array.isArray(list)) return txFail("conflict", `"${key}" in the OpenCode config is not a list; fix it by hand`)
+    list.forEach((entry, i) => {
+      const spec = specOf(entry)
+      const kind = spec === undefined ? undefined : classifyPluginSpec(spec)
+      if (kind) found.push({ pointer: `/${key}/${i}`, spec: spec!, object: isObject(entry), ...kind })
+    })
+  }
+  if (found.length === 0) return txOk({ state: "absent" })
+  if (found.length > 1)
+    return txFail("conflict", `the Hub plugin is listed ${found.length} times (${found.map((f) => `${f.pointer} ${f.spec}`).join(", ")}); OpenCode would load only one of them, so remove all but one by hand`)
+  const entry = found[0]!
+  const base = { pointer: entry.pointer, source: entry.source, ...(entry.version ? { found: entry.version } : {}) }
+  if (entry.source === "custom") {
+    findings.push({ code: "plugin-custom-source", message: `the Hub plugin comes from ${entry.spec} (your own install); hubctl leaves it as it is` })
+    return txOk({ state: "registered", ...base })
+  }
+  if (entry.source === "legacy") {
+    findings.push({ code: "plugin-legacy-name", message: `${entry.spec} is the plugin's old name; it becomes ${pluginSpec(desired)}` })
+    return txOk({ state: "drift", ...base, object: entry.object })
+  }
+  if (!desired.pluginVersion) return txOk({ state: "registered", ...base })
+  if (!entry.version) {
+    findings.push({ code: "plugin-unpinned", message: `${entry.spec} tracks the latest release; this hubctl is ${desired.pluginVersion}` })
+    return txOk({ state: "registered", ...base })
+  }
+  const order = compareVersions(entry.version, desired.pluginVersion)
+  if (order === 0) return txOk({ state: "registered", ...base })
+  if (order > 0) return txFail("conflict", `the OpenCode config pins the Hub plugin ${entry.version}, newer than this hubctl (${desired.pluginVersion}); upgrade hubctl or change the pin by hand`)
+  findings.push({ code: "plugin-drift", message: `the Hub plugin is pinned to ${entry.version}; it becomes ${pluginSpec(desired)}` })
+  return txOk({ state: "drift", ...base, object: entry.object })
+}
+
+const isHubMcp = (server: Value): server is { [key: string]: Value } & { command: string[] } =>
+  isObject(server) &&
+  server.type === "local" &&
+  Array.isArray(server.command) &&
+  server.command.length === 2 &&
+  server.command.every((w) => typeof w === "string") &&
+  HUB_PROGRAMS.has(basename(server.command[0] as string)) &&
+  server.command[1] === MCP_SUBCOMMAND
+
+function inspectMcp(config: { [key: string]: Value }, desired: DesiredRegistration, findings: Finding[]): TxResult<McpState> {
+  const mcp = config.mcp
+  if (mcp === undefined) return txOk({ state: "absent" })
+  if (!isObject(mcp)) return txFail("conflict", '"mcp" in the OpenCode config is not an object; fix it by hand')
+  const servers = mcp.servers
+  if (servers === undefined) return txOk({ state: "absent" })
+  if (!isObject(servers)) return txFail("conflict", '"mcp.servers" in the OpenCode config is not an object; fix it by hand')
+  const elsewhere = Object.entries(servers).find(([name, server]) => name !== HUB_MCP_NAME && isHubMcp(server))
+  if (elsewhere) return txFail("conflict", `hub's MCP server is already registered as "${elsewhere[0]}"; remove it or rename it to "${HUB_MCP_NAME}" by hand`)
+  const server = servers[HUB_MCP_NAME]
+  if (server === undefined) return txOk({ state: "absent" })
+  if (!isHubMcp(server)) return txFail("conflict", `another MCP server is already named "${HUB_MCP_NAME}" in the OpenCode config; hubctl will not replace it`)
+  if (server.command[0] === desired.authority) return txOk({ state: "registered" })
+  findings.push({ code: "mcp-stale-authority", message: `the hub MCP server runs ${server.command[0]}; it becomes ${desired.authority}` })
+  return txOk({ state: "stale", found: server.command[0]! })
+}
+
+/** Classifies the config's Hub registrations (undefined text: the file does not exist). Reads only. */
+export function inspectOpencodeConfig(text: string | undefined, desired: DesiredRegistration): TxResult<ConfigInspection> {
+  if (text === undefined) return txOk({ plugin: { state: "absent" }, mcp: { state: "absent" }, findings: [] })
+  const config = parse(text)
+  if (!config.ok) return config
+  const findings: Finding[] = []
+  const plugin = inspectPlugin(config.value, desired, findings)
+  if (!plugin.ok) return plugin
+  const mcp = inspectMcp(config.value, desired, findings)
+  if (!mcp.ok) return mcp
+  return txOk({ plugin: plugin.value, mcp: mcp.value, findings })
+}
+
+/** The merge-config sets that register the plugin (none when it already is). */
+export function pluginSets(plugin: PluginState, desired: { readonly pluginVersion?: string }): ConfigSet[] {
+  const spec = pluginSpec(desired)
+  switch (plugin.state) {
+    case "absent":
+      return [{ pointer: "/plugins/-", value: spec }]
+    case "drift":
+      return [{ pointer: plugin.object ? `${plugin.pointer}/package` : plugin.pointer, value: spec }]
+    case "registered":
+      return []
+  }
+}
+
+/** The MCP server entry hubctl registers: this hubctl's `mcp` subcommand at the stable authority. */
+export const mcpServerValue = (authority: string): Json => ({ type: "local", command: [authority, MCP_SUBCOMMAND] })
+
+/**
+ * The sets that register hubctl's MCP server in this config text (computed at apply, from the file as it is then):
+ * the whole entry when absent, only the command when it is stale, nothing when it is registered.
+ */
+export function mcpServerSets(text: string | undefined, authority: string): TxResult<ConfigSet[]> {
+  const inspected = inspectOpencodeConfig(text, { authority })
+  if (!inspected.ok) return inspected
+  const at = `/mcp/servers/${HUB_MCP_NAME}`
+  switch (inspected.value.mcp.state) {
+    case "absent":
+      return txOk([{ pointer: at, value: mcpServerValue(authority) }])
+    case "stale":
+      return txOk([{ pointer: `${at}/command`, value: [authority, MCP_SUBCOMMAND] }])
+    case "registered":
+      return txOk([])
+  }
+}

package/packages/cli/src/bootstrap/adapters/opencode/index.ts

@@ -0,0 +1,81 @@
+// The OpenCode harness adapter (HBS-06): one entry point for the integrator (HBS-13), built on the frozen bootstrap
+// contracts. createOpencodeHarness wires the pure planner (plan.ts), discovery-backed presence, the real readiness
+// probes (verify.ts), the pinned-artifact source (apply.ts, archive.ts) and the executors for register-mcp-server
+// and verify-harness. Every capability is injected: a read-only DiscoveryProbe, a fixed-argv ProcessRunner, the hub
+// spoke probe, the download. See README.md for the upstream source findings and the integration requirements.
+import type { AdapterContext, HarnessAdapter, HarnessPresence, HarnessVerification, PathRef, VerifiedManifest } from "../../contracts/index.ts"
+import { discover } from "../../discovery/discover.ts"
+import type { DiscoveryProbe } from "../../discovery/probe.ts"
+import type { HarnessSource } from "../../transaction/builtin.ts"
+import type { ExecutorMap } from "../../transaction/executor.ts"
+import type { ReadinessGate } from "../readiness.ts"
+import { createOpencodeHarnessSource, httpsDownload, opencodeExecutors, type Download } from "./apply.ts"
+import { createOpencodeAdapter, type OpencodePlanOptions } from "./plan.ts"
+import { locateOpencodeBinary, nodeProcessRunner, verifyOpencode, type ProcessRunner, type ProviderProbe, type SpokeProbe } from "./verify.ts"
+
+export * from "./archive.ts"
+export * from "./config.ts"
+export * from "./plan.ts"
+export * from "./verify.ts"
+export * from "./apply.ts"
+
+export interface OpencodeHarnessOptions extends Omit<OpencodePlanOptions, "readConfig"> {
+  /** Read-only host access (createNodeProbe() in the CLI, memoryProbe() in tests). */
+  readonly probe: DiscoveryProbe
+  /** Default: nodeProcessRunner (execFile, no shell). */
+  readonly runner?: ProcessRunner
+  /** Whether the hub sees this machine's OpenCode spoke; without it OpenCode is never ready. */
+  readonly spoke?: SpokeProbe
+  readonly provider?: ProviderProbe
+  /** Default: httpsDownload(fetch). */
+  readonly download?: Download
+  /** Downgrade-policy inputs for the harness source (from the install history). */
+  readonly installed?: () => { readonly version: string; readonly sha256: string } | undefined
+  readonly floor?: () => string | undefined
+  readonly allowDowngrade?: boolean
+  readonly onVerification?: (verification: HarnessVerification) => void
+}
+
+export interface OpencodeHarness {
+  readonly adapter: HarnessAdapter
+  /** Absent without a manifest (nothing can be installed then). */
+  readonly source?: HarnessSource
+  /** Executors for apply's context: merge them over builtinExecutors. `gate`: the v1.2 readiness gate. */
+  executors(context: () => AdapterContext, gate?: ReadinessGate): Pick<ExecutorMap, "register-mcp-server" | "verify-harness">
+}
+
+/** The version directory a hub-managed binary lives in (data:hub/harnesses/opencode/<version>/bin/opencode). */
+const HUB_VERSION = /\/hub\/harnesses\/opencode\/([^/]+)\/bin\/opencode$/
+
+export function createOpencodeHarness(options: OpencodeHarnessOptions): OpencodeHarness {
+  const { probe } = options
+  const runner = options.runner ?? nodeProcessRunner
+  const presence = async (context: AdapterContext): Promise<HarnessPresence> => {
+    const snap = discover(probe, { now: context.now() })
+    const found = snap.ok ? snap.value.harnesses.find((h) => h.id === "opencode") : undefined
+    return found ?? { id: "opencode", installed: false, health: { state: "unverified", probes: [] } }
+  }
+  const verify = async (context: AdapterContext): Promise<HarnessVerification> => {
+    // Located fresh at every verification: after an install, `current` points at the new version.
+    const located = locateOpencodeBinary(probe)
+    const binary = located.ok ? located.value : undefined
+    const expectVersion = binary ? HUB_VERSION.exec(binary)?.[1] : undefined
+    return verifyOpencode(context, { runner, binary, ...(options.spoke ? { spoke: options.spoke } : {}), ...(options.provider ? { provider: options.provider } : {}), ...(expectVersion ? { expectVersion } : {}) })
+  }
+  const adapter = createOpencodeAdapter({ ...options, readConfig: (path) => probe.readFile(path), discover: presence, verify })
+  const source = options.manifest
+    ? createOpencodeHarnessSource({
+        manifest: options.manifest as VerifiedManifest,
+        download: options.download ?? httpsDownload(),
+        ...(options.installed ? { installed: options.installed } : {}),
+        ...(options.floor ? { floor: options.floor } : {}),
+        ...(options.allowDowngrade ? { allowDowngrade: true } : {}),
+      })
+    : undefined
+  return {
+    adapter,
+    ...(source ? { source } : {}),
+    executors: (context, gate = {}) =>
+      opencodeExecutors({ adapter, context, ...gate, ...(options.authority ? { authority: options.authority as PathRef } : {}), ...(options.onVerification ? { onVerification: options.onVerification } : {}) }),
+  }
+}

package/packages/cli/src/bootstrap/adapters/opencode/plan.ts

@@ -0,0 +1,266 @@
+// Planning OpenCode (contract §3.10): the OpenCode HarnessAdapter's plan, a pure function of the discovery snapshot,
+// the profile and what the adapter was built with (the verified hub manifest, a read-only reader for the configs the
+// snapshot already found, the stable hubctl authority). It proposes, in this order (preview/plan.ts PHASE):
+//
+//   install-harness         the artifact hub's signed manifest pins for this host's exact target (§3.6.1), into its
+//                           own immutable version directory; only when OpenCode is missing (or `install: "always"`),
+//                           or hub manages it at another, older version. Never a downgrade from planning.
+//   select-harness-version  makes that version `current`.
+//   merge-config            the Hub plugin in `plugins` (lossless JSONC merge; nothing else changes).
+//   register-mcp-server     hubctl's `mcp` at the stable authority (the command is implied by the action kind).
+//   verify-harness          real probes: the binary runs, a provider answers, the spoke is connected.
+//
+// Determinism: config bytes are read only for files the snapshot lists, and must still have the snapshot's digest
+// (else preview_stale), so the same snapshot always gives the same plan. A config hubctl must not edit (a duplicate
+// plugin, a newer pin, a foreign "hub" server, an unparseable file) is refused, never half-planned: planOpencode
+// returns the failure, and the adapter's plan() throws it as an OpencodePlanError (HarnessAdapter.plan returns only
+// actions). A config behind a symlink is not this module's concern: planSetup turns those actions into manual edits.
+import {
+  compareVersions,
+  executionContextOf,
+  harnessCurrentRef,
+  harnessVersionRef,
+  REQUIRED_PROBES,
+  resolvePathRef,
+  type Action,
+  type ConfigFormat,
+  type DiscoverySnapshot,
+  type ErrorCode,
+  type HarnessAdapter,
+  type HarnessPin,
+  type HarnessVerification,
+  type AdapterContext,
+  type PathRef,
+  type PlanInput,
+  type Precondition,
+  type VerifiedManifest,
+} from "../../contracts/index.ts"
+import { txFail, txOk, type TxResult } from "../../transaction/result.ts"
+import { sha256Of } from "../../transaction/state.ts"
+import { inspectOpencodeConfig, pluginSets, pluginSpec, type ConfigInspection, type Finding } from "./config.ts"
+
+/** The Hub plugin is an OpenCode 2 plugin (the @opencode/plugin 2 API): no older OpenCode is ever installed for it. */
+export const MIN_OPENCODE_VERSION = "2.0.0"
+
+/** The stable hubctl authority: the standalone hubctl hub installs (contract install-artifact, user-bin:hubctl). */
+export const DEFAULT_AUTHORITY: PathRef = { root: "user-bin", rel: "hubctl" }
+/** Authorities the MCP server may run: hubctl or its hub alias (one command surface), in a bin root. */
+const AUTHORITY_ROOTS = new Set<PathRef["root"]>(["user-bin", "system-bin"])
+const AUTHORITY_NAMES = new Set(["hubctl", "hub"])
+
+/** The config files OpenCode reads from its global config dir, in the order hubctl prefers to edit them. */
+export const CONFIG_REFS: readonly { readonly ref: PathRef; readonly format: ConfigFormat }[] = [
+  { ref: { root: "config", rel: "opencode/opencode.jsonc" }, format: "jsonc" },
+  { ref: { root: "config", rel: "opencode/opencode.json" }, format: "json" },
+]
+/** The file a new config is created as (plain JSON is valid JSONC too). */
+const NEW_CONFIG = CONFIG_REFS[1]!
+
+export interface OpencodePlanOptions {
+  /** The verified hub release manifest whose pins vouch for OpenCode downloads; without it nothing is installed. */
+  readonly manifest?: VerifiedManifest
+  /** Reads a file the snapshot listed (DiscoveryProbe.readFile): read-only, following links. */
+  readonly readConfig: (path: string) => Uint8Array | undefined
+  /** The hubctl the MCP server runs (default user-bin:hubctl; user-bin:hub is the same command surface). */
+  readonly authority?: PathRef
+  /** Pin the Hub plugin to this exact version (this hubctl's own); unpinned when absent. */
+  readonly pluginVersion?: string
+  /** "if-missing" (default): keep an OpenCode the user installed. "always": install hub's pinned one beside it. */
+  readonly install?: "if-missing" | "always"
+}
+
+export interface OpencodePlan {
+  readonly actions: readonly Action[]
+  readonly findings: readonly Finding[]
+}
+
+/** A refusal from the adapter's plan(): the config or host cannot be planned for without overwriting something. */
+export class OpencodePlanError extends Error {
+  constructor(
+    readonly code: ErrorCode,
+    message: string,
+  ) {
+    super(message)
+    this.name = "OpencodePlanError"
+  }
+}
+
+/** Throws if `ref` is not a stable hubctl authority (never a plugin-cache launcher or a path under state/data). */
+export function checkAuthority(ref: PathRef): void {
+  if (!AUTHORITY_ROOTS.has(ref.root) || !AUTHORITY_NAMES.has(ref.rel))
+    throw new Error(`the MCP authority must be the installed hubctl (or its hub alias) in a bin directory, not ${ref.root}:${ref.rel}`)
+}
+
+const LABEL = "OpenCode"
+
+function installActions(snapshot: DiscoverySnapshot, manifest: VerifiedManifest, pin: HarnessPin): Action[] {
+  return [
+    {
+      id: "install-opencode",
+      kind: "install-harness",
+      escalation: "user",
+      summary: `Install ${LABEL} ${pin.version} for ${pin.target} (pinned by hub ${manifest.release})`,
+      harness: "opencode",
+      version: pin.version,
+      target: pin.target,
+      source: { manifest: manifest.release, url: pin.url, file: pin.file },
+      size: pin.size,
+      sha256: pin.sha256,
+      evidence: [...pin.evidence],
+      path: harnessVersionRef("opencode", pin.version),
+      owner: "hub",
+      rollback: "restore-previous",
+    },
+    {
+      id: "select-opencode",
+      kind: "select-harness-version",
+      escalation: "user",
+      summary: `Make ${LABEL} ${pin.version} the current version`,
+      harness: "opencode",
+      version: pin.version,
+      path: harnessCurrentRef("opencode"),
+      target: harnessVersionRef("opencode", pin.version),
+    },
+  ]
+}
+
+/** Whether (and what) to install. */
+function planInstall(snapshot: DiscoverySnapshot, options: OpencodePlanOptions, findings: Finding[]): TxResult<Action[]> {
+  const presence = snapshot.harnesses.find((h) => h.id === "opencode")
+  const installed = presence?.installed === true
+  const pin = options.manifest?.harnesses.find((h) => h.harness === "opencode" && h.target === snapshot.host.target)
+  if (pin && compareVersions(pin.version, MIN_OPENCODE_VERSION) < 0) return txFail("invalid", `hub pins ${LABEL} ${pin.version}, but the Hub plugin needs ${LABEL} ${MIN_OPENCODE_VERSION} or later`)
+  if (presence?.installMethod === "hub" && presence.version) {
+    if (!pin || pin.version === presence.version) return txOk([])
+    if (compareVersions(pin.version, presence.version) < 0) {
+      findings.push({ code: "harness-newer-than-pin", message: `hub manages ${LABEL} ${presence.version}, newer than the pinned ${pin.version}; planning never downgrades it` })
+      return txOk([])
+    }
+    return txOk(installActions(snapshot, options.manifest!, pin))
+  }
+  if (installed && (options.install ?? "if-missing") === "if-missing") {
+    findings.push({ code: "harness-user-installed", message: `${LABEL} is already installed at ${presence!.path} (${presence!.installMethod ?? "unknown"}); hubctl keeps it` })
+    return txOk([])
+  }
+  if (!pin || !options.manifest) return txFail("unpinned_artifact", `this hub release pins no ${LABEL} for ${snapshot.host.target}; install ${LABEL} 2 yourself, or use a hub release that pins it`)
+  return txOk(installActions(snapshot, options.manifest, pin))
+}
+
+interface ConfigView {
+  readonly ref: PathRef
+  readonly format: ConfigFormat
+  readonly precondition: Precondition
+  readonly inspection: ConfigInspection
+}
+
+/** The configs the snapshot found, read and inspected (their bytes pinned by the snapshot's digests). */
+function readConfigs(snapshot: DiscoverySnapshot, options: OpencodePlanOptions, authority: string): TxResult<ConfigView[]> {
+  const context = executionContextOf(snapshot)
+  const views: ConfigView[] = []
+  for (const { ref, format } of CONFIG_REFS) {
+    const where = resolvePathRef(ref, snapshot.roots, context)
+    if (!where.ok) return txFail("invalid", `this host has no ${ref.root} root`)
+    const found = snapshot.configs.find((c) => c.path === where.value)
+    if (!found || found.sha256 === null) continue
+    const bytes = options.readConfig(where.value)
+    if (!bytes || sha256Of(bytes) !== found.sha256) return txFail("preview_stale", `${where.value} changed since discovery; discover and preview again`)
+    const inspection = inspectOpencodeConfig(new TextDecoder().decode(bytes), { authority, ...(options.pluginVersion ? { pluginVersion: options.pluginVersion } : {}) })
+    if (!inspection.ok) return txFail(inspection.code, `${where.value}: ${inspection.message}`)
+    views.push({ ref, format, precondition: { exists: true, sha256: found.sha256 }, inspection: inspection.value })
+  }
+  return txOk(views)
+}
+
+function planConfig(snapshot: DiscoverySnapshot, options: OpencodePlanOptions, authorityRef: PathRef, findings: Finding[]): TxResult<Action[]> {
+  const authority = resolvePathRef(authorityRef, snapshot.roots, executionContextOf(snapshot))
+  if (!authority.ok) return txFail("invalid", `this host has no ${authorityRef.root} root for hubctl`)
+  const views = readConfigs(snapshot, options, authority.value)
+  if (!views.ok) return views
+  const fresh: ConfigView = { ...NEW_CONFIG, precondition: { exists: false }, inspection: { plugin: { state: "absent" }, mcp: { state: "absent" }, findings: [] } }
+  const preferred = views.value[0] ?? fresh
+  // OpenCode merges its config files: an entry in two of them is a duplicate, whichever wins.
+  const withPlugin = views.value.filter((v) => v.inspection.plugin.state !== "absent")
+  const withMcp = views.value.filter((v) => v.inspection.mcp.state !== "absent")
+  if (withPlugin.length > 1) return txFail("conflict", `the Hub plugin is listed in both ${CONFIG_REFS.map((c) => c.ref.rel).join(" and ")}; keep it in one of them`)
+  if (withMcp.length > 1) return txFail("conflict", `the hub MCP server is registered in both ${CONFIG_REFS.map((c) => c.ref.rel).join(" and ")}; keep it in one of them`)
+  for (const v of views.value) findings.push(...v.inspection.findings)
+  const pluginFile = withPlugin[0] ?? preferred
+  const mcpFile = withMcp[0] ?? preferred
+  const actions: Action[] = []
+  const sets = pluginSets(pluginFile.inspection.plugin, options)
+  if (sets.length > 0)
+    actions.push({
+      id: "opencode-plugin",
+      kind: "merge-config",
+      escalation: "user",
+      summary: pluginFile.inspection.plugin.state === "drift" ? `Update the Hub plugin in ${LABEL}'s config to ${pluginSpec(options)}` : `Add the Hub plugin (${pluginSpec(options)}) to ${LABEL}'s config`,
+      path: pluginFile.ref,
+      format: pluginFile.format,
+      owner: "harness:opencode",
+      precondition: pluginFile.precondition,
+      set: sets,
+      preserveUnknown: true,
+    })
+  if (mcpFile.inspection.mcp.state !== "registered")
+    actions.push({
+      id: "opencode-mcp",
+      kind: "register-mcp-server",
+      escalation: "user",
+      summary: `Register hubctl's MCP server (${authority.value} mcp) with ${LABEL} as "hub"`,
+      harness: "opencode",
+      path: mcpFile.ref,
+      name: "hub",
+      precondition: mcpFile.precondition,
+    })
+  return txOk(actions)
+}
+
+const verifyAction = (): Action => ({
+  id: "verify-opencode",
+  kind: "verify-harness",
+  escalation: "user",
+  summary: `Verify ${LABEL} really runs, reaches its provider and connects to the hub`,
+  harness: "opencode",
+  probes: REQUIRED_PROBES.opencode.filter((p): p is Exclude<typeof p, "presence"> => p !== "presence"),
+})
+
+/** The OpenCode actions for this snapshot and profile, with the findings worth showing; or the refusal. */
+export function planOpencode(input: PlanInput, options: OpencodePlanOptions): TxResult<OpencodePlan> {
+  if (!input.profile.harnesses.includes("opencode")) return txOk({ actions: [], findings: [] })
+  const authority = options.authority ?? DEFAULT_AUTHORITY
+  try {
+    checkAuthority(authority)
+  } catch (error) {
+    return txFail("invalid", (error as Error).message)
+  }
+  const findings: Finding[] = []
+  const install = planInstall(input.snapshot, options, findings)
+  if (!install.ok) return install
+  const config = planConfig(input.snapshot, options, authority, findings)
+  if (!config.ok) return config
+  return txOk({ actions: [...install.value, ...config.value, verifyAction()], findings })
+}
+
+export interface OpencodeAdapterOptions extends OpencodePlanOptions {
+  /** Presence (adapters/opencode/verify.ts wires discovery); absent: discover() is not available here. */
+  readonly discover?: HarnessAdapter["discover"]
+  /** The real probes (adapters/opencode/verify.ts); absent: every required probe fails (never ready). */
+  readonly verify?: (context: AdapterContext) => Promise<HarnessVerification>
+}
+
+/** The OpenCode HarnessAdapter (register it with createAdapterRegistry). */
+export function createOpencodeAdapter(options: OpencodeAdapterOptions): HarnessAdapter {
+  checkAuthority(options.authority ?? DEFAULT_AUTHORITY)
+  return {
+    id: "opencode",
+    discover: options.discover ?? (async () => ({ id: "opencode", installed: false, health: { state: "unverified", probes: [] } })),
+    plan(input) {
+      const planned = planOpencode(input, options)
+      if (!planned.ok) throw new OpencodePlanError(planned.code, planned.message)
+      return planned.value.actions
+    },
+    verify:
+      options.verify ??
+      (async (context) => ({ harness: "opencode", probes: REQUIRED_PROBES.opencode.map((kind) => ({ kind, ok: false, observedAt: context.now(), detail: "no probe configured" })) })),
+  }
+}