Docs+handbook

2026-04-03 03:12:44 -04:00
parent d794c87b32
commit 7435f4b353
16 changed files with 1044 additions and 33 deletions
@@ -0,0 +1,66 @@
+# bare-os-booter
+
+**Pear / Bare application** that **boots from the network only**: joins the same Hyperswarm topic as the seeder, reads **MBR** block 0 from peers, opens the **system Hyperdrive** (and a **personal** namespaced drive), replicates, then runs **`/boot/init.js`** with a rich `ctx` (VFS, shell, identity, HDMS, initd services).
+
+There is **no local seed fallback** — a running seeder (or another peer with the image) must be reachable within `BARE_OS_BOOT_TIMEOUT_MS`.
+
+## Run
+
+```bash
+# repo root (links node_modules for Pear)
+npm run os:booter
+```
+
+Or:
+
+```bash
+cd packages/bare-os-booter
+node index.js
+```
+
+## Major subsystems (lib/)
+
+| Module                                                 | Role                                                                    |
+| ------------------------------------------------------ | ----------------------------------------------------------------------- |
+| `index.js`                                             | Swarm, `SwarmDisk`, boot timeout, `executeKernel`, ctx assembly         |
+| `swarm-disk.js`                                        | Peer mux, MBR/read RPC, replication hooks                               |
+| `kernel-runner.js`                                     | `runKernelFromSource`, `runBinCommand` (paths, `*.js` in cwd, PATH)     |
+| `vfs.js`                                               | Two-drive routing: system vs `$HOME` on personal drive                  |
+| `shell.js`                                             | Tokenize, pipelines, redirections, builtins, `execShellLine`            |
+| `identity-session.js` / `identity-account.js`          | Guest vs unlocked user, `/.bare/account`, vault                         |
+| `hdms-manager.js`                                      | Extra Hyperdrives, mounts under `/mnt`, Autopass pair/invite            |
+| `bare-initd.js`                                        | Service registry, `startBareInitd`, `stopBareInitd`, **kernel-logger**  |
+| `bare-cron.js`                                         | `~/.crontab`, minute scheduler, `ctx.execLine` jobs                     |
+| `repl-session.js`                                      | Fish-style TTY line editor, synced `console`, cleanup → `stopBareInitd` |
+| `boot-splash.js`                                       | TTY boot progress UI                                                    |
+| `fish-readline.js`                                     | History, completion helpers                                             |
+| `cli-readline.js`, `resolve-stdio.js`, `debug-repl.js` | Stdio and debug tooling                                                 |
+| `paths.js`                                             | Pear-safe package root and Corestore path                               |
+
+## Environment
+
+| Variable                  | Meaning                                                       |
+| ------------------------- | ------------------------------------------------------------- |
+| `BARE_OS_BOOT_TIMEOUT_MS` | Total time to find peers + load kernel (default `60000`)      |
+| `BARE_OS_NO_SPLASH`       | Disable TTY splash                                            |
+| `BARE_OS_SKIP_REPL`       | Non-interactive kernel (`readLine` → null)                    |
+| `BARE_OS_FISH`            | Set `0` to disable fish-style editor                          |
+| `HYPERSWARM_BOOTSTRAP`    | Optional comma-separated bootstrap nodes (HDMS / replication) |
+
+## Tests
+
+```bash
+npm test -w bare-os-booter
+```
+
+- `brittle-bare test.identity.js` — crypto account codec (Bare)
+- `brittle-node test.js` — Hyperdrive, VFS, shell, kernel runner, cron matchers, etc.
+
+## Pear staging
+
+`pear.stage` includes hoisted `../../node_modules`. Run **`scripts/ensure-pear-node-modules.mjs`** from the repo root before `pear run` so the app package sees symlinked deps (see root README).
+
+## See also
+
+- [Handbook — Booter runtime](../../handbook/04-the-booter-runtime.md)
+- [DOCUMENTATION.md](../../DOCUMENTATION.md) §12 (detailed; some lists may lag code)