@bun-native/cli 0.0.0-stage → 0.33.0

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

@@ -0,0 +1,408 @@
+import { createHash } from 'node:crypto'
+import { readdir, realpath, stat } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+import { isDeepStrictEqual } from 'node:util'
+import toolchain from '../../toolchain.json'
+import {
+  dependencyClosure,
+  lockedPackages,
+  localArchiveLock,
+  verifyConsumerLock,
+  type DependencyLock,
+} from './package-lock.ts'
+import { inside, packageArchivePath, packagePath } from './paths.ts'
+import { fileDigest, type FileDigest } from './artifact.ts'
+import { verifyPackageArchive } from './package-archive.ts'
+
+export const packageNames = [
+  '@bun-native/cli',
+  '@bun-native/core',
+  '@bun-native/protocol',
+  '@bun-native/react',
+  '@bun-native/renderer',
+  '@bun-native/runtime',
+  '@bun-native/solid',
+] as const
+
+export type PackageManifest = {
+  name: string
+  version: string
+  private: true
+  type: 'module'
+  license: 'MIT'
+  files: string[]
+  engines: { bun: string }
+  dependencies?: Record<string, string>
+  exports?: string | Record<string, string>
+  bin?: Record<string, string>
+}
+export type LocalPackage = {
+  manifest: PackageManifest
+  archive: FileDigest & { file: string }
+  files: Record<string, FileDigest>
+}
+export type Consumer = {
+  dependencies: Record<string, string>
+  devDependencies: Record<string, string>
+  lock: DependencyLock
+}
+export type PackageSet = {
+  schemaVersion: 1
+  source: { commit: string; tree: string; files: Record<string, FileDigest> }
+  toolchain: typeof toolchain
+  compiler: { revision: string; os: string; architecture: string; executable: FileDigest }
+  packages: Record<string, LocalPackage>
+  consumers: { solid: Consumer; react: Consumer }
+}
+export type ReadPackageSet = { directory: string; manifest: PackageSet; text: string }
+
+function object(value: unknown): Record<string, unknown> {
+  if (!value || typeof value !== 'object' || Array.isArray(value))
+    throw new Error('Invalid package-set object')
+  return value as Record<string, unknown>
+}
+
+function keys(value: Record<string, unknown>, required: string[], optional: string[] = []): void {
+  if (
+    required.some((key) => !Object.hasOwn(value, key)) ||
+    Object.keys(value).some((key) => !required.includes(key) && !optional.includes(key))
+  )
+    throw new Error('Unexpected or missing package-set fields')
+}
+
+function digest(value: unknown): FileDigest {
+  const fields = object(value)
+  if (
+    !Number.isSafeInteger(fields['bytes']) ||
+    (fields['bytes'] as number) < 0 ||
+    typeof fields['sha256'] !== 'string' ||
+    !/^[a-f0-9]{64}$/.test(fields['sha256'])
+  )
+    throw new Error('Invalid package-set file digest')
+  return { bytes: fields['bytes'] as number, sha256: fields['sha256'] }
+}
+
+function files(value: unknown): Record<string, FileDigest> {
+  const result: Record<string, FileDigest> = Object.create(null)
+  for (const [path, entry] of Object.entries(object(value))) {
+    if (!packagePath(path)) throw new Error(`Invalid package-set file path: ${path}`)
+    keys(object(entry), ['bytes', 'sha256'])
+    result[path] = digest(entry)
+  }
+  return result
+}
+
+function versions(value: unknown): Record<string, string> {
+  const result: Record<string, string> = Object.create(null)
+  for (const [name, version] of Object.entries(object(value))) {
+    if (
+      !/^(?:@[a-z0-9._-]+\/)?[a-z0-9._-]+$/.test(name) ||
+      typeof version !== 'string' ||
+      !/^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/.test(version)
+    )
+      throw new Error(`Package-set dependency must have an exact version: ${name}`)
+    result[name] = version
+  }
+  return result
+}
+
+function exportedPaths(value: unknown): string[] {
+  return typeof value === 'string'
+    ? [value]
+    : Object.values(object(value)).map((entry) => {
+        if (typeof entry !== 'string') throw new Error('Invalid package export/bin path')
+        return entry
+      })
+}
+
+function packageManifest(
+  value: unknown,
+  name: string,
+  contents: Record<string, FileDigest>
+): PackageManifest {
+  const manifest = object(value)
+  keys(
+    manifest,
+    ['name', 'version', 'private', 'type', 'license', 'files', 'engines'],
+    ['dependencies', 'exports', 'bin']
+  )
+  if (
+    manifest['name'] !== name ||
+    manifest['private'] !== true ||
+    manifest['type'] !== 'module' ||
+    manifest['license'] !== 'MIT' ||
+    !isDeepStrictEqual(manifest['engines'], { bun: toolchain.bun.version }) ||
+    !Array.isArray(manifest['files']) ||
+    manifest['files'].some((path) => !packageArchivePath(path))
+  )
+    throw new Error(`Invalid materialized package manifest: ${name}`)
+  versions({ [name]: manifest['version'] })
+  if (manifest['dependencies'] !== undefined) versions(manifest['dependencies'])
+  for (const field of ['exports', 'bin']) {
+    if (manifest[field] === undefined) continue
+    for (const exported of exportedPaths(manifest[field])) {
+      const path = exported.replace(/^\.\//, '')
+      if (!packagePath(path) || !Object.hasOwn(contents, path))
+        throw new Error(`Unpackaged ${field} target: ${name} ${exported}`)
+    }
+  }
+  if (
+    !Object.hasOwn(contents, 'LICENSE') ||
+    !Object.hasOwn(contents, 'bun-native-source.json') ||
+    !Object.hasOwn(contents, 'package.json') ||
+    (name === '@bun-native/cli'
+      ? !isDeepStrictEqual(manifest['bin'], { 'bun-native': './src/scripts/native.ts' }) ||
+        manifest['exports'] !== undefined
+      : manifest['exports'] === undefined || manifest['bin'] !== undefined)
+  )
+    throw new Error(`Missing package entry/license/provenance: ${name}`)
+  const text = JSON.stringify(manifest, null, 2) + '\n'
+  if (
+    !isDeepStrictEqual(contents['package.json'], {
+      bytes: Buffer.byteLength(text),
+      sha256: createHash('sha256').update(text).digest('hex'),
+    })
+  )
+    throw new Error(`Package manifest digest mismatch: ${name}`)
+  return manifest as PackageManifest
+}
+
+export function requiredPackages(set: PackageSet, framework: 'solid' | 'react'): string[] {
+  const pending = ['@bun-native/cli', '@bun-native/core', `@bun-native/${framework}`]
+  const required = new Set<string>()
+  for (let index = 0; index < pending.length; index += 1) {
+    const name = pending[index]!
+    if (required.has(name)) continue
+    const pkg = set.packages[name]
+    if (!pkg) throw new Error(`Missing local package: ${name}`)
+    required.add(name)
+    for (const [dependency, version] of Object.entries(pkg.manifest.dependencies ?? {})) {
+      if (!dependency.startsWith('@bun-native/')) continue
+      if (set.packages[dependency]?.manifest.version !== version)
+        throw new Error(`Inconsistent internal dependency: ${name} -> ${dependency}`)
+      pending.push(dependency)
+    }
+  }
+  return [...required].sort()
+}
+
+export function consumerArchiveLock(
+  set: PackageSet,
+  framework: 'solid' | 'react',
+  archiveDirectory = 'vendor/bun-native'
+) {
+  return localArchiveLock(
+    requiredPackages(set, framework).map((name) => {
+      const pkg = set.packages[name]!
+      return {
+        name,
+        file: `${archiveDirectory ? archiveDirectory + '/' : ''}${pkg.archive.file}`,
+        sha256: pkg.archive.sha256,
+        ...(pkg.manifest.dependencies ? { dependencies: pkg.manifest.dependencies } : {}),
+        ...(pkg.manifest.bin ? { bin: pkg.manifest.bin } : {}),
+      }
+    })
+  )
+}
+
+/** Validates data only; archives are hashed separately before any destination is written. */
+export function parsePackageSet(value: unknown): PackageSet {
+  const fields = object(value)
+  keys(fields, ['schemaVersion', 'source', 'toolchain', 'compiler', 'packages', 'consumers'])
+  if (fields['schemaVersion'] !== 1 || !isDeepStrictEqual(fields['toolchain'], toolchain))
+    throw new Error('Package set requires the exact pinned Bun Native toolchain')
+  const source = object(fields['source'])
+  keys(source, ['commit', 'tree', 'files'])
+  if (
+    ![source['commit'], source['tree']].every(
+      (value) => typeof value === 'string' && /^[a-f0-9]{40}$/.test(value)
+    )
+  )
+    throw new Error('Package set requires exact source commit and tree identities')
+  files(source['files'])
+  const compiler = object(fields['compiler'])
+  keys(compiler, ['revision', 'os', 'architecture', 'executable'])
+  if (
+    compiler['revision'] !== toolchain.bun.revision ||
+    typeof compiler['os'] !== 'string' ||
+    typeof compiler['architecture'] !== 'string'
+  )
+    throw new Error('Invalid package producer compiler identity')
+  digest(compiler['executable'])
+  const packages = object(fields['packages'])
+  keys(packages, [...packageNames])
+  const archives = new Set<string>()
+  for (const [name, entry] of Object.entries(packages)) {
+    const pkg = object(entry)
+    keys(pkg, ['manifest', 'archive', 'files'])
+    const contents = files(pkg['files'])
+    if (Object.keys(contents).some((path) => !packageArchivePath(path)))
+      throw new Error(`Source archive contains reserved installer metadata: ${name}`)
+    packageManifest(pkg['manifest'], name, contents)
+    const archive = object(pkg['archive'])
+    keys(archive, ['file', 'bytes', 'sha256'])
+    digest(archive)
+    if (
+      !packagePath(archive['file']) ||
+      !/^archives\/[a-z0-9._-]+\.tgz$/.test(archive['file']) ||
+      archives.has(archive['file'])
+    )
+      throw new Error('Package archives must have unique contained relative paths')
+    archives.add(archive['file'])
+  }
+  const consumers = object(fields['consumers'])
+  keys(consumers, ['solid', 'react'])
+  const set = fields as PackageSet
+  for (const framework of ['solid', 'react'] as const) {
+    const consumer = object(consumers[framework])
+    keys(consumer, ['dependencies', 'devDependencies', 'lock'])
+    const runtime = versions(consumer['dependencies'])
+    const development = versions(consumer['devDependencies'])
+    if (
+      !runtime['@bun-native/core'] ||
+      !runtime[`@bun-native/${framework}`] ||
+      !runtime[framework === 'solid' ? 'solid-js' : 'react'] ||
+      !development['@bun-native/cli'] ||
+      !development['@types/bun'] ||
+      (framework === 'react' &&
+        (!development['@types/react'] || !development['@types/react-reconciler']))
+    )
+      throw new Error(`Missing required consumer dependencies for ${framework}`)
+    const dependencies = { ...runtime, ...development }
+    const external: Record<string, string> = Object.create(null)
+    for (const name of requiredPackages(set, framework)) {
+      for (const [dependency, version] of Object.entries(
+        set.packages[name]!.manifest.dependencies ?? {}
+      )) {
+        if (dependencies[dependency] !== undefined && dependencies[dependency] !== version)
+          throw new Error(`Inconsistent consumer dependency: ${dependency}`)
+        dependencies[dependency] = version
+      }
+    }
+    for (const [name, version] of Object.entries(dependencies)) {
+      if (name.startsWith('@bun-native/')) {
+        if (set.packages[name]?.manifest.version !== version)
+          throw new Error(`Unknown local dependency: ${name}`)
+      } else external[name] = version
+    }
+    const lock = lockedPackages(consumer['lock'])
+    if (
+      !isDeepStrictEqual(consumer['lock'], lock) ||
+      !isDeepStrictEqual(lock, dependencyClosure(lock, external))
+    )
+      throw new Error(`Unexpected dependency-lock entries for ${framework}`)
+  }
+  return set
+}
+
+async function containedFile(directory: string, path: string): Promise<string> {
+  const target = await realpath(join(directory, path))
+  if (!inside(directory, target) || !(await stat(target)).isFile())
+    throw new Error(`Package file escapes its owned directory or is not a file: ${path}`)
+  return target
+}
+
+export async function readPackageSet(path: string): Promise<ReadPackageSet> {
+  if (Bun.revision !== toolchain.bun.revision)
+    throw new Error('Use the pinned Bun for this package set')
+  const filename = await realpath(path)
+  const directory = dirname(filename)
+  const text = await Bun.file(filename).text()
+  const manifest = parsePackageSet(JSON.parse(text))
+  if (text !== JSON.stringify(manifest, null, 2) + '\n')
+    throw new Error('Package-set manifest must use its original canonical JSON encoding')
+  for (const [name, pkg] of Object.entries(manifest.packages)) {
+    const file = await containedFile(directory, pkg.archive.file)
+    if (!isDeepStrictEqual(await fileDigest(file), digest(pkg.archive)))
+      throw new Error(`Package archive digest mismatch: ${name}`)
+    await verifyPackageArchive(file, pkg.files)
+  }
+  return { directory, manifest, text }
+}
+
+/** Validate the installed CLI too, before its lazy compiler/watch modules are imported. */
+export async function verifyInstalledPackages(
+  directory: string,
+  set: PackageSet,
+  framework: 'solid' | 'react',
+  archiveDirectory = 'vendor/bun-native'
+): Promise<void> {
+  let modules: string
+  try {
+    modules = await realpath(join(directory, 'node_modules'))
+  } catch (error) {
+    if (error instanceof Error && 'code' in error && error.code === 'ENOENT')
+      throw new Error(
+        "Standalone dependencies are not installed; follow this project's pinned offline-install instructions"
+      )
+    throw error
+  }
+  if (!inside(directory, modules))
+    throw new Error('Installed packages must belong to this consumer')
+  const required = requiredPackages(set, framework)
+  verifyConsumerLock(
+    Bun.JSONC.parse(await Bun.file(join(directory, 'bun.lock')).text()),
+    set.consumers[framework].lock,
+    true,
+    consumerArchiveLock(set, framework, archiveDirectory)
+  )
+  const locations = new Map<string, string>()
+  for (const name of required) {
+    const pkg = set.packages[name]!
+    const root = await realpath(join(modules, name))
+    if (!inside(modules, root))
+      throw new Error(`Installed package resolves outside this consumer: ${name}`)
+    locations.set(name, root)
+    if (Object.keys(pkg.files).some((path) => !packageArchivePath(path)))
+      throw new Error(`Source archive contains reserved installer metadata: ${name}`)
+    // Pinned Integrity::Display uses unpadded base64 followed by "==" for
+    // SHA-256. This is its 52-byte installer tag, not the canonical lock SRI.
+    const tag = `sha256-${Buffer.from(pkg.archive.sha256, 'hex').toString('base64').replace(/=+$/, '')}==`
+    const installedFiles: Record<string, FileDigest> = {
+      ...pkg.files,
+      '.bun-tag': {
+        bytes: Buffer.byteLength(tag),
+        sha256: createHash('sha256').update(tag).digest('hex'),
+      },
+    }
+    const expected = Object.keys(installedFiles).sort()
+    const folders = new Set(
+      expected.flatMap((path) => {
+        const parts = path.split('/')
+        return parts.slice(1).map((_, index) => parts.slice(0, index + 1).join('/'))
+      })
+    )
+    const inventory: string[] = []
+    const visit = async (directory: string, prefix: string): Promise<void> => {
+      for (const entry of await readdir(directory, { withFileTypes: true })) {
+        const path = prefix + entry.name
+        if (entry.isDirectory() && folders.has(path))
+          await visit(join(directory, entry.name), path + '/')
+        else if (entry.isFile() && Object.hasOwn(installedFiles, path)) inventory.push(path)
+        else throw new Error(`Installed package file inventory differs: ${name}/${path}`)
+      }
+    }
+    await visit(root, '')
+    if (!isDeepStrictEqual(inventory.sort(), expected))
+      throw new Error(`Installed package file inventory differs: ${name}`)
+    for (const [path, expected] of Object.entries(installedFiles)) {
+      const file = await containedFile(root, path)
+      if (!isDeepStrictEqual(await fileDigest(file), expected))
+        throw new Error(`Installed package digest mismatch: ${name}/${path}`)
+    }
+  }
+  for (const name of required) {
+    const root = locations.get(name)!
+    for (const dependency of Object.keys(set.packages[name]!.manifest.dependencies ?? {})) {
+      if (!dependency.startsWith('@bun-native/')) continue
+      const expected = locations.get(dependency)!
+      const resolved = await realpath(Bun.resolveSync(dependency, root))
+      const exported = set.packages[dependency]!.manifest.exports!
+      const entry = typeof exported === 'string' ? exported : exported['.']!
+      if (resolved !== (await realpath(join(expected, entry))))
+        throw new Error(
+          `Installed dependency resolves to a different package: ${name} -> ${dependency}`
+        )
+    }
+  }
+}

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,251 @@
+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'
+
+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
+): Promise<string> {
+  const set = packages === undefined ? undefined : await readPackageSet(packages)
+  const root = await realpath(repository)
+  const directory = resolve(destination)
+  if (!set && !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 (!set && 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))
+    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 (set) {
+      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 async function readProject(repository: string, path: string): 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 set = await readPackageSet(manifestPath)
+    await verifyInstalledPackages(
+      directory,
+      set.manifest,
+      config['framework'],
+      relative(directory, set.directory).split(sep).join('/')
+    )
+    return {
+      directory,
+      framework: config['framework'],
+      entry,
+      packageSet: {
+        source: { commit: set.manifest.source.commit, tree: set.manifest.source.tree },
+        manifest: await fileDigest(manifestPath),
+      },
+    }
+  }
+  if (!inside(root, directory)) throw new Error('Project must be inside this Bun Native checkout')
+  return { directory, framework: config['framework'], entry }
+}