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

Updates

Browse Source
This commit is contained in:
Raven Scott
2026-04-03 20:11:00 -04:00
parent 0334ece75a
commit 58d1571627
29 changed files with 1939 additions and 179 deletions
Download Patch File Download Diff File Expand all files Collapse all files
developer-guide/02-the-context-object.md
+5 -3
View File
@@ -23,8 +23,10 @@ The following are set on `ctx` before the kernel starts (unless noted as overwri
| Field | Role |
| -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`bareOsCtxApiVersion`** | String semver for the documented **`ctx`** contract (e.g. **`1.3.0`**). Bump in [`bare-os-ctx-api.js`](../packages/bare-os-booter/lib/bare-os-ctx-api.js) when you make breaking changes to stable fields. |
| **`bareOsRuntimeCaps`** | **Frozen** snapshot from [`bare-os-runtime-caps.js`](../packages/bare-os-booter/lib/bare-os-runtime-caps.js): **`ctxApiVersion`**, resolved simulated **pipeline** limits (from **`env`** / defaults), documented pseudo **`/`** paths (**`pseudoFsPaths`**), and **`features`** flags (**`simulatedPipelines`**, **`bareInitd`**, **`vfsTwoDrive`**, **`identityVault`**, **`httpDelegate`**, **`gitDelegate`**, **`systemctlDelegate`**). Reflects session env at **`executeKernel`** start (including host **`BARE_OS_PIPELINE_*`** when set). |
| **`bareOsCtxApiVersion`** | String semver for the documented **`ctx`** contract (e.g. **`1.4.0`**). Bump in [`bare-os-ctx-api.js`](../packages/bare-os-booter/lib/bare-os-ctx-api.js) when you make breaking changes to stable fields. |
| **`bareOsRuntimeCaps`** | **Frozen** snapshot from [`bare-os-runtime-caps.js`](../packages/bare-os-booter/lib/bare-os-runtime-caps.js): **`ctxApiVersion`**, simulated **pipeline** limits, **`pseudoFsPaths`**, and **`features`** (including **`jobControl`**, **`shellHereString`**, **`bootReadyPseudoFs`**, **`vfsChown`**, **`auditLog`**, **`initdRequiresWants`**, **`seederRpcExtended`**, …). |
| **`bareOsPublishBootReady(patch)`** | Kernel-only: merge **`patch`** into the session boot-ready state exposed as **`/run/bare-os/boot.json`** and **`/run/bare-os/ready`**. |
| **`bareOsSessionStats`** | Mutable **`{ execLineCount, pipelineBytesTotal }`** mirrored in **`/proc/bare_os_session_stats`**. |
| **`bareOsBootStartedMs`** | Epoch milliseconds when the booter started building the session (used for synthetic **`/proc/uptime`**). |
| **`bareOsSkipRepl`** | **`true`** when **`BARE_OS_SKIP_REPL=1`** (non-interactive stdin); kernels may shorten banners. |
| **`disk`** | Disk bundle used during boot (includes drives and helpers); advanced use |
@@ -45,7 +47,7 @@ The following are set on `ctx` before the kernel starts (unless noted as overwri
| **`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). |
Kernel boot composition lives on the **system image** (`/boot/init.js`, `/etc/bare-os/rc`, `/etc/bare-os/rc.d/`, optional **`/etc/bare-os/rc.local`**, optional **`/etc/bare-os/kernel.d/`** (same digit-prefix rules as **`rc.d`**), optional **`/etc/bare-os/profile`** / **`rc.profile.*`**, **`/etc/bare-os/onboot`**), not on `ctx`—extend the image or hooks like **`registerKernelShutdownHook`** rather than adding boot fields to the context object. The booter seeds **`ctx.env`** from the host for **`BARE_OS_PIPELINE_MAX_STAGES`**, **`BARE_OS_PIPELINE_MAX_BYTES`**, **`BARE_OS_PIPELINE_MAX_LINES`**, **`BARE_OS_BOOT_PROFILE`**, **`BARE_OS_ONBOOT`**, **`BARE_OS_BOOT_STRICT`**, and **`BARE_OS_RC_D_SKIP`** when those variables are set, always sets **`BARE_OS_BOOT_PROFILE_RESOLVED`** for **`rc.profile.*`** and **`/run/bare-os/boot_profile`**, and assigns **`BARE_OS_SESSION_ID`** (UUID) for **`/run/bare-os/session`** and **`/proc/self/environ`**. When **`ctx.httpFetch`** handles **`curl`**, check optional **`init.bareOsCurlTls`** (`insecure`, **`caPem`**) for **`--cacert`** / **`-k`** semantics.
Kernel boot composition lives on the **system image** (`/boot/init.js`, `/etc/bare-os/rc`, `/etc/bare-os/rc.d/`, optional **`/etc/bare-os/rc.local`**, optional **`/etc/bare-os/kernel.d/`** (same digit-prefix rules as **`rc.d`**), optional **`/etc/bare-os/profile`** / **`rc.profile.*`**, **`/etc/bare-os/onboot`**), not on `ctx`—extend the image or hooks like **`registerKernelShutdownHook`** rather than adding boot fields to the context object. The booter seeds **`ctx.env`** from the host for **`BARE_OS_PIPELINE_*`**, **`BARE_OS_BOOT_PROFILE`**, **`BARE_OS_ONBOOT`**, **`BARE_OS_BOOT_STRICT`**, **`BARE_OS_RC_D_SKIP`**, **`BARE_OS_BOOT_MINIMAL`**, **`BARE_OS_BOOT_SKIP`**, **`BARE_OS_BOOT_TRACE`**, **`BARE_OS_KERNEL_SELFTEST`**, **`BARE_OS_AUDIT`**, and **`BARE_OS_IMAGE_DIGEST`** when set; always sets **`BARE_OS_BOOT_PROFILE_RESOLVED`** and **`BARE_OS_SESSION_ID`**. When **`ctx.httpFetch`** handles **`curl`**, check optional **`init.bareOsCurlTls`** (`insecure`, **`caPem`**) for **`--cacert`** / **`-k`** semantics.
After [`createKernelReplSession`](../packages/bare-os-booter/lib/repl-session.js) returns: