@huynle/hub 0.8.4 → 0.8.6

package/packages/cli/src/bootstrap/release/cli.ts

@@ -20,8 +20,17 @@
 //   trust-root [--key-id ID]
 //       Prints the v1 trust root (public key only) for the key in $HUB_RELEASE_SIGNING_KEY, for the maintainer
 //       who sets up the release key (README.md next to this file).
+//   dev --targets T,… --out DIR [--pins FILE] [--pending FILE | --no-pending] [--release V] [--minimum-version V]
+//       [--skip-pin-download] [--bun BIN]
+//       A throwaway release for testing on real machines (README "Testing on real machines"): a fresh ed25519 key,
+//       held only in memory, whose public trust root (DIR/dev-trust-root.json) the binaries embed; the hubctl
+//       builds; the reviewed and the pending (unreviewed) harness pins; a manifest signed with that key; and
+//       HUBCTL_SHA256SUMS. Serve DIR over HTTP and point a hub's HUB_RELEASE_BASE at it. Refuses to run with
+//       $HUB_RELEASE_SIGNING_KEY set, on GitHub Actions, or into the repository's dist/: it never makes a shipped
+//       artifact, and nothing but the binaries built here trusts its key.
 //
 // Exit codes: 0 ok, 1 other, 2 usage, 11 artifact rejected (contracts §3.11).
+import { generateKeyPairSync, randomBytes } from "node:crypto"
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"
 import path from "node:path"
 import pkg from "../../../package.json" with { type: "json" }
@@ -37,8 +46,8 @@ import {
   type Result,
   type TrustRoot,
 } from "../contracts/index.ts"
-import { buildManifestBody, manifestJSON, parseSigningKey, signVerified, trustRootFor } from "./manifest.ts"
-import { PIN_LIST_FILE, validatePinList, verifyPinDownloads, type Downloader } from "./pins.ts"
+import { buildManifestBody, hubctlFile, manifestJSON, parseSigningKey, signVerified, trustRootFor } from "./manifest.ts"
+import { PENDING_PIN_LIST_FILE, PIN_LIST_FILE, redownload, sortPins, validatePendingPinList, validatePinList, verifyPinDownloads, type Downloader } from "./pins.ts"
 import { shippedTrustRoot, trustRootDefine } from "./trust-root.ts"
 import { digestBytes, parseManifest, verifyHubctlRelease } from "./verify.ts"
 
@@ -171,7 +180,7 @@ export function hubctlBuildArgv(target: string, options: { readonly bun: string;
     ...(options.root ? trustRootDefine(options.root) : []),
     HUBCTL_ENTRY,
     "--outfile",
-    path.join(options.outdir, `hubctl-${t.target}`),
+    path.join(options.outdir, hubctlFile(t.target)),
   ]
 }
 
@@ -199,6 +208,20 @@ async function build(argv: readonly string[], io: ReleaseIo): Promise<number> {
   return 0
 }
 
+/** Each target's built hubctl in `dist`, with its size and digest. */
+function readArtifacts(dist: string, targets: readonly string[], what: string) {
+  return targets.map((target) => {
+    const file = hubctlFile(target)
+    let bytes: Uint8Array
+    try {
+      bytes = readFileSync(path.join(dist, file))
+    } catch {
+      throw new Failure(`missing ${path.join(dist, file)}: build ${what} first`, EXIT_OTHER)
+    }
+    return { target, file, ...digestBytes(bytes) }
+  })
+}
+
 async function manifest(argv: readonly string[], io: ReleaseIo): Promise<number> {
   const p = parseArgs(argv, ["--dist", "--pins", "--minimum-version", "--release", "--issued-at", "--out", "--targets"], [])
   const listed = targetsArg(p)
@@ -210,16 +233,7 @@ async function manifest(argv: readonly string[], io: ReleaseIo): Promise<number>
   const issuedAt = issuedText === undefined ? io.now() : Number(issuedText)
   if (!Number.isSafeInteger(issuedAt) || issuedAt < 0) throw new Usage("--issued-at takes milliseconds since the epoch")
   const pins = unwrap(validatePinList(readJSON(path.resolve(io.cwd, p.values.get("--pins") ?? PIN_LIST_FILE), "pin list")), "the pin list is invalid")
-  const artifacts = targets.map((target) => {
-    const file = `hubctl-${target}`
-    let bytes: Uint8Array
-    try {
-      bytes = readFileSync(path.join(dist, file))
-    } catch {
-      throw new Failure(`missing ${path.join(dist, file)}: build ${listed ? "every listed target" : "every supported target (or name a subset with --targets)"} first`, EXIT_OTHER)
-    }
-    return { target, file, ...digestBytes(bytes) }
-  })
+  const artifacts = readArtifacts(dist, targets, listed ? "every listed target" : "every supported target (or name a subset with --targets)")
   io.stderr(`re-downloading ${pins.pins.length} pinned harness file(s)\n`)
   const harnesses = unwrap(await verifyPinDownloads(pins, io.download), "a pinned harness file does not match its pin")
   const body = unwrap(
@@ -268,7 +282,7 @@ async function verify(argv: readonly string[], io: ReleaseIo): Promise<number> {
   const dist = p.values.get("--dist")
   if (listed && !dist) throw new Usage("--targets goes with --dist")
   const jobs: { target: string; file: string }[] = dist
-    ? (listed ?? SUPPORTED_TARGETS.map((t) => t.target)).map((target) => ({ target, file: path.resolve(io.cwd, dist, `hubctl-${target}`) }))
+    ? (listed ?? SUPPORTED_TARGETS.map((t) => t.target)).map((target) => ({ target, file: path.resolve(io.cwd, dist, hubctlFile(target)) }))
     : [{ target: required(p, "--target"), file: path.resolve(io.cwd, required(p, "--file")) }]
   const installedVersion = p.values.get("--installed")
   const installedSha = p.values.get("--installed-sha256")
@@ -304,9 +318,73 @@ async function trustRoot(argv: readonly string[], io: ReleaseIo): Promise<number
   return 0
 }
 
-const COMMANDS: Record<string, (argv: readonly string[], io: ReleaseIo) => Promise<number>> = { build, manifest, sign, verify, "trust-root": trustRoot }
+/** The file a dev release writes its (public) trust root to, in --out. */
+export const DEV_TRUST_ROOT_FILE = "dev-trust-root.json"
+
+async function dev(argv: readonly string[], io: ReleaseIo): Promise<number> {
+  const p = parseArgs(argv, ["--targets", "--out", "--pins", "--pending", "--release", "--minimum-version", "--bun"], ["--skip-pin-download", "--no-pending"])
+  // Never where a real release is made: a dev release is signed by a throwaway key and must never ship.
+  if (io.env[SIGNING_KEY_ENV] !== undefined) throw new Usage(`refusing a dev release while ${SIGNING_KEY_ENV} is set (that is the release signing job); dev releases never ship`)
+  if (io.env.GITHUB_ACTIONS === "true") throw new Usage("refusing a dev release on GitHub Actions; dev releases are for testing on your own machines and never ship")
+  const listed = targetsArg(p)
+  if (!listed) throw new Usage("--targets is required (e.g. --targets linux-x64,windows-x64)")
+  const out = path.resolve(io.cwd, required(p, "--out"))
+  const repoDist = path.resolve(io.cwd, "dist")
+  if (out === repoDist || out.startsWith(`${repoDist}${path.sep}`)) throw new Usage(`refusing a dev release into ${repoDist}, where release builds go; choose another --out`)
+  if (p.flags.has("--no-pending") && p.values.has("--pending")) throw new Usage("--pending and --no-pending exclude each other")
+
+  // The pins: the reviewed list, plus the pending (unreviewed) one, which only a dev release ever includes.
+  const reviewed = unwrap(validatePinList(readJSON(path.resolve(io.cwd, p.values.get("--pins") ?? PIN_LIST_FILE), "pin list")), "the pin list is invalid")
+  const pending = p.flags.has("--no-pending")
+    ? []
+    : unwrap(validatePendingPinList(readJSON(path.resolve(io.cwd, p.values.get("--pending") ?? PENDING_PIN_LIST_FILE), "pending pin list")), "the pending pin list is invalid").pins
+  const pins = [...reviewed.pins.map((e) => e.pin), ...pending.map((e) => e.pin)]
+  const seen = new Set<string>()
+  for (const pin of pins) {
+    const key = `${pin.harness} ${pin.target}`
+    if (seen.has(key)) throw new Failure(`${pin.harness} ${pin.target} is pinned in both the reviewed and the pending list; keep it in one`, EXIT_OTHER)
+    seen.add(key)
+  }
+  for (const { pin } of pending) io.stderr(`including a PENDING (unreviewed) pin: ${pin.harness} ${pin.version} ${pin.target} (${pin.file}); dev release only\n`)
+  if (!p.flags.has("--skip-pin-download")) {
+    io.stderr(`re-downloading ${pins.length} pinned harness file(s)\n`)
+    unwrap(await redownload(pins, io.download), "a pinned harness file does not match its pin")
+  }
+
+  // The throwaway key: in memory only. Its public trust root is written for reference (and for `verify`).
+  const { privateKey } = generateKeyPairSync("ed25519")
+  const keyID = `dev-${randomBytes(4).toString("hex")}`
+  const root = trustRootFor(privateKey, keyID)
+  mkdirSync(out, { recursive: true })
+  writeFileSync(path.join(out, DEV_TRUST_ROOT_FILE), `${JSON.stringify(root, null, 2)}\n`)
+
+  const bun = p.values.get("--bun") ?? process.execPath
+  for (const target of listed) {
+    const words = hubctlBuildArgv(target, { bun, outdir: out, root })
+    io.stderr(`==> ${words.at(-1)}\n`)
+    const code = await io.run(words)
+    if (code !== 0) throw new Failure(`bun build failed for ${target} (exit ${code})`, EXIT_OTHER)
+  }
+  const artifacts = readArtifacts(out, listed, "every listed target")
+  const body = unwrap(
+    buildManifestBody({ release: p.values.get("--release") ?? HUBCTL_VERSION, minimumVersion: p.values.get("--minimum-version") ?? "0.0.0", issuedAt: io.now(), artifacts, harnesses: sortPins(pins), targets: listed }),
+    "the manifest is invalid",
+  )
+  const verified = unwrap(signVerified(body, { keyID, privateKey }, root), "the dev manifest does not verify against its own trust root")
+  writeFileSync(path.join(out, "hubctl-manifest.json"), manifestJSON(verified))
+  // As sha256sum prints it (install.sh and install.ps1 read this file).
+  writeFileSync(path.join(out, "HUBCTL_SHA256SUMS"), artifacts.map((a) => `${a.sha256.slice("sha256:".length)}  ${a.file}\n`).join(""))
+  io.stdout(
+    `${out}: DEV release hubctl ${body.release} (${artifacts.map((a) => a.file).join(", ")}), ${body.harnesses.length} harness pins (${pending.length} pending), signed by throwaway key ${keyID}\n` +
+      `serve it:   cd ${out} && python3 -m http.server 8000 --bind 0.0.0.0\n` +
+      `on the hub: HUB_RELEASE_BASE=http://<this machine's LAN IP>:8000\n`,
+  )
+  return 0
+}
+
+const COMMANDS: Record<string, (argv: readonly string[], io: ReleaseIo) => Promise<number>> = { build, manifest, sign, verify, "trust-root": trustRoot, dev }
 
-const USAGE = "usage: hubctl-release <build|manifest|sign|verify|trust-root> [options] (see packages/cli/src/bootstrap/release/cli.ts)\n"
+const USAGE = "usage: hubctl-release <build|manifest|sign|verify|trust-root|dev> [options] (see packages/cli/src/bootstrap/release/cli.ts)\n"
 
 export async function runRelease(argv: readonly string[], io: ReleaseIo): Promise<number> {
   const [name, ...rest] = argv

package/packages/cli/src/bootstrap/release/harness-pins.pending.json

@@ -0,0 +1,24 @@
+{
+  "schema": "hub.harness-pin-pending",
+  "version": 1,
+  "pins": [
+    {
+      "pin": {
+        "harness": "opencode",
+        "version": "2.2.0",
+        "target": "windows-x64",
+        "url": "https://github.com/anomalyco/opencode/releases/download/v2.2.0/opencode-windows-x64-baseline.zip",
+        "file": "opencode-windows-x64-baseline.zip",
+        "size": 118610005,
+        "sha256": "sha256:810fe13f6d85c6121e8ab0dd09933ababa2d52dccce9f3bc9ec70de5a9ae126e",
+        "evidence": [],
+        "minimumVersion": "2.0.0"
+      },
+      "prepared": {
+        "by": "agent (Phase 2 release workstream; NOT a review)",
+        "on": "2026-11-05",
+        "note": "UNREVIEWED. The author downloaded the asset (curl -fsSL), measured 118610005 bytes and sha256 810fe13f…126e, which equal the release's SHA256SUMS line and the GitHub API assets[].digest for tag v2.2.0 (published 2026-10-27 by github-actions[bot] from dev). unzip -Zl lists exactly one member, opencode.exe (253303688 bytes, deflate, FAT host). The owner must redo every check of release/README.md themselves and move this entry into harness-pins.json with their own review record; until then only the dev release includes it."
+      }
+    }
+  ]
+}

package/packages/cli/src/bootstrap/release/manifest.ts

@@ -46,6 +46,9 @@ export interface SigningKey {
   readonly privateKey: KeyObject
 }
 
+/** The published file name of a target's hubctl: hubctl-<target>, with .exe on Windows (hubctl-windows-x64.exe). */
+export const hubctlFile = (target: string): string => `hubctl-${target}${target.startsWith("windows-") ? ".exe" : ""}`
+
 /** A pre-release (x.y.z-…) goes to `next`, everything else to `stable`. */
 export const channelFor = (release: string): "stable" | "next" => (SEMVER.exec(release)?.[4] ? "next" : "stable")
 

package/packages/cli/src/bootstrap/release/pins.ts

@@ -112,17 +112,18 @@ function checkSource(c: Checker, p: string, pin: unknown) {
   if (typeof pin.file === "string" && last !== pin.file) c.add(pointer(p, "file"), "inconsistent", `the file must be the URL's last path segment (${last})`)
 }
 
-export function validatePinList(value: unknown): Result<PinList> {
+/** The shared checks of both lists: the header, each entry (`record` names its review or prepared record), the pins. */
+function validateList(value: unknown, schema: string, record: string, checkRecord: (c: Checker, p: string, v: unknown) => void): Checker {
   const c = new Checker()
   const r = shape(c, "", value, ["schema", "version", "pins"])
-  if (!r) return c.result(value)
-  header(c, "", r, PIN_LIST_SCHEMA, PIN_LIST_VERSION)
+  if (!r) return c
+  header(c, "", r, schema, PIN_LIST_VERSION)
   const pins: unknown[] = []
   const listed = list(c, "/pins", r.pins, MAX_PINS, (p, entry) => {
-    const e = shape(c, p, entry, ["pin", "review"])
+    const e = shape(c, p, entry, ["pin", record])
     pins.push(e?.pin)
     if (!e) return
-    if (e.review !== undefined) checkReview(c, pointer(p, "review"), e.review)
+    if (e[record] !== undefined) checkRecord(c, pointer(p, record), e[record])
     checkSource(c, pointer(p, "pin"), e.pin)
   })
   if (listed) {
@@ -133,7 +134,48 @@ export function validatePinList(value: unknown): Result<PinList> {
     }
   }
   for (const path of findSecrets(value)) c.add(path, "secret", "a pin list never carries a secret")
-  return c.result(value)
+  return c
+}
+
+export function validatePinList(value: unknown): Result<PinList> {
+  return validateList(value, PIN_LIST_SCHEMA, "review", checkReview).result<PinList>(value)
+}
+
+// ---------- pins prepared but not reviewed yet ----------
+//
+// harness-pins.pending.json (schema `hub.harness-pin-pending`): pins an author (e.g. an agent) prepared from their own
+// download, waiting for the owner's review. Each carries a `prepared` record instead of a `review`, so it is never a
+// pin list the release job accepts (validatePinList refuses it), and only the dev release (`hubctl-release dev`)
+// includes it. Promoting a pin = moving the entry into harness-pins.json with the reviewer's own `review`.
+
+export const PENDING_PIN_LIST_SCHEMA = "hub.harness-pin-pending"
+export const PENDING_PIN_LIST_FILE = "packages/cli/src/bootstrap/release/harness-pins.pending.json"
+
+export interface PinPreparation {
+  /** Who prepared the entry (not a review). */
+  readonly by: string
+  /** YYYY-MM-DD. */
+  readonly on: string
+  /** What the author checked, and what the reviewer still has to. */
+  readonly note?: string
+}
+
+export interface PendingPinList {
+  readonly schema: typeof PENDING_PIN_LIST_SCHEMA
+  readonly version: typeof PIN_LIST_VERSION
+  readonly pins: readonly { readonly pin: HarnessPin; readonly prepared: PinPreparation }[]
+}
+
+function checkPrepared(c: Checker, p: string, v: unknown) {
+  const r = shape(c, p, v, ["by", "on"], ["note"])
+  if (!r) return
+  text(c, pointer(p, "by"), r.by, 80)
+  text(c, pointer(p, "on"), r.on, 10, DATE)
+  if (r.note !== undefined) text(c, pointer(p, "note"), r.note, 2000)
+}
+
+export function validatePendingPinList(value: unknown): Result<PendingPinList> {
+  return validateList(value, PENDING_PIN_LIST_SCHEMA, "prepared", checkPrepared).result<PendingPinList>(value)
 }
 
 const targetOrder = (a: HarnessPin, b: HarnessPin) =>
@@ -141,9 +183,12 @@ const targetOrder = (a: HarnessPin, b: HarnessPin) =>
 
 /** The manifest's `harnesses`: the pins in HARNESS_ORDER, then by target (deterministic). */
 export function harnessPins(list: PinList): HarnessPin[] {
-  return list.pins.map((p) => p.pin).sort(targetOrder)
+  return sortPins(list.pins.map((p) => p.pin))
 }
 
+/** Pins in the manifest's order (HARNESS_ORDER, then target). */
+export const sortPins = (pins: readonly HarnessPin[]): HarnessPin[] => [...pins].sort(targetOrder)
+
 export type Downloader = (url: string) => Promise<{ readonly size: number; readonly sha256: string }>
 
 /**
@@ -153,8 +198,14 @@ export type Downloader = (url: string) => Promise<{ readonly size: number; reado
 export async function verifyPinDownloads(value: unknown, download: Downloader): Promise<Result<HarnessPin[]>> {
   const valid = validatePinList(value)
   if (!valid.ok) return valid
+  const checked = await redownload(valid.value.pins.map((p) => p.pin), download)
+  return checked.ok ? ok(harnessPins(valid.value)) : checked
+}
+
+/** Downloads every pin again and compares size and digest (issue paths /pins/<i>/pin/…, in `pins` order). */
+export async function redownload(pins: readonly HarnessPin[], download: Downloader): Promise<Result<void>> {
   const c = new Checker()
-  for (const [i, { pin }] of valid.value.pins.entries()) {
+  for (const [i, pin] of pins.entries()) {
     const at = `/pins/${i}/pin`
     try {
       const got = await download(pin.url)
@@ -165,7 +216,7 @@ export async function verifyPinDownloads(value: unknown, download: Downloader):
     }
   }
   if (c.issues.length > 0) return { ok: false, issues: c.issues }
-  return ok(harnessPins(valid.value))
+  return ok(undefined)
 }
 
 /** Streams a URL and returns its size and digest (redirects followed); throws on an HTTP error. */

package/packages/cli/src/bootstrap/transaction/builtin.ts

@@ -5,10 +5,12 @@
 //   ensure-directory   a directory (an existing directory is left as it is)
 //   write-file         an embedded/rendered asset whose bytes must match the plan's digest; never overwrites
 //   merge-config       a lossless JSON merge, only if the file is still as previewed (precondition digest)
-//   link-executable    the hub ↔ hubctl alias symlink (an existing entry is backed up and replaced)
+//   link-executable    the hub ↔ hubctl alias symlink (an existing entry is backed up and replaced); on win32 a
+//                      cmd shim file instead (shim.ts), since executable symlinks need admin there
 //   select-harness-version  v1.1: the harness's `current` link, switched atomically to an installed version
-//                      directory (relative, so it reads the same inside and outside a container); the previous
-//                      link is backed up, so a rollback makes the previous version current again
+//                      directory (relative, so it reads the same inside and outside a container; on win32 an NTFS
+//                      junction, whose target is always absolute); the previous link is backed up, so a rollback
+//                      makes the previous version current again
 //   install-service    the rendered unit, whose bytes must match the plan's digest
 //   deactivate-service v1.1: unloads a hub service through the injected ServiceControl (an external effect; its
 //                      undo loads it again)
@@ -43,6 +45,7 @@ import {
 import type { ActionExecutor, ExecutorMap, StepContext, TreeFile } from "./executor.ts"
 import { mergeConfigText } from "./json-merge.ts"
 import { fromResult, txFail, txOk, type TxResult } from "./result.ts"
+import { cmdShim } from "./shim.ts"
 import { sha256Of } from "./state.ts"
 import { fileDigest, type StagedFile, type StagingArea } from "./stream.ts"
 
@@ -156,7 +159,15 @@ export const linkExecutableExecutor = (): ActionExecutor<"link-executable"> => (
     // The link's own path is symlink-checked (it is what gets written). Its target is only the link's text, never
     // written through, and may lead through a harness's `current` link, which is a symlink by design (§3.6.1).
     const target = ctx.resolve(action.target, { targetOnly: true })
-    return target.ok ? txOk({ type: "symlink", target: target.value, replace: "backup" }) : target
+    if (!target.ok) return target
+    if ((ctx.platform ?? process.platform) !== "win32") return txOk({ type: "symlink", target: target.value, replace: "backup" })
+    let shim: Uint8Array
+    try {
+      shim = cmdShim(target.value)
+    } catch (error) {
+      return txFail("invalid", (error as Error).message)
+    }
+    return txOk({ type: "file", bytes: shim, mode: 0o755, replace: "backup" })
   },
 })
 
@@ -167,8 +178,9 @@ export const selectHarnessVersionExecutor = (): ActionExecutor<"select-harness-v
     const dir = ctx.resolve(action.target)
     if (!dir.ok) return dir
     if (ctx.fs.lstat(dir.value)?.kind !== "directory") return txFail("not_found", `${action.harness} ${action.version} is not installed (${dir.value} is not a directory)`)
-    // `current` and the version directory are siblings (contract harnessCurrentRef / harnessVersionRef).
-    return txOk({ type: "symlink", target: action.version, replace: "backup" })
+    // `current` and the version directory are siblings (contract harnessCurrentRef / harnessVersionRef). A junction
+    // stores an absolute target, so on win32 the link's text is the version directory's canonical path.
+    return txOk({ type: "symlink", target: (ctx.platform ?? process.platform) === "win32" ? dir.value : action.version, replace: "backup" })
   },
 })