@bun-native/cli 0.0.0-stage → 0.33.1

package/src/scripts/native/doctor.ts

@@ -0,0 +1,69 @@
+import toolchain from '../../toolchain.json'
+import { cliContext } from './context.ts'
+import { prebuiltHost } from './host.ts'
+
+type Diagnosis = { name: string; status: 'ok' | 'failed' | 'skipped'; detail: string }
+
+const message = (error: unknown) => (error instanceof Error ? error.message : String(error))
+
+/**
+ * Report toolchain, platform, host and project compatibility without launching anything.
+ * A matching host header is not proof of a Bun Native host; the runtime handshake decides that.
+ */
+export async function diagnose(
+  repository: string,
+  options: { host?: string | undefined; project?: string | undefined }
+): Promise<Diagnosis[]> {
+  const results: Diagnosis[] = []
+  results.push(
+    Bun.revision === toolchain.bun.revision
+      ? { name: 'bun', status: 'ok', detail: `pinned revision ${toolchain.bun.cliRevision}` }
+      : {
+          name: 'bun',
+          status: 'failed',
+          detail: `running ${Bun.version} (${Bun.revision}); dev, build and package sets require ${toolchain.bun.cliRevision} from toolchain.json`,
+        }
+  )
+  const target = `${process.platform}-${process.arch}`
+  results.push(
+    target in toolchain.bun.packages
+      ? { name: 'platform', status: 'ok', detail: `${target} has a pinned Bun distribution` }
+      : {
+          name: 'platform',
+          status: 'failed',
+          detail: `${target} has no pinned Bun distribution; supported: ${Object.keys(toolchain.bun.packages).join(', ')}`,
+        }
+  )
+  if (options.host === undefined)
+    results.push({
+      name: 'host',
+      status: 'skipped',
+      detail: 'pass --host /absolute/path/to/bun-native-host to check a prebuilt host',
+    })
+  else
+    try {
+      const host = await prebuiltHost(options.host)
+      results.push({
+        name: 'host',
+        status: 'ok',
+        detail: `${host} is a readable ${process.platform}/${process.arch} executable (protocol handshake not run)`,
+      })
+    } catch (error) {
+      results.push({ name: 'host', status: 'failed', detail: message(error) })
+    }
+  if (options.project === undefined)
+    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' : (await cliContext(repository)).mode === 'package' ? ' with registry packages' : ' in this checkout'}`,
+      })
+    } catch (error) {
+      results.push({ name: 'project', status: 'failed', detail: message(error) })
+    }
+  return results
+}

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

@@ -0,0 +1,179 @@
+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 = [
+  'linux-x64',
+  'linux-arm64',
+  'darwin-arm64',
+  'darwin-x64',
+] as const
+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,
+  arch: string = process.arch
+): ReleaseHostTarget {
+  const target = `${platform}-${arch}`
+  if (!(releaseHostTargets as readonly string[]).includes(target))
+    throw new Error(
+      `No released native host for ${target}; supply --host with a host built from source (released: ${releaseHostTargets.join(', ')})`
+    )
+  return target as ReleaseHostTarget
+}
+
+export function releaseHostAsset(target: ReleaseHostTarget): string {
+  return `bun-native-host-${target}.tar.gz`
+}
+
+/** The expected digest of `asset` from a release's `sha256sum`-format SHA256SUMS. */
+export function checksumFor(sums: string, asset: string): string {
+  const matches = sums
+    .split('\n')
+    .map((line) => /^([0-9a-f]{64}) [ *]([A-Za-z0-9._-]+)$/.exec(line.trimEnd()))
+    .filter((match): match is RegExpExecArray => match !== null && match[2] === asset)
+  if (matches.length !== 1)
+    throw new Error(`SHA256SUMS must list ${asset} exactly once (found ${matches.length})`)
+  return matches[0]![1]!
+}
+
+/**
+ * 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.
+ */
+export function hostFromArchive(archive: Uint8Array): Buffer {
+  const tar = gunzipSync(archive, { maxOutputLength: maximumArchiveBytes })
+  if (tar.length < 1024 || tar.length % 512 !== 0) throw new Error('Host archive is truncated')
+  const header = tar.subarray(0, 512)
+  const name = header.toString('latin1', 0, 100).replace(/\0+$/, '')
+  if (name !== 'bun-native-host')
+    throw new Error(`Host archive must hold only bun-native-host, not ${name || 'nothing'}`)
+  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')
+  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))
+    throw new Error('Host archive must hold exactly one member')
+  return Buffer.from(tar.subarray(512, 512 + size))
+}
+
+/**
+ * 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 = {
+  version: string
+  /** Release download base; the tag directory is appended. Defaults to GitHub releases. */
+  baseUrl?: string
+  /** Directory that holds one host per version and target. */
+  cache: string
+  force?: boolean
+  target?: ReleaseHostTarget
+  /** Deadline for each download, request and body together. Defaults to 5 minutes. */
+  timeoutMs?: number
+}
+
+function installedHostPath(options: HostInstallOptions): string {
+  const target = options.target ?? releaseHostTarget()
+  return join(options.cache, `v${options.version}`, target, 'bun-native-host')
+}
+
+/**
+ * Download this version's release host for the current OS and CPU, check the
+ * archive against the release's SHA256SUMS, unpack its one member and check its
+ * executable header. A cached host from an earlier install is reused unless
+ * `force` is set. The host is unsigned; the checksum proves only that the bytes
+ * match what the release workflow attached (docs/developer-tooling.md).
+ */
+export async function installReleaseHost(options: HostInstallOptions): Promise<string> {
+  if (!/^\d+\.\d+\.\d+$/.test(options.version))
+    throw new Error(`Release host version must be x.y.z, not ${options.version}`)
+  const target = options.target ?? releaseHostTarget()
+  const destination = installedHostPath({ ...options, target })
+  if (!options.force && (await stat(destination).catch(() => undefined))?.isFile())
+    return prebuiltHost(destination)
+  const base = `${(options.baseUrl ?? process.env['BUN_NATIVE_HOST_RELEASE_URL'] ?? releases).replace(/\/+$/, '')}/v${options.version}`
+  const asset = releaseHostAsset(target)
+  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, timeoutMs)
+  const actual = sha256(archive)
+  if (actual !== expected)
+    throw new Error(`${asset} digest ${actual} does not match SHA256SUMS ${expected}`)
+  const host = hostFromArchive(archive)
+  await mkdir(dirname(destination), { recursive: true })
+  const partial = `${destination}.${process.pid}.partial`
+  try {
+    await writeFile(partial, host, { mode: 0o755 })
+    await chmod(partial, 0o755)
+    await prebuiltHost(partial)
+    await rename(partial, destination)
+  } finally {
+    await rm(partial, { force: true })
+  }
+  await writeFile(`${destination}.archive.sha256`, `${actual}  ${asset}\n`)
+  return prebuiltHost(destination)
+}

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

@@ -0,0 +1,33 @@
+import type { FileHandle } from 'node:fs/promises'
+
+/** Inspect the existing bounded header fields; the caller retains the read handle. */
+export async function hasExecutableHeader(
+  file: Pick<FileHandle, 'read'>,
+  target: { platform: NodeJS.Platform; arch: NodeJS.Architecture }
+): Promise<boolean> {
+  const header = Buffer.alloc(64)
+  const { bytesRead } = await file.read(header, 0, header.length, 0)
+  if (bytesRead !== header.length) return false
+  if (target.platform === 'linux')
+    return (
+      header.readUInt32LE(0) === 0x464c457f &&
+      header[4] === 2 &&
+      header[5] === 1 &&
+      header.readUInt16LE(18) === (target.arch === 'arm64' ? 183 : 62)
+    )
+  if (target.platform === 'darwin')
+    return (
+      header.readUInt32LE(0) === 0xfeedfacf &&
+      header.readUInt32LE(4) === (target.arch === 'arm64' ? 0x0100000c : 0x01000007)
+    )
+  if (target.platform === 'win32' && header.subarray(0, 2).toString() === 'MZ') {
+    const pe = Buffer.alloc(6)
+    const read = await file.read(pe, 0, pe.length, header.readUInt32LE(60))
+    return (
+      read.bytesRead === pe.length &&
+      pe.readUInt32LE(0) === 0x00004550 &&
+      pe.readUInt16LE(4) === (target.arch === 'arm64' ? 0xaa64 : 0x8664)
+    )
+  }
+  return false
+}

package/src/scripts/native/host.ts

@@ -0,0 +1,22 @@
+import { constants } from 'node:fs'
+import { access, open, realpath, stat } from 'node:fs/promises'
+import { isAbsolute } from 'node:path'
+import { hasExecutableHeader } from './host-header.ts'
+
+export async function prebuiltHost(path: string | undefined): Promise<string> {
+  if (!path || !isAbsolute(path))
+    throw new Error(
+      '--host must be an absolute path to an existing prebuilt native host, or auto for the released host; this command never runs Cargo'
+    )
+  const host = await realpath(path)
+  if (!(await stat(host)).isFile()) throw new Error('The prebuilt native host must be a file')
+  await access(host, constants.R_OK | (process.platform === 'win32' ? 0 : constants.X_OK))
+  const file = await open(host, 'r')
+  try {
+    if (!(await hasExecutableHeader(file, { platform: process.platform, arch: process.arch })))
+      throw new Error(`Prebuilt host must be a ${process.platform}/${process.arch} executable`)
+  } finally {
+    await file.close()
+  }
+  return host
+}

package/src/scripts/native/inputs.ts

@@ -0,0 +1,95 @@
+import { readdir, realpath, stat } from 'node:fs/promises'
+import { join, relative } from 'node:path'
+
+const ignored = new Set(['node_modules', '.git', '.bun-native', 'dist', 'build'])
+
+export function rescanInput(path: string | Buffer | null | undefined): boolean {
+  // Missing names request a content rescan; they do not establish a source edit.
+  if (path === null || path === undefined) return true
+  const name = path.toString().replaceAll('\\', '/')
+  // A name without an extension may be a directory being replaced or removed.
+  // The snapshot decides whether relevant files actually changed.
+  return !name.split('/').some((part) => ignored.has(part))
+}
+
+function disappeared(error: unknown): boolean {
+  return (
+    error instanceof Error &&
+    'code' in error &&
+    (error.code === 'ENOENT' || error.code === 'ENOTDIR')
+  )
+}
+
+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 inputs: Input[] = []
+  const visit = async (folder: string, prefix: string): Promise<void> => {
+    signal?.throwIfAborted()
+    let entries
+    try {
+      entries = await readdir(folder, { withFileTypes: true })
+    } catch (error) {
+      if (disappeared(error)) return
+      throw error
+    }
+    entries.sort((left, right) => (left.name < right.name ? -1 : left.name > right.name ? 1 : 0))
+    for (const entry of entries) {
+      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) &&
+        (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

@@ -0,0 +1,43 @@
+import { existsSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+// Package the template lint rules with the CLI so projects without their own config use them.
+import '../../.oxlintrc.json'
+// Importing the manifest makes oxlint a pinned dependency of the packaged CLI.
+import oxlint from 'oxlint/package.json'
+import type { Project } from './project.ts'
+import { runQualityStep, type QualityStep } from './quality.ts'
+
+/** The rules the generated templates satisfy; a project's own `.oxlintrc.json` replaces them. */
+export const templateLinterConfig = join(import.meta.dir, '../../.oxlintrc.json')
+
+/** Generated build output and development bundles are never linted. */
+const generatedOutput = ['dist/**', '.bun-native/**', 'node_modules/**']
+
+/** The CLI's own pinned oxlint, resolved from the CLI location rather than the project. */
+function linterEntry(): string {
+  const manifest = Bun.resolveSync('oxlint/package.json', import.meta.dir)
+  return join(dirname(manifest), oxlint.bin.oxlint)
+}
+
+/** Arguments for the pinned linter with deterministic, uncoloured line output. */
+export function lintArguments(project: Project): string[] {
+  const own = join(project.directory, '.oxlintrc.json')
+  const args = [
+    '--no-install',
+    linterEntry(),
+    '--config',
+    existsSync(own) ? own : templateLinterConfig,
+    '--deny-warnings',
+    '--format',
+    'unix',
+  ]
+  // Package archives and their canonical manifest are verified by digest, never linted.
+  const ignored = project.packageSet ? [...generatedOutput, 'vendor/**'] : generatedOutput
+  for (const pattern of ignored) args.push('--ignore-pattern', pattern)
+  args.push('.')
+  return args
+}
+
+export async function lintProject(project: Project): Promise<QualityStep> {
+  return { name: 'lint', ...(await runQualityStep(project, lintArguments(project))) }
+}

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

@@ -0,0 +1,94 @@
+import { gunzipSync } from 'node:zlib'
+import { sha256, type FileDigest } from './artifact.ts'
+import { packageArchivePath } from './paths.ts'
+import { USTAR_BLOCK as block, ustarChecksumValid, ustarNumber } from './ustar.ts'
+
+const maximumBytes = 64 * 1024 * 1024
+
+function text(field: Buffer): string {
+  const end = field.indexOf(0)
+  if (end !== -1 && field.subarray(end).some((byte) => byte !== 0))
+    throw new Error('Invalid package tar text padding')
+  return field.subarray(0, end === -1 ? undefined : end).toString('latin1')
+}
+
+function octal(field: Buffer): number {
+  const number = ustarNumber(field)
+  if (number === undefined) throw new Error('Invalid package tar numeric field')
+  return number
+}
+
+/** Inspect original USTAR members before any map can erase duplicates or link metadata. */
+export async function verifyPackageArchive(
+  path: string,
+  expected: Record<string, FileDigest>
+): Promise<void> {
+  const files = new Map<string, FileDigest>()
+  const directories = new Set<string>()
+  let paddedContents = 0
+  for (const [name, digest] of Object.entries(expected)) {
+    if (!packageArchivePath(name) || !Number.isSafeInteger(digest.bytes) || digest.bytes < 0)
+      throw new Error('Invalid expected package archive inventory')
+    const full = `package/${name}`
+    files.set(full, digest)
+    const parts = full.split('/')
+    for (let index = 1; index < parts.length; index += 1)
+      directories.add(parts.slice(0, index).join('/'))
+    paddedContents += Math.ceil(digest.bytes / block) * block
+  }
+  // Permit the declared files, directory headers, end blocks and one conventional
+  // 10 KiB blocking pad. Bound decompression before parsing any member contents.
+  const limit = paddedContents + (files.size + directories.size + 2) * block + 10_240
+  if (!Number.isSafeInteger(limit) || limit > maximumBytes || Bun.file(path).size > maximumBytes)
+    throw new Error('Package archive exceeds the bounded source-package inspection limit')
+  const data = gunzipSync(await Bun.file(path).bytes(), { maxOutputLength: limit })
+  if (data.length % block !== 0) throw new Error('Truncated package tar blocks')
+  const seen = new Set<string>()
+  const regular = new Set<string>()
+  let ended = false
+  for (let offset = 0; offset + block <= data.length;) {
+    const header = data.subarray(offset, offset + block)
+    if (header.every((byte) => byte === 0)) {
+      if (data.length - offset < block * 2 || data.subarray(offset).some((byte) => byte !== 0))
+        throw new Error('Invalid package tar end records or trailing data')
+      ended = true
+      break
+    }
+    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]!)
+    if (!['0', '5'].includes(kind) || text(header.subarray(157, 257)) !== '')
+      throw new Error(`Unsupported package tar member type or link: ${kind}`)
+    const size = octal(header.subarray(124, 136))
+    const prefix = text(header.subarray(345, 500))
+    const raw = (prefix ? prefix + '/' : '') + text(header.subarray(0, 100))
+    const name = kind === '5' ? raw.replace(/\/$/, '') : raw
+    if (!packageArchivePath(name))
+      throw new Error(`Package archive inventory contains an invalid path: ${raw}`)
+    if (seen.has(name)) throw new Error(`Duplicate package tar member: ${name}`)
+    seen.add(name)
+    const start = offset + block
+    const end = start + size
+    const next = start + Math.ceil(size / block) * block
+    if (!Number.isSafeInteger(next) || next > data.length)
+      throw new Error('Truncated package tar member')
+    if (data.subarray(end, next).some((byte) => byte !== 0))
+      throw new Error('Invalid package tar member padding')
+    if (kind === '5') {
+      if (size !== 0 || !directories.has(name))
+        throw new Error(`Unexpected package tar directory: ${name}`)
+    } else {
+      const expected = files.get(name)
+      if (!expected) throw new Error(`Packed archive file inventory differs: ${name}`)
+      if (size !== expected.bytes || sha256(data.subarray(start, end)) !== expected.sha256)
+        throw new Error(`Packed archive digest mismatch: ${name}`)
+      regular.add(name)
+    }
+    offset = next
+  }
+  if (!ended) throw new Error('Package tar has no end records')
+  if (regular.size !== files.size)
+    throw new Error('Packed archive file inventory differs from the staged package')
+}