Raven Scott
@@ -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)
|
||||
@@ -0,0 +1,41 @@
|
||||
# bare-os-coreutils
|
||||
|
||||
**Build step**, not a runtime library: concatenates a tiny shared prelude (`lib/runtime.js`) with each `src/<command>.js` and writes standalone scripts to:
|
||||
|
||||
- `kernel/bin/<command>` — staged into the **system** Hyperdrive as `/bin/*`
|
||||
- `packages/bare-os-seeder/kernel/bin/<command>` — **vendored** copy for Pear bundles (seeder has no sibling `bare-os-coreutils` at runtime)
|
||||
|
||||
## Command contract
|
||||
|
||||
Each `src/*.js` file must define:
|
||||
|
||||
```js
|
||||
async function run(ctx, argv) {
|
||||
/* ... */
|
||||
}
|
||||
```
|
||||
|
||||
No top-level `import` — commands are loaded by the booter via `AsyncFunction` for Bare/Pear compatibility. Use `ctx.vfs`, `ctx.console`, `ctx.b4a`, `ctx.drive`, `bareStdin(ctx)` from the prelude where needed.
|
||||
|
||||
## Build
|
||||
|
||||
From the **monorepo root**:
|
||||
|
||||
```bash
|
||||
npm run build -w bare-os-coreutils
|
||||
```
|
||||
|
||||
Or `node packages/bare-os-coreutils/build.mjs`.
|
||||
|
||||
**CI / tests:** root `pretest` runs this build so `kernel/bin` exists before workspace tests.
|
||||
|
||||
## Commands (current)
|
||||
|
||||
`basename`, `cat`, `clear`, `crontab`, `date`, `dirname`, `echo`, `env`, `exit`, `false`, `head`, `hdms`, `help`, `hostname`, `id`, `login`, `logout`, `ls`, `nl`, `pathchk`, `printenv`, `pwd`, `rm`, `savevault`, `seq`, `sleep`, `sort`, `tail`, `test`, `touch`, `true`, `tty`, `uname`, `wc`, `which`, `whoami`
|
||||
|
||||
See [handbook command reference](../../handbook/06-kernel-and-binaries.md) for behavior notes (e.g. `ls -a`, `crontab` identity gating).
|
||||
|
||||
## See also
|
||||
|
||||
- [kernel/README.md](../../kernel/README.md) — where built artifacts live in the source tree.
|
||||
- [DOCUMENTATION.md](../../DOCUMENTATION.md) §12.10 (may lag the command list; this README and `build.mjs` are authoritative).
|
||||
@@ -0,0 +1,37 @@
|
||||
# bare-os-protocol
|
||||
|
||||
Shared **wire format and constants** for the Bare operating system monorepo: Hyperswarm topic, 512-byte MBR layout, and Protomux **bare-os-v1** seed-channel message shapes.
|
||||
|
||||
## What it provides
|
||||
|
||||
| Export (from `index.js`) | Role |
|
||||
| ------------------------------- | ---------------------------------------------------------------------------------------------------- |
|
||||
| `PROTOCOL_NAME`, `TOPIC_STRING` | Protomux channel name and swarm topic input string (`bare-os-v1`) |
|
||||
| `topicKey()` | 32-byte topic for `swarm.join()` |
|
||||
| `BLOCK_SIZE`, `MBR_MAGIC` | 512-byte MBR, magic `BIOS` at offset 0 |
|
||||
| `buildMbr` / `parseMbr` | Pack/unpack primary + optional failover Hyperdrive keys |
|
||||
| `setupSeedChannel` | Wire Protomux messages 0–6 for RAM block reads, gossip stub, search, RPC stub, and `drive.replicate` |
|
||||
|
||||
Subpath exports: `bare-os-protocol/constants.js`, `bare-os-protocol/messages` (compact-encoding schemas).
|
||||
|
||||
## Consumers
|
||||
|
||||
- **[bare-os-seeder](../bare-os-seeder)** — builds MBR, serves block 0 over the channel, replicates the system Hyperdrive.
|
||||
- **[bare-os-booter](../bare-os-booter)** — parses MBR from `SwarmDisk`, opens system drives, uses the same channel on the client side.
|
||||
|
||||
## Tests
|
||||
|
||||
```bash
|
||||
npm test -w bare-os-protocol
|
||||
```
|
||||
|
||||
Runs `brittle-bare` against `test.js` (topic stability, MBR roundtrip, encodings).
|
||||
|
||||
## Dependencies
|
||||
|
||||
`b4a`, `compact-encoding`, `hypercore-crypto` (via constants/topic). No Hyperdrive or Hyperswarm here — this package stays small and testable.
|
||||
|
||||
## See also
|
||||
|
||||
- Repo root [README.md](../../README.md) and [DOCUMENTATION.md](../../DOCUMENTATION.md) §10.
|
||||
- [Handbook — Blueprints § protocol](../../handbook/02-blueprints.md) (high-level).
|
||||
@@ -0,0 +1,53 @@
|
||||
# bare-os-seeder
|
||||
|
||||
**Pear / Bare application** that owns the **canonical system Hyperdrive**: it walks a kernel tree on disk, writes `/boot/init.js`, `/bin/*`, `/etc/*` into the drive (no host temp dirs), builds a **512-byte MBR** with the drive key, joins **Hyperswarm** on `bare-os-v1`, and serves MBR block reads + **Protomux** `bare-os-v1` replication to peers.
|
||||
|
||||
## Run
|
||||
|
||||
From package directory (after `npm ci` at repo root):
|
||||
|
||||
```bash
|
||||
node index.js
|
||||
```
|
||||
|
||||
Or with Bare/Pear:
|
||||
|
||||
```bash
|
||||
npm run pear:dev
|
||||
```
|
||||
|
||||
From **repo root** (recommended — fixes workspace `node_modules` for Pear):
|
||||
|
||||
```bash
|
||||
npm run os:seeder
|
||||
```
|
||||
|
||||
## Environment
|
||||
|
||||
| Variable | Meaning |
|
||||
| --------------------- | -------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `BARE_OS_KERNEL_ROOT` | Absolute path to kernel tree to stage (default: package `kernel/` vendored copy, or repo `kernel/` under Node `file:` URL) |
|
||||
| `BARE_OS_SEED_STORE` | Corestore directory (default under repo `data/` when resolving from `file:`) |
|
||||
|
||||
## Pear vs Node
|
||||
|
||||
- **`import.meta.url` is `file:`** — seeder may **dynamically import** `bare-os-coreutils/build.mjs` and rebuild `/bin` before staging.
|
||||
- **`pear:` bundle** — coreutils must be **pre-built** into `kernel/bin/`; run `npm run build -w bare-os-coreutils` before `pear run`.
|
||||
|
||||
## Layout
|
||||
|
||||
| Path | Role |
|
||||
| -------------- | -------------------------------------------------------------------------- |
|
||||
| `index.js` | Entry: Corestore, Hyperdrive, `stageKernelTree`, swarm, `setupSeedChannel` |
|
||||
| `lib/paths.js` | `packageRootDir`, kernel root, Corestore path (Pear RTI–aware) |
|
||||
| `kernel/` | Vendored mirror of repo `kernel/` for Pear staging |
|
||||
|
||||
## Dependencies
|
||||
|
||||
`bare-os-protocol` (workspace), `hyperdrive`, `corestore`, `hyperswarm`, `protomux`, `b4a`, `compact-encoding`, `safety-catch`, `bare-os`.
|
||||
|
||||
## See also
|
||||
|
||||
- [bare-os-protocol](../bare-os-protocol/README.md)
|
||||
- [Handbook — Seeder path](../../handbook/03-protocol-and-disk.md#seeder-lifecycle)
|
||||
- Root [README.md](../../README.md)
|
||||
Reference in New Issue
Block a user