snxraven/bare-operating-system
1
1
Fork 1
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

update docs

Browse Source
This commit is contained in:
Raven Scott
2026-04-04 08:40:17 -04:00
parent 081e4c587c
commit 0cff2069b7
18 changed files with 888 additions and 468 deletions
Download Patch File Download Diff File Expand all files Collapse all files
kernel/lib/bare/README.md
+61 -7
View File
@@ -1,13 +1,67 @@
# /lib/bare (system image)
Self-contained **`ctx.bare` support** on the system Hyperdrive:
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 README](./README.md).
**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).
- **`bare-module-manifest.json`** — copy of the booter manifest (same keys and packages as host resolution).
- **`manifest.json`** — drive loader index: `bundles` lists IIFE paths that assign into `globalThis.__bare_os_stdlib__`; `bundleStats` summarizes esbuild success vs stub-only placeholders.
- **`bundles/*.js`** — one file per manifest row. Successful builds are full IIFE bundles; failures are no-op stubs (see file header). Regenerate with `npm run build -w bare-os-bare-libs`.
---
At boot the booter runs **drive bundles first**, then (unless **`BARE_OS_BARE_HOST_IMPORTS=0`**) fills any missing keys via host `import()`.
## On this page
Trusted image only: executing these bundles is equivalent to running seeded `/bin` utilities.
- [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`** summarizes esbuild success versus stub-only placeholders (per-entry success/failure counts and paths).
- **`bundles/*.js`** — One file per manifest row. Successful builds are full IIFE bundles; failures are no-op stubs (see the file header comment). Regenerate with **`npm run build -w bare-os-bare-libs`**.
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](../../../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/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. Re-run the seeder so peers replicate the updated system drive.
---
## When builds fail (stubs)
If **`bundleStats`** shows failures, open the corresponding **`bundles/*.js`** stub: the header usually names the missing dependency or unsupported pattern. Fix the catalog entry, adjust esbuild options in **`packages/bare-os-bare-libs/build.mjs`**, or mark the module optional in the manifest until the ecosystem catches up. **`npm run smoke:bare-manifest`** guards required imports listed in the manifest smoke list.
---
_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.
kernel/lib/bare/manifest.json
+214 -214
View File
@@ -1,12 +1,6 @@
{
"version": 1,
"bundles": [
{
"path": "/lib/bare/bundles/hypercoreIdEncoding.js",
"keys": [
"hypercoreIdEncoding"
]
},
{
"path": "/lib/bare/bundles/safetyCatch.js",
"keys": [
@@ -20,9 +14,9 @@
]
},
{
"path": "/lib/bare/bundles/compactEncoding.js",
"path": "/lib/bare/bundles/hypercoreIdEncoding.js",
"keys": [
"compactEncoding"
"hypercoreIdEncoding"
]
},
{
@@ -32,15 +26,15 @@
]
},
{
"path": "/lib/bare/bundles/protomux.js",
"path": "/lib/bare/bundles/compactEncoding.js",
"keys": [
"protomux"
"compactEncoding"
]
},
{
"path": "/lib/bare/bundles/bareEvents.js",
"path": "/lib/bare/bundles/protomux.js",
"keys": [
"bareEvents"
"protomux"
]
},
{
@@ -55,6 +49,12 @@
"barePath"
]
},
{
"path": "/lib/bare/bundles/bareEvents.js",
"keys": [
"bareEvents"
]
},
{
"path": "/lib/bare/bundles/bareAbort.js",
"keys": [
@@ -67,6 +67,12 @@
"bareAbortController"
]
},
{
"path": "/lib/bare/bundles/bareReadline.js",
"keys": [
"bareReadline"
]
},
{
"path": "/lib/bare/bundles/bareAddonResolve.js",
"keys": [
@@ -79,18 +85,24 @@
"bareAnsiEscapes"
]
},
{
"path": "/lib/bare/bundles/bareReadline.js",
"keys": [
"bareReadline"
]
},
{
"path": "/lib/bare/bundles/bareCrypto.js",
"keys": [
"bareCrypto"
]
},
{
"path": "/lib/bare/bundles/fetch.js",
"keys": [
"fetch"
]
},
{
"path": "/lib/bare/bundles/bareAsyncHooks.js",
"keys": [
"bareAsyncHooks"
]
},
{
"path": "/lib/bare/bundles/bareAppKit.js",
"keys": [
@@ -98,9 +110,9 @@
]
},
{
"path": "/lib/bare/bundles/bareAsyncHooks.js",
"path": "/lib/bare/bundles/bareAtomics.js",
"keys": [
"bareAsyncHooks"
"bareAtomics"
]
},
{
@@ -115,18 +127,6 @@
"bareAssert"
]
},
{
"path": "/lib/bare/bundles/fetch.js",
"keys": [
"fetch"
]
},
{
"path": "/lib/bare/bundles/bareAtomics.js",
"keys": [
"bareAtomics"
]
},
{
"path": "/lib/bare/bundles/bareBmp.js",
"keys": [
@@ -139,6 +139,12 @@
"bareBundleCompile"
]
},
{
"path": "/lib/bare/bundles/bareBluetoothApple.js",
"keys": [
"bareBluetoothApple"
]
},
{
"path": "/lib/bare/bundles/bareBundle.js",
"keys": [
@@ -151,36 +157,36 @@
"bareBuffer"
]
},
{
"path": "/lib/bare/bundles/bareBluetoothApple.js",
"keys": [
"bareBluetoothApple"
]
},
{
"path": "/lib/bare/bundles/bareBundleEvaluate.js",
"keys": [
"bareBundleEvaluate"
]
},
{
"path": "/lib/bare/bundles/bareConsole.js",
"keys": [
"bareConsole"
]
},
{
"path": "/lib/bare/bundles/bareBoot.js",
"keys": [
"bareBoot"
]
},
{
"path": "/lib/bare/bundles/bareConsole.js",
"keys": [
"bareConsole"
]
},
{
"path": "/lib/bare/bundles/bareBundleId.js",
"keys": [
"bareBundleId"
]
},
{
"path": "/lib/bare/bundles/bareDelta.js",
"keys": [
"bareDelta"
]
},
{
"path": "/lib/bare/bundles/bareDebugLog.js",
"keys": [
@@ -193,18 +199,18 @@
"bareChannel"
]
},
{
"path": "/lib/bare/bundles/bareDelta.js",
"keys": [
"bareDelta"
]
},
{
"path": "/lib/bare/bundles/bareDaemon.js",
"keys": [
"bareDaemon"
]
},
{
"path": "/lib/bare/bundles/bareCov.js",
"keys": [
"bareCov"
]
},
{
"path": "/lib/bare/bundles/bareDiagnosticsChannel.js",
"keys": [
@@ -229,24 +235,18 @@
"bareExif"
]
},
{
"path": "/lib/bare/bundles/bareDgram.js",
"keys": [
"bareDgram"
]
},
{
"path": "/lib/bare/bundles/bareCov.js",
"keys": [
"bareCov"
]
},
{
"path": "/lib/bare/bundles/bareFfmpegEncodings.js",
"keys": [
"bareFfmpegEncodings"
]
},
{
"path": "/lib/bare/bundles/bareDgram.js",
"keys": [
"bareDgram"
]
},
{
"path": "/lib/bare/bundles/bareFfmpeg.js",
"keys": [
@@ -259,24 +259,18 @@
"bareGif"
]
},
{
"path": "/lib/bare/bundles/bareFormData.js",
"keys": [
"bareFormData"
]
},
{
"path": "/lib/bare/bundles/bareFileLogger.js",
"keys": [
"bareFileLogger"
]
},
{
"path": "/lib/bare/bundles/bareFormat.js",
"keys": [
"bareFormat"
]
},
{
"path": "/lib/bare/bundles/bareFormData.js",
"keys": [
"bareFormData"
]
},
{
"path": "/lib/bare/bundles/bareHeif.js",
"keys": [
@@ -289,12 +283,24 @@
"bareGtk"
]
},
{
"path": "/lib/bare/bundles/bareFileLogger.js",
"keys": [
"bareFileLogger"
]
},
{
"path": "/lib/bare/bundles/bareHrtime.js",
"keys": [
"bareHrtime"
]
},
{
"path": "/lib/bare/bundles/bareFs.js",
"keys": [
"bareFs"
]
},
{
"path": "/lib/bare/bundles/bareHttpParser.js",
"keys": [
@@ -314,9 +320,9 @@
]
},
{
"path": "/lib/bare/bundles/bareFs.js",
"path": "/lib/bare/bundles/bareInspect.js",
"keys": [
"bareFs"
"bareInspect"
]
},
{
@@ -325,54 +331,54 @@
"bareHttp1"
]
},
{
"path": "/lib/bare/bundles/bareInspect.js",
"keys": [
"bareInspect"
]
},
{
"path": "/lib/bare/bundles/bareHttps.js",
"keys": [
"bareHttps"
]
},
{
"path": "/lib/bare/bundles/bareIntl.js",
"keys": [
"bareIntl"
]
},
{
"path": "/lib/bare/bundles/bareJpeg.js",
"keys": [
"bareJpeg"
]
},
{
"path": "/lib/bare/bundles/bareLief.js",
"keys": [
"bareLief"
]
},
{
"path": "/lib/bare/bundles/bareInspector.js",
"keys": [
"bareInspector"
]
},
{
"path": "/lib/bare/bundles/bareIpc.js",
"keys": [
"bareIpc"
]
},
{
"path": "/lib/bare/bundles/bareJpeg.js",
"keys": [
"bareJpeg"
]
},
{
"path": "/lib/bare/bundles/bareIntl.js",
"keys": [
"bareIntl"
]
},
{
"path": "/lib/bare/bundles/bareMake.js",
"keys": [
"bareMake"
]
},
{
"path": "/lib/bare/bundles/bareLief.js",
"keys": [
"bareLief"
]
},
{
"path": "/lib/bare/bundles/bareLogger.js",
"keys": [
"bareLogger"
]
},
{
"path": "/lib/bare/bundles/bareInspector.js",
"keys": [
"bareInspector"
]
},
{
"path": "/lib/bare/bundles/bareLink.js",
"keys": [
@@ -380,9 +386,15 @@
]
},
{
"path": "/lib/bare/bundles/bareMake.js",
"path": "/lib/bare/bundles/bareDev.js",
"keys": [
"bareMake"
"bareDev"
]
},
{
"path": "/lib/bare/bundles/bareModuleResolve.js",
"keys": [
"bareModuleResolve"
]
},
{
@@ -397,18 +409,6 @@
"bareModule"
]
},
{
"path": "/lib/bare/bundles/bareModuleResolve.js",
"keys": [
"bareModuleResolve"
]
},
{
"path": "/lib/bare/bundles/bareNdk.js",
"keys": [
"bareNdk"
]
},
{
"path": "/lib/bare/bundles/bareModuleTraverse.js",
"keys": [
@@ -422,9 +422,9 @@
]
},
{
"path": "/lib/bare/bundles/bareMedia.js",
"path": "/lib/bare/bundles/bareNdk.js",
"keys": [
"bareMedia"
"bareNdk"
]
},
{
@@ -433,12 +433,6 @@
"bareNodeFetch"
]
},
{
"path": "/lib/bare/bundles/bareNet.js",
"keys": [
"bareNet"
]
},
{
"path": "/lib/bare/bundles/bareOpen.js",
"keys": [
@@ -452,15 +446,15 @@
]
},
{
"path": "/lib/bare/bundles/bareDev.js",
"path": "/lib/bare/bundles/bareNet.js",
"keys": [
"bareDev"
"bareNet"
]
},
{
"path": "/lib/bare/bundles/barePerformance.js",
"path": "/lib/bare/bundles/bareMedia.js",
"keys": [
"barePerformance"
"bareMedia"
]
},
{
@@ -469,12 +463,30 @@
"barePng"
]
},
{
"path": "/lib/bare/bundles/barePerformance.js",
"keys": [
"barePerformance"
]
},
{
"path": "/lib/bare/bundles/barePack.js",
"keys": [
"barePack"
]
},
{
"path": "/lib/bare/bundles/barePackDrive.js",
"keys": [
"barePackDrive"
]
},
{
"path": "/lib/bare/bundles/barePunycode.js",
"keys": [
"barePunycode"
]
},
{
"path": "/lib/bare/bundles/barePipe.js",
"keys": [
@@ -488,15 +500,9 @@
]
},
{
"path": "/lib/bare/bundles/barePack.js",
"path": "/lib/bare/bundles/bareNodeRuntime.js",
"keys": [
"barePack"
]
},
{
"path": "/lib/bare/bundles/barePunycode.js",
"keys": [
"barePunycode"
"bareNodeRuntime"
]
},
{
@@ -505,18 +511,6 @@
"bareQuerystring"
]
},
{
"path": "/lib/bare/bundles/bareProcess.js",
"keys": [
"bareProcess"
]
},
{
"path": "/lib/bare/bundles/bareNodeRuntime.js",
"keys": [
"bareNodeRuntime"
]
},
{
"path": "/lib/bare/bundles/bareQueueMicrotask.js",
"keys": [
@@ -529,6 +523,12 @@
"bareRealm"
]
},
{
"path": "/lib/bare/bundles/bareProcess.js",
"keys": [
"bareProcess"
]
},
{
"path": "/lib/bare/bundles/barePromClient.js",
"keys": [
@@ -542,21 +542,9 @@
]
},
{
"path": "/lib/bare/bundles/bareRpc.js",
"path": "/lib/bare/bundles/bareSdl.js",
"keys": [
"bareRpc"
]
},
{
"path": "/lib/bare/bundles/bareRun.js",
"keys": [
"bareRun"
]
},
{
"path": "/lib/bare/bundles/bareRepl.js",
"keys": [
"bareRepl"
"bareSdl"
]
},
{
@@ -566,9 +554,9 @@
]
},
{
"path": "/lib/bare/bundles/bareSdl.js",
"path": "/lib/bare/bundles/bareRpc.js",
"keys": [
"bareSdl"
"bareRpc"
]
},
{
@@ -584,21 +572,15 @@
]
},
{
"path": "/lib/bare/bundles/bareStringDecoder.js",
"path": "/lib/bare/bundles/bareRun.js",
"keys": [
"bareStringDecoder"
"bareRun"
]
},
{
"path": "/lib/bare/bundles/bareStorage.js",
"path": "/lib/bare/bundles/bareRepl.js",
"keys": [
"bareStorage"
]
},
{
"path": "/lib/bare/bundles/bareStream.js",
"keys": [
"bareStream"
"bareRepl"
]
},
{
@@ -607,6 +589,18 @@
"bareStdio"
]
},
{
"path": "/lib/bare/bundles/bareStorage.js",
"keys": [
"bareStorage"
]
},
{
"path": "/lib/bare/bundles/bareStringDecoder.js",
"keys": [
"bareStringDecoder"
]
},
{
"path": "/lib/bare/bundles/bareSvg.js",
"keys": [
@@ -614,15 +608,9 @@
]
},
{
"path": "/lib/bare/bundles/bareStructuredClone.js",
"path": "/lib/bare/bundles/bareStream.js",
"keys": [
"bareStructuredClone"
]
},
{
"path": "/lib/bare/bundles/bareTap.js",
"keys": [
"bareTap"
"bareStream"
]
},
{
@@ -632,9 +620,9 @@
]
},
{
"path": "/lib/bare/bundles/bareSubprocess.js",
"path": "/lib/bare/bundles/bareStructuredClone.js",
"keys": [
"bareSubprocess"
"bareStructuredClone"
]
},
{
@@ -643,6 +631,18 @@
"bareTiff"
]
},
{
"path": "/lib/bare/bundles/bareSubprocess.js",
"keys": [
"bareSubprocess"
]
},
{
"path": "/lib/bare/bundles/bareTap.js",
"keys": [
"bareTap"
]
},
{
"path": "/lib/bare/bundles/bareTimers.js",
"keys": [
@@ -674,9 +674,9 @@
]
},
{
"path": "/lib/bare/bundles/bareTls.js",
"path": "/lib/bare/bundles/bareTty.js",
"keys": [
"bareTls"
"bareTty"
]
},
{
@@ -686,9 +686,15 @@
]
},
{
"path": "/lib/bare/bundles/bareTty.js",
"path": "/lib/bare/bundles/bareUnpack.js",
"keys": [
"bareTty"
"bareUnpack"
]
},
{
"path": "/lib/bare/bundles/bareTls.js",
"keys": [
"bareTls"
]
},
{
@@ -697,12 +703,6 @@
"bareV8"
]
},
{
"path": "/lib/bare/bundles/bareUnpack.js",
"keys": [
"bareUnpack"
]
},
{
"path": "/lib/bare/bundles/bareVm.js",
"keys": [
@@ -710,9 +710,9 @@
]
},
{
"path": "/lib/bare/bundles/bareWalkHandles.js",
"path": "/lib/bare/bundles/bareWebKit.js",
"keys": [
"bareWalkHandles"
"bareWebKit"
]
},
{
@@ -722,9 +722,9 @@
]
},
{
"path": "/lib/bare/bundles/bareWebKit.js",
"path": "/lib/bare/bundles/bareWalkHandles.js",
"keys": [
"bareWebKit"
"bareWalkHandles"
]
},
{
@@ -745,6 +745,12 @@
"bareWhich"
]
},
{
"path": "/lib/bare/bundles/bareWinUi.js",
"keys": [
"bareWinUi"
]
},
{
"path": "/lib/bare/bundles/bareUtils.js",
"keys": [
@@ -757,12 +763,6 @@
"bareV8ToIstanbul"
]
},
{
"path": "/lib/bare/bundles/bareWinUi.js",
"keys": [
"bareWinUi"
]
},
{
"path": "/lib/bare/bundles/bareXdiff.js",
"keys": [
@@ -775,6 +775,12 @@
"bareZlib"
]
},
{
"path": "/lib/bare/bundles/bareWs.js",
"keys": [
"bareWs"
]
},
{
"path": "/lib/bare/bundles/bareZmq.js",
"keys": [
@@ -786,12 +792,6 @@
"keys": [
"bareWorker"
]
},
{
"path": "/lib/bare/bundles/bareWs.js",
"keys": [
"bareWs"
]
}
],
"bundleStats": {