73 lines
5.1 KiB
Markdown
73 lines
5.1 KiB
Markdown
# /lib/bare (system image)
|
||
|
||
Self-contained **`ctx.bare` support** on the **system** Hyperdrive: Holepunch **Bare** packages bundled as IIFE scripts the booter can execute without a traditional Node module graph on the drive.
|
||
|
||
**Documentation:** [Developer guide ch.12](../../../developer-guide/12-bare-modules-and-pear-ecosystem.md) · [bare-os-bare-libs package README](../../../packages/bare-os-bare-libs/README.md).
|
||
|
||
---
|
||
|
||
## On this page
|
||
|
||
- [What gets staged](#what-gets-staged)
|
||
- [Boot order: drive bundles vs host imports](#boot-order-drive-bundles-vs-host-imports)
|
||
- [Environment toggles](#environment-toggles)
|
||
- [Trust model](#trust-model)
|
||
- [Regenerating bundles](#regenerating-bundles)
|
||
- [When builds fail (stubs)](#when-builds-fail-stubs)
|
||
|
||
---
|
||
|
||
## What gets staged
|
||
|
||
- **`bare-module-manifest.json`** — Copy of the booter manifest (same keys and packages as host resolution). Tells the runtime which logical module names exist.
|
||
- **`manifest.json`** — Drive loader index: **`bundles`** lists IIFE paths that assign into **`globalThis.__bare_os_stdlib__`**; **`bundleStats`** counts attempted bundles; **`bundleDiagnostics`** lists each bundle’s byte size (same data as **`docs/audit/bundle-health.json`**).
|
||
- **`bundles/*.js`** — One esbuild IIFE per catalog entry. The bare-libs build is **fail-fast** (esbuild errors abort; no stub placeholders). The plugin resolves package.json **`#imports`** with host **`platform` / `bare`** conditions (Bluetooth and other conditional packages). Stale `***.js**` left from older tiered builds are **pruned** on each successful build. Regenerate with **`npm run build -w bare-os-bare-libs`** (updates **`docs/audit/bundle-health.json`**).
|
||
|
||
At boot the booter runs **drive bundles first**, then (unless **`BARE_OS_BARE_HOST_IMPORTS=0`**) fills any missing keys via host **`import()`** so development iterations can patch a single package without re-seeding the entire drive.
|
||
|
||
---
|
||
|
||
## Boot order: drive bundles vs host imports
|
||
|
||
1. **Seeded bundles** win for keys they actually populate — they are part of the trusted image, same class as **`/bin`**.
|
||
2. **Host imports** run only for keys still missing after bundle evaluation, keeping local checkout workflows fast.
|
||
3. Disabling host imports (**`BARE_OS_BARE_HOST_IMPORTS=0`**) approximates production Pear behavior where only the drive contents exist.
|
||
|
||
---
|
||
|
||
## Environment toggles
|
||
|
||
The authoritative list is in the [environment appendix](../../../docs/reference/environment-and-posix-appendix.md). Names that operators mention most often alongside **`/lib/bare`**:
|
||
|
||
- **`BARE_OS_BARE_HOST_IMPORTS`** — Set to **`0`** / **`false`** to forbid host `**import()`** fallback (drive-only resolution).
|
||
- Related Pear **`ctx.bare`** toggles and HTTP allow lists are documented in **[PEAR-RUN.md](../../../docs/PEAR-RUN.md)** and the booter package reference.
|
||
|
||
---
|
||
|
||
## Trust model
|
||
|
||
**Trusted image only:** executing these bundles is equivalent to running seeded **`/bin`** utilities. Do not copy arbitrary third-party IIFEs into **`kernel/lib/bare/bundles/`** without reviewing them the same way you would review a new setuid binary on a Unix system.
|
||
|
||
---
|
||
|
||
## Regenerating bundles
|
||
|
||
1. Edit **`packages/bare-os-booter/lib/ctx/bare-module-manifest.json`** or bundle sources under **`packages/bare-os-bare-libs/`** as needed.
|
||
2. Run **`npm run build -w bare-os-bare-libs`** — output lands in **`kernel/lib/bare/`** (and CI expects **`packages/bare-os-seeder/kernel/`** to match **`kernel/`** byte-for-byte afterward).
|
||
3. Mirror **`kernel/`** into **`packages/bare-os-seeder/kernel/`** (same tree) so **`scripts/verify-kernel-seeder-parity.mjs`** passes — typically `rsync -a --delete kernel/ packages/bare-os-seeder/kernel/` from the repo root after init/bundle changes.
|
||
4. Re-run the seeder so peers replicate the updated system drive.
|
||
|
||
**Order with coreutils:** from repo root, prefer **`npm run build -w bare-os-coreutils && npm run build -w bare-os-bare-libs && npm run bundle:kernel`** before parity check (matches root **`pretest`**).
|
||
|
||
---
|
||
|
||
## When builds fail
|
||
|
||
Esbuild prints the failing **`ctxKey`** and package. Fix **`bare-module-manifest.json`**, adjust **`build.mjs`** (plugins, platform), or mark the entry **`optional`** / **`bundle: false`** when host-only resolution is intended. **`npm run smoke:bare-manifest`** guards required imports listed in the manifest smoke list.
|
||
|
||
**CI:** **`scripts/verify-bundle-health.mjs`** checks **`docs/audit/bundle-health.json`** against on-disk sizes; **`scripts/verify-bundle-markers.mjs`** and **`scripts/verify-bundle-throws.mjs`** gate incomplete-looking substrings / **`Error`** messages. **`scripts/sanitize-bare-bundles.mjs`** (run from this build) normalizes known upstream HTTP helpers, stream-base-class messages, and ICO encode paths so **`docs/audit/bundle-marker-allowlist.json`** and **`docs/audit/bundle-throw-allowlist.json`** stay **empty**.
|
||
|
||
---
|
||
|
||
_Note:_ This file is copied to **`kernel/lib/bare/README.md`** (and the vendored seeder tree) by **`bare-os-bare-libs`** build. Links are written for the **`kernel/lib/bare/`** path; **`verify-doc-links`** skips this template path because its on-disk location differs.
|