@huynle/hub 0.6.1 → 0.7.2

package/packages/cli/src/bootstrap/contracts/discovery.ts

@@ -0,0 +1,215 @@
+// DiscoverySnapshot: what `hubctl setup` found on this host, read-only, before anything is planned. It separates
+// presence from health (an installed harness stays "unverified" until real probes pass), records the container and
+// shim topology (a `claude` on PATH may be a shim into another environment), the package/runtime/service managers,
+// who owns each config file it would touch, and where each path root lives. It can describe an unsupported host
+// (supported: false) so the refusal is explicit; planning for such a host fails.
+import { CONFIG_OWNERS, type ConfigOwner } from "./actions.ts"
+import { HARNESS_ORDER, PROBE_KINDS, RUNTIME_IDS, type HarnessID, type Probe, type RuntimeID } from "./harness.ts"
+import { digestOf } from "./canonical.ts"
+import { ROOT_IDS, type ExecutionContext, type RootMapping } from "./paths.ts"
+import { checkTarget, targetOf, type Libc, type ServiceManager } from "./platform.ts"
+import { findSecrets } from "./secrets.ts"
+import { absPath, bool, Checker, digest, header, instant, list, oneOf, pointer, semver, shape, subset, text, type Result } from "./validate.ts"
+
+export const DISCOVERY_SCHEMA = "hub.discovery-snapshot"
+export const DISCOVERY_VERSION = 1
+
+export type ContainerKind = "none" | "docker" | "podman" | "lxc" | "wsl" | "unknown"
+export type ShimKind = "host" | "container-shim" | "wrapper" | "unknown"
+export const PACKAGE_MANAGERS = ["brew", "npm", "bun", "apt", "dnf", "apk", "pacman", "nix"] as const
+export type PackageManager = (typeof PACKAGE_MANAGERS)[number]
+/** hub: installed by hubctl from a pinned artifact. */
+export type InstallMethod = "native" | "npm" | "brew" | "package-manager" | "hub" | "unknown"
+
+export interface HostInfo {
+  readonly fingerprint: string
+  /** process.platform as found (may be unsupported). */
+  readonly platform: string
+  readonly arch: string
+  readonly libc: Libc
+  readonly target: string
+  /** Exactly whether `target` is in SUPPORTED_TARGETS. */
+  readonly supported: boolean
+  readonly os: { readonly name: string; readonly version: string }
+}
+
+export interface Shim {
+  readonly name: string
+  readonly path: string
+  readonly kind: ShimKind
+  /** For a shim: what it forwards to, when known. */
+  readonly resolvesTo?: string
+}
+
+export interface RuntimeInfo {
+  readonly id: "bun" | "node"
+  readonly version: string
+  readonly path: string
+}
+
+export interface HarnessHealth {
+  readonly state: "unverified" | "verified" | "failed"
+  readonly probes: readonly Probe[]
+}
+
+/** A harness as discovery sees it. `installed` is presence only; `health` is what probes proved. */
+export interface HarnessPresence {
+  readonly id: HarnessID
+  readonly installed: boolean
+  readonly path?: string
+  readonly version?: string
+  readonly installMethod?: InstallMethod
+  readonly health: HarnessHealth
+}
+
+export interface RuntimePresence {
+  readonly id: RuntimeID
+  readonly present: boolean
+  readonly version?: string
+}
+
+export interface ConfigFile {
+  readonly path: string
+  readonly owner: ConfigOwner | "package-manager"
+  readonly format: "json" | "jsonc" | "toml" | "plist" | "unit"
+  /** Digest of its bytes now; null when it does not exist. Contents are never recorded. */
+  readonly sha256: string | null
+}
+
+export interface DiscoverySnapshot {
+  readonly schema: typeof DISCOVERY_SCHEMA
+  readonly version: typeof DISCOVERY_VERSION
+  readonly capturedAt: number
+  readonly host: HostInfo
+  readonly topology: { readonly container: ContainerKind; readonly shims: readonly Shim[] }
+  readonly managers: { readonly package: readonly PackageManager[]; readonly runtime: readonly RuntimeInfo[]; readonly service: ServiceManager | "none" }
+  readonly harnesses: readonly HarnessPresence[]
+  readonly runtimes: readonly RuntimePresence[]
+  readonly configs: readonly ConfigFile[]
+  readonly roots: readonly RootMapping[]
+}
+
+const NAME = /^[A-Za-z0-9._+-]{1,64}$/
+const VERSION_TEXT = /^[0-9A-Za-z.+_-]{1,64}$/
+
+function checkProbe(c: Checker, p: string, v: unknown) {
+  const r = shape(c, p, v, ["kind", "ok", "observedAt"], ["detail"])
+  if (!r) return
+  oneOf(c, pointer(p, "kind"), r.kind, PROBE_KINDS)
+  bool(c, pointer(p, "ok"), r.ok)
+  instant(c, pointer(p, "observedAt"), r.observedAt)
+  if (r.detail !== undefined) text(c, pointer(p, "detail"), r.detail)
+}
+
+function checkHarness(c: Checker, p: string, v: unknown) {
+  const r = shape(c, p, v, ["id", "installed", "health"], ["path", "version", "installMethod"])
+  if (!r) return
+  oneOf(c, pointer(p, "id"), r.id, HARNESS_ORDER)
+  bool(c, pointer(p, "installed"), r.installed)
+  if (r.path !== undefined) absPath(c, pointer(p, "path"), r.path)
+  if (r.version !== undefined) text(c, pointer(p, "version"), r.version, 64, VERSION_TEXT)
+  if (r.installMethod !== undefined) oneOf(c, pointer(p, "installMethod"), r.installMethod, ["native", "npm", "brew", "package-manager", "hub", "unknown"] as const)
+  if (r.installed === false && (r.path !== undefined || r.version !== undefined)) c.add(p, "inconsistent", "a harness that is not installed has no path or version")
+  const h = shape(c, pointer(p, "health"), r.health, ["state", "probes"])
+  if (!h) return
+  oneOf(c, pointer(pointer(p, "health"), "state"), h.state, ["unverified", "verified", "failed"] as const)
+  list(c, pointer(pointer(p, "health"), "probes"), h.probes, 32, (pp, probe) => checkProbe(c, pp, probe))
+  const probes = Array.isArray(h.probes) ? (h.probes as Partial<Probe>[]) : []
+  if (h.state === "verified") {
+    const real = probes.filter((pr) => pr.kind !== "presence")
+    if (real.length === 0 || !probes.every((pr) => pr.ok === true)) c.add(pointer(p, "health"), "inconsistent", "verified needs passing real probes, not presence")
+  }
+  if (h.state === "failed" && !probes.some((pr) => pr.ok === false)) c.add(pointer(p, "health"), "inconsistent", "failed needs a failing probe")
+  if (r.installed === false && h.state !== "unverified") c.add(pointer(p, "health"), "inconsistent", "a harness that is not installed cannot be verified")
+}
+
+/**
+ * v1.1: the one canonical digest of a snapshot that plans, preview tokens, journals, audits and the Ansible vars
+ * pin: the canonical JSON without `capturedAt`, so rediscovering an unchanged host gives the same digest.
+ */
+export const snapshotDigest = (snapshot: DiscoverySnapshot): string => digestOf({ ...snapshot, capturedAt: undefined })
+
+/** v1.1: the context a plan made from this snapshot resolves paths in: where discovery (and so apply) ran. */
+export const executionContextOf = (snapshot: Pick<DiscoverySnapshot, "topology">): ExecutionContext => (snapshot.topology.container === "none" ? "host" : "container")
+
+export function validateDiscoverySnapshot(value: unknown): Result<DiscoverySnapshot> {
+  const c = new Checker()
+  const r = shape(c, "", value, ["schema", "version", "capturedAt", "host", "topology", "managers", "harnesses", "runtimes", "configs", "roots"])
+  if (!r) return c.result(value)
+  header(c, "", r, DISCOVERY_SCHEMA, DISCOVERY_VERSION)
+  instant(c, "/capturedAt", r.capturedAt)
+
+  const host = shape(c, "/host", r.host, ["fingerprint", "platform", "arch", "libc", "target", "supported", "os"])
+  if (host) {
+    digest(c, "/host/fingerprint", host.fingerprint)
+    text(c, "/host/platform", host.platform, 32, NAME)
+    text(c, "/host/arch", host.arch, 32, NAME)
+    oneOf(c, "/host/libc", host.libc, ["none", "glibc", "musl", "unknown"] as const)
+    text(c, "/host/target", host.target, 64, NAME)
+    bool(c, "/host/supported", host.supported)
+    const os = shape(c, "/host/os", host.os, ["name", "version"])
+    if (os) {
+      text(c, "/host/os/name", os.name, 64)
+      text(c, "/host/os/version", os.version, 64)
+    }
+    if (typeof host.platform === "string" && typeof host.arch === "string" && typeof host.libc === "string" && host.target !== targetOf(host.platform, host.arch, host.libc as Libc))
+      c.add("/host/target", "inconsistent", "target does not match platform, arch and libc")
+    if (typeof host.target === "string" && host.supported !== checkTarget(host.target).ok) c.add("/host/supported", "inconsistent", "supported must say exactly whether the target is in the support matrix")
+  }
+
+  const topology = shape(c, "/topology", r.topology, ["container", "shims"])
+  if (topology) {
+    oneOf(c, "/topology/container", topology.container, ["none", "docker", "podman", "lxc", "wsl", "unknown"] as const)
+    list(c, "/topology/shims", topology.shims, 64, (p, v) => {
+      const s = shape(c, p, v, ["name", "path", "kind"], ["resolvesTo"])
+      if (!s) return
+      text(c, pointer(p, "name"), s.name, 64, NAME)
+      absPath(c, pointer(p, "path"), s.path)
+      oneOf(c, pointer(p, "kind"), s.kind, ["host", "container-shim", "wrapper", "unknown"] as const)
+      if (s.resolvesTo !== undefined) absPath(c, pointer(p, "resolvesTo"), s.resolvesTo)
+    })
+  }
+
+  const managers = shape(c, "/managers", r.managers, ["package", "runtime", "service"])
+  if (managers) {
+    subset(c, "/managers/package", managers.package, PACKAGE_MANAGERS)
+    list(c, "/managers/runtime", managers.runtime, 8, (p, v) => {
+      const rt = shape(c, p, v, ["id", "version", "path"])
+      if (!rt) return
+      oneOf(c, pointer(p, "id"), rt.id, ["bun", "node"] as const)
+      semver(c, pointer(p, "version"), rt.version)
+      absPath(c, pointer(p, "path"), rt.path)
+    })
+    oneOf(c, "/managers/service", managers.service, ["launchd", "systemd-user", "none"] as const)
+    const platform = host?.platform
+    if (managers.service === "launchd" && platform !== "darwin") c.add("/managers/service", "inconsistent", "launchd is macOS only")
+    if (managers.service === "systemd-user" && platform !== "linux") c.add("/managers/service", "inconsistent", "systemd is Linux only")
+  }
+
+  list(c, "/harnesses", r.harnesses, HARNESS_ORDER.length, (p, v) => checkHarness(c, p, v), (v) => (v as { id?: string })?.id)
+  list(c, "/runtimes", r.runtimes, RUNTIME_IDS.length, (p, v) => {
+    const rt = shape(c, p, v, ["id", "present"], ["version"])
+    if (!rt) return
+    oneOf(c, pointer(p, "id"), rt.id, RUNTIME_IDS)
+    bool(c, pointer(p, "present"), rt.present)
+    if (rt.version !== undefined) text(c, pointer(p, "version"), rt.version, 64, VERSION_TEXT)
+  }, (v) => (v as { id?: string })?.id)
+  list(c, "/configs", r.configs, 128, (p, v) => {
+    const cf = shape(c, p, v, ["path", "owner", "format", "sha256"])
+    if (!cf) return
+    absPath(c, pointer(p, "path"), cf.path)
+    oneOf(c, pointer(p, "owner"), cf.owner, [...CONFIG_OWNERS, "package-manager"])
+    oneOf(c, pointer(p, "format"), cf.format, ["json", "jsonc", "toml", "plist", "unit"] as const)
+    if (cf.sha256 !== null) digest(c, pointer(p, "sha256"), cf.sha256)
+  }, (v) => (v as { path?: string })?.path)
+  list(c, "/roots", r.roots, ROOT_IDS.length, (p, v) => {
+    const root = shape(c, p, v, ["id", "path"], ["containerPath"])
+    if (!root) return
+    oneOf(c, pointer(p, "id"), root.id, ROOT_IDS)
+    absPath(c, pointer(p, "path"), root.path)
+    if (root.containerPath !== undefined) absPath(c, pointer(p, "containerPath"), root.containerPath)
+  }, (v) => (v as { id?: string })?.id)
+
+  for (const p of findSecrets(value)) c.add(p, "secret", "discovery never records credentials")
+  return c.result(value)
+}

package/packages/cli/src/bootstrap/contracts/envelope.ts

@@ -0,0 +1,143 @@
+// The JSON output envelope and exit codes of the bootstrap commands (`hubctl machine …`, `hubctl setup …`). With
+// --json, stdout carries exactly one envelope; without it, people get text and the same exit code. Exit codes 0–9
+// are the CLI's existing ones (http.ts EXIT) with unchanged meanings; the bootstrap adds 10 and up.
+import { EXIT } from "../../http.ts"
+import { findSecrets } from "./secrets.ts"
+import { bool, Checker, header, isRecord, list, oneOf, shape, text, type Result } from "./validate.ts"
+
+export const BOOTSTRAP_EXIT = Object.freeze({
+  ...EXIT,
+  /** A file the plan would change was edited by someone else, is not ours, or is a symlink the user must edit themselves: nothing was overwritten. */
+  conflict: 10,
+  /** A hubctl or harness artifact failed authentication: unpinned, tampered, wrong platform, bad signature or evidence, or a refused downgrade. */
+  artifactRejected: 11,
+  /** The preview is stale, foreign, expired, replayed or malformed: preview again. */
+  previewInvalid: 12,
+  /** Another apply holds the lock. */
+  locked: 13,
+  /** An interrupted transaction must be recovered (`hubctl setup recover`) before anything else applies. */
+  recoveryRequired: 14,
+  /** A harness or provider failed its real probes. */
+  notReady: 15,
+} as const)
+
+export const ERROR_CODES = [
+  "usage",
+  "invalid",
+  "unsupported_platform",
+  "wrong_platform",
+  "integrity_mismatch",
+  "signature_invalid",
+  "downgrade_rejected",
+  "below_security_floor",
+  "trust_root_rollback",
+  "unpinned_artifact",
+  "evidence_failed",
+  "preview_invalid",
+  "preview_foreign",
+  "preview_expired",
+  "preview_not_yet_valid",
+  "preview_replayed",
+  "preview_stale",
+  "locked",
+  "conflict",
+  "manual_edit_required",
+  "recovery_required",
+  "escalation_required",
+  "needs_user",
+  "forbidden",
+  "unauthorized",
+  "revoked",
+  "offline",
+  "not_found",
+  "harness_not_ready",
+  // v1.1
+  "no_service_manager",
+  "enrollment_denied",
+  "enrollment_expired",
+  "cancelled",
+  // v1.3
+  "service_failed",
+  "internal",
+] as const
+export type ErrorCode = (typeof ERROR_CODES)[number]
+
+const EXIT_OF: Readonly<Record<ErrorCode, number>> = {
+  usage: EXIT.usage,
+  invalid: EXIT.usage,
+  unsupported_platform: EXIT.unavailable,
+  wrong_platform: BOOTSTRAP_EXIT.artifactRejected,
+  integrity_mismatch: BOOTSTRAP_EXIT.artifactRejected,
+  signature_invalid: BOOTSTRAP_EXIT.artifactRejected,
+  downgrade_rejected: BOOTSTRAP_EXIT.artifactRejected,
+  below_security_floor: BOOTSTRAP_EXIT.artifactRejected,
+  trust_root_rollback: BOOTSTRAP_EXIT.artifactRejected,
+  unpinned_artifact: BOOTSTRAP_EXIT.artifactRejected,
+  evidence_failed: BOOTSTRAP_EXIT.artifactRejected,
+  preview_invalid: BOOTSTRAP_EXIT.previewInvalid,
+  preview_foreign: BOOTSTRAP_EXIT.previewInvalid,
+  preview_expired: BOOTSTRAP_EXIT.previewInvalid,
+  preview_not_yet_valid: BOOTSTRAP_EXIT.previewInvalid,
+  preview_replayed: BOOTSTRAP_EXIT.previewInvalid,
+  preview_stale: BOOTSTRAP_EXIT.previewInvalid,
+  locked: BOOTSTRAP_EXIT.locked,
+  conflict: BOOTSTRAP_EXIT.conflict,
+  manual_edit_required: BOOTSTRAP_EXIT.conflict,
+  recovery_required: BOOTSTRAP_EXIT.recoveryRequired,
+  escalation_required: EXIT.needsUser,
+  needs_user: EXIT.needsUser,
+  forbidden: EXIT.forbidden,
+  unauthorized: EXIT.unauthorized,
+  revoked: EXIT.unauthorized,
+  offline: EXIT.unavailable,
+  not_found: EXIT.notFound,
+  harness_not_ready: BOOTSTRAP_EXIT.notReady,
+  // v1.1: specific codes for outcomes that already had these exits (the exits are unchanged).
+  no_service_manager: EXIT.unavailable,
+  enrollment_denied: EXIT.forbidden,
+  enrollment_expired: EXIT.needsUser,
+  cancelled: EXIT.needsUser,
+  // v1.3: an activated service that does not stay running (failed, crash-looping, never settles) is not ready.
+  service_failed: BOOTSTRAP_EXIT.notReady,
+  internal: EXIT.other,
+}
+
+export const exitFor = (code: ErrorCode | string): number => EXIT_OF[code as ErrorCode] ?? EXIT.other
+
+export const ENVELOPE_SCHEMA = "hub.bootstrap.result"
+
+export interface ResultEnvelope<T = unknown> {
+  readonly schema: typeof ENVELOPE_SCHEMA
+  readonly version: 1
+  /** The command words ("machine status", "setup apply"). */
+  readonly command: string
+  readonly ok: boolean
+  readonly data?: T
+  readonly error?: { readonly code: ErrorCode; readonly message: string; readonly hint?: string }
+  readonly warnings?: readonly string[]
+}
+
+export function validateEnvelope(value: unknown): Result<ResultEnvelope> {
+  const c = new Checker()
+  const r = shape(c, "", value, ["schema", "version", "command", "ok"], ["data", "error", "warnings"])
+  if (!r) return c.result(value)
+  header(c, "", r, ENVELOPE_SCHEMA, 1)
+  text(c, "/command", r.command, 64, /^[a-z][a-z-]*(?: [a-z][a-z-]*)*$/)
+  bool(c, "/ok", r.ok)
+  if (r.error !== undefined) {
+    const e = shape(c, "/error", r.error, ["code", "message"], ["hint"])
+    if (e) {
+      oneOf(c, "/error/code", e.code, ERROR_CODES)
+      text(c, "/error/message", e.message, 500)
+      if (e.hint !== undefined) text(c, "/error/hint", e.hint, 500)
+    }
+  }
+  if (r.ok === true && r.error !== undefined) c.add("/error", "inconsistent", "a success has no error")
+  if (r.ok === false && r.error === undefined) c.add("/error", "inconsistent", "a failure names its error")
+  if (r.warnings !== undefined) list(c, "/warnings", r.warnings, 64, (p, w) => text(c, p, w, 500))
+  // `setup preview --json` prints the SetupPreview, whose /token is a preview token (no authority, contract §3.4),
+  // not a credential; its values are still scanned.
+  const allow = isRecord(r.data) && r.data.schema === "hub.setup-preview" ? new Set(["/data/token"]) : new Set<string>()
+  for (const p of findSecrets(value, "", allow)) c.add(p, "secret", "output never carries credentials")
+  return c.result(value)
+}

package/packages/cli/src/bootstrap/contracts/exec.ts

@@ -0,0 +1,74 @@
+// The executable contract. `hub` and `hubctl` are two names for one command surface: the name never changes what a
+// caller may do (credentials, scopes and grants do). The CLI runs either as a standalone compiled binary (a signed
+// hubctl with the Bun runtime and its assets embedded) or as a script under a runtime (the npm package, or the
+// OpenCode binary acting as bun). Services always start it with an argv word list built here, never a shell string,
+// and their unit templates are embedded assets so a standalone binary needs nothing beside it on disk.
+import path from "node:path"
+import { isAbsolutePath } from "./validate.ts"
+
+export const COMMAND_ALIASES = ["hub", "hubctl"] as const
+export type CommandAlias = (typeof COMMAND_ALIASES)[number]
+
+/** The single command surface both names resolve to; undefined for any other program name. */
+export function commandSurface(argv0: string): "hub-cli" | undefined {
+  return (COMMAND_ALIASES as readonly string[]).includes(path.basename(argv0)) ? "hub-cli" : undefined
+}
+
+export type ProgramLayout =
+  /** A compiled hubctl: the executable is the whole program. */
+  | { readonly kind: "standalone"; readonly executable: string }
+  /** A script (hub-cli.js) run by a runtime (bun, node, or OpenCode with BUN_BE_BUN=1). */
+  | { readonly kind: "script"; readonly runtime: string; readonly entry: string }
+
+/** Where `bun build --compile` mounts the embedded entry (POSIX and Windows forms). */
+const EMBEDDED_PREFIXES = ["/$bunfs/", "B:/~BUN/", "B:\\~BUN\\"]
+
+/** This process's layout from process.execPath and the (real path of) process.argv[1]. */
+export function programLayout(program: { readonly execPath: string; readonly entry: string }): ProgramLayout {
+  if (EMBEDDED_PREFIXES.some((p) => program.entry.startsWith(p))) return { kind: "standalone", executable: program.execPath }
+  return { kind: "script", runtime: program.execPath, entry: program.entry }
+}
+
+export const SERVICE_IDS = ["node", "claude-code", "codex-spoke"] as const
+export type ServiceID = (typeof SERVICE_IDS)[number]
+
+/** The subcommand each long-running service runs (after the program words). */
+export const SERVICE_COMMANDS: Readonly<Record<ServiceID, readonly string[]>> = Object.freeze({
+  node: ["node", "run"],
+  "claude-code": ["claude-code", "daemon"],
+  "codex-spoke": ["codex-spoke", "serve"],
+})
+
+// eslint-disable-next-line no-control-regex
+const CONTROL = /[\u0000-\u001f\u007f]/
+
+/** The argv a service unit starts: absolute program words, then the service's subcommand. Throws on unsafe paths. */
+export function serviceArgv(layout: ProgramLayout, service: ServiceID): string[] {
+  const program = layout.kind === "standalone" ? [layout.executable] : [layout.runtime, layout.entry]
+  for (const word of program) if (!isAbsolutePath(word) || CONTROL.test(word)) throw new Error(`service argv needs absolute, single-line paths, not ${JSON.stringify(word)}`)
+  const command = SERVICE_COMMANDS[service]
+  if (!command) throw new Error(`unknown service ${String(service)}`)
+  return [...program, ...command]
+}
+
+export type AssetKind = "launchd-plist" | "systemd-unit"
+
+export interface EmbeddedAsset {
+  readonly kind: AssetKind
+  readonly service: ServiceID
+  readonly manager: "launchd" | "systemd-user"
+  /** The repository file it is embedded from (the template the source install reads today). */
+  readonly source: string
+  /** The file name it is installed as. */
+  readonly installAs: string
+}
+
+/** Every service template a standalone hubctl must carry inside the binary. */
+export const EMBEDDED_ASSETS: Readonly<Record<string, EmbeddedAsset>> = Object.freeze({
+  "service/launchd/node": { kind: "launchd-plist", service: "node", manager: "launchd", source: "scripts/io.github.huynle.hub-node.plist", installAs: "io.github.huynle.hub-node.plist" },
+  "service/systemd-user/node": { kind: "systemd-unit", service: "node", manager: "systemd-user", source: "scripts/hub-node.service", installAs: "hub-node.service" },
+  "service/launchd/claude-code": { kind: "launchd-plist", service: "claude-code", manager: "launchd", source: "scripts/io.github.huynle.hub-claude-code.plist", installAs: "io.github.huynle.hub-claude-code.plist" },
+  "service/systemd-user/claude-code": { kind: "systemd-unit", service: "claude-code", manager: "systemd-user", source: "scripts/hub-claude-code.service", installAs: "hub-claude-code.service" },
+  "service/launchd/codex-spoke": { kind: "launchd-plist", service: "codex-spoke", manager: "launchd", source: "scripts/io.github.huynle.hub-codex-spoke.plist", installAs: "io.github.huynle.hub-codex-spoke.plist" },
+  "service/systemd-user/codex-spoke": { kind: "systemd-unit", service: "codex-spoke", manager: "systemd-user", source: "scripts/hub-codex-spoke.service", installAs: "hub-codex-spoke.service" },
+})

package/packages/cli/src/bootstrap/contracts/harness.ts

@@ -0,0 +1,202 @@
+// Harness adapters: how the bootstrap discovers, plans for and verifies each agent harness. An installed binary is
+// not a healthy harness: readiness needs real probes (the binary runs and reports its version on the host, not a
+// container shim; its model provider answers; its spoke is connected to the hub), each fresh and passing. Presence
+// alone never counts. Adapters are pure planners: they return typed Actions and run probes through the context the
+// applier gives them; they never get a shell.
+import type { Action } from "./actions.ts"
+import type { DiscoverySnapshot, HarnessPresence } from "./discovery.ts"
+import type { Profile } from "./profile.ts"
+
+/** Supported harnesses, in the order the bootstrap offers, installs and verifies them. */
+export const HARNESS_ORDER = ["opencode", "claude-code", "codex"] as const
+export type HarnessID = (typeof HARNESS_ORDER)[number]
+
+/** Sandboxed runtimes: opt-in, discovery and verification only (never installed or configured by the bootstrap). */
+export const RUNTIME_IDS = ["openshell"] as const
+export type RuntimeID = (typeof RUNTIME_IDS)[number]
+
+/**
+ * Upstream authenticity evidence a pinned harness download may carry beyond hub's signed digest pin. It is always
+ * optional extra evidence (recorded as verified, unavailable or deferred); the pin itself is mandatory.
+ *   gpg-manifest        Claude Code's GPG-signed per-release manifest.json
+ *   macos-notarization  Apple notarization / codesign of the macOS binary
+ *   sigstore            a sigstore bundle published next to the asset (Codex, where available)
+ */
+export const EVIDENCE_KINDS = ["gpg-manifest", "macos-notarization", "sigstore"] as const
+export type EvidenceKind = (typeof EVIDENCE_KINDS)[number]
+
+/** Which evidence each harness's upstream can offer. OpenCode offers none: only hub's pinned digest vouches for it. */
+export const HARNESS_EVIDENCE: Readonly<Record<HarnessID, readonly EvidenceKind[]>> = Object.freeze({
+  opencode: [],
+  "claude-code": ["gpg-manifest", "macos-notarization"],
+  // v1.1 (HBS-13): Codex's macOS binaries are codesigned; the Codex source records only sigstore so far, so a pin may
+  // list macos-notarization only once the source checks it.
+  codex: ["sigstore", "macos-notarization"],
+})
+
+/**
+ * presence: found on PATH / at a known location (never sufficient). version-exec: executed on the host and printed
+ * a version. provider-auth: a real request to its model provider succeeded with the configured credentials.
+ * api-health: the harness's local server answered its health endpoint. spoke-connected: the hub sees its spoke.
+ */
+export const PROBE_KINDS = ["presence", "version-exec", "provider-auth", "api-health", "spoke-connected"] as const
+export type ProbeKind = (typeof PROBE_KINDS)[number]
+/** Probes that exercise the harness for real; a verify-harness action may only ask for these. */
+export const REAL_PROBES: readonly Exclude<ProbeKind, "presence">[] = ["version-exec", "provider-auth", "api-health", "spoke-connected"]
+
+export interface Probe {
+  readonly kind: ProbeKind
+  readonly ok: boolean
+  readonly observedAt: number
+  /** One line for people (a version string, an HTTP status); never a credential. */
+  readonly detail?: string
+}
+
+export interface HarnessVerification {
+  readonly harness: HarnessID
+  readonly probes: readonly Probe[]
+}
+
+/** What each harness must pass before it is ready. */
+export const REQUIRED_PROBES: Readonly<Record<HarnessID, readonly ProbeKind[]>> = Object.freeze({
+  opencode: ["version-exec", "provider-auth", "spoke-connected"],
+  "claude-code": ["version-exec", "provider-auth", "spoke-connected"],
+  codex: ["version-exec", "provider-auth", "spoke-connected"],
+})
+
+/** How old a probe may be and still count. */
+export const PROBE_MAX_AGE_MS = 15 * 60_000
+const CLOCK_SKEW_MS = 60_000
+
+/** Every required probe was run, passed, and is fresh; any failing or stale required probe means not ready. */
+export function isHarnessReady(verification: HarnessVerification, now: number): boolean {
+  const required = REQUIRED_PROBES[verification.harness]
+  if (!required) return false
+  return required.every((kind) => {
+    const probes = verification.probes.filter((p) => p.kind === kind)
+    return probes.length > 0 && probes.every((p) => p.ok && p.observedAt <= now + CLOCK_SKEW_MS && now - p.observedAt <= PROBE_MAX_AGE_MS)
+  })
+}
+
+/**
+ * v1.2: what a probe that is not passing means. `integrity`: the install itself is wrong (the binary is missing, does
+ * not run, is not the pinned version, is a container shim, its local API does not answer), so apply rolls back.
+ * `user`: the install is fine but waits on the user (their provider login, a spoke they start), which only the
+ * installed harness lets them do, so apply commits it as "installed, not ready" unless --require-ready is given.
+ * The class belongs to the probe kind, never to a probe's detail, so it cannot be argued from harness output.
+ */
+export const PROBE_CLASSES = ["integrity", "user"] as const
+export type ProbeClass = (typeof PROBE_CLASSES)[number]
+export const PROBE_CLASS: Readonly<Record<ProbeKind, ProbeClass>> = Object.freeze({
+  presence: "integrity",
+  "version-exec": "integrity",
+  "api-health": "integrity",
+  "provider-auth": "user",
+  "spoke-connected": "user",
+})
+
+/** v1.2: pass (present, passing, fresh); pending (a user probe that is not passing); fail (anything else). */
+export type ProbeStatus = "pass" | "pending" | "fail"
+/** v1.2: ready (every probe passes); pending (only user probes do not); failed (an integrity probe does not). */
+export type ReadinessState = "ready" | "pending" | "failed"
+
+export interface ProbeReadiness {
+  readonly kind: ProbeKind
+  readonly class: ProbeClass
+  readonly status: ProbeStatus
+  readonly detail?: string
+}
+
+export interface HarnessReadiness {
+  readonly harness: HarnessID
+  readonly state: ReadinessState
+  readonly probes: readonly ProbeReadiness[]
+  /** What the user does next, in order (empty when ready); never a command hubctl runs. */
+  readonly nextSteps: readonly string[]
+}
+
+/** v1.2: the user's next step for each pending user probe. */
+export const PENDING_STEPS: Readonly<Record<HarnessID, Readonly<Partial<Record<ProbeKind, string>>>>> = Object.freeze({
+  opencode: {
+    "provider-auth": "sign in to a model provider on this machine: run `opencode auth login`",
+    "spoke-connected": "start OpenCode (`opencode`) so the hub plugin connects its spoke",
+  },
+  "claude-code": {
+    "provider-auth": "log in to Claude Code on this machine: run `claude auth login`",
+    "spoke-connected": "start the claude-code spoke (`hub claude-code daemon`, or activate the hub services)",
+  },
+  codex: {
+    "provider-auth": "log in to Codex on this machine: run `codex login`",
+    "spoke-connected": "start the Codex spoke (`hub codex-spoke serve`, or activate the hub services)",
+  },
+})
+export const VERIFY_STEP = "then check readiness with `hubctl setup verify`"
+
+const fresh = (p: Probe, now: number) => p.ok && p.observedAt <= now + CLOCK_SKEW_MS && now - p.observedAt <= PROBE_MAX_AGE_MS
+
+/**
+ * v1.2: classifies a verification. Every REQUIRED_PROBES kind and every kind in `also` (the probes a verify-harness
+ * action asks for) must be present; a missing one is a failure (an adapter reports every probe it owes). `ready`
+ * implies isHarnessReady.
+ */
+export function harnessReadiness(verification: HarnessVerification, now: number, also: readonly ProbeKind[] = []): HarnessReadiness {
+  const required = REQUIRED_PROBES[verification.harness] ?? []
+  const kinds = [...required, ...also.filter((k) => !required.includes(k))]
+  const probes: ProbeReadiness[] = kinds.map((kind) => {
+    const found = verification.probes.filter((p) => p.kind === kind)
+    const cls = PROBE_CLASS[kind]
+    if (found.length === 0) return { kind, class: cls, status: "fail", detail: "not run" }
+    const bad = found.find((p) => !fresh(p, now))
+    const detail = (bad ?? found[found.length - 1]!).detail
+    const status: ProbeStatus = !bad ? "pass" : cls === "user" ? "pending" : "fail"
+    return { kind, class: cls, status, ...(detail !== undefined ? { detail } : {}) }
+  })
+  const state: ReadinessState = probes.some((p) => p.status === "fail") ? "failed" : probes.some((p) => p.status === "pending") ? "pending" : "ready"
+  const steps = state === "pending" ? probes.flatMap((p) => (p.status === "pending" ? (PENDING_STEPS[verification.harness]?.[p.kind] ?? []) : [])) : []
+  return { harness: verification.harness, state, probes, nextSteps: state === "pending" ? [...steps, VERIFY_STEP] : [] }
+}
+
+/** What an adapter may use: typed, injected capabilities only (the applier implements them). */
+export interface AdapterContext {
+  readonly env: Readonly<Record<string, string | undefined>>
+  readonly home: string
+  readonly platform: string
+  readonly arch: string
+  readonly now: () => number
+  readonly signal?: AbortSignal
+}
+
+export interface PlanInput {
+  readonly snapshot: DiscoverySnapshot
+  readonly profile: Profile
+}
+
+export interface HarnessAdapter {
+  readonly id: HarnessID
+  /** Presence and configuration only; health stays "unverified" until verify runs real probes. */
+  discover(context: AdapterContext): Promise<HarnessPresence>
+  /** Deterministic: the same snapshot and profile always give the same actions. */
+  plan(input: PlanInput): readonly Action[]
+  /** Runs the real probes (REQUIRED_PROBES) and reports each, passing or not. */
+  verify(context: AdapterContext): Promise<HarnessVerification>
+}
+
+export interface AdapterRegistry {
+  register(adapter: HarnessAdapter): void
+  get(id: HarnessID): HarnessAdapter | undefined
+  /** Registered adapters in HARNESS_ORDER. */
+  list(): readonly HarnessAdapter[]
+}
+
+export function createAdapterRegistry(): AdapterRegistry {
+  const adapters = new Map<HarnessID, HarnessAdapter>()
+  return {
+    register(adapter) {
+      if (!(HARNESS_ORDER as readonly string[]).includes(adapter.id)) throw new Error(`unknown harness ${String(adapter.id)} (one of ${HARNESS_ORDER.join(", ")})`)
+      if (adapters.has(adapter.id)) throw new Error(`harness ${adapter.id} is already registered`)
+      adapters.set(adapter.id, adapter)
+    },
+    get: (id) => adapters.get(id),
+    list: () => HARNESS_ORDER.flatMap((id) => adapters.get(id) ?? []),
+  }
+}

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

@@ -0,0 +1,28 @@
+// Bootstrap contracts, version 1 (frozen). The types, validators and pure decision rules every bootstrap layer
+// shares: discovery, planning and preview, profiles, artifact authentication, the executable contract, enrollment
+// status, the transaction journal and lock, harness adapters, and the output envelope. See
+// docs/bootstrap-contracts.md for the threat model and the requirement → check mapping.
+//
+// Changing a contract means a new schema version (and a migration where documents persist); never an in-place
+// change of meaning.
+export const CONTRACT_VERSION = 1
+/** The amendment of the v1 contracts this code implements (docs/bootstrap-contracts.md, items marked "v1.1"/"v1.2"). */
+export const CONTRACT_AMENDMENT = "1.2"
+
+export * from "./validate.ts"
+export * from "./canonical.ts"
+export * from "./secrets.ts"
+export * from "./platform.ts"
+export * from "./paths.ts"
+export * from "./exec.ts"
+export * from "./harness.ts"
+export * from "./actions.ts"
+export * from "./discovery.ts"
+export * from "./profile.ts"
+export * from "./plan.ts"
+export * from "./preview.ts"
+export * from "./artifact.ts"
+export * from "./credentials.ts"
+export * from "./journal.ts"
+export * from "./envelope.ts"
+