@huynle/hub 0.7.1 → 0.7.3

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

@@ -0,0 +1,146 @@
+// Read-only discovery: what `hubctl setup discover` reports about this host, as a contract DiscoverySnapshot.
+// Everything comes through the injected DiscoveryProbe (reads only). Discovery never runs a harness (running even
+// `--version` may create state), never records file contents or environment values, and never claims health:
+// every harness it finds stays "unverified" until an adapter runs real probes. The snapshot is deterministic: the
+// same host gives the same document, except for capturedAt.
+import {
+  checkTarget,
+  EMBEDDED_ASSETS,
+  fail,
+  HARNESS_ORDER,
+  hostFingerprint,
+  PACKAGE_MANAGERS,
+  rootPathIn,
+  SEMVER,
+  sha256Hex,
+  targetOf,
+  validateDiscoverySnapshot,
+  type ConfigFile,
+  type DiscoverySnapshot,
+  type ExecutionContext,
+  type HarnessPresence,
+  type PackageManager,
+  type Result,
+  type RootID,
+  type RootMapping,
+  type RuntimeInfo,
+  type Shim,
+} from "../contracts/index.ts"
+import { classifyExecutable, HARNESS_BINARIES, installOf, pathDirs, which } from "./executables.ts"
+import { discoverContainer, discoverLibc, discoverOS, discoverRoots, mapContainerRoots, parseMountinfo } from "./host.ts"
+import type { DiscoveryProbe } from "./probe.ts"
+import { decode, join, normalizeAbs } from "./util.ts"
+
+export interface DiscoverOptions {
+  readonly now: number
+}
+
+// ---------- configs ----------
+
+interface ConfigCandidate {
+  readonly path: string
+  readonly owner: ConfigFile["owner"]
+  readonly format: ConfigFile["format"]
+}
+
+/** The config files a setup plan might touch, with their owners, as seen from `context` (where discovery runs). */
+export function configCandidates(platform: string, roots: readonly RootMapping[], context: ExecutionContext = "host"): ConfigCandidate[] {
+  const at = (id: RootID, rel: string) => {
+    const r = roots.find((x) => x.id === id)
+    return r ? join(rootPathIn(r, context), rel) : undefined
+  }
+  const list: (ConfigCandidate | undefined)[] = []
+  const add = (id: RootID, rel: string, owner: ConfigFile["owner"], format: ConfigFile["format"]) => {
+    const path = at(id, rel)
+    list.push(path ? { path, owner, format } : undefined)
+  }
+  add("config", "hub/config.json", "hub", "json")
+  add("config", "hub/node.json", "hub", "json")
+  add("config", "hub/claude-code.json", "hub", "json")
+  add("config", "opencode/opencode.json", "harness:opencode", "json")
+  add("config", "opencode/opencode.jsonc", "harness:opencode", "jsonc")
+  add("home", ".claude.json", "harness:claude-code", "json")
+  add("home", ".claude/settings.json", "harness:claude-code", "json")
+  add("home", ".codex/config.toml", "harness:codex", "toml")
+  for (const asset of Object.values(EMBEDDED_ASSETS)) {
+    if (platform === "darwin" && asset.manager === "launchd") add("launch-agents", asset.installAs, "hub", "plist")
+    if (platform === "linux" && asset.manager === "systemd-user") add("systemd-user", asset.installAs, "hub", "unit")
+  }
+  return list.filter((c): c is ConfigCandidate => c !== undefined)
+}
+
+// ---------- snapshot ----------
+
+/** Where each harness's binary is inside a hub install root (the adapters' unpackers). */
+const HARNESS_BIN_DIR: Readonly<Record<(typeof HARNESS_ORDER)[number], string>> = { opencode: "/bin", "claude-code": "", codex: "/bin" }
+
+/** Discovers this host through `probe`. Fails (instead of recording) if anything found looks like a credential. */
+export function discover(probe: DiscoveryProbe, options: DiscoverOptions): Result<DiscoverySnapshot> {
+  let roots = discoverRoots(probe)
+  if (!roots) return fail("/roots", "unmapped_root", "this host has no absolute home directory")
+  const home = roots[0]!.path
+  const libc = discoverLibc(probe)
+  const target = targetOf(probe.platform, probe.arch, libc)
+  const container = discoverContainer(probe)
+  // v1.1: discovery runs where apply will run; inside a container every root is read as containerPath ?? path.
+  const context: ExecutionContext = container === "none" ? "host" : "container"
+  if (container !== "none") roots = mapContainerRoots(roots, parseMountinfo(decode(probe.readFile("/proc/self/mountinfo", 1024 * 1024))))
+
+  const dirs = pathDirs(probe)
+  const extra = probe.platform === "darwin" ? ["/opt/homebrew/bin", "/usr/local/bin"] : ["/usr/local/sbin", "/usr/sbin", "/sbin", "/nix/var/nix/profiles/default/bin"]
+  const managerDirs = [...dirs, ...extra.filter((d) => !dirs.includes(d))]
+  const packages: PackageManager[] = PACKAGE_MANAGERS.filter((m) => which(probe, managerDirs, m) !== undefined)
+  const runtime: RuntimeInfo[] = probe.runtime && SEMVER.test(probe.runtime.version) && normalizeAbs(probe.runtime.path) ? [{ ...probe.runtime }] : []
+  let service: DiscoverySnapshot["managers"]["service"] = "none"
+  if (probe.platform === "darwin" && probe.executable("/bin/launchctl")) service = "launchd"
+  if (probe.platform === "linux" && probe.lstat("/run/systemd/system") === "directory" && which(probe, [...dirs, "/usr/bin", "/bin"], "systemctl")) service = "systemd-user"
+
+  const shims: Shim[] = []
+  const harnesses: HarnessPresence[] = HARNESS_ORDER.map((id) => {
+    const name = HARNESS_BINARIES[id]
+    const known = id === "opencode" ? [join(home, ".opencode/bin")] : id === "claude-code" ? [join(home, ".local/bin"), join(home, ".claude/local")] : []
+    // A harness hub installed (data:hub/harnesses/<id>/current) is found off PATH too, so a rerun after an install
+    // sees it (installMethod "hub") and plans nothing more. PATH still wins.
+    const data = roots!.find((r) => r.id === "data")
+    if (data) known.push(join(rootPathIn(data, context), `hub/harnesses/${id}/current${HARNESS_BIN_DIR[id]}`))
+    const path = which(probe, [...dirs, ...known.filter((d) => !dirs.includes(d))], name)
+    if (!path) return { id, installed: false, health: { state: "unverified", probes: [] } }
+    const shim = classifyExecutable(probe, name, path)
+    shims.push(shim)
+    const install = installOf(probe, id, shim, roots!, context)
+    return { id, installed: true, path, ...(install.version ? { version: install.version } : {}), installMethod: install.installMethod, health: { state: "unverified", probes: [] } }
+  })
+
+  const configs: ConfigFile[] = []
+  for (const c of configCandidates(probe.platform, roots, context)) {
+    if (probe.stat(c.path) !== "file") continue
+    const bytes = probe.readFile(c.path)
+    if (!bytes) return fail("/configs", "invalid_value", `${c.path} exists but cannot be read; discovery will not guess its contents`)
+    configs.push({ ...c, sha256: `sha256:${sha256Hex(bytes)}` })
+  }
+  configs.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0))
+
+  const machineID = probe.machineID()?.trim() || `hostname:${probe.hostname}`
+  const snapshot: DiscoverySnapshot = {
+    schema: "hub.discovery-snapshot",
+    version: 1,
+    capturedAt: options.now,
+    host: {
+      fingerprint: hostFingerprint({ machineID, platform: probe.platform, arch: probe.arch, uid: probe.uid, home }),
+      platform: probe.platform,
+      arch: probe.arch,
+      libc,
+      target,
+      supported: checkTarget(target).ok,
+      os: discoverOS(probe),
+    },
+    topology: { container, shims },
+    managers: { package: packages, runtime, service },
+    harnesses,
+    runtimes: [{ id: "openshell", present: which(probe, dirs, "openshell") !== undefined }],
+    configs,
+    roots,
+  }
+  return validateDiscoverySnapshot(snapshot)
+}
+

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

@@ -0,0 +1,134 @@
+// Executables on PATH: where a command is, whether it is a native binary, a wrapper script or a shim into a
+// container (docker/podman exec), what it resolves to, and how (and at which version) a harness was installed,
+// read from the install layout. A harness is never run to find out.
+import { rootPathIn, SEMVER, type ExecutionContext, type HarnessID, type InstallMethod, type RootMapping, type Shim, type ShimKind } from "../contracts/index.ts"
+import type { DiscoveryProbe } from "./probe.ts"
+import { decode, join, normalizeAbs } from "./util.ts"
+
+/** How much of an executable discovery reads to tell a native binary from a script. */
+const HEAD_BYTES = 4096
+const MAX_PATH_DIRS = 64
+
+/** The command each harness is started with. */
+export const HARNESS_BINARIES: Readonly<Record<HarnessID, string>> = Object.freeze({ opencode: "opencode", "claude-code": "claude", codex: "codex" })
+
+// ---------- executables ----------
+
+export function pathDirs(probe: DiscoveryProbe): string[] {
+  const dirs: string[] = []
+  for (const raw of (probe.env.PATH ?? "").split(":")) {
+    const d = normalizeAbs(raw)
+    if (d && !dirs.includes(d)) dirs.push(d)
+    if (dirs.length >= MAX_PATH_DIRS) break
+  }
+  return dirs
+}
+
+export function which(probe: DiscoveryProbe, dirs: readonly string[], name: string): string | undefined {
+  for (const d of dirs) {
+    const candidate = join(d, name)
+    if (probe.executable(candidate)) return candidate
+  }
+  return undefined
+}
+
+const CONTAINER_EXEC = /\b(?:docker|podman|nerdctl|distrobox|toolbox|lxc|lxc-attach)\b[^\n]*\b(?:exec|enter|run|attach)\b/
+/** Container-exec options that take a value (the next word is not the program). */
+const VALUE_OPTIONS = new Set(["-w", "--workdir", "-e", "--env", "-u", "--user", "--env-file", "--detach-keys", "--name"])
+
+/** The first absolute program path after a container exec (`docker exec -i box /usr/bin/opencode "$@"`). */
+function containerTarget(script: string): string | undefined {
+  const line = script.split("\n").find((l) => CONTAINER_EXEC.test(l))
+  if (!line) return undefined
+  const words = line.trim().split(/\s+/)
+  const start = words.findIndex((w, i) => /^(?:exec|enter|run|attach)$/.test(w) && words.slice(0, i).some((x) => /(?:docker|podman|nerdctl|distrobox|toolbox|lxc|lxc-attach)$/.test(x)))
+  for (let i = start + 1; start >= 0 && i < words.length; i++) {
+    if (VALUE_OPTIONS.has(words[i - 1]!)) continue
+    const p = normalizeAbs(words[i])
+    if (p) return p
+  }
+  return undefined
+}
+
+/** The absolute program a wrapper script execs (`exec /opt/x/bin/tool "$@"`). */
+function wrapperTarget(script: string): string | undefined {
+  for (const line of script.split("\n").slice(1)) {
+    const m = /^\s*exec\s+(\S+)/.exec(line)
+    const p = m ? normalizeAbs(m[1]) : undefined
+    if (p) return p
+  }
+  return undefined
+}
+
+const MAGIC = [
+  [0x7f, 0x45, 0x4c, 0x46], // ELF
+  [0xcf, 0xfa, 0xed, 0xfe],
+  [0xce, 0xfa, 0xed, 0xfe],
+  [0xfe, 0xed, 0xfa, 0xcf],
+  [0xfe, 0xed, 0xfa, 0xce],
+  [0xca, 0xfe, 0xba, 0xbe], // Mach-O (thin and universal)
+]
+
+/** What an executable on PATH is: a native binary, a script wrapper, or a shim into a container. */
+export function classifyExecutable(probe: DiscoveryProbe, name: string, path: string): Shim {
+  const isLink = probe.lstat(path) === "symlink"
+  const real = isLink ? normalizeAbs(probe.realpath(path)) : undefined
+  const head = probe.readFile(path, HEAD_BYTES) ?? new Uint8Array()
+  const native = MAGIC.some((m) => m.every((b, i) => head[i] === b))
+  let kind: ShimKind = native || isLink ? "host" : "unknown"
+  let resolvesTo = real && real !== path ? real : undefined
+  if (!native && head[0] === 0x23 && head[1] === 0x21) {
+    const script = decode(head)
+    if (CONTAINER_EXEC.test(script)) {
+      kind = "container-shim"
+      resolvesTo = containerTarget(script)
+    } else {
+      kind = "wrapper"
+      resolvesTo ??= wrapperTarget(script)
+    }
+  }
+  return resolvesTo ? { name, path, kind, resolvesTo } : { name, path, kind }
+}
+
+function packageVersion(probe: DiscoveryProbe, real: string): string | undefined {
+  const m = /^(.*\/node_modules\/(?:@[^/]+\/)?[^/]+)\//.exec(real)
+  if (!m) return undefined
+  try {
+    const pkg = JSON.parse(decode(probe.readFile(`${m[1]}/package.json`, 64 * 1024))) as { version?: unknown }
+    return typeof pkg.version === "string" && SEMVER.test(pkg.version) ? pkg.version : undefined
+  } catch {
+    return undefined
+  }
+}
+
+/** How a harness was installed, and its version when the install layout states it (never by running it). */
+export function installOf(probe: DiscoveryProbe, id: HarnessID, shim: Shim, roots: readonly RootMapping[], context: ExecutionContext = "host"): { installMethod: InstallMethod; version?: string } {
+  if (shim.kind === "container-shim") return { installMethod: "unknown" }
+  const real = shim.kind === "host" || shim.kind === "wrapper" ? (shim.resolvesTo ?? shim.path) : shim.path
+  const semver = (v: string | undefined) => (v && SEMVER.test(v) ? v : undefined)
+  // Paths are read in this (possibly container) view of each root (v1.1 rootPathIn).
+  const local = (root: string) => {
+    const r = roots.find((x) => x.id === root)
+    return r ? rootPathIn(r, context) : undefined
+  }
+  const data = local("data")
+  const home = local("home")
+  const hubLayout = data ? new RegExp(`^${escape(data)}/hub/harnesses/${escape(id)}/([^/]+)(?:/|$)`) : undefined
+  let hub = hubLayout?.exec(real) ?? null
+  // v1.1 layout: `current` is a link to the version directory in use; the version is where it leads.
+  if (hub?.[1] === "current") hub = hubLayout!.exec(normalizeAbs(probe.realpath(real)) ?? "") ?? null
+  if (hub && semver(hub[1])) return { installMethod: "hub", version: hub[1] }
+  const brew = /\/(?:Cellar|Caskroom)\/[^/]+\/([^/]+)\//.exec(real)
+  if (brew) return { installMethod: "brew", ...(semver(brew[1]) ? { version: brew[1] } : {}) }
+  if (real.includes("/node_modules/")) {
+    const version = packageVersion(probe, real)
+    return { installMethod: "npm", ...(version ? { version } : {}) }
+  }
+  const claude = /\/claude\/versions\/([^/]+)$/.exec(real)
+  if (id === "claude-code" && claude) return { installMethod: "native", ...(semver(claude[1]) ? { version: claude[1] } : {}) }
+  if (home && id === "opencode" && real.startsWith(`${home}/.opencode/bin/`)) return { installMethod: "native" }
+  if (/^\/(?:usr\/)?s?bin\//.test(real)) return { installMethod: "package-manager" }
+  return { installMethod: "unknown" }
+}
+
+const escape = (s: string) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")

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

@@ -0,0 +1,96 @@
+// Host facts: path roots (and their host location inside a container), C library, OS name and version, and
+// container kind. Everything is read through the probe; nothing is executed.
+import { ROOT_IDS, type ContainerKind, type Libc, type RootID, type RootMapping } from "../contracts/index.ts"
+import type { DiscoveryProbe } from "./probe.ts"
+import { decode, join, normalizeAbs, oneLine } from "./util.ts"
+
+// ---------- roots ----------
+
+export function discoverRoots(probe: DiscoveryProbe): RootMapping[] | undefined {
+  const home = normalizeAbs(probe.env.HOME) ?? normalizeAbs(probe.home)
+  if (!home) return undefined
+  const xdg = (key: string, fallback: string) => normalizeAbs(probe.env[key]) ?? join(home, fallback)
+  const config = xdg("XDG_CONFIG_HOME", ".config")
+  const paths: Partial<Record<RootID, string>> = {
+    home,
+    config,
+    state: xdg("XDG_STATE_HOME", ".local/state"),
+    data: xdg("XDG_DATA_HOME", ".local/share"),
+    "user-bin": join(home, ".local/bin"),
+    "system-bin": "/usr/local/bin",
+  }
+  if (probe.platform === "darwin") paths["launch-agents"] = join(home, "Library/LaunchAgents")
+  if (probe.platform === "linux") paths["systemd-user"] = join(config, "systemd/user")
+  return ROOT_IDS.flatMap((id) => (paths[id] ? [{ id, path: paths[id]! }] : []))
+}
+
+export interface Mount {
+  readonly root: string
+  readonly point: string
+}
+
+const unescapeMount = (s: string) => s.replace(/\\([0-7]{3})/g, (_, o: string) => String.fromCharCode(parseInt(o, 8)))
+
+export function parseMountinfo(text: string): Mount[] {
+  const mounts: Mount[] = []
+  for (const line of text.split("\n")) {
+    const f = line.split(" ")
+    if (f.length < 5) continue
+    const root = normalizeAbs(unescapeMount(f[3]!))
+    const point = normalizeAbs(unescapeMount(f[4]!))
+    if (root && point) mounts.push({ root, point })
+  }
+  return mounts
+}
+
+/** In a container: where each root lives on the host, when it sits in a bind mount of a host directory. */
+export function mapContainerRoots(roots: RootMapping[], mounts: readonly Mount[]): RootMapping[] {
+  return roots.map((r) => {
+    const mount = mounts
+      .filter((m) => r.path === m.point || r.path.startsWith(m.point === "/" ? "/" : `${m.point}/`))
+      .sort((a, b) => b.point.length - a.point.length)[0]
+    if (!mount || mount.root === "/" || mount.root === mount.point) return r
+    const host = normalizeAbs(mount.root + r.path.slice(mount.point.length))
+    return host ? { id: r.id, path: host, containerPath: r.path } : r
+  })
+}
+
+// ---------- host ----------
+
+export function discoverLibc(probe: DiscoveryProbe): Libc {
+  if (probe.platform === "darwin") return "none"
+  if (probe.platform !== "linux") return "unknown"
+  const names = ["/lib", "/lib64", "/usr/lib"].flatMap((d) => probe.readdir(d) ?? [])
+  if (names.some((n) => n.startsWith("ld-musl-"))) return "musl"
+  if (names.some((n) => n.startsWith("ld-linux"))) return "glibc"
+  return "unknown"
+}
+
+export function discoverOS(probe: DiscoveryProbe): { name: string; version: string } {
+  if (probe.platform === "darwin") {
+    const plist = decode(probe.readFile("/System/Library/CoreServices/SystemVersion.plist", 64 * 1024))
+    const value = (key: string) => oneLine(new RegExp(`<key>${key}</key>\\s*<string>([^<]*)</string>`).exec(plist)?.[1])
+    return { name: value("ProductName") ?? "macOS", version: value("ProductVersion") ?? "unknown" }
+  }
+  if (probe.platform === "linux") {
+    const text = decode(probe.readFile("/etc/os-release", 64 * 1024) ?? probe.readFile("/usr/lib/os-release", 64 * 1024))
+    const value = (key: string) => oneLine(new RegExp(`^${key}=(.*)$`, "m").exec(text)?.[1]?.trim().replace(/^(["'])(.*)\1$/, "$2"))
+    return { name: value("NAME") ?? "Linux", version: value("VERSION_ID") ?? "unknown" }
+  }
+  return { name: oneLine(probe.platform, 32) ?? "unknown", version: "unknown" }
+}
+
+export function discoverContainer(probe: DiscoveryProbe): ContainerKind {
+  if (probe.platform !== "linux") return "none"
+  if (probe.lstat("/.dockerenv") !== "missing") return "docker"
+  if (probe.lstat("/run/.containerenv") !== "missing") return "podman"
+  const env = probe.env.container
+  if (env === "docker" || env === "podman" || env === "lxc") return env
+  if (env) return "unknown"
+  const cgroup = decode(probe.readFile("/proc/1/cgroup", 64 * 1024))
+  if (/libpod/.test(cgroup)) return "podman"
+  if (/docker|containerd/.test(cgroup)) return "docker"
+  if (/\blxc\b/.test(cgroup)) return "lxc"
+  if (/microsoft|wsl/i.test(decode(probe.readFile("/proc/sys/kernel/osrelease", 4096)))) return "wsl"
+  return "none"
+}

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

@@ -0,0 +1,6 @@
+// Read-only discovery (HBS-03): DiscoveryProbe in, contract DiscoverySnapshot out.
+export * from "./probe.ts"
+export * from "./discover.ts"
+export { classifyExecutable, HARNESS_BINARIES } from "./executables.ts"
+export { normalizeAbs } from "./util.ts"
+export { createNodeProbe, MAX_READ_BYTES, type NodeProbeOptions } from "./node-probe.ts"

package/packages/cli/src/bootstrap/discovery/node-probe.ts

@@ -0,0 +1,97 @@
+// The real DiscoveryProbe, over node:fs. Every method is a read: lstat/stat, a bounded read of a file opened
+// read-only, readdir, readlink, realpath and an access(X_OK) check. Errors mean "missing" or "unknown", never a
+// throw. The only process it may start is the macOS machine-identity query (`ioreg`, a fixed read-only argv, no
+// shell), and only when no machine ID was injected; Linux reads /etc/machine-id.
+import childProcess from "node:child_process"
+import fs from "node:fs"
+import os from "node:os"
+import { programLayout, type EntryKind } from "../contracts/index.ts"
+import type { DiscoveryProbe, RuntimeFact } from "./probe.ts"
+
+export interface NodeProbeOptions {
+  /** Defaults to process.env (read, never recorded). */
+  readonly env?: Readonly<Record<string, string | undefined>>
+  readonly home?: string
+  /** Injected machine identity (tests); otherwise read from the OS. */
+  readonly machineID?: string
+  /** The running runtime; null when hubctl runs standalone. Detected by default. */
+  readonly runtime?: RuntimeFact | null
+}
+
+/** Reads without a limit are capped (configs are small; a bigger file is not read at all). */
+export const MAX_READ_BYTES = 16 * 1024 * 1024
+
+const kindOf = (st: fs.Stats): EntryKind => (st.isSymbolicLink() ? "symlink" : st.isDirectory() ? "directory" : st.isFile() ? "file" : "other")
+
+function attempt<T>(f: () => T): T | undefined {
+  try {
+    return f()
+  } catch {
+    return undefined
+  }
+}
+
+function currentRuntime(): RuntimeFact | undefined {
+  const layout = programLayout({ execPath: process.execPath, entry: process.argv[1] ?? "" })
+  if (layout.kind === "standalone") return undefined
+  const bun = process.versions.bun
+  return bun ? { id: "bun", version: bun, path: process.execPath } : { id: "node", version: process.versions.node, path: process.execPath }
+}
+
+function osMachineID(): string | undefined {
+  if (process.platform === "linux")
+    for (const p of ["/etc/machine-id", "/var/lib/dbus/machine-id"]) {
+      const id = attempt(() => fs.readFileSync(p, "utf8").trim())
+      if (id) return id
+    }
+  if (process.platform === "darwin") {
+    const out = attempt(() => childProcess.execFileSync("/usr/sbin/ioreg", ["-rd1", "-c", "IOPlatformExpertDevice"], { encoding: "utf8", timeout: 5000, stdio: ["ignore", "pipe", "ignore"] }))
+    return out ? /"IOPlatformUUID"\s*=\s*"([^"]+)"/.exec(out)?.[1] : undefined
+  }
+  return undefined
+}
+
+export function createNodeProbe(options: NodeProbeOptions = {}): DiscoveryProbe {
+  let machineID: string | undefined | null = options.machineID ?? null
+  const runtime = options.runtime === null ? undefined : (options.runtime ?? currentRuntime())
+  return {
+    platform: process.platform,
+    arch: process.arch,
+    uid: process.getuid?.() ?? 0,
+    home: options.home ?? os.homedir(),
+    hostname: os.hostname(),
+    env: options.env ?? process.env,
+    ...(runtime ? { runtime } : {}),
+    lstat: (p) => attempt(() => kindOf(fs.lstatSync(p))) ?? "missing",
+    stat: (p) => attempt(() => kindOf(fs.statSync(p))) ?? "missing",
+    readFile(p, limit) {
+      const max = Math.min(limit ?? MAX_READ_BYTES, MAX_READ_BYTES)
+      const fd = attempt(() => fs.openSync(p, "r"))
+      if (fd === undefined) return undefined
+      try {
+        const st = fs.fstatSync(fd)
+        if (!st.isFile() || (limit === undefined && st.size > MAX_READ_BYTES)) return undefined
+        const buffer = Buffer.alloc(Math.min(max, st.size))
+        let read = 0
+        while (read < buffer.length) {
+          const n = fs.readSync(fd, buffer, read, buffer.length - read, read)
+          if (n === 0) break
+          read += n
+        }
+        return new Uint8Array(buffer.subarray(0, read))
+      } catch {
+        return undefined
+      } finally {
+        attempt(() => fs.closeSync(fd))
+      }
+    },
+    readdir: (p) => attempt(() => fs.readdirSync(p).sort()),
+    readlink: (p) => attempt(() => fs.readlinkSync(p)),
+    realpath: (p) => attempt(() => fs.realpathSync(p)),
+    executable: (p) => attempt(() => fs.statSync(p).isFile() && (fs.accessSync(p, fs.constants.X_OK), true)) ?? false,
+    machineID() {
+      if (machineID === null) machineID = osMachineID()
+      return machineID
+    },
+  }
+}

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

@@ -0,0 +1,41 @@
+// The read-only probe discovery and preview run through. It is the only way they see the host: a handful of
+// filesystem reads (lstat, stat, readFile, readdir, readlink, realpath, an executable check), facts about this
+// process, and the machine identity. The interface has no method that writes, deletes, connects or spawns an
+// arbitrary command, so discover and preview cannot change the host or reach the network even by mistake. Tests
+// inject an in-memory probe; the CLI injects createNodeProbe().
+import type { EntryKind } from "../contracts/index.ts"
+
+export interface RuntimeFact {
+  readonly id: "bun" | "node"
+  readonly version: string
+  readonly path: string
+}
+
+export interface DiscoveryProbe {
+  /** process.platform and process.arch as found (may be unsupported). */
+  readonly platform: string
+  readonly arch: string
+  readonly uid: number
+  /** The user's home directory (os.homedir()). */
+  readonly home: string
+  readonly hostname: string
+  /** Read, never recorded: discovery looks at PATH, HOME, XDG_* and `container` only. */
+  readonly env: Readonly<Record<string, string | undefined>>
+  /** The runtime running this script, when hubctl runs as a script (absent for a standalone binary). */
+  readonly runtime?: RuntimeFact
+  /** Does not follow a final symlink. */
+  lstat(path: string): EntryKind
+  /** Follows symlinks. */
+  stat(path: string): EntryKind
+  /** Up to `limit` bytes of a file (following symlinks), or undefined when it cannot be read. */
+  readFile(path: string, limit?: number): Uint8Array | undefined
+  /** Entry names of a directory (sorted), or undefined. */
+  readdir(path: string): readonly string[] | undefined
+  readlink(path: string): string | undefined
+  /** The canonical path (every link resolved), or undefined when it does not exist. */
+  realpath(path: string): string | undefined
+  /** A regular file (after links) this user may execute. */
+  executable(path: string): boolean
+  /** /etc/machine-id (Linux) or IOPlatformUUID (macOS); never recorded raw. */
+  machineID(): string | undefined
+}

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

@@ -0,0 +1,13 @@
+// Small path and text helpers shared by discovery and preview.
+import { isAbsolutePath } from "../contracts/index.ts"
+
+/** A normalized absolute path (duplicate and trailing slashes removed), or undefined. */
+export function normalizeAbs(value: string | undefined): string | undefined {
+  if (typeof value !== "string" || !value.startsWith("/")) return undefined
+  const p = value.replace(/\/{2,}/g, "/").replace(/(.)\/+$/, "$1")
+  return isAbsolutePath(p) ? p : undefined
+}
+
+export const join = (dir: string, rel: string) => (dir === "/" ? `/${rel}` : `${dir}/${rel}`)
+export const decode = (bytes: Uint8Array | undefined) => (bytes ? new TextDecoder("utf-8", { fatal: false }).decode(bytes) : "")
+export const oneLine = (v: string | undefined, max = 64) => (v && v.length <= max && !/[\u0000-\u001f\u007f]/.test(v) ? v : undefined)