themes

developer-guide/02-the-context-object.md

@@ -23,8 +23,8 @@ 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.5.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`**, …). |
+| **`bareOsCtxApiVersion`**                                                        | String semver for the documented **`ctx`** contract (e.g. **`1.7.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`**, **`bareCtxModules`**, **`bareDriveBundles`**, …). |
 | **`bareOsPublishBootReady(patch)`**                                              | Kernel-only: merge **`patch`** into the session boot-ready state exposed as **`/run/bare-os/boot.json`** and **`/run/bare-os/ready`**. The booter pre-seeds **`imageDigest`**, **`pearChannel`**, **`pearRelease`** from host env when set (see **`BARE_OS_IMAGE_DIGEST`**, **`BARE_OS_PEAR_CHANNEL`**, **`BARE_OS_PEAR_RELEASE`**, **`PEAR_CHANNEL`**).                      |
 | **`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`**).                                                                                                                                                                                                                                                                      |
@@ -35,6 +35,7 @@ The following are set on `ctx` before the kernel starts (unless noted as overwri
 | **`vfs`**                                                                        | Path layer: resolves logical paths, routes to system vs personal drive, implements `mkdir`, `readFile`, etc. See [`vfs.js`](../packages/bare-os-booter/lib/vfs.js)                                                                                                                                                                                                            |
 | **`env`**                                                                        | Shell environment object (`HOME`, `PATH`, `USER`, …), same object as **`vfs.env`**. Mutated by builtins (`export`, `cd` updates `PWD`, identity unlock updates user fields). After each **`execLine`**, **`BARE_OS_EXIT_STATUS`** holds the last command’s exit code as a decimal string (POSIX **`$?`** parity); use **`$?`** or **`${?}`** in shell words for expansion.    |
 | **`b4a`**                                                                        | **`b4a`** module (byte helpers); used to convert Hyperdrive buffers to strings                                                                                                                                                                                                                                                                                                |
+| **`bare`** _(optional)_                                                          | **Frozen** map of host-loaded (and optionally drive-bundled) npm modules for in-image use (**`ctx.bare.b4a`**, **`ctx.bare.protomux`**, …). Absent when **`BARE_OS_BARE_MODULES=0`**. See [`bare-module-manifest.json`](../packages/bare-os-booter/lib/bare-module-manifest.json) and [Chapter 12](12-bare-modules-and-pear-ecosystem.md).                                      |
 | **`topic`**                                                                      | Topic key helper from protocol package (rarely needed in user scripts)                                                                                                                                                                                                                                                                                                        |
 | **`console`**                                                                    | Initially the raw global; **replaced** with session-bound `log`/`error` that respect the REPL and fish-style UI                                                                                                                                                                                                                                                               |
 | **`readLine`**                                                                   | Placeholder async function; **replaced** with session `readLine(prompt)` that reads a line from stdin (or returns `null` when session ends)                                                                                                                                                                                                                                   |
@@ -44,6 +45,7 @@ The following are set on `ctx` before the kernel starts (unless noted as overwri
 | **`requestBooterExit(code)`**                                                    | Ends the session from `/bin/exit` or equivalent                                                                                                                                                                                                                                                                                                                               |
 | **`applyUnlock` / `applyRegister` / `applyLogin` / `applyLogout` / `saveVault`** | Identity and vault operations used by **`login`**, **`logout`**, **`savevault`**                                                                                                                                                                                                                                                                                              |
 | **`shellAliases`**                                                               | Populated when the shell loads default or `~/.barerc` aliases                                                                                                                                                                                                                                                                                                                 |
+| **`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).                                                                                                                                                                                                                                                                |
@@ -56,7 +58,7 @@ The following are set on `ctx` before the kernel starts (unless noted as overwri
 | **`bareOsHostStats`** _(optional)_                                               | When the **`bare-os`** npm module loads on the host, a **frozen** snapshot: **`hostname`**, **`loadavg`**, **`cpus`**, **`networkInterfaces`**.                                                                                                                                                                                                                               |
 | **`httpFetch`** _(optional)_                                                     | When Node/global **`fetch`** exists, the booter sets a **`fetch`** compatible function with optional **HTTP allow/deny** policy (**`BARE_OS_HTTP_ALLOWLIST`**, **`BARE_OS_HTTP_DENYLIST`**) and audit hooks when **`BARE_OS_AUDIT`** is on.                                                                                                                                   |
 
-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_SELFTEST_FORMAT`**, **`BARE_OS_AUDIT`**, **`BARE_OS_AUDIT_JSON`**, **`BARE_OS_AUDIT_REDACT`**, **`BARE_OS_BOOT_ALLOWLIST`**, **`BARE_OS_EXEC_MAX_DEPTH`**, **`BARE_OS_IPC_MAX_BYTES`**, **`BARE_OS_IPC_RPC_TOKEN`**, **`BARE_OS_IPC_FANOUT`** (set to **`0`** to disable fan-out), **`BARE_OS_IPC_JSON_MAX_BYTES`**, **`BARE_OS_HTTP_ALLOWLIST`**, **`BARE_OS_HTTP_DENYLIST`**, **`BARE_OS_TLS_PIN_SHA256`** (comma-separated SHA-256 hints for delegated TLS; host **`httpFetch`** may honor **`init.bareOsCurlTls.pinnedSha256`**), **`BARE_OS_VFS_WATCH`**, **`BARE_OS_IMAGE_DIGEST`**, **`BARE_OS_PEAR_CHANNEL`**, **`BARE_OS_PEAR_RELEASE`**, and **`PEAR_CHANNEL`** 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`**, **`pinnedSha256`**) 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_SELFTEST_FORMAT`**, **`BARE_OS_AUDIT`**, **`BARE_OS_AUDIT_JSON`**, **`BARE_OS_AUDIT_REDACT`**, **`BARE_OS_BOOT_ALLOWLIST`**, **`BARE_OS_EXEC_MAX_DEPTH`**, **`BARE_OS_IPC_MAX_BYTES`**, **`BARE_OS_IPC_RPC_TOKEN`**, **`BARE_OS_IPC_FANOUT`** (set to **`0`** to disable fan-out), **`BARE_OS_IPC_JSON_MAX_BYTES`**, **`BARE_OS_HTTP_ALLOWLIST`**, **`BARE_OS_HTTP_DENYLIST`**, **`BARE_OS_TLS_PIN_SHA256`** (comma-separated SHA-256 hints for delegated TLS; host **`httpFetch`** may honor **`init.bareOsCurlTls.pinnedSha256`**), **`BARE_OS_VFS_WATCH`**, **`BARE_OS_IMAGE_DIGEST`**, **`BARE_OS_PEAR_CHANNEL`**, **`BARE_OS_PEAR_RELEASE`**, **`BARE_OS_BARE_MODULES`**, **`BARE_OS_BARE_DRIVE_BUNDLES`**, **`TERM`**, **`COLORTERM`**, and **`PEAR_CHANNEL`** 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`**, **`pinnedSha256`**) for **`--cacert`** / **`-k`** semantics.
 
 After [`createVfs`](../packages/bare-os-booter/lib/vfs.js), **`ctx.vfs.watch(logicalPath)`** returns a Hyperdrive watcher when **`BARE_OS_VFS_WATCH`** is not disabled. **`ctx.bareOsIpc`** exposes FIFO **`push`/`take`**, optional JSON-RPC **`pushJson`/`takeJson`** (max line size, optional RPC token), **`fanoutPublish`/`fanoutSubscribe`**, and **`stats`** (see [`bare-os-ipc.js`](../packages/bare-os-booter/lib/bare-os-ipc.js)).