43 lines
4.3 KiB
Markdown
43 lines
4.3 KiB
Markdown
# bare-os-bare-libs
|
||
|
||
Builds trusted IIFE bundles from [`bare-module-manifest.json`](../bare-os-booter/lib/bare-module-manifest.json) entries marked `"bundle": true`. **`npm run build`** runs **`prebuild`**: **`../../scripts/generate-bare-module-manifest-data.mjs`**, which refreshes **[`bare-module-manifest.data.mjs`](../bare-os-booter/lib/bare-module-manifest.data.mjs)** for Pear before esbuild. Output:
|
||
|
||
- `kernel/lib/bare/bundles/<ctxKey>.js`
|
||
- `kernel/lib/bare/manifest.json` (paths for the booter drive merge)
|
||
- Mirrored under `packages/bare-os-seeder/kernel/lib/bare/` for seeder parity
|
||
|
||
**When to use:** run this build after changing **`bare-module-manifest.json`**, bumping Holepunch catalog entries, or refreshing upstream **`bare-*`** packages — **`pretest`** expects **`kernel/lib/bare/bundles`** and **`bundle-health.json`** to match.
|
||
|
||
**Documentation:** [Developer guide ch.12 — Bare modules](../../developer-guide/12-bare-modules-and-pear-ecosystem.md) · [Kernel extensions](../../docs/reference/kernel-extensions.md) · [Kernel tree — `lib/bare`](../../kernel/README.md).
|
||
|
||
Run from repo root:
|
||
|
||
```bash
|
||
npm run build -w bare-os-bare-libs
|
||
```
|
||
|
||
**Catalog bump pipeline (maintainers):** refresh Holepunch package metadata with **`npm run gen:bare-catalog`** at the repo root (updates **`docs/bare-holepunch-catalog.json`**), then rebuild this workspace, run **`npm test`** ( **`verify-bundle-health`**, **`verify-bundle-markers`**, **`verify-bundle-throws`**), and sync **`kernel/lib/bare/`** → seeder per **`verify-kernel-seeder-parity`**. Intentional large bundle size shifts should add a row under **Bundle health log** below.
|
||
|
||
The booter loads these only when `BARE_OS_BARE_MODULES` is enabled and `BARE_OS_BARE_DRIVE_BUNDLES` is not disabled; see the developer guide.
|
||
|
||
Manifest rows may include optional **`tier`** (**`core`** default when omitted) and **`risk`** (**`low`** / **`medium`** / **`high`**) so distributors can filter bundles without reading upstream READMEs. The catalog sync scripts preserve unknown fields when merging from **`docs/bare-holepunch-catalog.json`**.
|
||
|
||
## Bundle health, markers, and upstream closure
|
||
|
||
- **`docs/audit/bundle-health.json`** — per-bundle byte sizes; regenerated by **`npm run build -w bare-os-bare-libs`**. When a bundle’s size moves by more than roughly **10%**, add a dated one-line note under **Bundle health log** below (or in the same PR description) so reviewers can tell intentional catalog bumps from accidents.
|
||
- **`scripts/verify-bundle-health.mjs`** — CI compares committed JSON to on-disk bundle sizes.
|
||
- **`scripts/verify-bundle-markers.mjs`** + **`docs/audit/bundle-marker-allowlist.json`** — gate `**TODO` / `NOT_IMPLEMENTED`** substrings inside vendored IIFEs; shrink the allowlist when upgrading Holepunch packages removes markers.
|
||
- **`scripts/verify-bundle-throws.mjs`** + **`docs/audit/bundle-throw-allowlist.json`** — same for `**throw new Error("not implemented")`** phrasing.
|
||
|
||
**Scope split:** **`verify-runtime-no-incomplete-markers.mjs`** applies to **first-party** kernel/boot/booter sources; **`verify-bundle-markers.mjs`** / **`verify-bundle-throws.mjs`** apply **only** to `**kernel/lib/bare/bundles/*.js`**. Upstream HTTP helpers may still expose **501 Not Implemented** behavior under sanitized method names—that is not the same as an unfinished Bare OS syscall surface (those use documented **`ENOTSUP`** in the booter).
|
||
|
||
See **[`docs/audit/PLACEHOLDER_BASELINE.md`](../../docs/audit/PLACEHOLDER_BASELINE.md)** § P3 for policy: first-party kernel code stays marker-free via **`verify-runtime-no-incomplete-markers.mjs`**; bundle gaps close through **version bumps**, **post-processing** (rare), or **allowlist shrink**. Full table: [developer-guide ch.8 — CI marker scope](../../developer-guide/08-testing-and-debugging.md#ci-marker-scope-first-party-vs-vendored-bundles).
|
||
|
||
### Bundle health log
|
||
|
||
| Date (UTC) | Note |
|
||
|------------|------|
|
||
| 2026-08-13 | Catalog + Holepunch pin bump (compact-encoding 3, fetch/tls/https/ws 3, subprocess 6, new optional `bare-*` rows). Build plugin now resolves package.json `#imports` with host platform conditions. Intentional size churn across `kernel/lib/bare/bundles/`. |
|
||
| _Append a row when a bundle size change ≥ ~10% is intentional (catalog version, esbuild flags, or new upstream files)._ | |
|
||
|