@bun-native/cli 0.0.0-stage → 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/paths.ts

@@ -0,0 +1,20 @@
+import { isAbsolute, relative, sep } from 'node:path'
+
+export function inside(parent: string, child: string): boolean {
+  const path = relative(parent, child)
+  return path !== '' && path !== '..' && !path.startsWith(`..${sep}`) && !isAbsolute(path)
+}
+
+/** Package-set filenames are portable archive paths, never platform-specific paths. */
+export function packagePath(value: unknown): value is string {
+  return (
+    typeof value === 'string' &&
+    /^[A-Za-z0-9_@./-]+$/.test(value) &&
+    value.split('/').every((part) => part !== '' && part !== '.' && part !== '..')
+  )
+}
+
+/** Installer-owned metadata must not originate in a source archive at any depth. */
+export function packageArchivePath(value: unknown): value is string {
+  return packagePath(value) && !value.split('/').includes('.bun-tag')
+}

package/src/scripts/native/project.ts

@@ -0,0 +1,271 @@
+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 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'
+export type Project = {
+  directory: string
+  framework: Framework
+  entry: string
+  packageSet?: { source: { commit: string; tree: string }; manifest: FileDigest }
+}
+
+function template(framework: Framework, language: Language): string {
+  const typed = language === 'typescript'
+  const solid = framework === 'solid'
+  const title = `Bun Native ${solid ? 'Solid' : 'React'}`
+  return `${solid ? '' : '/** @jsxImportSource @bun-native/react */\n'}import { createApplication, reportHealthy } from '@bun-native/core'
+import { render${typed ? ', type JSX' : ''} } from '@bun-native/${framework}'
+import { ${solid ? 'createSignal' : 'useState'} } from '${solid ? 'solid-js' : 'react'}'
+
+const executable = process.env['BUN_NATIVE_HOST']
+if (!executable)
+  throw new Error('Run the dev command with --host pointing to a prebuilt native host')
+const application = await createApplication({ executable })
+${typed ? `let view: ReturnType<typeof render> | undefined` : '/** @type {ReturnType<typeof render> | undefined} */\nlet view'}
+const stopped = Promise.withResolvers${typed ? '<void>' : ''}()
+const stop = () => stopped.resolve(${typed ? '' : 'undefined'})
+${typed ? '' : '/** @param {unknown} message */\n'}function stopFromParent(message${typed ? ': unknown' : ''}) {
+  if (
+    message &&
+    typeof message === 'object' &&
+    'type' in message &&
+    message.type === 'bun-native:stop'
+  )
+    stop()
+}
+process.once('SIGINT', stop)
+process.once('SIGTERM', stop)
+process.on('message', stopFromParent)
+
+function App()${typed ? ': JSX.Element' : ''} {
+  const [clicks, setClicks] = ${solid ? 'createSignal' : 'useState'}(0)
+  return (
+    <box style={{ direction: 'column', gap: 12, padding: 24 }}>
+      <text text="${title}" style={{ font_size: 28 }} />
+      <text text={'Clicks: ' + ${solid ? 'clicks()' : 'clicks'}} />
+      <button
+        text="Increment"
+        style={{ width: 160, height: 44 }}
+        onClick={() => {
+          setClicks((value) => value + 1)
+        }}
+      />
+    </box>
+  )
+}
+
+try {
+  const window = await application.openWindow({
+    title: '${title}',
+    width: 640,
+    height: 480,
+  })
+  view = render(${solid ? 'App' : '<App />'}, window)
+  await view.ready
+  // Confirms a pending update when the installed app was started by the verifying launcher.
+  await reportHealthy()
+  process.send?.({ type: 'bun-native:ready' })
+  await Promise.race([window.closed, view.closed, stopped.promise])
+} finally {
+  process.off('SIGINT', stop)
+  process.off('SIGTERM', stop)
+  process.off('message', stopFromParent)
+  try {
+    await view?.dispose()
+  } finally {
+    await application.shutdown()
+    await application.closed
+    process.send?.({
+      type: 'bun-native:stopped',
+      application: application.diagnostics,
+      nodes: view?.diagnostics.nodes ?? 0,
+    })
+    if (process.connected) process.disconnect?.()
+  }
+}
+`
+}
+
+function readme(name: string, framework: Framework, guide: string): string {
+  const solid = framework === 'solid'
+  const rules = solid
+    ? `This app uses the Solid adapter (\`@bun-native/solid\`). Components run once and signals update only the native nodes that read them. Pass the component itself to \`render(App, window)\`. \`solid-js/web\` and DOM components are not available.`
+    : `This app uses the React adapter (\`@bun-native/react\`). Hooks, refs, effect cleanup and error boundaries work as in React. Pass an element to \`render(<App />, window)\`. \`react-dom\` and DOM components are not available.`
+  return `# ${name}
+
+This project uses the surrounding Bun Native checkout and its pinned dependencies.
+Run \`bun install --frozen-lockfile\` in the checkout first; no Rust compiler is needed when you supply a prebuilt host.
+
+- \`bun run check\` checks TypeScript or checked JavaScript.
+- \`bun run format\` applies Bun's built-in formatter; \`bun run format:check\` only reports differences.
+- \`bun run lint\` runs the checkout's pinned oxlint with the checkout's lint rules, or this project's own \`.oxlintrc.json\`.
+- \`bun run dev --host /absolute/path/to/bun-native-host\` bundles and opens the app once. Close the window or press Ctrl-C to end it.
+- Add \`--watch\` to remount after source edits with joined teardown. State resets on every successful edit; state-preserving hot reload is not implemented.
+- \`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.
+
+${rules} Build the interface from native elements such as \`box\`, \`text\`, \`button\` and \`input\`; CSS selectors and browser events do not apply.
+
+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 supplied explicitly and never downloaded or rebuilt.
+
+See the checkout's [getting-started guide](${guide}) for the ${solid ? 'SolidJS' : 'React'} walkthrough, debugging and upgrade steps, and \`docs/developer-tooling.md\` for requirements and limitations.
+`
+}
+
+export async function createProject(
+  repository: string,
+  destination: string,
+  framework: Framework,
+  language: Language,
+  packages?: string,
+  registry?: RegistryTemplate
+): Promise<string> {
+  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 (!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)
+  let resolvedAncestor: string | undefined
+  while (resolvedAncestor === undefined) {
+    try {
+      resolvedAncestor = await realpath(ancestor)
+    } catch (error) {
+      if (!(error instanceof Error) || !('code' in error) || error.code !== 'ENOENT') throw error
+      const parent = dirname(ancestor)
+      if (parent === ancestor) throw error
+      ancestor = parent
+    }
+  }
+  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 (!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 {
+    const entry = language === 'typescript' ? 'main.tsx' : 'main.jsx'
+    const cli = relative(directory, join(root, 'scripts/native.ts')).split(sep).join('/')
+    const tsconfig = relative(directory, join(root, 'tsconfig.json')).split(sep).join('/')
+    const guide = relative(directory, join(root, 'docs/getting-started.md')).split(sep).join('/')
+    const files: Record<string, string> = {
+      'bun-native.json': JSON.stringify({ schemaVersion: 1, framework, entry }, null, 2) + '\n',
+      'package.json':
+        JSON.stringify(
+          {
+            name: basename(directory),
+            private: true,
+            type: 'module',
+            scripts: {
+              // See docs/developer-tooling.md "Controller memory".
+              dev: `MIMALLOC_PURGE_DELAY=0 bun ${JSON.stringify(cli)} dev .`,
+              build: `bun ${JSON.stringify(cli)} build .`,
+              check: 'bun check --no-script --no-pretty',
+              format: `bun ${JSON.stringify(cli)} format .`,
+              'format:check': `bun ${JSON.stringify(cli)} format . --check`,
+              lint: `bun ${JSON.stringify(cli)} lint .`,
+            },
+          },
+          null,
+          2
+        ) + '\n',
+      'tsconfig.json': `{
+  "extends": ${JSON.stringify(tsconfig)},
+  "compilerOptions": {
+    "jsxImportSource": "@bun-native/${framework}"
+  },
+  "include": [${JSON.stringify(entry)}],
+  "exclude": ["dist", ".bun-native"]
+}
+`,
+      '.gitignore': 'dist/\n.bun-native/\n',
+      'README.md': readme(basename(directory), framework, guide),
+      [entry]: template(framework, language),
+    }
+    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)
+    }
+    for (const [name, content] of Object.entries(files))
+      await writeFile(join(directory, name), content, { flag: 'wx' })
+    return directory
+  } catch (error) {
+    await rm(directory, { recursive: true, force: true })
+    throw error
+  }
+}
+
+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()
+  if (!value || typeof value !== 'object' || Array.isArray(value))
+    throw new Error('Invalid bun-native.json project configuration')
+  const config = value as Record<string, unknown>
+  if (
+    Object.keys(config).some(
+      (key) => !['schemaVersion', 'framework', 'entry', 'packageSet'].includes(key)
+    ) ||
+    config['schemaVersion'] !== 1 ||
+    (config['framework'] !== 'solid' && config['framework'] !== 'react') ||
+    typeof config['entry'] !== 'string' ||
+    isAbsolute(config['entry']) ||
+    !/\.[jt]sx?$/.test(config['entry'])
+  )
+    throw new Error(
+      'bun-native.json requires schemaVersion 1, framework solid|react and a relative TS/JS entry'
+    )
+  const entry = await realpath(join(directory, config['entry']))
+  if (!inside(directory, entry) || !(await stat(entry)).isFile())
+    throw new Error('Project entry must be a source file inside the project')
+  if (config['packageSet'] !== undefined) {
+    if (typeof config['packageSet'] !== 'string' || isAbsolute(config['packageSet']))
+      throw new Error('Project packageSet must be a relative manifest path inside the project')
+    const manifestPath = await realpath(join(directory, config['packageSet']))
+    if (!inside(directory, manifestPath))
+      throw new Error('Project packageSet resolves outside the project')
+    const { verifyStandalone } = await import('./package-stamp.ts')
+    const packageSet = await verifyStandalone(
+      directory,
+      manifestPath,
+      config['framework'],
+      options.verification === 'stamp'
+    )
+    return { directory, framework: config['framework'], entry, packageSet }
+  }
+  // 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

@@ -0,0 +1,76 @@
+import { join, relative, sep } from 'node:path'
+// Package the template style with the CLI so standalone projects without their own config use it.
+import '../../.oxfmtrc.json'
+import type { Project } from './project.ts'
+
+/** The style the generated templates use; projects with a discoverable config keep theirs. */
+export const templateFormatterConfig = join(import.meta.dir, '../../.oxfmtrc.json')
+
+export type QualityStep = {
+  name: 'typecheck' | 'format' | 'lint'
+  command: string[]
+  exitCode: number
+  output: string
+}
+
+/** 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 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: child.signalCode ? 1 : exitCode,
+    output: (stdout + stderr).trimEnd(),
+  }
+}
+
+/** Arguments for the built-in formatter, never a same-named package script. */
+export async function formatArguments(project: Project, check: boolean): Promise<string[]> {
+  const entry = relative(project.directory, project.entry).split(sep).join('/')
+  const discovered = await Bun.spawn(
+    [process.execPath, 'fmt', '--no-script', '--find-config-path', entry],
+    { 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 !== 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 async function formatProject(project: Project, check: boolean): Promise<QualityStep> {
+  return {
+    name: 'format',
+    ...(await runQualityStep(project, await formatArguments(project, check))),
+  }
+}
+
+/** 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).
+`,
+  }
+}