@bun-native/cli 0.0.0-stage → 0.33.1

package/src/scripts/native/session.ts

@@ -0,0 +1,299 @@
+import { mkdtempSync } from 'node:fs'
+import { mkdtemp, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { bundleProject } from './build.ts'
+import { readProject } from './project.ts'
+
+const diagnosticKeys = [
+  'windows',
+  'nodes',
+  'callbacks',
+  'queuedTransactions',
+  'queuedCallbacks',
+  'activeCallbacks',
+  'serviceRequests',
+] as const
+
+function record(value: unknown): Record<string, unknown> | undefined {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : undefined
+}
+
+type StoppedResources = {
+  application: Record<(typeof diagnosticKeys)[number], 0>
+  nodes: 0
+}
+
+export type TeardownReport = StoppedResources & { pid: number; clean: true }
+
+function cleanStop(value: Record<string, unknown>): StoppedResources | undefined {
+  const application = record(value['application'])
+  if (
+    value['nodes'] !== 0 ||
+    application === undefined ||
+    !diagnosticKeys.every((key) => application[key] === 0)
+  )
+    return undefined
+  return {
+    // Copy only the counters validated above; retain no arbitrary child payload.
+    application: Object.fromEntries(
+      diagnosticKeys.map((key) => [key, application[key]])
+    ) as StoppedResources['application'],
+    nodes: 0,
+  }
+}
+
+async function bounded<T>(value: Promise<T>, milliseconds: number, message: string): Promise<T> {
+  let timer: ReturnType<typeof setTimeout> | undefined
+  try {
+    return await Promise.race([
+      value,
+      new Promise<never>((_, reject) => {
+        timer = setTimeout(() => reject(new Error(message)), milliseconds)
+      }),
+    ])
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
+type OwnedProcess = {
+  child: Bun.Subprocess<'ignore', 'inherit', 'inherit'>
+  directory: string
+  ready: Promise<void>
+  exited: Promise<number>
+  disconnected: Promise<void>
+  terminated: boolean
+  mounted: boolean
+  stopping: boolean
+  resources: StoppedResources | undefined
+}
+
+export type RemountReport = {
+  generation: number
+  pid: number
+  bundle: string
+  bundleMs: number
+  shutdownMs: number
+  mountMs: number
+  editToReadyMs: number
+  previous?: TeardownReport
+}
+
+/** One app process at a time; its native host belongs to that app's public core. */
+export class DevSession {
+  private current: OwnedProcess | undefined
+  private active: Promise<RemountReport> | undefined
+  private closing: Promise<TeardownReport | undefined> | undefined
+  private stopped = false
+  private generation = 0
+  private readonly completion = Promise.withResolvers<number>()
+  readonly exited = this.completion.promise
+  readonly temporaryDirectory: string
+
+  constructor(
+    private readonly repository: string,
+    private readonly projectDirectory: string,
+    private readonly host: string,
+    private readonly timeoutMs = 5_000
+  ) {
+    if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 60_000)
+      throw new Error('Dev session timeout must be between 1 and 60000 milliseconds')
+    this.temporaryDirectory = mkdtempSync(join(tmpdir(), 'bun-native-dev-'))
+  }
+
+  reload(changedAt = performance.now()): Promise<RemountReport> {
+    if (this.stopped) return Promise.reject(new Error('Development session is closed'))
+    if (this.active) return Promise.reject(new Error('A reload is already running'))
+    this.active = this.replace(changedAt).finally(() => {
+      this.active = undefined
+    })
+    return this.active
+  }
+
+  close(): Promise<TeardownReport | undefined> {
+    this.stopped = true
+    return (this.closing ??= (async () => {
+      try {
+        await this.active?.catch(() => {})
+        const previous = this.current
+        this.current = undefined
+        let teardown: TeardownReport | undefined
+        if (previous) {
+          try {
+            teardown = await this.stop(previous)
+          } finally {
+            if (!previous.terminated) this.current = previous
+          }
+        }
+        this.completion.resolve(0)
+        return teardown
+      } finally {
+        // A failed app can already be reaped while its teardown error must still
+        // propagate. Remove only this session's root once no process owns it.
+        if (!this.current) await rm(this.temporaryDirectory, { recursive: true, force: true })
+      }
+    })())
+  }
+
+  private launch(entry: string, directory: string): OwnedProcess {
+    const ready = Promise.withResolvers<void>()
+    const disconnected = Promise.withResolvers<void>()
+    // A synchronous spawn failure or immediate exit must never orphan a rejection.
+    void ready.promise.catch(() => {})
+    let owner: OwnedProcess | undefined
+    const child = Bun.spawn([process.execPath, entry], {
+      cwd: this.projectDirectory,
+      env: { ...process.env, BUN_NATIVE_HOST: this.host },
+      stdin: 'ignore',
+      stdout: 'inherit',
+      stderr: 'inherit',
+      ipc(message: unknown) {
+        const value = record(message)
+        if (value?.['type'] === 'bun-native:ready' && owner && !owner.stopping) {
+          owner.mounted = true
+          ready.resolve()
+        } else if (value?.['type'] === 'bun-native:stopped' && owner) {
+          owner.resources = cleanStop(value)
+        }
+      },
+      onDisconnect: () => {
+        disconnected.resolve()
+      },
+      onExit: async (_child, code, signal) => {
+        ready.reject(new Error(`Application exited before readiness (${code ?? signal})`))
+        // Exit notification can precede the final IPC message on a different pipe.
+        await disconnected.promise
+        if (owner?.mounted && !owner.stopping) {
+          this.stopped = true
+          this.completion.resolve(code === 0 && owner.resources ? 0 : 1)
+        }
+      },
+    })
+    const exited = child.exited.then((code) => {
+      if (owner) owner.terminated = true
+      return code
+    })
+    owner = {
+      child,
+      directory,
+      ready: ready.promise,
+      exited,
+      disconnected: disconnected.promise,
+      terminated: false,
+      mounted: false,
+      stopping: false,
+      resources: undefined,
+    }
+    return owner
+  }
+
+  private async stop(owner: OwnedProcess): Promise<TeardownReport> {
+    owner.stopping = true
+    try {
+      if (!owner.terminated && !owner.resources) {
+        // The child may be closing normally while this request is in flight.
+        // Always join exit and validate its final acknowledgement below.
+        try {
+          owner.child.send({ type: 'bun-native:stop' })
+        } catch {
+          /* joined below */
+        }
+      }
+      const [code] = await bounded(
+        Promise.all([owner.exited, owner.disconnected]),
+        this.timeoutMs,
+        'Application did not acknowledge shutdown in time'
+      )
+      if (code !== 0 || !owner.resources)
+        throw new Error(
+          `Application did not report clean teardown (exit ${code}); preserve the template dev-control hooks`
+        )
+      return { pid: owner.child.pid, clean: true, ...owner.resources }
+    } catch (error) {
+      if (!owner.terminated) {
+        owner.child.kill('SIGKILL')
+        await bounded(
+          Promise.all([owner.exited, owner.disconnected]),
+          this.timeoutMs,
+          'Application did not exit after termination'
+        )
+      }
+      throw error
+    } finally {
+      if (owner.terminated) {
+        await rm(owner.directory, { recursive: true, force: true })
+      }
+    }
+  }
+
+  private async replace(changedAt: number): Promise<RemountReport> {
+    // 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()
+    try {
+      // Compile before touching the live app, so an incomplete edit preserves it.
+      const entry = await bundleProject(project, directory)
+      const bundled = performance.now()
+      if (this.stopped) throw new Error('Development session is closed')
+      const previous = this.current
+      this.current = undefined
+      let teardown: TeardownReport | undefined
+      if (previous) {
+        try {
+          teardown = await this.stop(previous)
+        } catch (error) {
+          if (!previous.terminated) this.current = previous
+          this.stopped = true
+          this.completion.resolve(1)
+          throw error
+        }
+      }
+      const joined = performance.now()
+      if (this.stopped) throw new Error('Development session is closed')
+      owner = this.launch(entry, directory)
+      this.current = owner
+      await bounded(
+        owner.ready,
+        this.timeoutMs,
+        'Application readiness timed out; preserve the template dev-control hooks'
+      )
+      const ready = performance.now()
+      return {
+        generation: ++this.generation,
+        pid: owner.child.pid,
+        bundle: entry,
+        bundleMs: bundled - start,
+        shutdownMs: joined - bundled,
+        mountMs: ready - joined,
+        editToReadyMs: ready - changedAt,
+        ...(teardown ? { previous: teardown } : {}),
+      }
+    } catch (error) {
+      if (owner) {
+        this.stopped = true
+        this.completion.resolve(1)
+        try {
+          await this.stop(owner)
+        } catch (cleanupError) {
+          throw new AggregateError(
+            [error, cleanupError],
+            'Application startup failed and the session was stopped'
+          )
+        } finally {
+          if (owner.terminated) this.current = undefined
+        }
+      }
+      throw error
+    } finally {
+      if (!owner || (owner.terminated && owner !== this.current))
+        await rm(directory, { recursive: true, force: true })
+    }
+  }
+}

package/src/scripts/native/standalone.ts

@@ -0,0 +1,64 @@
+import { constants } from 'node:fs'
+import { copyFile, mkdir, writeFile } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+import { consumerScripts, consumerTsconfig, json } from './consumer-files.ts'
+import { seedConsumerLock } from './package-lock.ts'
+import { consumerArchiveLock, readPackageSet, type ReadPackageSet } from './package-set.ts'
+
+const packageSetPath = 'vendor/bun-native/manifest.json'
+
+export function standaloneFiles(
+  set: ReadPackageSet,
+  framework: 'solid' | 'react',
+  entry: string,
+  name: string
+): Record<string, string> {
+  const consumer = set.manifest.consumers[framework]
+  const localLock = consumerArchiveLock(set.manifest, framework)
+  const { overrides } = localLock
+  const local = (dependencies: Record<string, string>) =>
+    Object.fromEntries(
+      Object.entries(dependencies).map(([name, version]) => [name, overrides[name] ?? version])
+    )
+  const dependencies = local(consumer.dependencies)
+  const devDependencies = local(consumer.devDependencies)
+  return {
+    'bun-native.json': json({ schemaVersion: 1, framework, entry, packageSet: packageSetPath }),
+    'package.json': json({
+      name,
+      private: true,
+      type: 'module',
+      packageManager: `bun@${set.manifest.toolchain.bun.version}`,
+      engines: { bun: set.manifest.toolchain.bun.version },
+      scripts: consumerScripts(),
+      dependencies,
+      devDependencies,
+      overrides,
+    }),
+    'bun.lock': json(
+      seedConsumerLock(consumer.lock, { name, dependencies, devDependencies }, localLock)
+    ),
+    '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`,
+  }
+}
+
+/** Called only after the caller exclusively creates and owns the destination. */
+export async function copyPackageSet(set: ReadPackageSet, directory: string): Promise<void> {
+  const destination = join(directory, dirname(packageSetPath))
+  await mkdir(destination, { recursive: true })
+  for (const pkg of Object.values(set.manifest.packages)) {
+    const path = join(destination, pkg.archive.file)
+    await mkdir(dirname(path), { recursive: true })
+    await copyFile(join(set.directory, pkg.archive.file), path, constants.COPYFILE_EXCL)
+  }
+  await writeFile(join(directory, packageSetPath), set.text, { flag: 'wx' })
+  // Re-hash the owned copies to catch a changed input between validation and copy.
+  await readPackageSet(join(directory, packageSetPath))
+}

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)
+}

package/src/scripts/native/watch.ts

@@ -0,0 +1,104 @@
+import { watch } from 'node:fs'
+import type { FSWatcher } from 'node:fs'
+import { projectFingerprint, rescanInput } from './inputs.ts'
+import { DevSession, type RemountReport } from './session.ts'
+
+function report(value: RemountReport): void {
+  console.log('bun-native:ready ' + JSON.stringify(value))
+}
+
+export async function watchProject(
+  repository: string,
+  directory: string,
+  host: string
+): Promise<void> {
+  const session = new DevSession(repository, directory, host)
+  const stopped = Promise.withResolvers<void>()
+  const failed = Promise.withResolvers<Error>()
+  const scanController = new AbortController()
+  let watcher: FSWatcher | undefined
+  let timer: ReturnType<typeof setTimeout> | undefined
+  let pending: number | undefined
+  let snapshot = ''
+  let scanning: Promise<string> | undefined
+  let running = true
+  let closing = false
+  const stop = () => {
+    closing = true
+    scanController.abort()
+    stopped.resolve()
+    // close() marks cancellation synchronously before joining any active build.
+    // Its rejection is also observed by the final cleanup below.
+    void session.close().catch(() => {})
+  }
+
+  const pump = async () => {
+    timer = undefined
+    if (running || closing || pending === undefined) return
+    const changedAt = pending
+    pending = undefined
+    running = true
+    try {
+      scanning = projectFingerprint(directory, scanController.signal)
+      const next = await scanning
+      scanning = undefined
+      if (closing || next === snapshot) return
+      // Record the attempted bytes before compiling. A rejected edit stays live
+      // without a retry loop, and edits during the build remain pending.
+      snapshot = next
+      report(await session.reload(changedAt))
+    } catch (error) {
+      if (!closing) {
+        console.error(error instanceof Error ? error.message : String(error))
+        if (error instanceof AggregateError)
+          for (const detail of error.errors) console.error(detail)
+      }
+    } finally {
+      scanning = undefined
+      running = false
+      if (!closing && pending !== undefined && timer === undefined) timer = setTimeout(pump, 50)
+    }
+  }
+
+  process.once('SIGINT', stop)
+  process.once('SIGTERM', stop)
+  try {
+    watcher = watch(directory, { recursive: true }, (_event, filename) => {
+      if (closing || !rescanInput(filename)) return
+      pending = performance.now()
+      clearTimeout(timer)
+      timer = setTimeout(pump, 50)
+    })
+    // Store watcher failure as a value so an error during the initial build is
+    // observed after it settles, without a detached rejected promise.
+    watcher.on('error', failed.resolve)
+    try {
+      // Observe first, then snapshot: events during initial scanning/building are
+      // coalesced and checked against these bytes after the initial mount.
+      snapshot = await projectFingerprint(directory, scanController.signal)
+      report(await session.reload())
+    } catch (error) {
+      if (closing) return
+      throw error
+    }
+    running = false
+    if (pending !== undefined && timer === undefined) timer = setTimeout(pump, 50)
+    console.log(
+      'Watching project source. Each successful edit remounts the application and resets state.'
+    )
+    const exit = await Promise.race([session.exited, stopped.promise, failed.promise])
+    if (exit instanceof Error) throw exit
+    if (exit !== undefined && exit !== 0)
+      throw new Error('Application exited without clean teardown')
+  } finally {
+    closing = true
+    scanController.abort()
+    clearTimeout(timer)
+    watcher?.close()
+    process.off('SIGINT', stop)
+    process.off('SIGTERM', stop)
+    await scanning?.catch(() => {})
+    const teardown = await session.close()
+    if (teardown) console.log('bun-native:stopped ' + JSON.stringify(teardown))
+  }
+}