@bun-native/cli 0.0.0-stage → 0.33.0

package/src/scripts/native/build.ts

@@ -0,0 +1,250 @@
+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 { fileDigest } from './artifact.ts'
+import toolchain from '../../toolchain.json'
+
+/**
+ * Bun.build names each module in its `// path` comments relative to the process
+ * working directory, so bundling from another cwd changed the module bytes. Anchor
+ * it to the project for the bundle's duration; every path used here is absolute.
+ */
+async function inProjectDirectory<T>(project: Project, bundle: () => Promise<T>): Promise<T> {
+  const previous = process.cwd()
+  process.chdir(project.directory)
+  try {
+    return await bundle()
+  } finally {
+    process.chdir(previous)
+  }
+}
+
+export async function bundleProject(project: Project, outdir: string): Promise<string> {
+  const destination = resolve(outdir)
+  return inProjectDirectory(project, () => bundleFromProject(project, destination))
+}
+
+async function bundleFromProject(project: Project, outdir: string): Promise<string> {
+  if (project.framework === 'solid') {
+    // Only Solid needs the Babel universal transform; React builds skip loading it.
+    const { buildSolid } = await import('../solid-build.ts')
+    return buildSolid(project.entry, outdir)
+  }
+  await mkdir(outdir, { recursive: true })
+  const result = await Bun.build({
+    entrypoints: [project.entry],
+    outdir,
+    naming: 'application.js',
+    target: 'bun',
+    format: 'esm',
+    jsx: { runtime: 'automatic', importSource: '@bun-native/react' },
+    define: { 'process.env.NODE_ENV': '"production"' },
+    sourcemap: 'external',
+  })
+  if (!result.success) throw new AggregateError(result.logs, 'React native build failed')
+  return join(outdir, 'application.js')
+}
+
+/** 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' }
+  )
+  const compiled = compileApplication(launcher, join(outdir, applicationFile), project.directory)
+  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, ...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,
+      ...(await fileDigest(join(outdir, applicationFile))),
+      // 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 fileDigest(process.execPath) },
+      ...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/doctor.ts

@@ -0,0 +1,68 @@
+import toolchain from '../../toolchain.json'
+import { prebuiltHost } from './host.ts'
+import { readProject } from './project.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 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'}`,
+      })
+    } catch (error) {
+      results.push({ name: 'project', status: 'failed', detail: message(error) })
+    }
+  return results
+}

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

@@ -0,0 +1,139 @@
+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 { prebuiltHost } from './host.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
+
+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]!
+}
+
+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.
+ */
+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')
+  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)
+  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))
+}
+
+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
+}
+
+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
+}
+
+export 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 sums = new TextDecoder().decode(await download(`${base}/SHA256SUMS`, maximumChecksumBytes))
+  const expected = checksumFor(sums, asset)
+  const archive = await download(`${base}/${asset}`, maximumArchiveBytes)
+  const actual = createHash('sha256').update(archive).digest('hex')
+  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,65 @@
+import { createHash } from 'node:crypto'
+import { createReadStream } from 'node:fs'
+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')
+  )
+}
+
+/** 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 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) {
+      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
+        }
+      }
+    }
+  }
+  await visit(directory, '')
+  signal?.throwIfAborted()
+  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 function lintProject(project: Project): QualityStep {
+  return { name: 'lint', ...runQualityStep(project, lintArguments(project)) }
+}