@bun-native/cli 0.0.0-stage → 0.33.1

package/src/experiments/aot-gpui/inspect.ts

@@ -0,0 +1,66 @@
+import { readFileSync } from 'node:fs'
+
+// Layout is pinned to Bun da867c60: src/standalone_graph/StandaloneModuleGraph.rs
+// Offsets is repr(C), 32 bytes on all six supported 64-bit targets. A .bun_aot
+// section also exists in JIT executables; the actual module graph flag matters.
+const trailer = Buffer.from('\n---- Bun! ----\n')
+const offsetsSize = 32
+const moduleRecordSize = 52
+const compiledProgramFlag = 1 << 14
+
+/** Inspect an executable by path, or bytes a caller already read. */
+export function inspectBunExecutable(source: string | Buffer): {
+  format: 'elf' | 'macho' | 'pe'
+  payloadOffset: number
+  payloadBytes: number
+  flags: number
+  hasCompiledProgram: boolean
+} {
+  const bytes = typeof source === 'string' ? readFileSync(source) : source
+  const magic = bytes.length >= 4 ? bytes.readUInt32LE(0) : 0
+  const format =
+    magic === 0x464c457f
+      ? 'elf'
+      : magic === 0xfeedfacf
+        ? 'macho'
+        : bytes.subarray(0, 2).toString() === 'MZ'
+          ? 'pe'
+          : undefined
+  if (!format) throw new Error('Unsupported executable format')
+
+  let trailerOffset = bytes.lastIndexOf(trailer)
+  while (trailerOffset >= offsetsSize + 8) {
+    const offsets = trailerOffset - offsetsSize
+    const count64 = bytes.readBigUInt64LE(offsets)
+    if (count64 <= BigInt(offsets - 8)) {
+      const count = Number(count64)
+      const payloadOffset = offsets - count
+      const payloadBytes = count + offsetsSize + trailer.length
+      const modulesOffset = bytes.readUInt32LE(offsets + 8)
+      const modulesLength = bytes.readUInt32LE(offsets + 12)
+      const entryPoint = bytes.readUInt32LE(offsets + 16)
+      const argvOffset = bytes.readUInt32LE(offsets + 20)
+      const argvLength = bytes.readUInt32LE(offsets + 24)
+      const flags = bytes.readUInt32LE(offsets + 28)
+      if (
+        bytes.readBigUInt64LE(payloadOffset - 8) === BigInt(payloadBytes) &&
+        modulesLength > 0 &&
+        modulesLength % moduleRecordSize === 0 &&
+        modulesOffset + modulesLength <= count &&
+        entryPoint < modulesLength / moduleRecordSize &&
+        argvOffset + argvLength <= count &&
+        (flags & ~0x7fff) === 0
+      ) {
+        return {
+          format,
+          payloadOffset,
+          payloadBytes,
+          flags,
+          hasCompiledProgram: (flags & compiledProgramFlag) !== 0,
+        }
+      }
+    }
+    trailerOffset = bytes.lastIndexOf(trailer, trailerOffset - 1)
+  }
+  throw new Error('No valid pinned Bun standalone module graph found')
+}

package/src/scripts/native/artifact.ts

@@ -0,0 +1,73 @@
+import { mkdir, open, readFile, rename, rm, stat, writeFile } from 'node:fs/promises'
+import { dirname } from 'node:path'
+
+export type FileDigest = { bytes: number; sha256: string }
+
+// Source files and manifests are read whole; compilers and host binaries are
+// hashed through one reused buffer so memory stays bounded.
+const WHOLE_FILE_BYTES = 4 * 1024 * 1024
+const CHUNK_BYTES = 1024 * 1024
+
+/** SHA-256 hex through Bun's native hasher; avoids loading node:crypto on CLI paths. */
+export function sha256(data: string | Uint8Array): string {
+  return new Bun.CryptoHasher('sha256').update(data).digest('hex')
+}
+
+export async function fileDigest(path: string): Promise<FileDigest> {
+  const hash = new Bun.CryptoHasher('sha256')
+  // The size only picks a strategy; both read to EOF and count what they read.
+  if ((await stat(path)).size <= WHOLE_FILE_BYTES) {
+    const data = await readFile(path)
+    return { bytes: data.length, sha256: hash.update(data).digest('hex') }
+  }
+  let bytes = 0
+  const file = await open(path, 'r')
+  try {
+    const buffer = Buffer.allocUnsafe(CHUNK_BYTES)
+    for (;;) {
+      const { bytesRead } = await file.read(buffer, 0, CHUNK_BYTES, null)
+      if (bytesRead === 0) break
+      hash.update(buffer.subarray(0, bytesRead))
+      bytes += bytesRead
+    }
+  } finally {
+    await file.close()
+  }
+  return { bytes, sha256: hash.digest('hex') }
+}
+
+/**
+ * The digest of a large, rarely changing file (the compiler), reused from `cache`
+ * while the file keeps its device, inode, size, mtime and ctime. Any write or
+ * replacement changes one of those, and the file is hashed again.
+ */
+export async function cachedFileDigest(path: string, cache: string): Promise<FileDigest> {
+  const identity = async () => {
+    const stats = await stat(path, { bigint: true })
+    return [stats.dev, stats.ino, stats.size, stats.mtimeNs, stats.ctimeNs].join(':')
+  }
+  const before = await identity()
+  try {
+    const cached = await Bun.file(cache).json()
+    if (
+      cached?.path === path &&
+      cached.identity === before &&
+      Number.isSafeInteger(cached.digest?.bytes) &&
+      /^[0-9a-f]{64}$/.test(cached.digest?.sha256)
+    )
+      return { bytes: cached.digest.bytes, sha256: cached.digest.sha256 }
+  } catch {}
+  const digest = await fileDigest(path)
+  if ((await identity()) === before) {
+    const partial = `${cache}.${process.pid}.partial`
+    try {
+      await mkdir(dirname(cache), { recursive: true })
+      await writeFile(partial, JSON.stringify({ path, identity: before, digest }) + '\n')
+      await rename(partial, cache)
+    } catch {
+      // The cache is optional; a read-only project hashes every time.
+      await rm(partial, { force: true }).catch(() => {})
+    }
+  }
+  return digest
+}

package/src/scripts/native/build.ts

@@ -0,0 +1,231 @@
+import { constants } from 'node:fs'
+import { chmod, copyFile, mkdir, readFile, readdir, writeFile } from 'node:fs/promises'
+import { dirname, isAbsolute, join, relative, resolve } from 'node:path'
+import { compileApplication } from '../../experiments/aot-gpui/compile.ts'
+import type { Project } from './project.ts'
+import { bundleApplication } from './bundle.ts'
+import { cachedFileDigest, fileDigest, sha256 } from './artifact.ts'
+import { userCache } from './context.ts'
+import toolchain from '../../toolchain.json'
+
+/** Bundle a project's entry into `outdir/application.js` with the shared configuration. */
+export async function bundleProject(project: Project, outdir: string): Promise<string> {
+  const { module } = await bundleApplication({
+    framework: project.framework,
+    entry: project.entry,
+    outdir,
+    cwd: project.directory,
+  })
+  return module
+}
+
+/** The application bundle that holds the host in a macOS build. */
+export const MACOS_HOST_BUNDLE = 'BunNativeHost.app'
+const BUNDLE_IDENTIFIER = /^[A-Za-z0-9-]+(\.[A-Za-z0-9-]+)+$/
+
+const xml = (text: string) =>
+  text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;')
+
+/** The Info.plist that makes the macOS host an application bundle with an identifier. */
+export function hostInfoPlist(identifier: string, name: string, executable: string): string {
+  if (!BUNDLE_IDENTIFIER.test(identifier))
+    throw new Error(`Bundle identifier ${JSON.stringify(identifier)} is not reverse-DNS text`)
+  const entry = (key: string, value: string) =>
+    `  <key>${key}</key>\n  <string>${xml(value)}</string>`
+  return [
+    '<?xml version="1.0" encoding="UTF-8"?>',
+    '<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">',
+    '<plist version="1.0">',
+    '<dict>',
+    entry('CFBundleIdentifier', identifier),
+    entry('CFBundleExecutable', executable),
+    entry('CFBundleName', name),
+    entry('CFBundleDisplayName', name),
+    entry('CFBundlePackageType', 'APPL'),
+    entry('CFBundleInfoDictionaryVersion', '6.0'),
+    entry('CFBundleShortVersionString', '1.0'),
+    entry('CFBundleVersion', '1'),
+    '  <key>NSHighResolutionCapable</key>\n  <true/>',
+    '</dict>',
+    '</plist>',
+    '',
+  ].join('\n')
+}
+
+/**
+ * Where the host goes in a build. macOS user notifications serve only a process
+ * that runs from an application bundle with an identifier
+ * (docs/decisions/0009-native-notifications.md), so a macOS build puts the host in
+ * `BunNativeHost.app/Contents/MacOS` next to its Info.plist; every other platform
+ * keeps it adjacent to the application.
+ */
+export function hostLayout(
+  platform: NodeJS.Platform,
+  hostFile: string
+): { file: string; infoPlist?: string } {
+  if (platform !== 'darwin') return { file: hostFile }
+  return {
+    file: `${MACOS_HOST_BUNDLE}/Contents/MacOS/${hostFile}`,
+    infoPlist: `${MACOS_HOST_BUNDLE}/Contents/Info.plist`,
+  }
+}
+
+/** The default bundle identity: the project's package name under `dev.bun-native.app`. */
+export async function defaultBundleIdentity(
+  project: Project
+): Promise<{ identifier: string; name: string }> {
+  let name = 'application'
+  try {
+    const value = JSON.parse(await readFile(join(project.directory, 'package.json'), 'utf8')) as {
+      name?: unknown
+    }
+    if (typeof value.name === 'string' && value.name) name = value.name
+  } catch {}
+  const slug =
+    name
+      .replace(/^@/, '')
+      .replace(/[^A-Za-z0-9-]+/g, '-')
+      .replace(/^-+|-+$/g, '') || 'application'
+  return { identifier: `dev.bun-native.app.${slug}`, name }
+}
+
+export async function buildProject(
+  project: Project,
+  host: string,
+  destination: string,
+  hostProfile: 'dev' | 'release',
+  options: { bundleIdentifier?: string } = {}
+) {
+  if (Bun.revision !== toolchain.bun.revision) throw new Error('Use the pinned Bun AOT compiler')
+  const outdir = resolve(destination)
+  await mkdir(outdir, { recursive: true })
+  if ((await readdir(outdir)).length !== 0) throw new Error('Output directory must be empty')
+  const suffix = process.platform === 'win32' ? '.exe' : ''
+  const layout = hostLayout(process.platform, `bun-native-host${suffix}`)
+  const hostFile = layout.file
+  const identity = await defaultBundleIdentity(project)
+  if (options.bundleIdentifier !== undefined) identity.identifier = options.bundleIdentifier
+  // Validate before any output exists.
+  const infoPlist = layout.infoPlist
+    ? hostInfoPlist(identity.identifier, identity.name, `bun-native-host${suffix}`)
+    : undefined
+  const applicationFile = `application${suffix}`
+  const originalHost = await fileDigest(host)
+  const module = await bundleProject(project, join(outdir, 'development'))
+  const developmentModule = await fileDigest(module)
+  // Resolve the bundled host relative to the executable, independent of launch cwd.
+  const launcher = join(outdir, 'launcher.ts')
+  await writeFile(
+    launcher,
+    `import { dirname, join } from 'node:path'\nprocess.env['BUN_NATIVE_HOST'] ??= join(dirname(process.execPath), ${JSON.stringify(hostFile)})\nawait import('./development/application.js')\n`,
+    { flag: 'wx' }
+  )
+  // The compiler names the program by its path relative to its working directory,
+  // so compiling the relative launcher from the output directory keeps the
+  // executable independent of where that directory is.
+  const compiled = compileApplication('launcher.ts', join(outdir, applicationFile), outdir)
+  if (layout.infoPlist && infoPlist) {
+    await mkdir(dirname(join(outdir, hostFile)), { recursive: true })
+    await writeFile(join(outdir, layout.infoPlist), infoPlist, { flag: 'wx' })
+  }
+  await copyFile(host, join(outdir, hostFile), constants.COPYFILE_EXCL)
+  if (process.platform !== 'win32') await chmod(join(outdir, hostFile), 0o755)
+  const packagedHost = await fileDigest(join(outdir, hostFile))
+  if (
+    originalHost.sha256 !== packagedHost.sha256 ||
+    originalHost.sha256 !== (await fileDigest(host)).sha256
+  )
+    throw new Error('Prebuilt host changed while packaging; retry with a stable input')
+  if (developmentModule.sha256 !== (await fileDigest(module)).sha256)
+    throw new Error('Application module changed during AOT compilation')
+  // Keep machine-local paths and wall-clock timing out of the manifest so equal
+  // inputs produce an identical manifest; timing goes to a separate diagnostic.
+  const { compileCommand, buildMs, executable, ...inspected } = compiled
+  await writeFile(
+    join(outdir, 'build-metrics.json'),
+    JSON.stringify({ schemaVersion: 1, compileMs: buildMs }, null, 2) + '\n',
+    { flag: 'wx' }
+  )
+  const manifest = {
+    schemaVersion: 1,
+    ...(project.packageSet ? { packageSet: project.packageSet } : {}),
+    framework: project.framework,
+    entrypoint: relative(project.directory, project.entry),
+    target: { os: process.platform, architecture: process.arch },
+    toolchain,
+    application: {
+      file: applicationFile,
+      ...executable,
+      // Absolute arguments are recorded relative to this artifact directory; the
+      // compiler is identified by its digest instead of its install path.
+      compileCommand: compileCommand.map((argument, index) =>
+        index === 0 ? 'bun' : isAbsolute(argument) ? relative(outdir, argument) : argument
+      ),
+      compiler: {
+        revision: Bun.revision,
+        executable: await cachedFileDigest(
+          process.execPath,
+          join(userCache(), 'compiler', `${sha256(process.execPath).slice(0, 32)}.json`)
+        ),
+      },
+      ...inspected,
+    },
+    developmentModule: { file: 'development/application.js', ...developmentModule },
+    sourceMap: {
+      file: 'development/application.js.map',
+      ...(await fileDigest(join(outdir, 'development/application.js.map'))),
+    },
+    launcher: { file: 'launcher.ts', ...(await fileDigest(launcher)) },
+    reproducibility: {
+      deterministic: [
+        applicationFile,
+        hostFile,
+        ...(layout.infoPlist ? [layout.infoPlist] : []),
+        'development/application.js',
+        'development/application.js.map',
+        'launcher.ts',
+        'manifest.json',
+      ],
+      diagnostics: ['build-metrics.json', 'compile-aot.stdout.log', 'compile-aot.stderr.log'],
+    },
+    host: {
+      file: hostFile,
+      profile: hostProfile,
+      ...packagedHost,
+      ...(layout.infoPlist
+        ? {
+            bundle: {
+              directory: MACOS_HOST_BUNDLE,
+              identifier: identity.identifier,
+              infoPlist: {
+                file: layout.infoPlist,
+                ...(await fileDigest(join(outdir, layout.infoPlist))),
+              },
+            },
+          }
+        : {}),
+      provenance:
+        'Caller-supplied prebuilt executable. Profile is caller-declared; match the hash to native build evidence.',
+    },
+    launch: {
+      executable: applicationFile,
+      host:
+        process.platform === 'darwin'
+          ? 'Bundled host inside BunNativeHost.app, so macOS serves it user notifications; BUN_NATIVE_HOST can explicitly override it'
+          : 'Adjacent bundled host; BUN_NATIVE_HOST can explicitly override it',
+    },
+    verification: {
+      aotCompiledProgram: 'passed',
+      jitOmission: 'passed',
+      nativeRendering: 'not-run',
+      osInput: 'not-run',
+      teardown: 'not-run',
+      signing: 'unsigned',
+      installation: 'not-tested',
+    },
+  }
+  await writeFile(join(outdir, 'manifest.json'), JSON.stringify(manifest, null, 2) + '\n', {
+    flag: 'wx',
+  })
+  return manifest
+}

package/src/scripts/native/bundle.ts

@@ -0,0 +1,121 @@
+import type { BuildConfig, BunPlugin } from 'bun'
+import { mkdir, realpath, stat } from 'node:fs/promises'
+import { join, resolve, sep } from 'node:path'
+
+export type Framework = 'solid' | 'react'
+
+/**
+ * The one bundler configuration for a Bun Native application module. `native dev`,
+ * `native build`, the CI fixtures and the benchmarks all bundle through it, so CI
+ * qualifies the bytes users build. The module is not minified: `native dev` runs it
+ * as is (readable stacks), and the AOT compiler's `--production` minifies the
+ * compiled program anyway.
+ */
+export function bundleConfig(
+  framework: Framework,
+  entry: string,
+  outdir: string,
+  plugins: BunPlugin[] = []
+): BuildConfig & { outdir: string } {
+  return {
+    entrypoints: [entry],
+    outdir,
+    naming: 'application.js',
+    target: 'bun',
+    format: 'esm',
+    define: { 'process.env.NODE_ENV': '"production"' },
+    sourcemap: 'external',
+    metafile: true,
+    plugins,
+    // Solid's universal renderer is selected through the `browser` export condition;
+    // React uses its automatic JSX runtime from the adapter.
+    ...(framework === 'solid'
+      ? { conditions: ['browser'] }
+      : { jsx: { runtime: 'automatic', importSource: '@bun-native/react' } }),
+  }
+}
+
+/** Solid's universal JSX transform as a bundler plugin; Babel loads only for Solid builds. */
+async function solidPlugin(): Promise<BunPlugin> {
+  const { transformSolid } = await import('../solid/transform.ts')
+  return {
+    name: 'solid-native-universal',
+    setup(build) {
+      build.onLoad({ filter: /\.[jt]sx$/ }, async ({ path }) => ({
+        contents: transformSolid(await Bun.file(path).text(), path),
+        loader: 'ts',
+      }))
+    },
+  }
+}
+
+export type Bundle = {
+  /** The absolute path of `application.js`; its source map is next to it. */
+  module: string
+  /** Every module the bundle read, relative to `cwd`, `/`-separated and sorted (from the metafile). */
+  inputs: string[]
+}
+
+/**
+ * Bundle one application entry into `outdir/application.js`.
+ *
+ * Bun.build names each module in its `// path` comments relative to the process
+ * working directory, so the bundle runs with the working directory set to `cwd` (the
+ * project, or the checkout for fixtures) and equal sources give equal bytes from any
+ * caller directory.
+ */
+export async function bundleApplication(options: {
+  framework: Framework
+  entry: string
+  outdir: string
+  cwd: string
+  plugins?: BunPlugin[]
+}): Promise<Bundle> {
+  const entry = await realpath(options.entry)
+  if (!(await stat(entry)).isFile() || !/\.[jt]sx?$/.test(entry))
+    throw new Error(
+      `${options.framework === 'solid' ? 'Solid' : 'React'} entry must be a TypeScript/JavaScript source file`
+    )
+  const outdir = resolve(options.outdir)
+  await mkdir(outdir, { recursive: true })
+  const plugins =
+    options.plugins ?? (options.framework === 'solid' ? [await solidPlugin()] : undefined)
+  const previous = process.cwd()
+  process.chdir(options.cwd)
+  let result: Awaited<ReturnType<typeof Bun.build>>
+  try {
+    result = await Bun.build(bundleConfig(options.framework, entry, outdir, plugins))
+  } finally {
+    process.chdir(previous)
+  }
+  if (!result.success)
+    throw new AggregateError(
+      result.logs,
+      `${options.framework === 'solid' ? 'Solid' : 'React'} native build failed`
+    )
+  return {
+    module: join(outdir, 'application.js'),
+    inputs: Object.keys(result.metafile?.inputs ?? {})
+      .map((path) => path.split(sep).join('/'))
+      .sort(),
+  }
+}
+
+/**
+ * The modules an entry that is compiled directly (without a framework bundle) reads,
+ * from the same resolution `bun compile` uses; nothing is written.
+ */
+export async function moduleInputs(entry: string, cwd: string): Promise<string[]> {
+  const previous = process.cwd()
+  process.chdir(cwd)
+  let result: Awaited<ReturnType<typeof Bun.build>>
+  try {
+    result = await Bun.build({ entrypoints: [entry], target: 'bun', format: 'esm', metafile: true })
+  } finally {
+    process.chdir(previous)
+  }
+  if (!result.success) throw new AggregateError(result.logs, `Cannot resolve ${entry}`)
+  return Object.keys(result.metafile?.inputs ?? {})
+    .map((path) => path.split(sep).join('/'))
+    .sort()
+}

package/src/scripts/native/consumer-files.ts

@@ -0,0 +1,46 @@
+import compilerConfig from '../../tsconfig.json'
+
+/**
+ * Files shared by every project that installs Bun Native from packages (a local
+ * package set or the npm registry) instead of using a checkout's workspace.
+ */
+
+/** The installed CLI, run without auto-install so a missing package fails instead of downloading. */
+export const installedCli = 'bun --no-install ./node_modules/@bun-native/cli/src/scripts/native.ts'
+
+export const json = (value: unknown) => JSON.stringify(value, null, 2) + '\n'
+
+/** The template formatter keeps short string arrays on one line, so format checks pass as generated. */
+const formattedJSON = (value: unknown) =>
+  json(value).replace(
+    /\[\n\s*("[^"\n]*"(?:,\n\s*"[^"\n]*")*)\n\s*\]/g,
+    (_, items: string) => `[${items.split(/,\n\s*/).join(', ')}]`
+  )
+
+export function consumerScripts(): Record<string, string> {
+  return {
+    // The persistent watch controller returns freed bundler pages promptly;
+    // see docs/developer-tooling.md "Controller memory".
+    dev: `MIMALLOC_PURGE_DELAY=0 ${installedCli} dev .`,
+    build: `${installedCli} build .`,
+    check: 'bun --no-install check --no-script --no-pretty',
+    format: `${installedCli} format .`,
+    'format:check': `${installedCli} format . --check`,
+    lint: `${installedCli} lint .`,
+  }
+}
+
+export function consumerTsconfig(
+  framework: 'solid' | 'react',
+  entry: string,
+  exclude: string[]
+): string {
+  return formattedJSON({
+    compilerOptions: {
+      ...compilerConfig.compilerOptions,
+      jsxImportSource: `@bun-native/${framework}`,
+    },
+    include: [entry],
+    exclude,
+  })
+}

package/src/scripts/native/context.ts

@@ -0,0 +1,95 @@
+import { homedir } from 'node:os'
+import { basename, dirname, join } from 'node:path'
+
+/**
+ * Where this CLI runs from, computed once per invocation.
+ *
+ * - `checkout`: `scripts/native.ts` in a Bun Native checkout. The version is the
+ *   workspace's root `package.json`; released hosts are cached in the checkout's
+ *   `.bun-native/hosts`.
+ * - `package`: the installed `@bun-native/cli`, whose sources live under `src/`.
+ *   The version is the package's own manifest. Released hosts are cached in the
+ *   per-user cache, never inside the digest-verified CLI package and never in the
+ *   consumer project, whose `.bun-native/` holds only `dev` modules.
+ */
+export type CliContext = {
+  mode: 'checkout' | 'package'
+  /** The directory that holds `scripts/native.ts`: the checkout root, or the package's `src`. */
+  root: string
+  /** Absent only for a bare copy of the CLI sources; host downloads then need --version. */
+  version: string | undefined
+  hostCache: string
+  /** How the usage text spells this CLI. */
+  command: string
+}
+
+type Environment = Record<string, string | undefined>
+
+const packageCommand = 'bun --no-install ./node_modules/@bun-native/cli/src/scripts/native.ts'
+
+async function manifest(path: string): Promise<{ name?: unknown; version?: unknown } | undefined> {
+  const file = Bun.file(path)
+  return (await file.exists()) ? file.json() : undefined
+}
+
+/**
+ * The per-user cache for state the CLI keeps between runs (released hosts,
+ * verification stamps, the compiler digest). Projects stay free of it.
+ */
+export function userCache(
+  environment: Environment = process.env,
+  platform: NodeJS.Platform = process.platform,
+  home: string = homedir()
+): string {
+  const base =
+    environment['XDG_CACHE_HOME'] ||
+    (platform === 'darwin'
+      ? join(home, 'Library', 'Caches')
+      : platform === 'win32'
+        ? environment['LOCALAPPDATA'] || join(home, 'AppData', 'Local')
+        : join(home, '.cache'))
+  return join(base, 'bun-native')
+}
+
+/** Released hosts of an installed CLI. */
+export function userHostCache(
+  environment: Environment = process.env,
+  platform: NodeJS.Platform = process.platform,
+  home: string = homedir()
+): string {
+  return join(userCache(environment, platform, home), 'hosts')
+}
+
+export async function cliContext(
+  root: string,
+  environment: Environment = process.env
+): Promise<CliContext> {
+  const packageRoot = dirname(root)
+  const installed =
+    basename(root) === 'src' ? await manifest(join(packageRoot, 'package.json')) : undefined
+  if (installed?.name === '@bun-native/cli') {
+    return {
+      mode: 'package',
+      root,
+      version: typeof installed.version === 'string' ? installed.version : undefined,
+      hostCache: userHostCache(environment),
+      command: packageCommand,
+    }
+  }
+  const workspace = await manifest(join(root, 'package.json'))
+  return {
+    mode: 'checkout',
+    root,
+    version: typeof workspace?.version === 'string' ? workspace.version : undefined,
+    hostCache: join(root, '.bun-native', 'hosts'),
+    command: 'bun run native',
+  }
+}
+
+/** The release version for host downloads: an explicit one, else this CLI's own. */
+export function releaseVersion(context: CliContext, explicit?: string): string {
+  const version = explicit ?? context.version
+  if (version === undefined)
+    throw new Error('This CLI has no package version; pass host install --version x.y.z')
+  return version
+}