@huynle/hub 0.7.1 → 0.7.3

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

@@ -0,0 +1,208 @@
+// OpenCode readiness (contract §3.10, T14): real probes, never presence.
+//
+//   version-exec     the binary itself (hub's `current` version, else what the PATH entry resolves to; never a
+//                    container shim, which would test another environment) runs `opencode --version` and reports
+//                    OpenCode 2 (and the pinned version, when hub installed it).
+//   provider-auth    `opencode models` answers with at least one provider/model: the user's providers load and
+//                    list models with the user's own, user-local configuration and credentials. It sends no prompt
+//                    (it costs nothing). A stronger probe (a real completion) can be injected.
+//   spoke-connected  the hub sees this machine's OpenCode spoke (an injected client: the integrator asks the hub with
+//                    the machine credential; without one this probe fails, so the harness is never ready by default).
+//
+// Every process is a fixed argv of the harness binary (OPENCODE_PROBE_ARGV) run through an injected ProcessRunner:
+// no shell, no command from a plan, an absolute file, bounded time and output. Probe details are built here (a
+// version, counts, an exit status), never the harness's raw output, and anything credential-shaped is withheld.
+import { execFile } from "node:child_process"
+import { compareVersions, executionContextOf, isSecretValue, REQUIRED_PROBES, rootPathIn, SEMVER, type AdapterContext, type HarnessVerification, type Probe } from "../../contracts/index.ts"
+import { discover } from "../../discovery/discover.ts"
+import type { DiscoveryProbe } from "../../discovery/probe.ts"
+import { txFail, txOk, type TxResult } from "../../transaction/result.ts"
+import { OPENCODE_BINARY_REL } from "./archive.ts"
+import { MIN_OPENCODE_VERSION } from "./plan.ts"
+
+/** The only argv the adapter ever runs (after the absolute binary path). */
+export const OPENCODE_PROBE_ARGV = Object.freeze({ version: Object.freeze(["--version"]), models: Object.freeze(["models"]) }) as {
+  readonly version: readonly string[]
+  readonly models: readonly string[]
+}
+
+export interface ProcessRequest {
+  /** Absolute path of the harness binary. */
+  readonly file: string
+  readonly argv: readonly string[]
+  /** The user's own environment (provider configuration stays user-local; nothing here is recorded). */
+  readonly env: Readonly<Record<string, string | undefined>>
+  readonly timeoutMs: number
+  readonly maxOutputBytes: number
+  readonly signal?: AbortSignal
+}
+
+export interface ProcessOutcome {
+  /** null when it was killed (timeout, signal). */
+  readonly exitCode: number | null
+  readonly stdout: string
+  /** Read only to recognise the cold-start activation failure (ACTIVATION_FAILURE); never reported raw. */
+  readonly stderr?: string
+  readonly timedOut: boolean
+}
+
+/** Runs one fixed argv without a shell. Tests inject fakes; the CLI injects nodeProcessRunner. */
+export interface ProcessRunner {
+  run(request: ProcessRequest): Promise<ProcessOutcome>
+}
+
+/** child_process.execFile with shell: false, bounded output and time; stdin closed. */
+export const nodeProcessRunner: ProcessRunner = {
+  run: (request) =>
+    new Promise((resolve, reject) => {
+      if (!request.file.startsWith("/")) return reject(new Error("the harness binary must be an absolute path"))
+      const env = Object.fromEntries(Object.entries(request.env).filter((e): e is [string, string] => typeof e[1] === "string"))
+      const child = execFile(
+        request.file,
+        [...request.argv],
+        { shell: false, env, timeout: request.timeoutMs, maxBuffer: request.maxOutputBytes, encoding: "utf8", windowsHide: true, ...(request.signal ? { signal: request.signal } : {}) },
+        (error, stdout, stderr) => {
+          const e = error as (NodeJS.ErrnoException & { killed?: boolean; code?: number | string }) | null
+          if (e && typeof e.code === "string" && e.code !== "ERR_CHILD_PROCESS_STDIO_MAXBUFFER") return reject(e)
+          resolve({ exitCode: e ? (typeof e.code === "number" ? e.code : null) : 0, stdout: String(stdout ?? ""), stderr: String(stderr ?? ""), timedOut: Boolean(e?.killed) })
+        },
+      )
+      child.stdin?.end()
+    }),
+}
+
+/** A provider probe beyond the default model listing (e.g. a real, tiny completion), injected by the integrator. */
+export type ProviderProbe = (input: { readonly binary: string; readonly context: AdapterContext; readonly runner: ProcessRunner }) => Promise<{ readonly ok: boolean; readonly detail?: string }>
+
+/** Whether the hub sees this machine's OpenCode spoke; the integrator asks the hub with the machine credential. */
+export interface SpokeProbe {
+  connected(input: { readonly harness: "opencode"; readonly context: AdapterContext }): Promise<{ readonly ok: boolean; readonly detail?: string }>
+}
+
+export interface OpencodeVerifyOptions {
+  readonly runner: ProcessRunner
+  /** The binary to probe (locateOpencodeBinary); undefined: not found, so every probe fails. */
+  readonly binary: string | undefined
+  readonly spoke?: SpokeProbe
+  readonly provider?: ProviderProbe
+  /** The version hub installed and made current; the binary must report exactly it. */
+  readonly expectVersion?: string
+  readonly versionTimeoutMs?: number
+  readonly providerTimeoutMs?: number
+  /** The pause before the one retry after a cold-start activation failure (default 1 s). */
+  readonly activationRetryDelayMs?: number
+}
+
+/**
+ * OpenCode 2's CLI gives a location's plugins ~5 s to activate in its background service, then fails with HTTP 503
+ * "Location plugins did not finish activating". On the first use of a directory (plugins loaded cold, MCP servers
+ * connecting) that can happen once; the service keeps activating, so the probe tries again once.
+ */
+export const ACTIVATION_FAILURE = /did not finish activating/i
+const ACTIVATION_RETRY_DELAY_MS = 1000
+
+const VERSION_TIMEOUT_MS = 15_000
+const PROVIDER_TIMEOUT_MS = 90_000
+const MAX_OUTPUT = 1024 * 1024
+const VERSION_IN = /(?:^|[^0-9.])v?(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)(?![0-9A-Za-z.-])/
+const MODEL_LINE = /^[A-Za-z0-9][A-Za-z0-9._-]*\/\S+$/
+
+/** One line for people; anything credential-shaped is withheld. */
+const safe = (detail: string): string => (isSecretValue(detail) ? "(details withheld: they looked like they carried a credential)" : detail.replace(/\s+/g, " ").trim().slice(0, 200))
+const errorText = (error: unknown) => (error instanceof Error ? error.message : String(error))
+
+async function runOnce(options: OpencodeVerifyOptions, context: AdapterContext, argv: readonly string[], timeoutMs: number): Promise<ProcessOutcome | string> {
+  try {
+    return await options.runner.run({ file: options.binary!, argv, env: context.env, timeoutMs, maxOutputBytes: MAX_OUTPUT, ...(context.signal ? { signal: context.signal } : {}) })
+  } catch (error) {
+    return `could not run ${options.binary}: ${errorText(error)}`
+  }
+}
+
+const coldStart = (r: ProcessOutcome | string): boolean => typeof r !== "string" && r.exitCode !== 0 && ACTIVATION_FAILURE.test(`${r.stderr ?? ""}\n${r.stdout}`)
+
+/** Runs one probe argv; a cold-start activation failure is retried once (ACTIVATION_FAILURE). */
+async function run(options: OpencodeVerifyOptions, context: AdapterContext, argv: readonly string[], timeoutMs: number): Promise<ProcessOutcome | string> {
+  const first = await runOnce(options, context, argv, timeoutMs)
+  if (!coldStart(first) || context.signal?.aborted) return first
+  const delay = options.activationRetryDelayMs ?? ACTIVATION_RETRY_DELAY_MS
+  if (delay > 0) await new Promise((resolve) => setTimeout(resolve, delay))
+  return runOnce(options, context, argv, timeoutMs)
+}
+
+const failedRun = (r: ProcessOutcome) =>
+  r.timedOut ? "timed out" : r.exitCode === null ? "was killed" : `exited ${r.exitCode}${coldStart(r) ? " (OpenCode's plugins did not finish activating in time, twice: start OpenCode once, then verify again)" : ""}`
+
+async function versionProbe(options: OpencodeVerifyOptions, context: AdapterContext): Promise<Omit<Probe, "observedAt">> {
+  const r = await run(options, context, OPENCODE_PROBE_ARGV.version, options.versionTimeoutMs ?? VERSION_TIMEOUT_MS)
+  if (typeof r === "string") return { kind: "version-exec", ok: false, detail: r }
+  if (r.exitCode !== 0) return { kind: "version-exec", ok: false, detail: `opencode --version ${failedRun(r)}` }
+  const version = VERSION_IN.exec(r.stdout)?.[1]
+  if (!version || !SEMVER.test(version)) return { kind: "version-exec", ok: false, detail: "opencode --version printed no version" }
+  if (compareVersions(version, MIN_OPENCODE_VERSION) < 0) return { kind: "version-exec", ok: false, detail: `opencode ${version} is older than ${MIN_OPENCODE_VERSION} (the Hub plugin needs OpenCode 2)` }
+  if (options.expectVersion && version !== options.expectVersion) return { kind: "version-exec", ok: false, detail: `opencode ${version} runs, but hub made ${options.expectVersion} current` }
+  return { kind: "version-exec", ok: true, detail: `opencode ${version}` }
+}
+
+async function providerProbe(options: OpencodeVerifyOptions, context: AdapterContext): Promise<Omit<Probe, "observedAt">> {
+  if (options.provider) {
+    try {
+      const r = await options.provider({ binary: options.binary!, context, runner: options.runner })
+      return { kind: "provider-auth", ok: r.ok, ...(r.detail ? { detail: r.detail } : {}) }
+    } catch (error) {
+      return { kind: "provider-auth", ok: false, detail: `the provider probe failed: ${errorText(error)}` }
+    }
+  }
+  const r = await run(options, context, OPENCODE_PROBE_ARGV.models, options.providerTimeoutMs ?? PROVIDER_TIMEOUT_MS)
+  if (typeof r === "string") return { kind: "provider-auth", ok: false, detail: r }
+  if (r.exitCode !== 0) return { kind: "provider-auth", ok: false, detail: `opencode models ${failedRun(r)}` }
+  const models = r.stdout.split("\n").map((l) => l.trim()).filter((l) => MODEL_LINE.test(l))
+  if (models.length === 0) return { kind: "provider-auth", ok: false, detail: "opencode lists no models: sign in to a provider (opencode auth login) or configure one" }
+  const providers = new Set(models.map((m) => m.slice(0, m.indexOf("/"))))
+  return { kind: "provider-auth", ok: true, detail: `${models.length} models from ${providers.size} providers` }
+}
+
+async function spokeProbe(options: OpencodeVerifyOptions, context: AdapterContext): Promise<Omit<Probe, "observedAt">> {
+  if (!options.spoke) return { kind: "spoke-connected", ok: false, detail: "no hub spoke probe is configured" }
+  try {
+    const r = await options.spoke.connected({ harness: "opencode", context })
+    return { kind: "spoke-connected", ok: r.ok, ...(r.detail ? { detail: r.detail } : {}) }
+  } catch (error) {
+    return { kind: "spoke-connected", ok: false, detail: `the hub could not be asked: ${errorText(error)}` }
+  }
+}
+
+/** Runs the required probes and reports each, passing or not (HarnessAdapter.verify). */
+export async function verifyOpencode(context: AdapterContext, options: OpencodeVerifyOptions): Promise<HarnessVerification> {
+  let results: Omit<Probe, "observedAt">[]
+  if (!options.binary) {
+    results = REQUIRED_PROBES.opencode.map((kind) => ({ kind, ok: false, detail: "OpenCode was not found on this host" }))
+  } else {
+    // Each probe on its own, so the report names every problem at once.
+    results = [await versionProbe(options, context), await providerProbe(options, context), await spokeProbe(options, context)]
+  }
+  const observedAt = context.now()
+  return { harness: "opencode", probes: results.map((p) => ({ ...p, observedAt, ...(p.detail !== undefined ? { detail: safe(p.detail) } : {}) })) }
+}
+
+/**
+ * The binary to probe on this host: hub's `current` OpenCode (through the link, to its version directory), else the
+ * one on PATH, followed to what it resolves to. A container shim is refused: running it would test the container,
+ * not this host (contract §3.10: version-exec runs what the shim resolves to, and that is not here).
+ */
+export function locateOpencodeBinary(probe: DiscoveryProbe): TxResult<string> {
+  const snap = discover(probe, { now: 0 })
+  if (!snap.ok) return txFail("invalid", "this host could not be discovered")
+  const data = snap.value.roots.find((r) => r.id === "data")
+  const base = data ? rootPathIn(data, executionContextOf(snap.value)) : undefined
+  if (base) {
+    const current = probe.realpath(`${base}/hub/harnesses/opencode/current/${OPENCODE_BINARY_REL}`)
+    if (current && probe.executable(current)) return txOk(current)
+  }
+  const presence = snap.value.harnesses.find((h) => h.id === "opencode")
+  if (!presence?.installed || !presence.path) return txFail("not_found", "OpenCode is not installed on this host")
+  const shim = snap.value.topology.shims.find((s) => s.name === "opencode" && s.path === presence.path)
+  if (shim?.kind === "container-shim") return txFail("not_found", `${presence.path} runs OpenCode in a container${shim.resolvesTo ? ` (${shim.resolvesTo})` : ""}; verify it there`)
+  const target = shim?.resolvesTo ?? presence.path
+  return probe.executable(target) ? txOk(target) : txFail("not_found", `${target} is not an executable on this host`)
+}

package/packages/cli/src/bootstrap/adapters/readiness.ts

@@ -0,0 +1,19 @@
+// The readiness gate every verify-harness executor shares (contract v1.2, docs/bootstrap-contracts.md §10). The
+// executor classifies its verification with harnessReadiness and reports it through onReadiness; then:
+//
+//   ready      the step passes
+//   failed     an integrity probe failed (the install is broken): harness_not_ready, so the apply rolls back
+//   pending    only user probes wait (provider login, spoke): harness_not_ready with requireReady (the default,
+//              and `hubctl setup apply --require-ready`); without it the step passes and the harness is reported
+//              "installed, not ready". It is never advertised as ready: only `ready` offers a capability.
+import type { HarnessReadiness } from "../contracts/index.ts"
+
+export interface ReadinessGate {
+  /** Fail unless ready (default true). false: a harness only waiting on the user passes as installed, not ready. */
+  readonly requireReady?: boolean
+  /** Sees the classified readiness of every verification (for the apply report); cannot change it. */
+  readonly onReadiness?: (readiness: HarnessReadiness) => void
+}
+
+/** Whether a verify-harness step that is not ready may still pass: only when it waits on the user alone. */
+export const passesAsPending = (readiness: HarnessReadiness, gate: ReadinessGate): boolean => readiness.state === "pending" && gate.requireReady === false

package/packages/cli/src/bootstrap/ansible/index.ts

@@ -0,0 +1,2 @@
+// The optional Ansible path (contrib/ansible/roles/hub_bootstrap): render a profile or a previewed plan as role vars.
+export * from "./render.ts"

package/packages/cli/src/bootstrap/ansible/render.ts

@@ -0,0 +1,279 @@
+// Renders a bootstrap profile, or a previewed setup plan, as the vars of the optional Ansible role
+// (contrib/ansible/roles/hub_bootstrap). The role reimplements nothing: it stages the signed hubctl pinned here and
+// runs the same `hubctl setup preview / apply / verify` a person would run directly, with the same canonical profile
+// and the same consent flags. So the vars carry only:
+//   - the profile, canonical, and its digest (the direct path's input, byte for byte);
+//   - when rendered from a plan, that plan's digest, host and snapshot, so the role refuses to apply anything but
+//     the plan that was previewed;
+//   - the hubctl artifacts and harness pins of a *verified* manifest (VerifiedManifest: only verifyManifest makes
+//     one), so the role can check the downloads before hubctl checks the signature again on the host;
+//   - explicit consent flags, all off by default.
+// Never a credential: inputs are validated, and the rendered vars are scanned (findSecrets) and refused, not
+// redacted, if anything credential-shaped got through. Enrollment is never part of the vars or the role: a plan that
+// enrolls is refused, because the device-code flow is a separate step a person approves.
+//
+// v1.1: the rendered profile always says `enrollment: "separate"`, so hubctl plans without enroll-machine on the
+// host and the role's plan digest equals the direct path's (`--enrollment separate`, or the same profile). A plan
+// rendered together with its snapshot is checked against the contract's one canonical snapshotDigest.
+import {
+  canonicalJSON,
+  checkHarnessPin,
+  digestOf,
+  findSecrets,
+  migrateProfile,
+  planDigest,
+  selectArtifact,
+  snapshotDigest,
+  validateDiscoverySnapshot,
+  validateSetupPlan,
+  type ErrorCode,
+  type Issue,
+  type Profile,
+  type SetupPlan,
+  type VerifiedManifest,
+} from "../contracts/index.ts"
+
+export const ANSIBLE_VARS_SCHEMA = "hub.ansible-vars"
+export const ANSIBLE_VARS_VERSION = 1
+/** The manifest file a release publishes next to its hubctl binaries (I5). */
+export const MANIFEST_FILE = "hubctl-manifest.json"
+
+/** Each consent var and the hubctl flag it becomes, in argv order. Never a default. */
+export const ROLE_FLAGS = Object.freeze({
+  hub_bootstrap_escalate: "--escalate",
+  hub_bootstrap_confirm_activation: "--confirm-activation",
+  hub_bootstrap_allow_downgrade: "--allow-downgrade",
+} as const)
+
+/**
+ * v1.2: apply-only flags (not consent). `--require-ready` makes apply fail and roll back unless every harness is
+ * ready; without it apply commits a harness that only waits on the user, and the role's verify step (with
+ * hub_bootstrap_require_ready) is the readiness gate.
+ */
+export const ROLE_APPLY_FLAGS = Object.freeze({
+  hub_bootstrap_apply_require_ready: "--require-ready",
+} as const)
+
+export interface RenderOptions {
+  /** https base URL of the hub release holding hubctl-manifest.json and the hubctl-<target> files. */
+  readonly releaseBaseURL: string
+  readonly escalate?: boolean
+  readonly confirmActivation?: boolean
+  readonly allowDowngrade?: boolean
+  /** Fail the play when `hubctl setup verify` finds a harness not ready (default true). */
+  readonly requireReady?: boolean
+  /** v1.2: pass --require-ready to `hubctl setup apply` (default false: apply commits installed-not-ready harnesses). */
+  readonly applyRequireReady?: boolean
+}
+
+export interface RenderInput {
+  /** A bootstrap profile document (older versions are migrated). */
+  readonly profile: unknown
+  /** The plan `hubctl setup preview` showed for one host, to pin the role to it. */
+  readonly plan?: unknown
+  /** v1.1: the discovery snapshot that plan was made from, to check the plan against it (canonical snapshotDigest). */
+  readonly snapshot?: unknown
+  readonly manifest: VerifiedManifest
+  readonly options: RenderOptions
+}
+
+export interface PinnedArtifact {
+  readonly url: string
+  readonly file: string
+  readonly size: number
+  readonly sha256: string
+}
+
+export interface PinnedHarness {
+  readonly harness: string
+  readonly version: string
+  readonly target: string
+  readonly sha256: string
+}
+
+export interface ExpectedPlan {
+  readonly planDigest: string
+  readonly hostFingerprint: string
+  readonly snapshotDigest: string
+  readonly target: string
+}
+
+export interface RoleVars {
+  readonly hub_bootstrap_vars_schema: typeof ANSIBLE_VARS_SCHEMA
+  readonly hub_bootstrap_vars_version: typeof ANSIBLE_VARS_VERSION
+  readonly hub_bootstrap_release: string
+  readonly hub_bootstrap_channel: string
+  readonly hub_bootstrap_minimum_version: string
+  readonly hub_bootstrap_manifest_url: string
+  /** Per supported target: the hubctl download and its pinned size and digest. */
+  readonly hub_bootstrap_artifacts: Readonly<Record<string, PinnedArtifact>>
+  readonly hub_bootstrap_harness_pins: readonly PinnedHarness[]
+  readonly hub_bootstrap_profile: Profile
+  readonly hub_bootstrap_profile_digest: string
+  readonly hub_bootstrap_expected_plan: ExpectedPlan | null
+  readonly hub_bootstrap_escalate: boolean
+  readonly hub_bootstrap_confirm_activation: boolean
+  readonly hub_bootstrap_allow_downgrade: boolean
+  readonly hub_bootstrap_require_ready: boolean
+  readonly hub_bootstrap_apply_require_ready: boolean
+}
+
+/** The order keys appear in the rendered YAML. */
+const VAR_ORDER: readonly (keyof RoleVars)[] = [
+  "hub_bootstrap_vars_schema",
+  "hub_bootstrap_vars_version",
+  "hub_bootstrap_release",
+  "hub_bootstrap_channel",
+  "hub_bootstrap_minimum_version",
+  "hub_bootstrap_manifest_url",
+  "hub_bootstrap_artifacts",
+  "hub_bootstrap_harness_pins",
+  "hub_bootstrap_profile",
+  "hub_bootstrap_profile_digest",
+  "hub_bootstrap_expected_plan",
+  "hub_bootstrap_escalate",
+  "hub_bootstrap_confirm_activation",
+  "hub_bootstrap_allow_downgrade",
+  "hub_bootstrap_require_ready",
+  "hub_bootstrap_apply_require_ready",
+]
+
+export interface RenderError {
+  readonly code: ErrorCode
+  readonly message: string
+  readonly path?: string
+}
+
+export type RenderResult = { readonly ok: true; readonly vars: RoleVars; readonly yaml: string } | { readonly ok: false; readonly error: RenderError }
+
+const refuse = (code: ErrorCode, message: string, path?: string): RenderResult => ({ ok: false, error: { code, message, ...(path === undefined ? {} : { path }) } })
+
+const describeIssues = (issues: readonly Issue[]) => issues.map((i) => `${i.path || "/"}: ${i.message}`).join("; ")
+
+/** A pin issue code as an envelope error code. */
+const pinCode = (code: string): ErrorCode => (code === "unpinned_artifact" || code === "integrity_mismatch" ? code : "invalid")
+
+function releaseBase(raw: string): string | undefined {
+  let url: URL
+  try {
+    url = new URL(raw)
+  } catch {
+    return undefined
+  }
+  if (url.protocol !== "https:" || url.username || url.password || url.search || url.hash || raw.includes("?") || raw.includes("#")) return undefined
+  return url.href.replace(/\/+$/, "")
+}
+
+/** Checks a plan against the profile, the manifest and the consent given; undefined when it may be rendered. */
+function checkPlan(plan: SetupPlan, profile: Profile, manifest: VerifiedManifest, options: RenderOptions): RenderResult | undefined {
+  if (plan.profile.id !== profile.id) return refuse("invalid", `the plan is for profile ${plan.profile.id}, not ${profile.id}`, "/plan/profile/id")
+  const artifact = selectArtifact(manifest, plan.target)
+  if (!artifact.ok) return refuse("wrong_platform", describeIssues(artifact.issues), "/plan/target")
+  for (const [i, action] of plan.actions.entries()) {
+    const at = `/plan/actions/${i}`
+    if (action.kind === "enroll-machine")
+      return refuse("usage", "enrollment is a separate, explicit step: run `hubctl machine enroll` on the host, then preview again", at)
+    if (action.kind === "install-artifact") {
+      if (action.version !== manifest.release || action.target !== plan.target)
+        return refuse("unpinned_artifact", `the plan installs hubctl ${action.version} for ${action.target}, but the manifest pins ${manifest.release} for ${plan.target}`, at)
+      if (action.sha256 !== artifact.value.sha256) return refuse("integrity_mismatch", "the plan's hubctl digest differs from the manifest's", at)
+    }
+    if (action.kind === "install-harness") {
+      const pin = checkHarnessPin(manifest, action)
+      if (!pin.ok) return refuse(pinCode(pin.issues[0]!.code), describeIssues(pin.issues), at)
+    }
+  }
+  if (plan.requiresEscalation && !options.escalate) return refuse("escalation_required", "the plan has elevated actions; pass escalate explicitly to allow them", "/plan/requiresEscalation")
+  if (!plan.requiresEscalation && options.escalate) return refuse("usage", "the plan needs no escalation; do not pass escalate", "/options/escalate")
+  if (plan.activatesServices && !options.confirmActivation) return refuse("needs_user", "the plan activates services; pass confirmActivation explicitly to allow it", "/plan/activatesServices")
+  return undefined
+}
+
+export function renderRoleVars(input: RenderInput): RenderResult {
+  const { manifest, options } = input
+  const base = releaseBase(options.releaseBaseURL)
+  if (!base) return refuse("usage", "the release URL must be https, without credentials, query or fragment", "/options/releaseBaseURL")
+  const migrated = migrateProfile(input.profile)
+  if (!migrated.ok) return refuse("invalid", `invalid profile: ${describeIssues(migrated.issues)}`, "/profile")
+  // The role never enrolls: hubctl on the host plans with a separate enrollment.
+  const profile = JSON.parse(canonicalJSON({ ...migrated.value, enrollment: "separate" })) as Profile
+  if (options.escalate && profile.escalation !== "explicit") return refuse("usage", "the profile never escalates; escalate cannot be passed", "/options/escalate")
+
+  let expected: ExpectedPlan | null = null
+  if (input.plan !== undefined) {
+    const checked = validateSetupPlan(input.plan)
+    if (!checked.ok) return refuse("invalid", `invalid plan: ${describeIssues(checked.issues)}`, "/plan")
+    const plan = checked.value
+    const problem = checkPlan(plan, profile, manifest, options)
+    if (problem) return problem
+    if (input.snapshot !== undefined) {
+      const snap = validateDiscoverySnapshot(input.snapshot)
+      if (!snap.ok) return refuse("invalid", `invalid snapshot: ${describeIssues(snap.issues)}`, "/snapshot")
+      if (snapshotDigest(snap.value) !== plan.snapshotDigest) return refuse("preview_stale", "the plan was not made from this snapshot; preview again", "/plan/snapshotDigest")
+    }
+    expected = { planDigest: planDigest(plan), hostFingerprint: plan.hostFingerprint, snapshotDigest: plan.snapshotDigest, target: plan.target }
+  }
+
+  const artifacts: Record<string, PinnedArtifact> = {}
+  for (const a of manifest.artifacts) artifacts[a.target] = { url: `${base}/${a.file}`, file: a.file, size: a.size, sha256: a.sha256 }
+  const vars: RoleVars = {
+    hub_bootstrap_vars_schema: ANSIBLE_VARS_SCHEMA,
+    hub_bootstrap_vars_version: ANSIBLE_VARS_VERSION,
+    hub_bootstrap_release: manifest.release,
+    hub_bootstrap_channel: manifest.channel,
+    hub_bootstrap_minimum_version: manifest.minimumVersion,
+    hub_bootstrap_manifest_url: `${base}/${MANIFEST_FILE}`,
+    hub_bootstrap_artifacts: artifacts,
+    hub_bootstrap_harness_pins: manifest.harnesses.map((p) => ({ harness: p.harness, version: p.version, target: p.target, sha256: p.sha256 })),
+    hub_bootstrap_profile: profile,
+    hub_bootstrap_profile_digest: digestOf(profile),
+    hub_bootstrap_expected_plan: expected,
+    hub_bootstrap_escalate: options.escalate === true,
+    hub_bootstrap_confirm_activation: options.confirmActivation === true,
+    hub_bootstrap_allow_downgrade: options.allowDowngrade === true,
+    hub_bootstrap_require_ready: options.requireReady !== false,
+    hub_bootstrap_apply_require_ready: options.applyRequireReady === true,
+  }
+  const secrets = findSecrets(vars)
+  if (secrets.length > 0) return refuse("invalid", `refusing to render credential-shaped values at ${secrets.join(", ")}`, secrets[0])
+  return { ok: true, vars, yaml: renderYAML(vars) }
+}
+
+/**
+ * The vars as YAML: one `key: <canonical JSON>` line per var, in a fixed order (JSON is YAML, so any YAML loader
+ * reads it back exactly, and the same vars always render the same bytes).
+ */
+export function renderYAML(vars: RoleVars): string {
+  const lines = [
+    "---",
+    "# Vars for the hub_bootstrap Ansible role, rendered by hubctl. Regenerate instead of editing by hand:",
+    "# the profile and the pins must stay exactly what was previewed and signed.",
+    ...VAR_ORDER.map((key) => `${key}: ${canonicalJSON(vars[key])}`),
+  ]
+  return `${lines.join("\n")}\n`
+}
+
+export interface RolePaths {
+  /** The staged, digest-checked hubctl the role runs. */
+  readonly hubctl: string
+  readonly profile: string
+  readonly preview: string
+  readonly manifest: string
+}
+
+export interface RoleCommands {
+  readonly preview: readonly string[]
+  readonly apply: readonly string[]
+  readonly verify: readonly string[]
+}
+
+/** The exact argv the role runs; the same words a person runs on the direct path. */
+export function directCommands(vars: RoleVars, paths: RolePaths): RoleCommands {
+  const consent = (Object.keys(ROLE_FLAGS) as (keyof typeof ROLE_FLAGS)[]).filter((key) => vars[key] === true).map((key) => ROLE_FLAGS[key])
+  const applyFlags = (Object.keys(ROLE_APPLY_FLAGS) as (keyof typeof ROLE_APPLY_FLAGS)[]).filter((key) => vars[key] === true).map((key) => ROLE_APPLY_FLAGS[key])
+  return {
+    preview: [paths.hubctl, "setup", "preview", "--profile", paths.profile, "--manifest", paths.manifest, "--out", paths.preview, "--json"],
+    apply: [paths.hubctl, "setup", "apply", "--preview", paths.preview, "--manifest", paths.manifest, ...consent, ...applyFlags, "--json"],
+    verify: [paths.hubctl, "setup", "verify", "--profile", paths.profile, "--json"],
+  }
+}