docks-kit 0.15.2 → 0.15.3

package/cli/src/engine-native/deps.ts

@@ -2,17 +2,17 @@
  * DependencyManager — one home for external-tool identity, presence probing,
  * and platform-correct install hints (Output Policy in DESIGN.md).
  *
- * Ownership split: SoT/toolchain.json + toolchain.ts keep version floors,
- * pin policy, and managed install/upgrade orchestration; this registry owns
- * WHICH external tools exist, whether they are required, and the one-line
- * command that installs a missing one.
+ * Ownership split: SoT/toolchain.json + toolchain.ts keep version floors, pin
+ * policy, and the doctor report, while bun.ts bunBootstrap owns the one managed
+ * install; this registry owns WHICH external tools exist, whether they are
+ * required, and the one-line command that installs a missing one.
  */
 import { homedir } from "node:os"
 import { isAbsolute } from "node:path"
 
 import { capture, commandExists, p, which } from "./exec"
 import { isObject, parseJson } from "./jq"
-import { rawPlatform } from "./os"
+import { hostOs, platformName, rawPlatform } from "./os"
 
 export type ToolId =
   | "git"
@@ -25,7 +25,6 @@ export type ToolId =
   | "codex"
   | "bun"
   | "bwrap"
-  | "effect-solutions"
   | "ffplay"
   | "intelephense"
   | "typescript-language-server"
@@ -42,11 +41,6 @@ export type ProbeResult =
   | { readonly state: "present"; readonly path?: string }
   | { readonly state: "missing" }
 
-export interface DependencyLocation {
-  readonly path: string
-  readonly binDir: string
-}
-
 export interface ProbeExecutor {
   readonly commandExists: (name: string) => boolean
   readonly capture: (cmd: string, args: ReadonlyArray<string>) => Promise<string>
@@ -61,16 +55,12 @@ export interface DependencySpec {
   readonly installHint: (platform?: NodeJS.Platform) => string
   readonly resolve?: (exec: ProbeExecutor, platform: NodeJS.Platform) => ProbeResult
   readonly version?: (exec: ProbeExecutor) => Promise<string>
-  readonly locate?: (exec: ProbeExecutor, platform: NodeJS.Platform) => Promise<DependencyLocation>
-  readonly latest?: (exec: ProbeExecutor) => Promise<string>
 }
 
 interface SpecOptions {
   readonly versionArgs?: ReadonlyArray<string>
   readonly resolve?: (exec: ProbeExecutor, platform: NodeJS.Platform) => ProbeResult
   readonly version?: (exec: ProbeExecutor) => Promise<string>
-  readonly locate?: (exec: ProbeExecutor, platform: NodeJS.Platform) => Promise<DependencyLocation>
-  readonly latest?: (exec: ProbeExecutor) => Promise<string>
 }
 
 const spec = (
@@ -84,16 +74,17 @@ const spec = (
   versionArgs: options.versionArgs ?? ["--version"],
   installHint,
   resolve: options.resolve,
-  version: options.version,
-  locate: options.locate,
-  latest: options.latest
+  version: options.version
 })
 
+// Presence is the injected executor's verdict; `which` only resolves WHERE the
+// tool is, which on Windows is the `.cmd`/`.exe` candidate rather than the name.
 const pathProbe = (id: string): ((exec: ProbeExecutor) => ProbeResult) =>
-  (exec) =>
-    exec.commandExists(id)
-      ? { state: "present", path: exec.which(id) }
-      : { state: "missing" }
+  (exec) => {
+    if (!exec.commandExists(id)) return { state: "missing" }
+    const path = exec.which(id)
+    return path === "" ? { state: "present" } : { state: "present", path }
+  }
 
 const versionProbe = (
   id: string,
@@ -135,31 +126,6 @@ const resolveBun = (exec: ProbeExecutor): ProbeResult => {
     : { state: "present", path: bun.path }
 }
 
-const resolveEffectSolutions = (exec: ProbeExecutor): ProbeResult => {
-  return exec.commandExists("effect-solutions")
-    ? { state: "present", path: exec.which("effect-solutions") }
-    : { state: "missing" }
-}
-
-const versionEffectSolutions = async (exec: ProbeExecutor): Promise<string> => {
-  const bun = findBun(exec)
-  if (bun === undefined) return ""
-  const match = /effect-solutions@([0-9][0-9.]*)/.exec(await exec.capture(bun.command, ["pm", "-g", "ls"]))
-  return match?.[1] ?? ""
-}
-
-const locateEffectSolutions = async (exec: ProbeExecutor): Promise<DependencyLocation> => {
-  const strictBun = findBun(exec)
-  const pathBun = exec.which("bun")
-  // This site may accept a relative hit because it does not persist the Bun path.
-  const bunForGlobalBin = strictBun?.command ?? (pathBun !== "" ? "bun" : undefined)
-  if (bunForGlobalBin === undefined) return { path: "", binDir: "" }
-  const globalBin = await exec.capture(bunForGlobalBin, ["pm", "-g", "bin"])
-  const path = globalBin !== "" ? p(globalBin, "effect-solutions") : ""
-  const resolved = path !== "" && exec.which(path) !== "" ? path : ""
-  return { path: resolved, binDir: globalBin }
-}
-
 const npmGlobalCache = new WeakMap<ProbeExecutor, Promise<{ [k: string]: string }>>()
 
 const npmGlobalVersions = (exec: ProbeExecutor): Promise<{ [k: string]: string }> => {
@@ -183,31 +149,21 @@ const npmGlobalVersions = (exec: ProbeExecutor): Promise<{ [k: string]: string }
 const versionNpmGlobal = (pkg: string) => async (exec: ProbeExecutor): Promise<string> =>
   (await npmGlobalVersions(exec))[pkg] ?? ""
 
-const latestNpm = (id: "effect-solutions") => async (exec: ProbeExecutor): Promise<string> =>
-  exec.commandExists("npm") ? await exec.capture("npm", ["view", id, "version"]) : ""
-
 export const defaultProbeExecutor: ProbeExecutor = { commandExists, capture, which }
 
 export const DEPENDENCIES: Record<ToolId, DependencySpec> = {
   git: spec(
     "git",
     "optional",
-    (pf = rawPlatform()) =>
-      pf === "darwin"
-        ? "brew install git"
-        : "sudo apt install -y git (or your distro's package manager)",
+    (pf = rawPlatform()) => hostOs(platformName(pf)).installHint("git"),
     { version: versionProbe("git") }
   ),
-  jq: spec("jq", "optional", (pf = rawPlatform()) =>
-    pf === "darwin"
-      ? "brew install jq"
-      : "sudo apt install -y jq",
-    { version: versionProbe("jq") }
-  ),
-  curl: spec("curl", "optional", (pf = rawPlatform()) =>
-    pf === "darwin" ? "brew install curl" : "sudo apt install -y curl",
-    { version: versionProbe("curl") }
-  ),
+  jq: spec("jq", "optional", (pf = rawPlatform()) => hostOs(platformName(pf)).installHint("jq"), {
+    version: versionProbe("jq")
+  }),
+  curl: spec("curl", "optional", (pf = rawPlatform()) => hostOs(platformName(pf)).installHint("curl"), {
+    version: versionProbe("curl")
+  }),
   node: spec("node", "optional", () => "install Node.js via https://nodejs.org (or your package manager)", {
     version: versionProbe("node")
   }),
@@ -216,13 +172,13 @@ export const DEPENDENCIES: Record<ToolId, DependencySpec> = {
   claude: spec(
     "claude",
     "optional",
-    () => "curl -fsSL https://claude.ai/install.sh -o /tmp/claude-install.sh && bash /tmp/claude-install.sh",
+    (pf = rawPlatform()) => hostOs(platformName(pf)).installHint("claude"),
     { version: versionProbe("claude") }
   ),
   codex: spec(
     "codex",
     "optional",
-    () => 'tmp=$(mktemp) && curl -fsSL https://chatgpt.com/codex/install.sh -o "$tmp" && CODEX_NON_INTERACTIVE=1 sh "$tmp"',
+    (pf = rawPlatform()) => hostOs(platformName(pf)).installHint("codex"),
     { version: versionProbe("codex") }
   ),
   bun: spec(
@@ -235,24 +191,16 @@ export const DEPENDENCIES: Record<ToolId, DependencySpec> = {
         const bun = findBun(exec)
         if (bun === undefined) return ""
         return await exec.capture(bun.command, ["--version"])
-      },
-      locate: async (exec) => ({ path: findBun(exec)?.path ?? "", binDir: "" })
+      }
     }
   ),
   bwrap: spec("bwrap", "optional", () => "sudo apt install -y bubblewrap (or dnf/pacman/zypper equivalent)", {
     version: versionProbe("bwrap")
   }),
-  "effect-solutions": spec("effect-solutions", "optional", () => "bun add -g effect-solutions", {
-    resolve: resolveEffectSolutions,
-    version: versionEffectSolutions,
-    locate: locateEffectSolutions,
-    latest: latestNpm("effect-solutions")
-  }),
   ffplay: spec(
     "ffplay",
     "optional",
-    (pf = rawPlatform()) =>
-      pf === "darwin" ? "brew install ffmpeg" : "sudo apt install -y ffmpeg",
+    (pf = rawPlatform()) => hostOs(platformName(pf)).installHint("ffplay"),
     { versionArgs: ["-version"], version: versionProbe("ffplay", ["-version"]), resolve: pathProbe("ffplay") }
   ),
   intelephense: spec("intelephense", "optional", () => "npm install -g intelephense", {
@@ -288,20 +236,11 @@ export async function resolveVersion(specification: DependencySpec, exec: ProbeE
   return await (specification.version ?? versionProbe(specification.id, specification.versionArgs))(exec)
 }
 
-export async function resolveLocation(
-  specification: DependencySpec,
-  exec: ProbeExecutor,
-  platform: NodeJS.Platform = rawPlatform()
-): Promise<DependencyLocation> {
-  if (specification.locate !== undefined) return await specification.locate(exec, platform)
-  const result = resolveDependency(specification, exec, platform)
-  return { path: result.state === "present" ? (result.path ?? exec.which(specification.id)) : "", binDir: "" }
-}
-
 export async function resolvePath(
   specification: DependencySpec,
   exec: ProbeExecutor,
-  platform?: NodeJS.Platform
+  platform: NodeJS.Platform = rawPlatform()
 ): Promise<string> {
-  return (await resolveLocation(specification, exec, platform)).path
+  const result = resolveDependency(specification, exec, platform)
+  return result.state === "present" ? (result.path ?? exec.which(specification.id)) : ""
 }

package/cli/src/engine-native/exec.ts

@@ -5,7 +5,8 @@
  */
 import { spawn, type ChildProcess, type SpawnOptions } from "node:child_process"
 import { accessSync, constants, existsSync, readFileSync, statSync, writeFileSync } from "node:fs"
-import { delimiter, isAbsolute, join } from "node:path"
+import { delimiter, extname, isAbsolute, join } from "node:path"
+import { hostOs, type HostOs } from "./os"
 
 /** Keep engine paths slash-separated so rendered output is host-stable. */
 export function p(...parts: Array<string>): string {
@@ -21,6 +22,8 @@ export interface AsyncProcessResult {
 
 export interface AsyncProcessOptions {
   readonly stdio?: SpawnOptions["stdio"]
+  /** Host whose executable resolution and argv shaping apply; tests inject it. */
+  readonly host?: HostOs
 }
 
 export function spawnProcess(
@@ -29,9 +32,25 @@ export function spawnProcess(
   options: AsyncProcessOptions = {}
 ): Promise<AsyncProcessResult> {
   const { promise, resolve } = Promise.withResolvers<AsyncProcessResult>()
+  const host = options.host ?? hostOs()
+  const resolvesSuffixes = host.executableSuffixes.some((suffix) => suffix !== "")
+  const executablePath = resolvesSuffixes ? which(cmd, host.executableSuffixes) : cmd
+  if (executablePath === "") {
+    // Never hand a pathless name to a host that resolves suffixes: CreateProcess
+    // searches the parent's current directory before the system one, so an
+    // untrusted checkout could answer for a missing tool.
+    resolve({ exitCode: null, stdout: "", stderr: "", error: new Error(`command not found on PATH: ${cmd}`) })
+    return promise
+  }
   let child: ChildProcess
   try {
-    child = spawn(cmd, [...args], { stdio: options.stdio ?? ["ignore", "pipe", "ignore"] })
+    // Inside the try: a host whose invocation encoding rejects a value it
+    // cannot represent reports it like any other spawn failure.
+    const invocation = host.invoke(executablePath, args)
+    child = spawn(invocation.command, [...invocation.args], {
+      stdio: options.stdio ?? ["ignore", "pipe", "ignore"],
+      windowsVerbatimArguments: invocation.windowsVerbatimArguments
+    })
   } catch (cause) {
     const error = cause instanceof Error ? cause : new Error(String(cause))
     resolve({ exitCode: null, stdout: "", stderr: "", error })
@@ -75,14 +94,20 @@ export async function capture(cmd: string, args: ReadonlyArray<string>): Promise
 }
 
 /** `command -v` — resolve an executable name on PATH. */
-export function which(name: string): string {
-  if (isAbsolute(name) || name.includes("/")) {
-    return isExecutable(name) ? name : ""
+export function which(name: string, suffixes: ReadonlyArray<string> = hostOs().executableSuffixes): string {
+  const runnableCandidate = (base: string): string => {
+    for (const suffix of suffixes) {
+      const candidate = `${base}${suffix}`
+      if (isExecutable(candidate, suffixes)) return candidate
+    }
+    return ""
   }
+
+  if (isAbsolute(name) || name.includes("/")) return runnableCandidate(name)
   for (const dir of (process.env["PATH"] ?? "").split(delimiter)) {
     if (dir === "") continue
-    const candidate = join(dir, name)
-    if (isExecutable(candidate)) return candidate
+    const candidate = runnableCandidate(join(dir, name))
+    if (candidate !== "") return candidate
   }
   return ""
 }
@@ -91,10 +116,16 @@ export function commandExists(name: string): boolean {
   return which(name) !== ""
 }
 
-export function isExecutable(p: string): boolean {
+export function isExecutable(path: string, suffixes: ReadonlyArray<string> = hostOs().executableSuffixes): boolean {
   try {
-    if (!statSync(p).isFile()) return false
-    accessSync(p, constants.X_OK)
+    if (!statSync(path).isFile()) return false
+    if (suffixes.some((suffix) => suffix !== "")) {
+      const lowerPath = path.toLowerCase()
+      return suffixes.some((suffix) =>
+        suffix === "" ? extname(path) === "" : lowerPath.endsWith(suffix.toLowerCase())
+      )
+    }
+    accessSync(path, constants.X_OK)
     return true
   } catch {
     return false

package/cli/src/engine-native/index.ts

@@ -87,7 +87,6 @@ export interface Ctx {
   skipPluginRefresh?: boolean
   reconcile: boolean
   prune: boolean
-  assumeYes: boolean
   claudeCompactWindow: string
   claudePermissive: boolean
   claudePlugins: Array<string>
@@ -140,7 +139,6 @@ function makeCtx(services: EngineServices): Ctx {
     skipPluginRefresh: false,
     reconcile: env["RECONCILE"] === "1",
     prune: env["PRUNE"] === "1",
-    assumeYes: env["ASSUME_YES"] === "1",
     claudeCompactWindow,
     claudePermissive: env["CLAUDE_PERMISSIVE"] === "1",
     claudePlugins,

package/cli/src/engine-native/modes.ts

@@ -12,8 +12,7 @@ import type { Ctx } from "./index"
 import { isObject, parseJson, type Json } from "./jq"
 import { printModels, validateClaudeModel, validateCodexModel } from "./models"
 import { bunBootstrap } from "./bun"
-import { effectSolutionsInstall } from "./skillsSync"
-import { ensure, report } from "./toolchain"
+import { installedVersion, present, report } from "./toolchain"
 
 export function modeModel(ctx: Ctx, args: ReadonlyArray<string>): number {
   const { echo, err, warn } = ctx.services.logger
@@ -119,15 +118,12 @@ function tomlModelText(text: string): string {
 }
 
 export async function modeToolchain(ctx: Ctx, args: ReadonlyArray<string>): Promise<number> {
-  const { err } = ctx.services.logger
+  const { echo, err, verbose } = ctx.services.logger
   const words = args.filter((arg) => !arg.startsWith("--"))
   const op = words[0] ?? "check"
   const tool = words[1] ?? ""
   for (const arg of args) {
-    if (arg === "--yes") ctx.assumeYes = true
-    else if (arg === "--verbose") {
-      ctx.verbose = true
-    }
+    if (arg === "--verbose") ctx.verbose = true
   }
 
   if (op === "check") {
@@ -135,20 +131,33 @@ export async function modeToolchain(ctx: Ctx, args: ReadonlyArray<string>): Prom
     return 0
   }
   if (op !== "ensure") {
-    err("Usage: toolchain [check|ensure <tool>] [--yes]")
+    err("Usage: toolchain [check|ensure <tool>]")
     return 2
   }
   if (tool === "") {
-    err("Usage: toolchain ensure <tool> [--yes]")
+    err("Usage: toolchain ensure <tool>")
     return 2
   }
   switch (tool) {
-    case "bun":
-      return (await bunBootstrap(ctx, ctx.services)).kind === "ready" ? 0 : 1
-    case "effect-solutions":
-      return await ensure(ctx, "effect-solutions", effectSolutionsInstall(ctx))
+    case "bun": {
+      // `bun` is the one managed tool, and its bootstrap is silent when Bun is
+      // already installed. Probe first so the no-op confirmation the `--verbose`
+      // contract promises is not mistaken for a fresh install.
+      const alreadyInstalled = present(ctx, "bun")
+      if ((await bunBootstrap(ctx, ctx.services)).kind !== "ready") return 1
+      if (alreadyInstalled) {
+        // A present tool whose --version cannot be read reports `unknown` in the
+        // doctor table; keep the same vocabulary rather than an empty pair of
+        // parentheses.
+        const probed = await installedVersion(ctx, "bun")
+        const installed = probed === "" ? "version unknown" : probed
+        if (ctx.dryRun) echo(`[dry-run] bun up to date (${installed})`)
+        else verbose(`bun up to date (${installed})`)
+      }
+      return 0
+    }
     default:
-      err("toolchain ensure supports managed tools only (bun, effect-solutions)")
+      err("toolchain ensure supports managed tools only (bun)")
       return 2
   }
 }

package/cli/src/engine-native/os/darwin.ts

@@ -0,0 +1,62 @@
+import { p } from "../exec"
+import type { HostOs } from "./types"
+
+function posixLiteral(value: string): string {
+  return `'${value.replaceAll("'", `'"'"'`)}'`
+}
+
+export const darwin: HostOs = {
+  id: "darwin",
+  toolchainOs: "darwin",
+  supportsBubblewrap: false,
+  directoryLinkKinds: ["symlink"],
+  executableSuffixes: [""],
+  invoke: (executablePath, args) => ({ command: executablePath, args }),
+  bunExecutableName: "bun",
+  bunInstaller: (pin, directory) => {
+    const scriptPath = p(directory, "install.sh")
+    return {
+      scriptPath,
+      download: {
+        command: "curl",
+        args: ["-fsSL", "https://bun.sh/install", "-o", scriptPath]
+      },
+      run: {
+        command: "bash",
+        args: [scriptPath, `bun-v${pin}`]
+      }
+    }
+  },
+  environmentSetting: (name, value) => ({
+    kind: "profile",
+    candidates: [".zshrc", ".bashrc", ".bash_profile", ".profile", ".zshenv"],
+    target: (shell) => {
+      const shellPath = shell ?? "bash"
+      const shellName = shellPath.slice(shellPath.lastIndexOf("/") + 1)
+      return shellName === "zsh" ? ".zshrc" : shellName === "bash" ? ".bashrc" : ".profile"
+    },
+    line: `export ${name}=${value}`
+  }),
+  statusLineCommand: (bun, script) => {
+    const bunLiteral = posixLiteral(bun)
+    const scriptLiteral = posixLiteral(script)
+    return `test -x ${bunLiteral} && test -f ${scriptLiteral} && exec ${bunLiteral} ${scriptLiteral} || true`
+  },
+  failureHookCommand: (command) => command,
+  installHint: (tool) => {
+    switch (tool) {
+      case "git":
+        return "brew install git"
+      case "jq":
+        return "brew install jq"
+      case "curl":
+        return "brew install curl"
+      case "ffplay":
+        return "brew install ffmpeg"
+      case "claude":
+        return "curl -fsSL https://claude.ai/install.sh -o /tmp/claude-install.sh && bash /tmp/claude-install.sh"
+      case "codex":
+        return 'tmp=$(mktemp) && curl -fsSL https://chatgpt.com/codex/install.sh -o "$tmp" && CODEX_NON_INTERACTIVE=1 sh "$tmp"'
+    }
+  }
+}

package/cli/src/engine-native/os/index.ts

@@ -0,0 +1,42 @@
+import { darwin } from "./darwin"
+import { linux } from "./linux"
+import type { HostOs, PlatformName } from "./types"
+import { windows } from "./windows"
+
+export * from "./types"
+
+export function rawPlatform(): NodeJS.Platform {
+  return process.platform
+}
+
+export function platformName(pf: NodeJS.Platform = rawPlatform()): PlatformName {
+  switch (pf) {
+    case "linux":
+      return "linux"
+    case "darwin":
+      return "darwin"
+    case "win32":
+      return "windows"
+    default:
+      return "unknown"
+  }
+}
+
+// An unrecognized host keeps Linux hint text, filters no toolchain row, and never claims bubblewrap — exactly today's behavior.
+const unknown: HostOs = {
+  ...linux,
+  id: "unknown",
+  toolchainOs: "",
+  supportsBubblewrap: false
+}
+
+const HOSTS: Readonly<Record<PlatformName, HostOs>> = {
+  linux,
+  darwin,
+  windows,
+  unknown
+}
+
+export function hostOs(id: PlatformName = platformName()): HostOs {
+  return HOSTS[id]
+}

package/cli/src/engine-native/os/linux.ts

@@ -0,0 +1,62 @@
+import { p } from "../exec"
+import type { HostOs } from "./types"
+
+function posixLiteral(value: string): string {
+  return `'${value.replaceAll("'", `'"'"'`)}'`
+}
+
+export const linux: HostOs = {
+  id: "linux",
+  toolchainOs: "linux",
+  supportsBubblewrap: true,
+  directoryLinkKinds: ["symlink"],
+  executableSuffixes: [""],
+  invoke: (executablePath, args) => ({ command: executablePath, args }),
+  bunExecutableName: "bun",
+  bunInstaller: (pin, directory) => {
+    const scriptPath = p(directory, "install.sh")
+    return {
+      scriptPath,
+      download: {
+        command: "curl",
+        args: ["-fsSL", "https://bun.sh/install", "-o", scriptPath]
+      },
+      run: {
+        command: "bash",
+        args: [scriptPath, `bun-v${pin}`]
+      }
+    }
+  },
+  environmentSetting: (name, value) => ({
+    kind: "profile",
+    candidates: [".zshrc", ".bashrc", ".bash_profile", ".profile", ".zshenv"],
+    target: (shell) => {
+      const shellPath = shell ?? "bash"
+      const shellName = shellPath.slice(shellPath.lastIndexOf("/") + 1)
+      return shellName === "zsh" ? ".zshrc" : shellName === "bash" ? ".bashrc" : ".profile"
+    },
+    line: `export ${name}=${value}`
+  }),
+  statusLineCommand: (bun, script) => {
+    const bunLiteral = posixLiteral(bun)
+    const scriptLiteral = posixLiteral(script)
+    return `test -x ${bunLiteral} && test -f ${scriptLiteral} && exec ${bunLiteral} ${scriptLiteral} || true`
+  },
+  failureHookCommand: (command) => command,
+  installHint: (tool) => {
+    switch (tool) {
+      case "git":
+        return "sudo apt install -y git (or your distro's package manager)"
+      case "jq":
+        return "sudo apt install -y jq"
+      case "curl":
+        return "sudo apt install -y curl"
+      case "ffplay":
+        return "sudo apt install -y ffmpeg"
+      case "claude":
+        return "curl -fsSL https://claude.ai/install.sh -o /tmp/claude-install.sh && bash /tmp/claude-install.sh"
+      case "codex":
+        return 'tmp=$(mktemp) && curl -fsSL https://chatgpt.com/codex/install.sh -o "$tmp" && CODEX_NON_INTERACTIVE=1 sh "$tmp"'
+    }
+  }
+}

package/cli/src/engine-native/os/targets.ts

@@ -0,0 +1,73 @@
+/**
+ * Host-to-artifact map (Platform seam in DESIGN.md). Every launcher, installer,
+ * build script, and release workflow selects a compiled binary from this one
+ * table; cli/test/unit/hostTargets.test.ts parses those scripts and fails when
+ * any of them drifts from it.
+ *
+ * Membership here is the support matrix: adding a row is how a host becomes
+ * supported, and `requireSupportedHost` in cli/src/engine.ts admits exactly the
+ * platform/arch pairs this table names.
+ */
+import { platformName, type PlatformName } from "./index"
+
+export type TargetId =
+  | "linux-x64"
+  | "linux-arm64"
+  | "darwin-x64"
+  | "darwin-arm64"
+  | "windows-x64"
+  | "windows-arm64"
+
+export type TargetArch = "x64" | "arm64"
+
+export interface HostTarget {
+  readonly id: TargetId
+  readonly platform: PlatformName
+  readonly arch: TargetArch
+  /** `bun build --compile --target=` value. */
+  readonly bunTarget: string
+  /** Compiled binary file name, including the Windows `.exe` suffix. */
+  readonly artifact: string
+  /** `uname -s`-`uname -m` keys the Bash launcher matches; empty on Windows. */
+  readonly unameKeys: ReadonlyArray<string>
+  /**
+   * `$env:PROCESSOR_ARCHITECTURE` values the PowerShell launcher matches; empty
+   * off Windows. Windows PowerShell 5.1 runs emulated on ARM64 and reports
+   * `AMD64` there, so a launcher must read `PROCESSOR_ARCHITEW6432` first.
+   */
+  readonly processorArchitectures: ReadonlyArray<string>
+}
+
+const target = (
+  id: TargetId,
+  platform: PlatformName,
+  arch: TargetArch,
+  unameKeys: ReadonlyArray<string>,
+  processorArchitectures: ReadonlyArray<string>
+): HostTarget => ({
+  id,
+  platform,
+  arch,
+  bunTarget: `bun-${id}`,
+  artifact: platform === "windows" ? `docks-kit-${id}.exe` : `docks-kit-${id}`,
+  unameKeys,
+  processorArchitectures
+})
+
+export const HOST_TARGETS: ReadonlyArray<HostTarget> = [
+  target("linux-x64", "linux", "x64", ["Linux-x86_64"], []),
+  target("linux-arm64", "linux", "arm64", ["Linux-aarch64"], []),
+  target("darwin-x64", "darwin", "x64", ["Darwin-x86_64"], []),
+  target("darwin-arm64", "darwin", "arm64", ["Darwin-arm64"], []),
+  target("windows-x64", "windows", "x64", [], ["AMD64"]),
+  target("windows-arm64", "windows", "arm64", [], ["ARM64"])
+]
+
+export function targetFor(platform: PlatformName, arch: string): HostTarget | undefined {
+  return HOST_TARGETS.find((t) => t.platform === platform && t.arch === arch)
+}
+
+/** Resolve the artifact for a raw Node platform/arch pair. */
+export function targetForHost(platform: NodeJS.Platform, arch: string): HostTarget | undefined {
+  return targetFor(platformName(platform), arch)
+}