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-06 06:31:59 -04:00
parent 140b17c5fd
commit 6d0d1b8049
39 changed files with 1041 additions and 596 deletions
Download Patch File Download Diff File Expand all files Collapse all files
developer-guide/02-the-context-object.md
+1 -1
View File
@@ -95,7 +95,7 @@ The following are set on `ctx` before the kernel starts (unless noted as overwri
- **`bareOsApplyTheme()`** / **`bareOsListThemes()`** — Re-apply **`BARE_OS_THEME`** / **`LS_COLORS`** / **`BARE_OS_DIRCOLORS`** to **`vfs.env`** (including **`BARE_OS_COLOR_DEPTH`** downgrades for **`BARE_OS_COLOR_*`**). Used by **`/bin/theme`** and documented for custom tooling (see [`bare-os-theme-presets.js`](../packages/bare-os-booter/lib/bare-os-theme-presets.js)).
- **`runBinCommand(argv)`** — Runs a command with the **same** resolution rules as the interactive shell (used by **`time`**, **`xargs`**, and similar)
- **`registerKernelShutdownHook(fn)`** — Register an async or sync function to run when the REPL session ends, **before** **`stopBareInitd`** and initd **disposers**. Pair with **`registerBareInitdDisposer(fn)`** in [`bare-initd.js`](../packages/bare-os-booter/lib/bare-initd.js) when you need teardown **after** shutdown hooks but still inside **`stopBareInitd`** (intervals, sync cleanup).
- **`bareOsSubscribeBootEvent(fn)`** / **`bareOsEmitBootEvent(ev)`** — Subscribe to or emit structured boot lifecycle events (same shape as **`BARE_OS_BOOT_TRACE=ndjson`** records). Phase records carry **`lifecycleSchemaVersion: 3`** alongside **`telemetrySchemaVersion`** where applicable (see [kernel extensions](../docs/reference/kernel-extensions.md)).
- **`bareOsSubscribeBootEvent(fn)`** / **`bareOsEmitBootEvent(ev)`** — Subscribe to or emit structured boot lifecycle events (same shape as **`BARE_OS_BOOT_TRACE=ndjson`** records). Phase records carry **`lifecycleSchemaVersion`** and **`telemetrySchemaVersion`** set from stock **`BARE_OS_LIFECYCLE_SCHEMA_VERSION`** (see [compatibility matrix](../docs/reference/compatibility-matrix.md) and [kernel extensions](../docs/reference/kernel-extensions.md)).
- **`bareOsSubscribeKernelEvent(fn)`** / **`bareOsEmitKernelEvent(ev)`** — Namespaced kernel event bus (e.g. **`topic: 'boot.phase'`**, **`bootStage`**); also mirrored to diagnostics subscribers with **`source: 'kernel'`**.
- **`bareOsAcquireKeyHandle(hint?)`** — Key-broker sketch returning an **opaque** handle string (no raw key material in guest).
- **`bareOsSubscribeHdmsLifecycle(fn)`** — After HDMS **`activate`** / before **`deactivate`**, run callbacks with **`{ kind, labels? }`**.
developer-guide/README.md
+17
View File
@@ -25,6 +25,7 @@ This project is **experimental research software**. APIs described here follow t
## On this page
- [Who this is for](#who-this-is-for)
- [Maintainer cheat sheet](#maintainer-cheat-sheet-artifacts--verifiers)
- [Reading order](#reading-order)
- [Related docs](#related-docs)
@@ -39,6 +40,22 @@ This project is **experimental research software**. APIs described here follow t
---
## Maintainer cheat sheet (artifacts → verifiers)
| What you touch | Responsibility | Root check |
| --- | --- | --- |
| [`packages/bare-os-coreutils/lib/commands.mjs`](../packages/bare-os-coreutils/lib/commands.mjs) | Tier-1 `/bin` names, `man.json` coverage | `verify-man-coverage.mjs`, `verify-doc-tier1-count.mjs` (via **`pretest`**) |
| [`packages/bare-os-coreutils/build.mjs`](../packages/bare-os-coreutils/build.mjs) | Emit `kernel/bin/*`, man merge | `npm run build -w bare-os-coreutils` |
| [`kernel/lib/boot/`](../kernel/lib/boot/), [`kernel/lib/init/`](../kernel/lib/init/) | Init bundle sources | `bundle-kernel-init.mjs`, `verify-init-bundle-recipe.mjs` |
| [`kernel/`](../kernel/) vs [`packages/bare-os-seeder/kernel/`](../packages/bare-os-seeder/kernel/) | Byte-identical mirror | `verify-kernel-seeder-parity.mjs` |
| [`packages/bare-os-booter/lib/bare-os-ctx-api.js`](../packages/bare-os-booter/lib/bare-os-ctx-api.js) | **`BARE_OS_CTX_API_VERSION`** | `verify-ctx-api-feature-bits.mjs`, `verify-compat-matrix.mjs`, `gen-ctx-client-helper.mjs` |
| [`docs/reference/compatibility-matrix.md`](../docs/reference/compatibility-matrix.md) | Version table for releases | `verify-compat-matrix.mjs`, `verify-doc-contracts.mjs` |
| [`docs/reference/posix-compliance-matrix.json`](../docs/reference/posix-compliance-matrix.json) | POSIX profile linkage | `verify-posix-compliance-matrix.mjs`, `gen-posix-dashboard.mjs` |
Full script index: [scripts/README.md](../scripts/README.md). Gate everything with **`npm run pretest`** before pushing doc or contract edits.
---
## Reading order
- **[01 — Two runtimes: host vs in-image](01-two-runtimes-host-vs-image.md)** — Pear/Node packages vs Hyperdrive JS evaluated with `AsyncFunction`; trust boundaries.