@huynle/hub 0.6.1 → 0.7.2

package/packages/cli/src/setup/contributors.ts

@@ -0,0 +1,171 @@
+// The plan contributors the CLI adds beside the harness adapters and the node services (preview/plan.ts
+// PlanContributor): pure, deterministic functions of (snapshot, profile) and what they were built with, so preview and
+// apply plan the same digest.
+//
+//   hubctlContributor      the standalone hubctl this verified manifest pins for the host's exact target, into
+//                          user-bin:hubctl (the stable authority services and MCP clients run), and the `hub` alias
+//                          next to it (one command surface; the name grants nothing).
+//   enrollmentContributor  inline enrollment: one enroll-machine for the hub the user named, only while this machine
+//                          is not enrolled with it (the device code is approved by a person on the hub).
+//   refusing               a contributor that can refuse: planSetup has no refusal channel for contributors, so a
+//                          Result failure is thrown as a typed PlanRefusal the CLI catches and maps with exitFor.
+import { ERROR_CODES, harnessCurrentRef, HARNESS_ORDER, selectArtifact, type Action, type ErrorCode, type HarnessID, type Issue, type PathRef, type PlanInput, type Result, type VerifiedManifest } from "../bootstrap/contracts/index.ts"
+import type { PlanContributor } from "../bootstrap/preview/plan.ts"
+import { userBinLinkDecision } from "./user-bin.ts"
+
+export const HUBCTL_REF = { root: "user-bin", rel: "hubctl" } as const
+export const HUB_ALIAS_REF = { root: "user-bin", rel: "hub" } as const
+
+/** A plan that cannot be made, with the envelope error code it maps to. */
+export class PlanRefusal extends Error {
+  override readonly name = "PlanRefusal"
+  constructor(
+    readonly code: ErrorCode,
+    message: string,
+  ) {
+    super(message)
+  }
+}
+
+/** The envelope code for a planner issue: the issue code when it is one, else `invalid`. */
+export const errorCodeOf = (code: string): ErrorCode => ((ERROR_CODES as readonly string[]).includes(code) ? (code as ErrorCode) : "invalid")
+
+export const issuesText = (issues: readonly Issue[]): string => issues.map((i) => `${i.path ? `${i.path}: ` : ""}${i.message}`).join("; ")
+
+/** A contributor from a planner that returns a Result: a refusal is thrown as a PlanRefusal. */
+export function refusing(plan: (input: PlanInput) => Result<readonly Action[]>): PlanContributor {
+  return (input) => {
+    const r = plan(input)
+    if (!r.ok) throw new PlanRefusal(errorCodeOf(r.issues[0]!.code), issuesText(r.issues))
+    return r.value
+  }
+}
+
+/**
+ * What is installed now (read-only): a file's digest (undefined when there is no regular file) and whether a path is
+ * a symlink to a target. The CLI reads the files the plan would write; tests inject fakes.
+ */
+export interface InstalledInspector {
+  sha256(ref: PathRef): string | undefined
+  linksTo(ref: PathRef, target: PathRef): boolean
+}
+
+/**
+ * The pinned hubctl and its `hub` alias, each only when not already in place: an installed hubctl with the pinned
+ * artifact's digest is that artifact, whichever path the hubctl that plans runs from (HBS-12 E3: a converged host
+ * plans no install and no link).
+ */
+export function hubctlContributor(options: { readonly manifest?: VerifiedManifest; readonly installed?: InstalledInspector }): PlanContributor {
+  return ({ snapshot }) => {
+    const manifest = options.manifest
+    if (!manifest) return []
+    const artifact = selectArtifact(manifest, snapshot.host.target)
+    if (!artifact.ok) return []
+    const installed = options.installed
+    const actions: Action[] = []
+    if (installed?.sha256(HUBCTL_REF) !== artifact.value.sha256)
+      actions.push({
+        id: "install-hubctl",
+        kind: "install-artifact",
+        escalation: "user",
+        summary: `Install hubctl ${manifest.release} for ${snapshot.host.target} as ~/.local/bin/hubctl (pinned by the signed release manifest)`,
+        artifact: "hubctl",
+        version: manifest.release,
+        target: snapshot.host.target,
+        sha256: artifact.value.sha256,
+        path: { ...HUBCTL_REF },
+      })
+    if (!installed?.linksTo(HUB_ALIAS_REF, HUBCTL_REF))
+      actions.push({ id: "link-hub", kind: "link-executable", escalation: "user", summary: "Link hub to hubctl (the same command surface)", path: { ...HUB_ALIAS_REF }, target: { ...HUBCTL_REF } })
+    return actions
+  }
+}
+
+/** Read-only facts about paths a plan would link, and the user's PATH (the CLI reads them through the probe). */
+export interface PathInspector {
+  /** What is at `ref` now, not following a final symlink. */
+  entry(ref: PathRef): "missing" | "file" | "directory" | "symlink" | "other"
+  /** The absolute path a symlink at `ref` points to (resolved against its directory); undefined for anything else. */
+  linkTarget(ref: PathRef): string | undefined
+  /** The absolute path of `ref` on this host. */
+  where(ref: PathRef): string | undefined
+  /** The first `name` on the user's PATH, as found (not followed). */
+  onPath(name: string): string | undefined
+}
+
+/** Each harness's executable: its command name, and where it is inside an install root (the adapters' unpackers). */
+export const HARNESS_EXECUTABLES: Readonly<Record<HarnessID, { readonly name: string; readonly rel: string; readonly label: string }>> = Object.freeze({
+  opencode: { name: "opencode", rel: "bin/opencode", label: "OpenCode" },
+  "claude-code": { name: "claude", rel: "claude", label: "Claude Code" },
+  codex: { name: "codex", rel: "bin/codex", label: "Codex" },
+})
+
+/**
+ * Contract amendment A6 (HBS-12 E4): a hub-installed harness goes on PATH through a typed link in user-bin
+ * (`~/.local/bin/opencode` → `data:hub/harnesses/opencode/current/bin/opencode`), journaled and rolled back like any
+ * link. Only for a harness hub makes current (this plan selects it, or its `current` is already there), and only when
+ * nothing else of that name is on PATH and user-bin holds nothing of that name but a link of hub's own (one into
+ * hub's harness directory): a user's binary is never shadowed or replaced.
+ */
+export function harnessLinkContributor(inspector: PathInspector): PlanContributor {
+  return ({ profile, planned = [] }) => {
+    const actions: Action[] = []
+    for (const harness of HARNESS_ORDER) {
+      if (!profile.harnesses.includes(harness)) continue
+      const exe = HARNESS_EXECUTABLES[harness]
+      const current = harnessCurrentRef(harness)
+      const target: PathRef = { root: current.root, rel: `${current.rel}/${exe.rel}` }
+      const selected = planned.some((a) => a.kind === "select-harness-version" && a.harness === harness)
+      if (!selected && inspector.entry(target) !== "file") continue
+      const link: PathRef = { root: "user-bin", rel: exe.name }
+      const linkPath = inspector.where(link)
+      const targetPath = inspector.where(target)
+      const ownDir = inspector.where({ root: current.root, rel: `hub/harnesses/${harness}` })
+      if (!linkPath || !targetPath || !ownDir) continue
+      const pointsTo = inspector.linkTarget(link)
+      const found = inspector.onPath(exe.name)
+      const decision = userBinLinkDecision({
+        entry: inspector.entry(link),
+        ...(pointsTo !== undefined ? { pointsTo } : {}),
+        target: targetPath,
+        linkPath,
+        hubOwned: (to) => to.startsWith(`${ownDir}/`),
+        ...(found !== undefined ? { foundOnPath: found } : {}),
+      })
+      if (decision !== "create" && decision !== "replace") continue
+      actions.push({
+        id: `link-${harness}`,
+        kind: "link-executable",
+        escalation: "user",
+        summary: `Put the hub-installed ${exe.label} on PATH: link ~/.local/bin/${exe.name} to its current version`,
+        path: link,
+        target,
+      })
+    }
+    return actions
+  }
+}
+
+export interface EnrollmentChoices {
+  /** The hub to enroll with (inline enrollment); without it the plan does not enroll. */
+  readonly server?: string
+  readonly machineName: string
+  /** The hub this machine is enrolled with now, if any (read from the credential store before planning). */
+  readonly enrolledWith: string | undefined
+}
+
+export function enrollmentContributor(choices: EnrollmentChoices): PlanContributor {
+  return () => {
+    if (!choices.server || choices.enrolledWith === choices.server) return []
+    return [
+      {
+        id: "enroll-machine",
+        kind: "enroll-machine",
+        escalation: "user",
+        summary: `Enroll this machine with ${choices.server} (device code; you approve it on the hub)`,
+        server: choices.server,
+        machineName: choices.machineName,
+      },
+    ]
+  }
+}

package/packages/cli/src/setup/dispatch.ts

@@ -0,0 +1,74 @@
+// Per-harness dispatch (HBS-13 integration item 1, adapter amendment A2). The engine holds one executor per action
+// kind (ExecutorMap) and builtinExecutors one HarnessSource, but OpenCode, Claude Code and Codex each supply their own
+// install-harness source and verify-harness (and OpenCode its register-mcp-server) executor. These route each step
+// by `action.harness`. A harness nothing was registered for is refused with a typed failure at preflight, never
+// thrown and never handed to another harness's executor.
+import type { HarnessID, InstallHarness } from "../bootstrap/contracts/index.ts"
+import type { HarnessSource } from "../bootstrap/transaction/builtin.ts"
+import type { ActionExecutor, ActionOf, StepPlan } from "../bootstrap/transaction/executor.ts"
+import { TxError, txFail, txOk } from "../bootstrap/transaction/result.ts"
+
+/** The action kinds that name a harness. */
+export type HarnessScopedKind = "install-harness" | "verify-harness" | "register-mcp-server"
+
+const LABEL: Readonly<Record<HarnessScopedKind, string>> = {
+  "install-harness": "installs",
+  "verify-harness": "verifies",
+  "register-mcp-server": "registers MCP servers with",
+}
+
+/** One executor of `kind` that hands each action to the executor registered for its harness. */
+export function dispatchByHarness<K extends HarnessScopedKind>(kind: K, executors: Partial<Record<HarnessID, ActionExecutor<K>>>): ActionExecutor<K> {
+  const harnessOf = (action: ActionOf<K>) => (action as { readonly harness: HarnessID }).harness
+  const pick = (action: ActionOf<K>) => executors[harnessOf(action)]
+  const missing = (action: ActionOf<K>) => txFail("internal", `this hubctl ${LABEL[kind]} no ${harnessOf(action)} (no executor for ${kind} on ${harnessOf(action)})`)
+  // The journal class must not depend on what is registered: an unregistered harness keeps the kind's class.
+  const fallback = (action: ActionOf<K>): StepPlan =>
+    kind === "verify-harness" ? { class: "external" } : { class: kind === "install-harness" ? "harness" : "config", path: (action as { path: StepPlan["path"] }).path }
+  return {
+    kind,
+    plan: (action) => pick(action)?.plan(action) ?? fallback(action),
+    check: async (action, ctx) => {
+      const exec = pick(action)
+      if (!exec) return missing(action)
+      return exec.check ? exec.check(action, ctx) : txOk(undefined)
+    },
+    change: async (action, ctx) => {
+      const exec = pick(action)
+      return exec ? exec.change(action, ctx) : missing(action)
+    },
+    undo: async (action, ctx) => {
+      const exec = pick(action)
+      if (!exec) return missing(action)
+      return exec.undo ? exec.undo(action, ctx) : txOk(undefined)
+    },
+  }
+}
+
+export interface HarnessSources {
+  /** The verified hub manifest every source pins against (one per release). */
+  readonly manifest: HarnessSource["manifest"]
+  readonly sources: Partial<Record<HarnessID, HarnessSource>>
+  /** Explicit --allow-downgrade (for every harness). */
+  readonly allowDowngrade?: boolean
+}
+
+/** One HarnessSource (builtinExecutors({harness})) over the adapters' sources, by `action.harness`. */
+export function dispatchHarnessSource(options: HarnessSources): HarnessSource {
+  const pick = (action: InstallHarness) => options.sources[action.harness]
+  return {
+    manifest: options.manifest,
+    ...(options.allowDowngrade ? { allowDowngrade: true } : {}),
+    fetch: async (action, staging) => {
+      const source = pick(action)
+      if (!source) throw new TxError("internal", `this hubctl has no source to install ${action.harness} from`)
+      return source.fetch(action, staging)
+    },
+    unpack: async (action, file, staging) => {
+      const source = pick(action)
+      return source ? source.unpack(action, file, staging) : txFail("internal", `this hubctl has no source to install ${action.harness} from`)
+    },
+    installed: (harness) => options.sources[harness]?.installed?.(harness),
+    floor: (harness) => options.sources[harness]?.floor?.(harness),
+  }
+}

package/packages/cli/src/setup/launch-driver.ts

@@ -0,0 +1,109 @@
+// The LaunchDriver of `hubctl setup`'s optional verification launch (launch-session; node-services/launch.ts),
+// over the existing hub launch API (the SDK's hub.launches, as `hub launch` uses it; no new central capability):
+//
+//   start         one launch of the harness in the workspace (checkout mode: the repository as it is), pinned to
+//                 this machine (placement require), ending when idle, cut off at the bound, cleaned up by the hub
+//   awaitResponse until the launch runs a session (or ended without one: failed)
+//   awaitIdle     until it ended idle (any other outcome fails)
+//   inspect       what the node reported it left in the workspace (uncommitted changes, commits)
+//   cleanup       nothing more: cleanup "remove" makes the hub's node remove the launch's own workspace changes
+//   cancel        stops the launch (an ended one is already gone)
+//   slotFree      whether the launch still counts against the node (any state but ended)
+//
+// The launch carries no credential; the caller's own hub login (`hub login`, an app token allowed to launch) is
+// what the SDK client authenticates with. Every wait polls with the verification's abort signal.
+import { randomBytes } from "node:crypto"
+import type { LaunchSpec, LaunchView, Launches } from "../../../sdk/src/index.ts"
+import type { LaunchDriver } from "../bootstrap/adapters/node-services/launch.ts"
+import { txFail, txOk } from "../bootstrap/transaction/result.ts"
+
+export const VERIFY_PROMPT = "This is a hubctl setup check: reply with the single word OK and change nothing."
+
+export interface HubLaunchDriverOptions {
+  readonly launches: Pick<Launches, "create" | "get" | "stop" | "list">
+  /** This machine's ID (the stored machine credential's); undefined: not enrolled. */
+  readonly machineID: () => Promise<string | undefined>
+  readonly pollMs?: number
+  readonly sleep?: (ms: number, signal: AbortSignal) => Promise<void>
+}
+
+const ACTIVE = ["queued", "placing", "provisioning", "running"] as const
+
+const abortableSleep = (ms: number, signal: AbortSignal) =>
+  new Promise<void>((resolve, reject) => {
+    if (signal.aborted) return reject(new Error("aborted"))
+    const t = setTimeout(resolve, ms)
+    signal.addEventListener("abort", () => (clearTimeout(t), reject(new Error("aborted"))), { once: true })
+  })
+
+const message = (error: unknown) => (error instanceof Error ? error.message : String(error))
+
+export function hubLaunchDriver(options: HubLaunchDriverOptions): LaunchDriver {
+  const pollMs = options.pollMs ?? 1000
+  const sleep = options.sleep ?? abortableSleep
+  const get = async (id: string): Promise<LaunchView> => (await options.launches.get(id)).launch
+
+  /** Polls until `done` says so (true: ok; a string: failed with it). */
+  async function until(id: string, signal: AbortSignal, done: (l: LaunchView) => true | string | undefined) {
+    try {
+      for (;;) {
+        const r = done(await get(id))
+        if (r === true) return txOk(undefined)
+        if (typeof r === "string") return txFail("harness_not_ready", r)
+        await sleep(pollMs, signal)
+      }
+    } catch (error) {
+      return txFail(signal.aborted ? "cancelled" : "offline", signal.aborted ? "cancelled" : `the hub could not be asked about launch ${id} (${message(error)})`)
+    }
+  }
+
+  return {
+    async start(request, signal) {
+      const machine = await options.machineID().catch(() => undefined)
+      if (!machine) return txFail("unauthorized", "this machine is not enrolled (run `hubctl machine enroll`)")
+      const spec: LaunchSpec = {
+        key: `hubctl-verify-${randomBytes(8).toString("hex")}`,
+        harness: request.harness,
+        workspace: { repo: request.workspace, mode: "checkout" },
+        placement: { machine, mode: "require" },
+        prompt: VERIFY_PROMPT,
+        labels: { "hub.setup": "verify" },
+        end: { when: "idle", timeout: `${Math.max(1, Math.ceil(request.maxDurationS / 60))}m`, cleanup: "remove" },
+      }
+      try {
+        const created = await options.launches.create(spec, { signal })
+        return txOk({ launchID: created.launch.id })
+      } catch (error) {
+        return txFail("harness_not_ready", `the hub refused the verification launch (${message(error)}); it needs \`hub login --scope sessions:launch\` and a grant with verb launch`)
+      }
+    },
+    awaitResponse: (id, signal) => until(id, signal, (l) => (l.state === "running" && l.sessionID ? true : l.state === "ended" ? `the launch ended ${l.outcome ?? ""} before its session answered`.trim() : undefined)),
+    awaitIdle: (id, signal) => until(id, signal, (l) => (l.state !== "ended" ? undefined : l.outcome === "idle" ? true : `the launch ended ${l.outcome ?? "without an outcome"}, not idle`)),
+    async inspect(id) {
+      try {
+        const a = (await get(id)).artifacts
+        const leftovers = [...(a?.dirty ? ["uncommitted changes"] : []), ...(a?.commits ? [`${a.commits} commit(s) on the launch branch`] : [])]
+        return txOk({ leftovers })
+      } catch (error) {
+        return txFail("offline", `the hub could not be asked about launch ${id} (${message(error)})`)
+      }
+    },
+    cleanup: async () => txOk(undefined),
+    async cancel(id) {
+      try {
+        if ((await get(id)).state !== "ended") await options.launches.stop(id)
+        return txOk(undefined)
+      } catch (error) {
+        return txFail("offline", `launch ${id} could not be stopped (${message(error)})`)
+      }
+    },
+    async slotFree(id) {
+      try {
+        const { launches } = await options.launches.list({ state: [...ACTIVE] })
+        return txOk(!launches.some((l) => l.id === id))
+      } catch (error) {
+        return txFail("offline", `the hub could not list launches (${message(error)})`)
+      }
+    },
+  }
+}