@bun-native/cli 0.33.0 → 0.33.1

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
+}

package/src/scripts/native/doctor.ts

@@ -1,6 +1,6 @@
 import toolchain from '../../toolchain.json'
+import { cliContext } from './context.ts'
 import { prebuiltHost } from './host.ts'
-import { readProject } from './project.ts'
 
 type Diagnosis = { name: string; status: 'ok' | 'failed' | 'skipped'; detail: string }
 
@@ -55,11 +55,12 @@ export async function diagnose(
     results.push({ name: 'project', status: 'skipped', detail: 'pass a project directory' })
   else
     try {
+      const { readProject } = await import('./project.ts')
       const project = await readProject(repository, options.project)
       results.push({
         name: 'project',
         status: 'ok',
-        detail: `${project.framework} project ${project.directory}${project.packageSet ? ' with verified installed package set' : ' in this checkout'}`,
+        detail: `${project.framework} project ${project.directory}${project.packageSet ? ' with verified installed package set' : (await cliContext(repository)).mode === 'package' ? ' with registry packages' : ' in this checkout'}`,
       })
     } catch (error) {
       results.push({ name: 'project', status: 'failed', detail: message(error) })

package/src/scripts/native/host-download.ts

@@ -1,8 +1,9 @@
-import { createHash } from 'node:crypto'
 import { chmod, mkdir, rename, rm, stat, writeFile } from 'node:fs/promises'
 import { dirname, join } from 'node:path'
 import { gunzipSync } from 'node:zlib'
+import { sha256 } from './artifact.ts'
 import { prebuiltHost } from './host.ts'
+import { ustarChecksumValid, ustarNumber } from './ustar.ts'
 
 /** The platforms whose release host archives the release workflow attaches (ADR 0021). */
 export const releaseHostTargets = [
@@ -16,6 +17,7 @@ export type ReleaseHostTarget = (typeof releaseHostTargets)[number]
 const releases = 'https://github.com/0xPlayerOne/bun-native/releases/download'
 const maximumArchiveBytes = 512 * 1024 * 1024
 const maximumChecksumBytes = 64 * 1024
+const defaultTimeoutMs = 5 * 60_000
 
 export function releaseHostTarget(
   platform: string = process.platform,
@@ -44,12 +46,6 @@ export function checksumFor(sums: string, asset: string): string {
   return matches[0]![1]!
 }
 
-function octal(header: Buffer, offset: number, length: number): number {
-  const text = header.toString('latin1', offset, offset + length).replace(/[\0 ]+$/, '')
-  if (!/^[0-7]+$/.test(text)) throw new Error('Host archive has an invalid USTAR number')
-  return Number.parseInt(text, 8)
-}
-
 /**
  * The single `bun-native-host` member of a host archive made by host-archive.ts:
  * a gzip-compressed USTAR stream with exactly one regular file, mode 0755.
@@ -64,11 +60,9 @@ export function hostFromArchive(archive: Uint8Array): Buffer {
   if (header[156] !== 0x30 && header[156] !== 0)
     throw new Error('Host member is not a regular file')
   if (header.toString('latin1', 257, 262) !== 'ustar') throw new Error('Host archive is not USTAR')
-  let checksum = 0
-  for (let index = 0; index < 512; index++)
-    checksum += index >= 148 && index < 156 ? 0x20 : header[index]!
-  if (checksum !== octal(header, 148, 8)) throw new Error('Host archive header checksum mismatch')
-  const size = octal(header, 124, 12)
+  if (!ustarChecksumValid(header)) throw new Error('Host archive header checksum mismatch')
+  const size = ustarNumber(header.subarray(124, 136))
+  if (size === undefined) throw new Error('Host archive has an invalid USTAR number')
   const end = 512 + Math.ceil(size / 512) * 512
   if (size === 0 || end + 1024 > tar.length) throw new Error('Host archive is truncated')
   if (tar.subarray(end).some((byte) => byte !== 0))
@@ -76,14 +70,55 @@ export function hostFromArchive(archive: Uint8Array): Buffer {
   return Buffer.from(tar.subarray(512, 512 + size))
 }
 
-async function download(url: string, limit: number): Promise<Uint8Array> {
-  const response = await fetch(url, { redirect: 'follow' })
-  if (!response.ok) throw new Error(`Download failed (${response.status}): ${url}`)
-  const declared = Number(response.headers.get('content-length') ?? '0')
-  if (declared > limit) throw new Error(`Download is larger than ${limit} bytes: ${url}`)
-  const bytes = new Uint8Array(await response.arrayBuffer())
-  if (bytes.length > limit) throw new Error(`Download is larger than ${limit} bytes: ${url}`)
-  return bytes
+/**
+ * One bounded download: the same deadline covers the request and the whole body,
+ * which is streamed into a byte-limited buffer (the install-bun/download.mjs pattern).
+ * A stalled release server fails the command instead of hanging it.
+ */
+async function download(url: string, limit: number, timeoutMs: number): Promise<Uint8Array> {
+  const controller = new AbortController()
+  const expired = () => new Error(`Download exceeded ${timeoutMs} ms: ${url}`)
+  let timer: ReturnType<typeof setTimeout> | undefined
+  const deadline = new Promise<never>((_, reject) => {
+    timer = setTimeout(() => {
+      controller.abort()
+      reject(expired())
+    }, timeoutMs)
+  })
+  const operation = (async () => {
+    let response: Response
+    try {
+      response = await fetch(url, { redirect: 'follow', signal: controller.signal })
+    } catch (error) {
+      if (controller.signal.aborted) throw expired()
+      throw error
+    }
+    try {
+      if (!response.ok) throw new Error(`Download failed (${response.status}): ${url}`)
+      const declared = Number(response.headers.get('content-length') ?? '0')
+      if (declared > limit) throw new Error(`Download is larger than ${limit} bytes: ${url}`)
+      const parts: Uint8Array[] = []
+      let total = 0
+      for await (const part of response.body ?? []) {
+        total += part.byteLength
+        if (total > limit) throw new Error(`Download is larger than ${limit} bytes: ${url}`)
+        parts.push(part)
+      }
+      return Buffer.concat(parts, total)
+    } catch (error) {
+      if (controller.signal.aborted) throw expired()
+      throw error
+    } finally {
+      // Release the connection on every early exit; a completed body is a no-op.
+      controller.abort()
+    }
+  })()
+  try {
+    return await Promise.race([operation, deadline])
+  } finally {
+    clearTimeout(timer)
+    operation.catch(() => {})
+  }
 }
 
 export type HostInstallOptions = {
@@ -94,9 +129,11 @@ export type HostInstallOptions = {
   cache: string
   force?: boolean
   target?: ReleaseHostTarget
+  /** Deadline for each download, request and body together. Defaults to 5 minutes. */
+  timeoutMs?: number
 }
 
-export function installedHostPath(options: HostInstallOptions): string {
+function installedHostPath(options: HostInstallOptions): string {
   const target = options.target ?? releaseHostTarget()
   return join(options.cache, `v${options.version}`, target, 'bun-native-host')
 }
@@ -117,10 +154,13 @@ export async function installReleaseHost(options: HostInstallOptions): Promise<s
     return prebuiltHost(destination)
   const base = `${(options.baseUrl ?? process.env['BUN_NATIVE_HOST_RELEASE_URL'] ?? releases).replace(/\/+$/, '')}/v${options.version}`
   const asset = releaseHostAsset(target)
-  const sums = new TextDecoder().decode(await download(`${base}/SHA256SUMS`, maximumChecksumBytes))
+  const timeoutMs = options.timeoutMs ?? defaultTimeoutMs
+  const sums = new TextDecoder().decode(
+    await download(`${base}/SHA256SUMS`, maximumChecksumBytes, timeoutMs)
+  )
   const expected = checksumFor(sums, asset)
-  const archive = await download(`${base}/${asset}`, maximumArchiveBytes)
-  const actual = createHash('sha256').update(archive).digest('hex')
+  const archive = await download(`${base}/${asset}`, maximumArchiveBytes, timeoutMs)
+  const actual = sha256(archive)
   if (actual !== expected)
     throw new Error(`${asset} digest ${actual} does not match SHA256SUMS ${expected}`)
   const host = hostFromArchive(archive)

package/src/scripts/native/inputs.ts

@@ -1,5 +1,3 @@
-import { createHash } from 'node:crypto'
-import { createReadStream } from 'node:fs'
 import { readdir, realpath, stat } from 'node:fs/promises'
 import { join, relative } from 'node:path'
 
@@ -22,9 +20,40 @@ function disappeared(error: unknown): boolean {
   )
 }
 
+type Input = { name: string; path: string; link: boolean }
+
+/** The digest entry for one input, or undefined when it vanished or is not a file. */
+async function inputDigest(
+  directory: string,
+  input: Input,
+  signal?: AbortSignal
+): Promise<string | undefined> {
+  try {
+    // File links are hashed through their targets. Do not follow directory
+    // links: recursive aliases can escape the project or introduce cycles.
+    if (input.link && !(await stat(input.path)).isFile()) return undefined
+    const target = input.link ? relative(directory, await realpath(input.path)) : null
+    const contents = await Bun.file(input.path).bytes()
+    signal?.throwIfAborted()
+    return JSON.stringify([
+      input.name,
+      target,
+      new Bun.CryptoHasher('sha256').update(contents).digest('hex'),
+    ])
+  } catch (error) {
+    // Deletion/atomic replacement during a scan is an absent input; a
+    // queued create/change event requests another scan. Other IO fails.
+    if (!disappeared(error)) throw error
+    return undefined
+  }
+}
+
+// Enough concurrent reads to overlap file system latency without exhausting descriptors.
+const READERS = 16
+
 /** One content digest, with no retained file contents or earlier generations. */
 export async function projectFingerprint(directory: string, signal?: AbortSignal): Promise<string> {
-  const fingerprint = createHash('sha256')
+  const inputs: Input[] = []
   const visit = async (folder: string, prefix: string): Promise<void> => {
     signal?.throwIfAborted()
     let entries
@@ -36,30 +65,31 @@ export async function projectFingerprint(directory: string, signal?: AbortSignal
     }
     entries.sort((left, right) => (left.name < right.name ? -1 : left.name > right.name ? 1 : 0))
     for (const entry of entries) {
-      signal?.throwIfAborted()
       if (ignored.has(entry.name)) continue
       const path = join(folder, entry.name)
       const name = prefix + entry.name
       if (entry.isDirectory()) await visit(path, name + '/')
-      else if (/\.(?:[cm]?[jt]s|[jt]sx|jsonc?|toml)$/.test(name)) {
-        try {
-          // File links are hashed through their targets. Do not follow directory
-          // links: recursive aliases can escape the project or introduce cycles.
-          if (!entry.isFile() && !(entry.isSymbolicLink() && (await stat(path)).isFile())) continue
-          const target = entry.isSymbolicLink() ? relative(directory, await realpath(path)) : null
-          const contents = createHash('sha256')
-          for await (const chunk of createReadStream(path, { signal })) contents.update(chunk)
-          signal?.throwIfAborted()
-          fingerprint.update(JSON.stringify([name, target, contents.digest('hex')]))
-        } catch (error) {
-          // Deletion/atomic replacement during a scan is an absent input; a
-          // queued create/change event requests another scan. Other IO fails.
-          if (!disappeared(error)) throw error
-        }
-      }
+      else if (
+        /\.(?:[cm]?[jt]s|[jt]sx|jsonc?|toml)$/.test(name) &&
+        (entry.isFile() || entry.isSymbolicLink())
+      )
+        inputs.push({ name, path, link: entry.isSymbolicLink() })
     }
   }
   await visit(directory, '')
+  // Read and hash files concurrently, then fold them in the sorted traversal order,
+  // so the digest is identical to a serial scan.
+  const digests: (string | undefined)[] = Array.from({ length: inputs.length })
+  let next = 0
+  const reader = async () => {
+    for (let index = next++; index < inputs.length; index = next++) {
+      signal?.throwIfAborted()
+      digests[index] = await inputDigest(directory, inputs[index]!, signal)
+    }
+  }
+  await Promise.all(Array.from({ length: Math.min(READERS, inputs.length) }, reader))
   signal?.throwIfAborted()
+  const fingerprint = new Bun.CryptoHasher('sha256')
+  for (const digest of digests) if (digest !== undefined) fingerprint.update(digest)
   return fingerprint.digest('hex')
 }

package/src/scripts/native/lint.ts

@@ -38,6 +38,6 @@ export function lintArguments(project: Project): string[] {
   return args
 }
 
-export function lintProject(project: Project): QualityStep {
-  return { name: 'lint', ...runQualityStep(project, lintArguments(project)) }
+export async function lintProject(project: Project): Promise<QualityStep> {
+  return { name: 'lint', ...(await runQualityStep(project, lintArguments(project))) }
 }

package/src/scripts/native/package-archive.ts

@@ -1,9 +1,8 @@
-import { createHash } from 'node:crypto'
 import { gunzipSync } from 'node:zlib'
-import type { FileDigest } from './artifact.ts'
+import { sha256, type FileDigest } from './artifact.ts'
 import { packageArchivePath } from './paths.ts'
+import { USTAR_BLOCK as block, ustarChecksumValid, ustarNumber } from './ustar.ts'
 
-const block = 512
 const maximumBytes = 64 * 1024 * 1024
 
 function text(field: Buffer): string {
@@ -14,10 +13,8 @@ function text(field: Buffer): string {
 }
 
 function octal(field: Buffer): number {
-  const value = field.toString('latin1')
-  if (!/^[\0 ]*[0-7]+[\0 ]*$/.test(value)) throw new Error('Invalid package tar numeric field')
-  const number = Number.parseInt(value.replaceAll('\0', '').trim(), 8)
-  if (!Number.isSafeInteger(number)) throw new Error('Invalid package tar size')
+  const number = ustarNumber(field)
+  if (number === undefined) throw new Error('Invalid package tar numeric field')
   return number
 }
 
@@ -57,11 +54,8 @@ export async function verifyPackageArchive(
       ended = true
       break
     }
-    const checksum = octal(header.subarray(148, 156))
-    let sum = 0
-    for (let index = 0; index < block; index += 1)
-      sum += index >= 148 && index < 156 ? 32 : header[index]!
-    if (sum !== checksum) throw new Error('Invalid package tar header checksum')
+    octal(header.subarray(148, 156))
+    if (!ustarChecksumValid(header)) throw new Error('Invalid package tar header checksum')
     if (!['ustar\0', 'ustar '].includes(header.subarray(257, 263).toString('latin1')))
       throw new Error('Package archive must use the supported USTAR format')
     const kind = header[156] === 0 ? '0' : String.fromCharCode(header[156]!)
@@ -88,10 +82,7 @@ export async function verifyPackageArchive(
     } else {
       const expected = files.get(name)
       if (!expected) throw new Error(`Packed archive file inventory differs: ${name}`)
-      if (
-        size !== expected.bytes ||
-        createHash('sha256').update(data.subarray(start, end)).digest('hex') !== expected.sha256
-      )
+      if (size !== expected.bytes || sha256(data.subarray(start, end)) !== expected.sha256)
         throw new Error(`Packed archive digest mismatch: ${name}`)
       regular.add(name)
     }

package/src/scripts/native/package-set.ts

@@ -1,4 +1,3 @@
-import { createHash } from 'node:crypto'
 import { readdir, realpath, stat } from 'node:fs/promises'
 import { dirname, join } from 'node:path'
 import { isDeepStrictEqual } from 'node:util'
@@ -11,7 +10,7 @@ import {
   type DependencyLock,
 } from './package-lock.ts'
 import { inside, packageArchivePath, packagePath } from './paths.ts'
-import { fileDigest, type FileDigest } from './artifact.ts'
+import { fileDigest, sha256, type FileDigest } from './artifact.ts'
 import { verifyPackageArchive } from './package-archive.ts'
 
 export const packageNames = [
@@ -160,7 +159,7 @@ function packageManifest(
   if (
     !isDeepStrictEqual(contents['package.json'], {
       bytes: Buffer.byteLength(text),
-      sha256: createHash('sha256').update(text).digest('hex'),
+      sha256: sha256(text),
     })
   )
     throw new Error(`Package manifest digest mismatch: ${name}`)
@@ -302,6 +301,12 @@ async function containedFile(directory: string, path: string): Promise<string> {
   return target
 }
 
+/** Run checks concurrently, but report the first failure in their listed order. */
+async function settledInOrder(tasks: Promise<void>[]): Promise<void> {
+  for (const result of await Promise.allSettled(tasks))
+    if (result.status === 'rejected') throw result.reason
+}
+
 export async function readPackageSet(path: string): Promise<ReadPackageSet> {
   if (Bun.revision !== toolchain.bun.revision)
     throw new Error('Use the pinned Bun for this package set')
@@ -311,12 +316,14 @@ export async function readPackageSet(path: string): Promise<ReadPackageSet> {
   const manifest = parsePackageSet(JSON.parse(text))
   if (text !== JSON.stringify(manifest, null, 2) + '\n')
     throw new Error('Package-set manifest must use its original canonical JSON encoding')
-  for (const [name, pkg] of Object.entries(manifest.packages)) {
-    const file = await containedFile(directory, pkg.archive.file)
-    if (!isDeepStrictEqual(await fileDigest(file), digest(pkg.archive)))
-      throw new Error(`Package archive digest mismatch: ${name}`)
-    await verifyPackageArchive(file, pkg.files)
-  }
+  await settledInOrder(
+    Object.entries(manifest.packages).map(async ([name, pkg]) => {
+      const file = await containedFile(directory, pkg.archive.file)
+      if (!isDeepStrictEqual(await fileDigest(file), digest(pkg.archive)))
+        throw new Error(`Package archive digest mismatch: ${name}`)
+      await verifyPackageArchive(file, pkg.files)
+    })
+  )
   return { directory, manifest, text }
 }
 
@@ -362,7 +369,7 @@ export async function verifyInstalledPackages(
       ...pkg.files,
       '.bun-tag': {
         bytes: Buffer.byteLength(tag),
-        sha256: createHash('sha256').update(tag).digest('hex'),
+        sha256: sha256(tag),
       },
     }
     const expected = Object.keys(installedFiles).sort()
@@ -385,11 +392,13 @@ export async function verifyInstalledPackages(
     await visit(root, '')
     if (!isDeepStrictEqual(inventory.sort(), expected))
       throw new Error(`Installed package file inventory differs: ${name}`)
-    for (const [path, expected] of Object.entries(installedFiles)) {
-      const file = await containedFile(root, path)
-      if (!isDeepStrictEqual(await fileDigest(file), expected))
-        throw new Error(`Installed package digest mismatch: ${name}/${path}`)
-    }
+    await settledInOrder(
+      Object.entries(installedFiles).map(async ([path, expected]) => {
+        const file = await containedFile(root, path)
+        if (!isDeepStrictEqual(await fileDigest(file), expected))
+          throw new Error(`Installed package digest mismatch: ${name}/${path}`)
+      })
+    )
   }
   for (const name of required) {
     const root = locations.get(name)!