@bun-native/cli 0.33.0 → 0.33.1

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

@@ -0,0 +1,209 @@
+import { lstat, mkdir, rename, rm, writeFile } from 'node:fs/promises'
+import { dirname, join, relative, resolve, sep } from 'node:path'
+import { isDeepStrictEqual } from 'node:util'
+import toolchain from '../../toolchain.json'
+import { sha256, type FileDigest } from './artifact.ts'
+import { userCache } from './context.ts'
+
+/**
+ * A verified standalone package set, as `readProject` reports it.
+ *
+ * Full verification hashes every archive, gunzips and hashes each member, checks
+ * the consumer lock, and walks and hashes every installed file. `build`, `create`
+ * and `doctor` always do that. The light commands (`check`, `format`, `lint`,
+ * `dev` and each watch remount) may instead accept a stamp that the last full
+ * verification left in `.bun-native/verified.json`. The stamp records the
+ * manifest digest and the lstat identity (device, inode, mode, size, mtime and
+ * ctime in nanoseconds) of every path that verification read: the manifest,
+ * each archive, `bun.lock`, `node_modules`, each required package root, each of
+ * its directories and installed files, and the verifier's own modules. Any
+ * write, replacement, added or removed entry changes one of those identities,
+ * and a miss falls back to full verification. A stamp hit trusts file system
+ * metadata; it is a cache for local edit loops, not a security boundary.
+ */
+export type VerifiedPackageSet = {
+  source: { commit: string; tree: string }
+  manifest: FileDigest
+}
+
+type Stamp = {
+  schemaVersion: 1
+  revision: string
+  framework: 'solid' | 'react'
+  manifestPath: string
+  archiveDirectory: string
+  manifest: FileDigest
+  source: VerifiedPackageSet['source']
+  entries: Record<string, string>
+}
+
+/** One stamp per project directory, in the user cache so the project stays clean. */
+export const stampFile = (
+  directory: string,
+  environment: Record<string, string | undefined> = process.env
+) => join(userCache(environment), 'verified', `${sha256(resolve(directory)).slice(0, 32)}.json`)
+
+// The modules whose rules decide verification; changing them invalidates every stamp.
+const verifier = [
+  'artifact.ts',
+  'package-archive.ts',
+  'package-lock.ts',
+  'package-set.ts',
+  'package-stamp.ts',
+  'paths.ts',
+].map((name) => join(import.meta.dir, name))
+
+/** One path's identity, or undefined for a symlink or other entry the stamp will not trust. */
+async function identity(path: string): Promise<string | undefined> {
+  const stats = await lstat(path, { bigint: true })
+  if (!stats.isFile() && !stats.isDirectory()) return undefined
+  return [stats.dev, stats.ino, stats.mode, stats.size, stats.mtimeNs, stats.ctimeNs].join(':')
+}
+
+async function identities(
+  directory: string,
+  paths: string[]
+): Promise<Record<string, string> | undefined> {
+  const values = await Promise.all(
+    paths.map((path) => identity(resolve(directory, path)).catch(() => undefined))
+  )
+  if (values.some((value) => value === undefined)) return undefined
+  return Object.fromEntries(paths.map((path, index) => [path, values[index]!]))
+}
+
+const portable = (path: string) => path.split(sep).join('/')
+
+async function manifestDigest(path: string): Promise<{ text: string; digest: FileDigest }> {
+  const bytes = await Bun.file(path).bytes()
+  return {
+    text: new TextDecoder().decode(bytes),
+    digest: { bytes: bytes.byteLength, sha256: sha256(bytes) },
+  }
+}
+
+/** The stamped result when every recorded identity still matches, else undefined. */
+async function stamped(
+  directory: string,
+  manifestPath: string,
+  framework: 'solid' | 'react',
+  archiveDirectory: string
+): Promise<VerifiedPackageSet | undefined> {
+  if (Bun.revision !== toolchain.bun.revision) return undefined
+  let stamp: Stamp
+  try {
+    stamp = await Bun.file(stampFile(directory)).json()
+  } catch {
+    return undefined
+  }
+  if (
+    stamp?.schemaVersion !== 1 ||
+    stamp.revision !== Bun.revision ||
+    stamp.framework !== framework ||
+    stamp.manifestPath !== manifestPath ||
+    stamp.archiveDirectory !== archiveDirectory ||
+    typeof stamp.entries !== 'object' ||
+    stamp.entries === null
+  )
+    return undefined
+  const [current, manifest] = await Promise.all([
+    identities(directory, Object.keys(stamp.entries)),
+    manifestDigest(manifestPath),
+  ])
+  if (!current || !isDeepStrictEqual(current, stamp.entries)) return undefined
+  if (!isDeepStrictEqual(manifest.digest, stamp.manifest)) return undefined
+  return { source: stamp.source, manifest: manifest.digest }
+}
+
+/** Every path full verification reads, relative to the project or absolute for the verifier. */
+async function verifiedPaths(
+  directory: string,
+  manifestPath: string,
+  manifestText: string,
+  framework: 'solid' | 'react'
+): Promise<string[]> {
+  const { parsePackageSet, requiredPackages } = await import('./package-set.ts')
+  const set = parsePackageSet(JSON.parse(manifestText))
+  const setDirectory = portable(relative(directory, dirname(manifestPath)))
+  const paths = new Set<string>([
+    portable(relative(directory, manifestPath)),
+    'bun.lock',
+    'node_modules',
+    ...verifier,
+  ])
+  for (const pkg of Object.values(set.packages)) paths.add(`${setDirectory}/${pkg.archive.file}`)
+  for (const name of requiredPackages(set, framework)) {
+    const root = `node_modules/${name}`
+    const parts = root.split('/')
+    for (let index = 2; index <= parts.length; index += 1)
+      paths.add(parts.slice(0, index).join('/'))
+    for (const file of [...Object.keys(set.packages[name]!.files), '.bun-tag']) {
+      const segments = file.split('/')
+      for (let index = 1; index <= segments.length; index += 1)
+        paths.add(`${root}/${segments.slice(0, index).join('/')}`)
+    }
+  }
+  return [...paths].sort()
+}
+
+async function writeStamp(directory: string, stamp: Stamp): Promise<void> {
+  const file = stampFile(directory)
+  const partial = `${file}.${process.pid}.partial`
+  try {
+    await mkdir(dirname(file), { recursive: true })
+    await writeFile(partial, JSON.stringify(stamp, null, 2) + '\n')
+    await rename(partial, file)
+  } catch {
+    // An unwritable user cache still verifies; it only loses the stamp.
+    await rm(partial, { force: true }).catch(() => {})
+  }
+}
+
+/**
+ * Verify a standalone project's package set and installed packages. With `reuse`,
+ * a matching stamp skips the archive and installed-file hashing, and a full
+ * verification refreshes the stamp when nothing changed while it ran.
+ */
+export async function verifyStandalone(
+  directory: string,
+  manifestPath: string,
+  framework: 'solid' | 'react',
+  reuse: boolean
+): Promise<VerifiedPackageSet> {
+  const archiveDirectory = portable(relative(directory, dirname(manifestPath)))
+  if (reuse) {
+    const hit = await stamped(directory, manifestPath, framework, archiveDirectory)
+    if (hit) return hit
+  }
+  const { readPackageSet, verifyInstalledPackages } = await import('./package-set.ts')
+  // Record identities before hashing, so a change during verification cannot be stamped.
+  const before = reuse ? await manifestDigest(manifestPath) : undefined
+  const paths = before
+    ? await verifiedPaths(directory, manifestPath, before.text, framework).catch(() => undefined)
+    : undefined
+  const recorded = paths ? await identities(directory, paths) : undefined
+  const set = await readPackageSet(manifestPath)
+  await verifyInstalledPackages(directory, set.manifest, framework, archiveDirectory)
+  const manifest =
+    before?.text === set.text ? before.digest : (await manifestDigest(manifestPath)).digest
+  const result = {
+    source: { commit: set.manifest.source.commit, tree: set.manifest.source.tree },
+    manifest,
+  }
+  if (
+    paths &&
+    recorded &&
+    before?.text === set.text &&
+    isDeepStrictEqual(recorded, await identities(directory, paths))
+  )
+    await writeStamp(directory, {
+      schemaVersion: 1,
+      revision: Bun.revision,
+      framework,
+      manifestPath,
+      archiveDirectory,
+      manifest,
+      source: result.source,
+      entries: recorded,
+    })
+  return result
+}

package/src/scripts/native/project.ts

@@ -1,9 +1,11 @@
 import { mkdir, realpath, rm, stat, writeFile } from 'node:fs/promises'
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path'
 import { inside } from './paths.ts'
-import { readPackageSet, verifyInstalledPackages } from './package-set.ts'
-import { fileDigest, type FileDigest } from './artifact.ts'
-import { copyPackageSet, standaloneFiles } from './standalone.ts'
+import type { FileDigest } from './artifact.ts'
+import { cliContext } from './context.ts'
+import type { RegistryTemplate } from './registry-project.ts'
+// Package-set modules (archive parsing, gzip, lock checks) load only for standalone
+// projects; checkout projects never need them.
 
 export type Framework = 'solid' | 'react'
 export type Language = 'typescript' | 'javascript'
@@ -121,12 +123,18 @@ export async function createProject(
   destination: string,
   framework: Framework,
   language: Language,
-  packages?: string
+  packages?: string,
+  registry?: RegistryTemplate
 ): Promise<string> {
-  const set = packages === undefined ? undefined : await readPackageSet(packages)
+  const set =
+    packages === undefined
+      ? undefined
+      : await (await import('./package-set.ts')).readPackageSet(packages)
+  // A project with installed packages (a local set or the registry) lives anywhere.
+  const installed = set !== undefined || registry !== undefined
   const root = await realpath(repository)
   const directory = resolve(destination)
-  if (!set && !inside(root, directory))
+  if (!installed && !inside(root, directory))
     throw new Error('Create the project inside this Bun Native checkout')
   // Resolve existing parents before writing, so a symlink cannot escape the checkout.
   let ancestor = dirname(directory)
@@ -141,11 +149,11 @@ export async function createProject(
       ancestor = parent
     }
   }
-  if (!set && resolvedAncestor !== root && !inside(root, resolvedAncestor))
+  if (!installed && resolvedAncestor !== root && !inside(root, resolvedAncestor))
     throw new Error('Project parent resolves outside this Bun Native checkout')
   await mkdir(dirname(directory), { recursive: true })
   const parent = await realpath(dirname(directory))
-  if (!set && parent !== root && !inside(root, parent))
+  if (!installed && parent !== root && !inside(root, parent))
     throw new Error('Project parent resolves outside this Bun Native checkout')
   await mkdir(directory) // Existing directories, including empty ones, are never overwritten.
   try {
@@ -187,7 +195,11 @@ export async function createProject(
       'README.md': readme(basename(directory), framework, guide),
       [entry]: template(framework, language),
     }
-    if (set) {
+    if (registry) {
+      const { registryFiles } = await import('./registry-project.ts')
+      Object.assign(files, registryFiles(registry, framework, entry, basename(directory)))
+    } else if (set) {
+      const { copyPackageSet, standaloneFiles } = await import('./standalone.ts')
       Object.assign(files, standaloneFiles(set, framework, entry, basename(directory)))
       await copyPackageSet(set, directory)
     }
@@ -200,7 +212,20 @@ export async function createProject(
   }
 }
 
-export async function readProject(repository: string, path: string): Promise<Project> {
+export type ReadProjectOptions = {
+  /**
+   * `full` (the default) re-verifies a standalone package set completely. `stamp`
+   * accepts the last full verification while no verified path changed; see
+   * package-stamp.ts. Use it only for commands that never ship an artifact.
+   */
+  verification?: 'full' | 'stamp'
+}
+
+export async function readProject(
+  repository: string,
+  path: string,
+  options: ReadProjectOptions = {}
+): Promise<Project> {
   const root = await realpath(repository)
   const directory = await realpath(path)
   const value: unknown = await Bun.file(join(directory, 'bun-native.json')).json()
@@ -229,23 +254,18 @@ export async function readProject(repository: string, path: string): Promise<Pro
     const manifestPath = await realpath(join(directory, config['packageSet']))
     if (!inside(directory, manifestPath))
       throw new Error('Project packageSet resolves outside the project')
-    const set = await readPackageSet(manifestPath)
-    await verifyInstalledPackages(
+    const { verifyStandalone } = await import('./package-stamp.ts')
+    const packageSet = await verifyStandalone(
       directory,
-      set.manifest,
+      manifestPath,
       config['framework'],
-      relative(directory, set.directory).split(sep).join('/')
+      options.verification === 'stamp'
     )
-    return {
-      directory,
-      framework: config['framework'],
-      entry,
-      packageSet: {
-        source: { commit: set.manifest.source.commit, tree: set.manifest.source.tree },
-        manifest: await fileDigest(manifestPath),
-      },
-    }
+    return { directory, framework: config['framework'], entry, packageSet }
   }
-  if (!inside(root, directory)) throw new Error('Project must be inside this Bun Native checkout')
+  // Without a package set, a project outside the checkout installs its packages from
+  // the registry; only an installed CLI (not a checkout's) serves such a project.
+  if (!inside(root, directory) && (await cliContext(root)).mode !== 'package')
+    throw new Error('Project must be inside this Bun Native checkout')
   return { directory, framework: config['framework'], entry }
 }

package/src/scripts/native/quality.ts

@@ -13,49 +13,64 @@ export type QualityStep = {
   output: string
 }
 
-/** Runs the pinned Bun with `args` in the project directory and captures its combined output. */
-export function runQualityStep(project: Project, args: string[]): Omit<QualityStep, 'name'> {
+/** A quality step that runs longer than this is killed and reported as failed. */
+const STEP_TIMEOUT_MS = 10 * 60_000
+
+/**
+ * Runs the pinned Bun with `args` in the project directory and captures its combined
+ * output. Asynchronous, so `check` runs its steps concurrently; callers print the
+ * results in a fixed order.
+ */
+export async function runQualityStep(
+  project: Project,
+  args: string[]
+): Promise<Omit<QualityStep, 'name'>> {
   const command = [process.execPath, ...args]
-  const result = Bun.spawnSync(command, {
+  const child = Bun.spawn(command, {
     cwd: project.directory,
     stdout: 'pipe',
     stderr: 'pipe',
     env: { ...process.env, NO_COLOR: '1' },
+    timeout: STEP_TIMEOUT_MS,
   })
+  const [stdout, stderr, exitCode] = await Promise.all([
+    new Response(child.stdout).text(),
+    new Response(child.stderr).text(),
+    child.exited,
+  ])
   return {
     command,
-    exitCode: result.exitCode ?? 1,
-    output: (result.stdout.toString() + result.stderr.toString()).trimEnd(),
+    exitCode: child.signalCode ? 1 : exitCode,
+    output: (stdout + stderr).trimEnd(),
   }
 }
 
 /** Arguments for the built-in formatter, never a same-named package script. */
-export function formatArguments(project: Project, check: boolean): string[] {
+export async function formatArguments(project: Project, check: boolean): Promise<string[]> {
   const entry = relative(project.directory, project.entry).split(sep).join('/')
-  const discovered = Bun.spawnSync(
+  const discovered = await Bun.spawn(
     [process.execPath, 'fmt', '--no-script', '--find-config-path', entry],
-    { cwd: project.directory, stdout: 'ignore', stderr: 'ignore' }
-  )
+    { cwd: project.directory, stdout: 'ignore', stderr: 'ignore', timeout: STEP_TIMEOUT_MS }
+  ).exited
   const args = ['--no-install', 'fmt', '--no-script', '--no-color']
   if (check) args.push('--check')
-  if (discovered.exitCode !== 0) args.push('--config', templateFormatterConfig)
+  if (discovered !== 0) args.push('--config', templateFormatterConfig)
   // Package archives and their canonical manifest are verified by digest, never reformatted.
   if (project.packageSet) args.push('--ignore-pattern', 'vendor/**')
   args.push('.')
   return args
 }
 
-export function formatProject(project: Project, check: boolean): QualityStep {
-  return { name: 'format', ...runQualityStep(project, formatArguments(project, check)) }
+export async function formatProject(project: Project, check: boolean): Promise<QualityStep> {
+  return {
+    name: 'format',
+    ...(await runQualityStep(project, await formatArguments(project, check))),
+  }
 }
 
-/** Built-in type checking, then formatting; both steps always run so one report covers both. */
-export function checkProject(project: Project): QualityStep[] {
-  return [
-    {
-      name: 'typecheck',
-      ...runQualityStep(project, ['--no-install', 'check', '--no-script', '--no-pretty']),
-    },
-    formatProject(project, true),
-  ]
+/** Built-in type checking and the formatter check, run together; one report covers both. */
+export async function checkProject(project: Project): Promise<QualityStep[]> {
+  const typecheck = runQualityStep(project, ['--no-install', 'check', '--no-script', '--no-pretty'])
+  const format = formatProject(project, true)
+  return [{ name: 'typecheck', ...(await typecheck) }, await format]
 }

package/src/scripts/native/registry-project.ts

@@ -0,0 +1,90 @@
+import { dirname, join } from 'node:path'
+import toolchain from '../../toolchain.json'
+import { consumerScripts, consumerTsconfig, installedCli, json } from './consumer-files.ts'
+import type { Framework } from './bundle.ts'
+
+/**
+ * The dependencies of a project created by the npm-installed CLI: every
+ * `@bun-native/*` package at the CLI's own release version, plus the framework and
+ * tool pins the release was qualified with. `scripts/registry-packages.ts` derives it
+ * from the package set's consumer definitions and publishes it in the CLI's
+ * `package.json` under `bunNative.templates`.
+ */
+export type RegistryTemplate = {
+  dependencies: Record<string, string>
+  devDependencies: Record<string, string>
+}
+export type RegistryTemplates = Record<Framework, RegistryTemplate>
+
+type ConsumerPins = Record<Framework, RegistryTemplate>
+
+/** The published templates for `version`: local `@bun-native/*` versions become the release version. */
+export function registryTemplates(consumers: ConsumerPins, version: string): RegistryTemplates {
+  const release = (pins: Record<string, string>) =>
+    Object.fromEntries(
+      Object.entries(pins).map(([name, pin]) => [
+        name,
+        name.startsWith('@bun-native/') ? version : pin,
+      ])
+    )
+  const template = (framework: Framework): RegistryTemplate => ({
+    dependencies: release(consumers[framework].dependencies),
+    devDependencies: release(consumers[framework].devDependencies),
+  })
+  return { solid: template('solid'), react: template('react') }
+}
+
+/**
+ * The templates an npm-installed CLI carries, read from its own `package.json`
+ * (`root` is the package's `src`). A CLI from a local package set has none.
+ */
+export async function installedTemplates(root: string): Promise<RegistryTemplates> {
+  const manifest: { bunNative?: { templates?: RegistryTemplates } } = await Bun.file(
+    join(dirname(root), 'package.json')
+  ).json()
+  const templates = manifest.bunNative?.templates
+  if (!templates?.solid || !templates.react)
+    throw new Error(
+      'This CLI was not installed from the npm registry; create the project with --packages /path/to/package-set/manifest.json'
+    )
+  return templates
+}
+
+export function registryFiles(
+  template: RegistryTemplate,
+  framework: Framework,
+  entry: string,
+  name: string
+): Record<string, string> {
+  const version = template.dependencies['@bun-native/core']
+  return {
+    'bun-native.json': json({ schemaVersion: 1, framework, entry }),
+    'package.json': json({
+      name,
+      private: true,
+      type: 'module',
+      packageManager: `bun@${toolchain.bun.version}`,
+      engines: { bun: toolchain.bun.version },
+      scripts: consumerScripts(),
+      dependencies: template.dependencies,
+      devDependencies: template.devDependencies,
+    }),
+    'tsconfig.json': consumerTsconfig(framework, entry, ['dist', 'node_modules', '.bun-native']),
+    '.gitignore': 'dist/\n.bun-native/\nnode_modules/\n',
+    'README.md': `# ${name}
+
+This project depends on the Bun Native ${version} packages from the npm registry. Use the Bun version in \`package.json\` \`engines\` (${toolchain.bun.cliRevision}); \`bun run build\` refuses any other compiler.
+
+1. \`bun install\` installs the pinned dependencies, including this project's own \`@bun-native/cli\`.
+2. \`${installedCli} host install\` downloads the released native host for this version into \`.bun-native/hosts\` and prints its path. Released hosts exist for linux-x64, linux-arm64, darwin-arm64 and darwin-x64.
+
+- \`bun run check\` checks TypeScript or checked JavaScript.
+- \`bun run format\` applies Bun's built-in formatter in the template style unless the project supplies its own formatter config; \`bun run format:check\` only reports differences.
+- \`bun run lint\` runs the CLI's pinned \`oxlint\` with the template rules unless the project supplies its own \`.oxlintrc.json\`.
+- \`bun run dev --host auto\` bundles and opens the app once with the released host (or pass \`--host /absolute/path/to/bun-native-host\`). Add \`--watch\` to remount after source edits; state resets on every edit.
+- \`bun run build --host auto --host-profile release\` creates an unsigned same-platform AOT app in \`dist\`. The output directory must be empty.
+
+Keep the template's optional development IPC hooks: they report readiness and clean up the renderer and owned host before a replacement starts. The host is unsigned; see the Bun Native [getting-started guide](https://github.com/0xPlayerOne/bun-native/blob/v${version}/docs/getting-started.md) and [developer tooling](https://github.com/0xPlayerOne/bun-native/blob/v${version}/docs/developer-tooling.md).
+`,
+  }
+}

package/src/scripts/native/session.ts

@@ -230,7 +230,10 @@ export class DevSession {
   }
 
   private async replace(changedAt: number): Promise<RemountReport> {
-    const project = await readProject(this.repository, this.projectDirectory)
+    // Remounts reuse the verification stamp; any change to a verified path re-verifies fully.
+    const project = await readProject(this.repository, this.projectDirectory, {
+      verification: 'stamp',
+    })
     const directory = await mkdtemp(join(this.temporaryDirectory, 'generation-'))
     let owner: OwnedProcess | undefined
     const start = performance.now()

package/src/scripts/native/standalone.ts

@@ -1,7 +1,7 @@
 import { constants } from 'node:fs'
 import { copyFile, mkdir, writeFile } from 'node:fs/promises'
 import { dirname, join } from 'node:path'
-import compilerConfig from '../../tsconfig.json'
+import { consumerScripts, consumerTsconfig, json } from './consumer-files.ts'
 import { seedConsumerLock } from './package-lock.ts'
 import { consumerArchiveLock, readPackageSet, type ReadPackageSet } from './package-set.ts'
 
@@ -22,14 +22,6 @@ export function standaloneFiles(
     )
   const dependencies = local(consumer.dependencies)
   const devDependencies = local(consumer.devDependencies)
-  const cli = 'bun --no-install ./node_modules/@bun-native/cli/src/scripts/native.ts'
-  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(', ')}]`
-    )
   return {
     'bun-native.json': json({ schemaVersion: 1, framework, entry, packageSet: packageSetPath }),
     'package.json': json({
@@ -38,16 +30,7 @@ export function standaloneFiles(
       type: 'module',
       packageManager: `bun@${set.manifest.toolchain.bun.version}`,
       engines: { bun: set.manifest.toolchain.bun.version },
-      scripts: {
-        // The persistent watch controller returns freed bundler pages promptly;
-        // see docs/developer-tooling.md "Controller memory".
-        dev: `MIMALLOC_PURGE_DELAY=0 ${cli} dev .`,
-        build: `${cli} build .`,
-        check: 'bun --no-install check --no-script --no-pretty',
-        format: `${cli} format .`,
-        'format:check': `${cli} format . --check`,
-        lint: `${cli} lint .`,
-      },
+      scripts: consumerScripts(),
       dependencies,
       devDependencies,
       overrides,
@@ -55,14 +38,12 @@ export function standaloneFiles(
     'bun.lock': json(
       seedConsumerLock(consumer.lock, { name, dependencies, devDependencies }, localLock)
     ),
-    'tsconfig.json': formattedJSON({
-      compilerOptions: {
-        ...compilerConfig.compilerOptions,
-        jsxImportSource: `@bun-native/${framework}`,
-      },
-      include: [entry],
-      exclude: ['dist', 'node_modules', '.bun-native', 'vendor'],
-    }),
+    'tsconfig.json': consumerTsconfig(framework, entry, [
+      'dist',
+      'node_modules',
+      '.bun-native',
+      'vendor',
+    ]),
     '.gitignore': 'dist/\n.bun-native/\nnode_modules/\n',
     'README.md': `# ${name}\n\nThis standalone project carries its local Bun Native package archives in \`vendor/bun-native\`. Commit that directory with this project. Its source snapshot is \`${set.manifest.source.commit}\`; use Bun revision \`${set.manifest.toolchain.bun.revision}\`. No checkout paths or workspace links are required.\n\nThe initial \`bun.lock\` contains every selected local archive tuple with SHA-256 integrity, matching local overrides, and the exact existing external dependency graph. No local root is left unresolved. First run \`bun install --offline --ignore-scripts --linker hoisted --backend copyfile\` with a populated package cache. An empty offline cache must fail; the local archives do not contain the third-party packages. Preserve the resulting lock, then use \`bun install --offline --frozen-lockfile --ignore-scripts --linker hoisted --backend copyfile\` for subsequent installs and relocation. The CLI never installs packages implicitly.\n\n- \`bun run check\` checks TypeScript or checked JavaScript.\n- \`bun run format\` applies Bun's built-in formatter in the template style unless the project supplies its own formatter config; \`bun run format:check\` only reports differences.\n- \`bun run lint\` runs the pinned \`oxlint\` with the CLI's template rules unless the project supplies its own \`.oxlintrc.json\`. It never lints \`vendor/\`, \`dist/\`, \`.bun-native/\` or \`node_modules/\`.\n- \`bun run dev --host /absolute/path/to/bun-native-host\` bundles and opens the app once.\n- Add \`--watch\` to remount after source edits with joined teardown. State resets; state-preserving hot reload is not implemented.\n- \`bun run build --host /absolute/path/to/bun-native-host --host-profile release\` creates an unsigned same-platform AOT app in \`dist\`. The output directory must be empty.\n\nSupply a separately acquired, compatible prebuilt native host. These commands never download it or run Cargo. Keep the template's optional development IPC hooks: they report readiness and join renderer/application/host cleanup. The archives are private experimental source packages, not a signed registry release. Their checksums establish consistency with the supplied manifest; verify that manifest's origin separately.\n\nSolid uses the universal JSX transform with \`jsx: preserve\`; its \`jsx-runtime\` export supplies types, not React-style automatic JSX functions. React uses its native JSX runtime. DOM/WebView APIs and browser component libraries are unsupported. See [the source-bound tooling documentation](https://github.com/0xPlayerOne/bun-native/blob/${set.manifest.source.commit}/docs/developer-tooling.md) for the native/platform and measurement limits.\n`,
   }

package/src/scripts/native/ustar.ts

@@ -0,0 +1,29 @@
+/**
+ * USTAR header primitives shared by the package-archive reader, the host-archive
+ * reader and the host-archive writer. Each reader keeps its own member rules and
+ * error messages; scripts/install-bun/archive.mjs keeps its own copy because it
+ * must run under Node before Bun exists.
+ */
+
+export const USTAR_BLOCK = 512
+
+/** A NUL/space-padded octal field as a safe integer, or undefined when malformed. */
+export function ustarNumber(field: Uint8Array): number | undefined {
+  const text = Buffer.from(field.buffer, field.byteOffset, field.byteLength).toString('latin1')
+  if (!/^[\0 ]*[0-7]+[\0 ]*$/.test(text)) return undefined
+  const value = Number.parseInt(text.replaceAll('\0', '').trim(), 8)
+  return Number.isSafeInteger(value) ? value : undefined
+}
+
+/** The header checksum, counting the checksum field itself as eight spaces. */
+export function ustarChecksum(header: Uint8Array): number {
+  let sum = 0
+  for (let index = 0; index < USTAR_BLOCK; index += 1)
+    sum += index >= 148 && index < 156 ? 0x20 : header[index]!
+  return sum
+}
+
+/** Whether a header's stored checksum field matches its bytes. */
+export function ustarChecksumValid(header: Uint8Array): boolean {
+  return ustarNumber(header.subarray(148, 156)) === ustarChecksum(header)
+}