Docs Update
This commit is contained in:
Raven Scott
+17
-575
@@ -1,575 +1,17 @@
|
||||
# bare-operating-system — full codebase reference
|
||||
|
||||
This document describes **every first-party file** in the repository: purpose, contents, dependencies, and how pieces connect. It does **not** enumerate third-party code under `node_modules/` or VCS metadata under `.git/`. **Host** Corestore defaults live under **`~/.bare-os/corestore/`** (seeder and booter). Legacy **`data/`** at the repo root and **`packages/*/.test-data/`** remain **gitignored** if present; brittle tests use `.test-data/` under the booter package. None of these are source files.
|
||||
|
||||
For a **narrative how-to** on writing `async function run(ctx, argv)` and `start(ctx)` scripts, extending `/bin`, and separating host Pear code from in-image `AsyncFunction` execution, see [developer-guide/README.md](developer-guide/README.md).
|
||||
|
||||
---
|
||||
|
||||
## 1. Repository tree (source only)
|
||||
|
||||
```
|
||||
bare-operating-system/
|
||||
├── package.json # Root workspace manifest
|
||||
├── package-lock.json # Locked dependency tree (npm, all workspaces)
|
||||
├── README.md # User-facing overview and runbook
|
||||
├── DOCUMENTATION.md # This file
|
||||
├── handbook/ # Narrative handbook (chapters + diagrams)
|
||||
│ ├── README.md # Index + links to chapters
|
||||
│ ├── 01-introduction.md … 10-manpages-and-online-help.md
|
||||
├── developer-guide/ # How-to: in-image JS, ctx, coreutils, testing
|
||||
│ ├── README.md # Index + reading order
|
||||
│ ├── 01-two-runtimes-host-vs-image.md … 12-bare-modules-and-pear-ecosystem.md
|
||||
├── LICENSE # Apache-2.0 notice (root repo)
|
||||
├── .gitignore # Ignore rules
|
||||
├── .prettierrc # Prettier formatting defaults
|
||||
├── .github/
|
||||
│ └── workflows/
|
||||
│ └── ci.yml # GitHub Actions CI
|
||||
├── kernel/ # Files staged into the system Hyperdrive
|
||||
│ ├── init.js
|
||||
│ ├── bin/ # Tier-1 utilities (built from bare-os-coreutils)
|
||||
│ ├── lib/bare/ # Optional ctx.bare drive bundles + manifest (bare-os-bare-libs)
|
||||
│ └── etc/
|
||||
│ └── os-release
|
||||
└── packages/
|
||||
├── bare-os-protocol/ # Shared protocol + MBR + seed channel
|
||||
│ ├── package.json
|
||||
│ ├── index.js
|
||||
│ ├── constants.js
|
||||
│ ├── test.js
|
||||
│ └── lib/
|
||||
│ ├── messages.js
|
||||
│ ├── channel.js
|
||||
│ └── kernel-feature-bits.js
|
||||
├── bare-os-bare-libs/ # esbuild → kernel/lib/bare/bundles + manifest.json (seeder mirror)
|
||||
│ ├── package.json
|
||||
│ └── build.mjs
|
||||
├── bare-os-coreutils/ # Sources + build → kernel/bin/* and seeder copy
|
||||
│ ├── package.json
|
||||
│ ├── build.mjs
|
||||
│ ├── lib/runtime.js
|
||||
│ ├── lib/sed-engine.js, lib/awk-engine.js ← prepended for sed/awk (see build preamble)
|
||||
│ └── src/*.js
|
||||
├── bare-os-seeder/ # Publishes OS drive + MBR
|
||||
│ ├── package.json
|
||||
│ ├── index.js
|
||||
│ ├── kernel/ # Vendored for Pear (sync from repo kernel/)
|
||||
│ └── lib/
|
||||
│ └── paths.js
|
||||
└── bare-os-booter/ # Boots from swarm peers only (TTY splash + timeout)
|
||||
├── package.json
|
||||
├── CHANGELOG.md # ctx API version history
|
||||
├── index.js
|
||||
├── test.js
|
||||
└── lib/
|
||||
├── paths.js
|
||||
├── swarm-disk.js
|
||||
├── kernel-runner.js
|
||||
├── bare-os-abort.js
|
||||
├── bare-os-http-policy.js
|
||||
├── bare-os-ctx-api.js
|
||||
├── bare-os-ctx-bare.js # ctx.bare host import + drive bundle merge
|
||||
├── bare-module-manifest.json
|
||||
├── bare-os-ctx.d.ts
|
||||
├── git-cli.js # isomorphic-git; booter delegates `git`
|
||||
├── curl-cli.js # Fetch HTTP client; booter delegates `curl`
|
||||
├── wget-cli.js # Fetch downloads; booter delegates `wget`
|
||||
├── identity-account.js # Ed25519 account blob (bare-crypto PBKDF2 + ChaCha20-Poly1305)
|
||||
├── identity-session.js # Guest vs unlocked env, vault save, ctx hooks
|
||||
├── vfs.js # Two-drive path routing ($HOME → personal drive)
|
||||
├── shell.js # POSIX-ish line parser + builtins (incl. login/logout)
|
||||
├── fish-readline.js # TTY editor; per-USER REPL history on personal drive
|
||||
├── repl-session.js
|
||||
└── …
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. Root: [package.json](package.json)
|
||||
|
||||
| Field | Value / meaning |
|
||||
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `name` | `bare-operating-system` |
|
||||
| `private` | `true` — not published as a single npm package |
|
||||
| `type` | `module` — ESM |
|
||||
| `workspaces` | `["packages/*"]` — npm workspaces (protocol, coreutils, seeder, booter, …) |
|
||||
| `scripts.pretest` | Runs `bare-os-coreutils` + `bare-os-bare-libs` builds, kernel/seeder parity, [`smoke:bare-manifest`](scripts/smoke-bare-manifest-imports.mjs) |
|
||||
| `scripts.gen:bare-catalog` | Refresh [`docs/bare-holepunch-catalog.json`](docs/bare-holepunch-catalog.json) from GitHub + npm (see [Chapter 12](developer-guide/12-bare-modules-and-pear-ecosystem.md)) |
|
||||
| `scripts.sync:bare-manifest` | Apply catalog → [`bare-module-manifest.json`](packages/bare-os-booter/lib/bare-module-manifest.json) + booter `optionalDependencies` |
|
||||
| `scripts.test` | Runs `npm run test --workspaces --if-present` |
|
||||
| `scripts.format` | `prettier --write .` |
|
||||
| `scripts.lint` | `prettier --check .` |
|
||||
| `engines.node` | `>=20` |
|
||||
| `devDependencies` | `prettier@^3.4.2` |
|
||||
|
||||
No runtime dependencies at the root; all stack deps live in workspace packages.
|
||||
|
||||
---
|
||||
|
||||
## 3. Root: [package-lock.json](package-lock.json)
|
||||
|
||||
- **Format**: npm lockfile v3 (`lockfileVersion: 3`).
|
||||
- **Role**: Pins exact versions of the full install graph (root + `packages/bare-os-protocol`, `bare-os-seeder`, `bare-os-booter` and all transitive dependencies: `hyperdrive`, `corestore`, `hyperswarm`, `protomux`, `brittle`, Bare-related packages, native addons such as `rocksdb-native`, etc.).
|
||||
- **Workspaces**: Lists workspace package paths and links workspace packages to `"node_modules/bare-os-protocol"` etc.
|
||||
- **Not reproduced here line-by-line** — it is thousands of lines; use `npm ls` or open the file for the exact tree.
|
||||
|
||||
---
|
||||
|
||||
## 4. Root: [README.md](README.md)
|
||||
|
||||
User-oriented documentation: project goal, layout table, prerequisites (Node 20+, Pear/Bare), `npm ci`, `npm test`, how to run seeder and booter with `node index.js`, environment variables, Corestore path semantics (`~/.bare-os` defaults), placeholder `pear://` table, protocol summary (`bare-os-v1`, MBR layout), license pointer.
|
||||
|
||||
Narrative handbook (architecture diagrams, chapter walkthrough): [handbook/README.md](handbook/README.md). Per-workspace overviews: [packages/bare-os-protocol/README.md](packages/bare-os-protocol/README.md), [packages/bare-os-coreutils/README.md](packages/bare-os-coreutils/README.md), [packages/bare-os-seeder/README.md](packages/bare-os-seeder/README.md), [packages/bare-os-booter/README.md](packages/bare-os-booter/README.md), [kernel/README.md](kernel/README.md), [scripts/README.md](scripts/README.md).
|
||||
|
||||
---
|
||||
|
||||
## 5. Root: [LICENSE](LICENSE)
|
||||
|
||||
Short Apache License, Version 2.0 header: copyright year 2026, standard AS-IS disclaimer, link to <http://www.apache.org/licenses/LICENSE-2.0>.
|
||||
|
||||
---
|
||||
|
||||
## 6. Root: [.gitignore](.gitignore)
|
||||
|
||||
Ignores:
|
||||
|
||||
- `node_modules/`
|
||||
- `data/` (legacy; optional local Corestore if you still keep trees here — defaults now use `~/.bare-os`)
|
||||
- `coverage/`
|
||||
- `.DS_Store`
|
||||
- `*.log`
|
||||
- `.pear/`
|
||||
- `packages/*/.test-data/` (brittle test Corestore dirs)
|
||||
|
||||
---
|
||||
|
||||
## 7. Root: [.prettierrc](.prettierrc)
|
||||
|
||||
JSON: `semi: false`, `singleQuote: true`, `trailingComma: "none"`.
|
||||
|
||||
---
|
||||
|
||||
## 8. CI: [.github/workflows/ci.yml](.github/workflows/ci.yml)
|
||||
|
||||
- **Triggers**: `push` and `pull_request` to `main`.
|
||||
- **Job `test`**: `ubuntu-latest`, checkout, `actions/setup-node@v4` with Node 20 and npm cache on `package-lock.json`, then `npm ci`, **`npm install -g bare`** (for `brittle-bare` / `test.identity.js`), and `npm test`.
|
||||
|
||||
---
|
||||
|
||||
## 9. Kernel sources (staged into Hyperdrive)
|
||||
|
||||
These files are **read from disk by the seeder** and written into the system drive with **no temp directory**; paths are determined by [packages/bare-os-seeder/index.js](packages/bare-os-seeder/index.js) `stageKernelTree()`.
|
||||
|
||||
### 9.1 [kernel/init.js](kernel/init.js)
|
||||
|
||||
- **Staged as**: `/boot/init.js`
|
||||
- **Contract**: Must define a top-level `async function start(ctx)` (see [kernel-runner.js](packages/bare-os-booter/lib/kernel-runner.js)).
|
||||
- **Behavior** (see [handbook/06-kernel-and-binaries.md](handbook/06-kernel-and-binaries.md)):
|
||||
- Prints `/etc/os-release`, optional `/etc/motd`, optional profile `rc`, `/etc/bare-os/rc`, sorted digit-prefixed `/etc/bare-os/rc.d/*`, optional `/etc/bare-os/rc.local`, then banner / issue.
|
||||
- When `BARE_OS_SKIP_REPL`: runs each non-comment line from `BARE_OS_ONBOOT` (newline-separated) or `/etc/bare-os/onboot` via `execLine`.
|
||||
- Loop: `readLine('')` (TTY shows `[user@host:path] > ` from the booter). If `null`, break. Empty line skips. `exit` breaks. Otherwise `await execLine(t)` (booter dispatches to `/bin/<cmd>`).
|
||||
|
||||
### 9.2 [kernel/bin/echo](kernel/bin/echo)
|
||||
|
||||
- **Staged as**: `/bin/echo`
|
||||
- **Contract**: `async function run(ctx, argv)` — argv[0] is command name.
|
||||
- **Behavior**: `ctx.console.log(argv.slice(1).join(' '))`.
|
||||
|
||||
### 9.3 [kernel/bin/help](kernel/bin/help)
|
||||
|
||||
- **Staged as**: `/bin/help`
|
||||
- **Contract**: `async function run(ctx, _argv)`.
|
||||
- **Behavior**: Logs a compact list of **`/bin`** names, builtins, and pointers to **`man`** / identity commands (not an exhaustive tutorial; see **`man edit`** / **`man nano`** for the TTY editor).
|
||||
|
||||
### 9.4 [kernel/etc/os-release](kernel/etc/os-release)
|
||||
|
||||
- **Staged as**: `/etc/os-release`
|
||||
- **Format**: Plain text key=value lines (familiar from Linux):
|
||||
|
||||
```
|
||||
NAME="BareOS"
|
||||
VERSION="0.1.0"
|
||||
VARIANT="hyperdrive-only"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 10. Package: `bare-os-protocol`
|
||||
|
||||
### 10.1 [packages/bare-os-protocol/package.json](packages/bare-os-protocol/package.json)
|
||||
|
||||
| Item | Detail |
|
||||
| --------------------------- | -------------------------------------------------------------------------- |
|
||||
| `name` | `bare-os-protocol` |
|
||||
| `version` | `0.1.0` |
|
||||
| `main` / `exports["."]` | `./index.js` |
|
||||
| `exports["./constants.js"]` | `./constants.js` (for `bare-os-protocol/constants.js` imports) |
|
||||
| `exports["./messages"]` | `./lib/messages.js` |
|
||||
| `scripts.test` | `brittle-bare test.js` |
|
||||
| `scripts.test:node` | `brittle-node test.js` |
|
||||
| `engines.bare` | `>=2.0.0` |
|
||||
| `dependencies` | `b4a`, `compact-encoding`, `hypercore-crypto` |
|
||||
| `devDependencies` | `brittle` |
|
||||
| `imports` | Conditional `fs` / `path` / `events` → `bare-*` under Bare, Node `default` |
|
||||
|
||||
### 10.2 [packages/bare-os-protocol/index.js](packages/bare-os-protocol/index.js)
|
||||
|
||||
Re-exports from `./constants.js`: `PROTOCOL_NAME`, `TOPIC_STRING`, `BLOCK_SIZE`, `MBR_MAGIC`, `topicKey`, `buildMbr`, `parseMbr`.
|
||||
|
||||
Re-exports from `./lib/channel.js`: `setupSeedChannel`.
|
||||
|
||||
### 10.3 [packages/bare-os-protocol/constants.js](packages/bare-os-protocol/constants.js)
|
||||
|
||||
| Export | Definition |
|
||||
| ------------------------------------- | --------------------------------------------------------------------------------------------------- |
|
||||
| `PROTOCOL_NAME` | `'bare-os-v1'` — Protomux channel name |
|
||||
| `TOPIC_STRING` | `'bare-os-v1'` — input to swarm topic hash |
|
||||
| `BLOCK_SIZE` | `512` — MBR size |
|
||||
| `MBR_MAGIC` | `b4a.from('BIOS')` — first 4 bytes of MBR |
|
||||
| `topicKey(b4aMod?)` | `crypto.hash(b4aMod.from(TOPIC_STRING))` — 32-byte Hyperswarm topic |
|
||||
| `buildMbr(primaryKey, failoverKeys?)` | Allocates 512 bytes, writes magic at 0, primary 32-byte key at offset 8, optional keys at 40 and 72 |
|
||||
| `parseMbr(mbr)` | Validates length ≥ 104, magic `BIOS`, returns `{ keys: Uint8Array[] }` (non-zero 32-byte slots) |
|
||||
|
||||
### 10.4 [packages/bare-os-protocol/lib/messages.js](packages/bare-os-protocol/lib/messages.js)
|
||||
|
||||
`compact-encoding` schemas (for tests and documentation parity with SwarmDisk):
|
||||
|
||||
- `msgRead` — placeholder object (`encoding: c.uint32`, `onmessage: null`).
|
||||
- `msgDataEncoding` — `{ index: uint32, data: buffer }`.
|
||||
- `msgSearchReqEncoding` — `{ id: uint32, query: string }`.
|
||||
- `msgSearchResEncoding` — `{ id: uint32, matches: string[] }`.
|
||||
- `msgRpcReqEncoding` — `{ id, module, method, args: string[] }`.
|
||||
- `msgRpcResEncoding` — `{ id, success: bool, result, error: string }`.
|
||||
|
||||
### 10.5 [packages/bare-os-protocol/lib/channel.js](packages/bare-os-protocol/lib/channel.js)
|
||||
|
||||
**`setupSeedChannel(mux, localRAM, replicateDrive)`**
|
||||
|
||||
- Creates Protomux channel with `protocol: PROTOCOL_NAME`.
|
||||
- **Message 0**: `uint32` read index → if `localRAM.get(index)`, send on message 1.
|
||||
- **Message 1**: `msgDataEncoding` (inbound only on client).
|
||||
- **Message 2**: `c.buffer` — after `chan.open()`, sends 250-byte bitfield with bit 0 set (gossip stub).
|
||||
- **Message 3**: search request → responds on message 4 with empty `matches`.
|
||||
- **Message 4**: search response encoding.
|
||||
- **Message 5**: RPC request → responds on message 6 with failure `"RPC not implemented on seeder"`.
|
||||
- **Message 6**: RPC response encoding.
|
||||
- Calls `replicateDrive(mux.stream)` (typically `drive.replicate(stream)`).
|
||||
|
||||
### 10.6 [packages/bare-os-protocol/test.js](packages/bare-os-protocol/test.js)
|
||||
|
||||
Brittle tests:
|
||||
|
||||
1. `topicKey` length 32 and stable.
|
||||
2. `topicKey` ≠ hash of `'other-topic'`.
|
||||
3. `buildMbr` + `parseMbr` roundtrip one key.
|
||||
4. `msgDataEncoding` encode/decode.
|
||||
5. `msgSearchReqEncoding` encode/decode.
|
||||
6. `TOPIC_STRING === 'bare-os-v1'`.
|
||||
|
||||
---
|
||||
|
||||
## 11. Package: `bare-os-seeder`
|
||||
|
||||
### 11.1 [packages/bare-os-seeder/package.json](packages/bare-os-seeder/package.json)
|
||||
|
||||
| Item | Detail |
|
||||
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `main` | `./index.js` |
|
||||
| `scripts.start` / `dev` | `bare index.js` (Pear/Bare entry) |
|
||||
| `dependencies` | `bare-os-protocol` (workspace `*`), `b4a`, `compact-encoding`, `corestore`, `hyperdrive`, `hyperswarm`, `protomux`, `safety-catch` |
|
||||
| `engines.bare` | `>=2.0.0` |
|
||||
| `pear.name` | `bare-os-seeder` |
|
||||
| `pear.stage.ignore` | `.git`, `test`, `coverage`, `.DS_Store`, `node_modules/.bin`, `node_modules/.package-lock.json` |
|
||||
| `imports` | `fs`, `fs/promises`, `path`, `url`, `node:url` — Bare vs `node:` shims |
|
||||
|
||||
### 11.2 [packages/bare-os-seeder/lib/paths.js](packages/bare-os-seeder/lib/paths.js)
|
||||
|
||||
Pear-safe path resolution (same idea as Holepunch [pear-rti](https://github.com/holepunchto/pear-rti) `MOUNT` / `swapDir`):
|
||||
|
||||
- **`packageRootDir(metaUrl)`** — If `import.meta.url` is `file:`, `path.dirname(fileURLToPath(...))` via **`node:url`** (so `file:` is only passed to `fileURLToPath`). If `pear:` / other, `global.Pear.constructor.RTI.mount`, else `Pear.config.swapDir`, else `process.cwd()`.
|
||||
- **`defaultKernelRoot(pkgRoot, metaUrl)`** — `BARE_OS_KERNEL_ROOT` or `path.join(pkgRoot, 'kernel')` (vendored copy under the seeder package for Pear bundles).
|
||||
- **`defaultSeedCorestorePath(pkgRoot, metaUrl)`** — `BARE_OS_SEED_STORE` or `path.join(hostDataRoot(), 'corestore', 'seeder')` where **`hostDataRoot()`** is `BARE_OS_HOST_DATA` (resolved) or `~/.bare-os`. Signature keeps `pkgRoot` / `metaUrl` for callers; defaults do not use them.
|
||||
|
||||
### 11.3 [packages/bare-os-seeder/index.js](packages/bare-os-seeder/index.js)
|
||||
|
||||
**Paths** — Uses `./lib/paths.js` for `_pkg`, `corestorePath()`, and `kernelRoot` (no `fileURLToPath(import.meta.url)` on the hot path for `pear:`).
|
||||
|
||||
**`stageKernelTree(drive, kernelRoot)`**
|
||||
|
||||
- Recursive `walk(rel)` using `fs/promises` `readdir` + `readFile`.
|
||||
- **Drive path mapping**:
|
||||
- `init.js` → `/boot/init.js`
|
||||
- `bin/<name>` → `/bin/<name>` (POSIX slashes)
|
||||
- `etc/...` → `/etc/...`
|
||||
- Any other file → `/<subRel>` with slashes normalized
|
||||
- `drive.put(drivePath, b4a.from(raw))` for each file.
|
||||
|
||||
**`main()`**
|
||||
|
||||
1. Optional `console.clear()`.
|
||||
2. **`maybeBuildCoreutilsFromSource()`** — only when `import.meta.url` starts with `file:` (Node / `node index.js`): dynamic import of `../bare-os-coreutils/build.mjs` and `await build()`. Under **Pear** (`pear://` URLs) this is skipped; the bundle must include an up-to-date vendored `kernel/` (run `npm run build -w bare-os-coreutils` before `pear run`).
|
||||
3. `Corestore(corestorePath())`, `Hyperdrive(store)`, `ready()`.
|
||||
4. `stageKernelTree`.
|
||||
5. `localRAM = Map`, `buildMbr(drive.key)`, `localRAM.set(0, mbr)`.
|
||||
6. `Hyperswarm`, on `connection`: `Protomux(socket)`, `setupSeedChannel(mux, localRAM, stream => drive.replicate(stream))`.
|
||||
7. `swarm.join(topicKey())`, `swarm.join(drive.discoveryKey)`, `flush()`.
|
||||
8. Logs topic prefix hex, full drive key hex, Corestore path.
|
||||
|
||||
**Entry**: `main().catch(safetyCatch)`.
|
||||
|
||||
---
|
||||
|
||||
## 12. Package: `bare-os-booter`
|
||||
|
||||
### 12.1 [packages/bare-os-booter/package.json](packages/bare-os-booter/package.json)
|
||||
|
||||
| Item | Detail |
|
||||
| ----------------------- | ---------------------------------------------------------------------------------------------- |
|
||||
| `main` | `./index.js` |
|
||||
| `scripts.start` / `dev` | `bare index.js` |
|
||||
| `scripts.test` | `brittle-node test.js` |
|
||||
| `dependencies` | Same hyperstack as seeder + `bare-os-protocol` + `bare-crypto` (identity account + vault AEAD) |
|
||||
| `devDependencies` | `brittle` |
|
||||
| `imports` | `path`, `url`, `node:url` Bare/Node conditional |
|
||||
| `pear.stage.ignore` | Includes `test.js`, `test.identity.js`, `.test-data` so tests are not staged |
|
||||
|
||||
**Pear + npm workspaces:** dependencies are hoisted to the repo root; Pear’s dev bundle often does not follow a single symlinked `node_modules` tree. **[scripts/ensure-pear-node-modules.mjs](scripts/ensure-pear-node-modules.mjs)** (run from the repo root) rebuilds `packages/<app>/node_modules` by symlinking **each top-level** package from the root `node_modules` (matching npm’s flat hoist), and **`pear.stage.includes`** lists **`../../node_modules`** so staging can pull hoisted deps. **`npm run os:booter`** / **`npm run os:seeder`** run the script before `pear run`. After `npm install` at the root, re-run the script if hoisted packages change.
|
||||
|
||||
### 12.2 [packages/bare-os-booter/lib/paths.js](packages/bare-os-booter/lib/paths.js)
|
||||
|
||||
- **`packageRootDir(metaUrl)`** — Same as seeder (Pear RTI / `swapDir` / `cwd`).
|
||||
- **`defaultBootCorestorePath`** / **`defaultLocalSeedCorestorePath`** — `BARE_OS_BOOT_STORE` / `BARE_OS_LOCAL_SEED`, or under **`hostDataRoot()`** (`BARE_OS_HOST_DATA` or `~/.bare-os`): `corestore/booter` and `corestore/seeder` respectively. Same signature stability as the seeder helper.
|
||||
|
||||
### 12.3 [packages/bare-os-booter/index.js](packages/bare-os-booter/index.js)
|
||||
|
||||
**Imports** — Hyperswarm, Protomux, protocol, `./lib/swarm-disk.js`, `./lib/kernel-runner.js`, `./lib/vfs.js`, `./lib/shell.js`, `./lib/paths.js`, `./lib/bare-os-ipc.js`, `./lib/bare-os-runtime-caps.js`, stdio/readline/repl/boot-splash helpers, `./lib/identity-session.js`.
|
||||
|
||||
**`bootStorePath()`** — `defaultBootCorestorePath(_pkg, import.meta.url)`.
|
||||
|
||||
**`createReadLine()`**
|
||||
|
||||
- If `BARE_OS_SKIP_REPL === '1'`: returns `async () => null`.
|
||||
- Else tries `node:readline` `createInterface` + `question` per prompt.
|
||||
- On failure: warns and returns `async () => null`.
|
||||
|
||||
**`executeKernel(disk, store, swarm, initSource)`** (`store`/`swarm` unused but kept for signature symmetry / future use)
|
||||
|
||||
- Builds `shellEnv` with **guest** defaults: `USER`/`LOGNAME`=`guest`, `HOME`/`PWD`=`/home/guest`, `UID`/`GID`=`65534`, `BARE_OS_IDENTITY=guest`, `BARE_OS_EXIT_STATUS`=`0`, `BARE_OS_CTX_API_VERSION`, `PATH=/bin`, `SHELL`, `HOSTNAME`, `0`. When the host sets any of the keys listed in **§14** under “host → session passthrough,” those values are copied into `shellEnv`. Sets **`BARE_OS_BOOT_PROFILE_RESOLVED`** from **`BARE_OS_BOOT_PROFILE`** or the first line of **`/etc/bare-os/profile`**, and **`BARE_OS_SESSION_ID`** (random UUID). Seeds **`/run/bare-os/boot.json`** fields **`imageDigest`**, **`pearChannel`**, **`pearRelease`** from **`BARE_OS_IMAGE_DIGEST`**, **`BARE_OS_PEAR_CHANNEL`** / **`PEAR_CHANNEL`**, **`BARE_OS_PEAR_RELEASE`** when present.
|
||||
- **`createBareOsIpc({ maxFifoBytes, ipcRpcToken?, enableFanout?, maxJsonRpcLineBytes? })`** ([`bare-os-ipc.js`](packages/bare-os-booter/lib/bare-os-ipc.js)) — FIFOs under **`/run/bare-os/ipc/<name>`**; JSON-RPC with optional token and line cap; fan-out **`fanoutPublish`/`fanoutSubscribe`**; **`stats`** includes fan-out counts when caps expose **`features.ipcFanout`**.
|
||||
- **`createVfs(drive, personalDrive, shellEnv, vfsMountRef, vfsOptions)`** → `ctx.vfs` (same `env` object as `ctx.env`). **`vfsOptions`** supply **`procSnapshot`**, dynamic **`/proc/*`** and **`/sys/*`** text (quotas JSON, net/disk stubs, session stats), **`bootProfileText`**, **`sessionText`**, **`initdRunText`**, **`bootReadyJsonText`**, mount map for **`/proc/mounts`**, **`bootStartedMs`** for **`/proc/uptime`**, etc. Exposes **`vfs.watch(logicalPath)`** for Hyperdrive-backed paths when **`BARE_OS_VFS_WATCH`** is not **`0`**.
|
||||
- **`applyGuestEnv(ctx)`** then **`ensureGuestHome(ctx)`** — normalizes `ctx.identity` and seeds `/.bare/` (and a guest marker) on the personal drive.
|
||||
- **`createReadLine()`** always resolves stdio first and returns `stdout` (may be `null`) alongside `readLine` so the kernel can write to the **same** stream as the REPL (including `bare-stdio` under Pear).
|
||||
- Builds `ctx`: **`bareOsCtxApiVersion`** (from [`bare-os-ctx-api.js`](packages/bare-os-booter/lib/bare-os-ctx-api.js)), **`bareOsRuntimeCaps`** (frozen snapshot from [`bare-os-runtime-caps.js`](packages/bare-os-booter/lib/bare-os-runtime-caps.js): pipeline limits, **`quotas`**, pseudo path list, feature flags such as **`vfsWatch`**, **`ipcRpcJson`**, **`initdSocketActivation`**), **`bareOsIpc`**, `disk`, `drive`, `personalDrive`, `vfs`, `env`, `console`, `b4a`, `topic: topicKey()`, `readLine`, **`writeScreen(str)`**, **`bareOsSubscribeBootEvent`** / **`bareOsEmitBootEvent`**, **`bareOsSubscribeHdmsLifecycle`**, **`bareOsAwaitInitdUnits`**, **`bareOsPublishBootReady`**, `execLine` → wraps **`execShellLine`** with optional **audit** (**`BARE_OS_AUDIT`**, **`BARE_OS_AUDIT_JSON`**, redaction), **`execLine` depth cap** (**`BARE_OS_EXEC_MAX_DEPTH`**), then the shell (returns `'ok'` or `'exit'`; updates **`BARE_OS_EXIT_STATUS`** in **`vfs.env`**; bare **`exit`** line sets status then **`requestBooterExit`**), **`runBinCommand(argv)`** → delegates to **`runBinCommand(this, argv)`** from `kernel-runner.js` (for `/bin/time` and similar), plus identity hooks for `/bin` and builtins:
|
||||
- **`applyUnlock(passphrase)`** — load `/.bare/account`, decrypt, unlock session.
|
||||
- **`applyRegister(passphrase)`** — create account file, unlock.
|
||||
- **`applyLogin({ publicKey, secretKey })`** — set session from an already-decoded keypair.
|
||||
- **`applyLogout({ save? })`** — optional **`save`** runs encrypted vault snapshot first (see `identity-session.js`).
|
||||
- **`saveVault()`** — encrypt personal-drive files into `/.bare/vault/` (skips `/.bare`, `bin`, `boot`, history paths).
|
||||
- **`registerKernelShutdownHook(fn)`** — register async/sync teardown before **`stopBareInitd`** when the REPL session cleans up.
|
||||
- After **`createKernelReplSession`**: wires **`readLine`**, **`console`**, **`execLine`**, **`suspendReplForSubprocess`** / **`resumeReplAfterSubprocess`**, then **`await startBareInitd(ctx)`** (services such as kernel log mirroring).
|
||||
- Sets `disk.os` with stub `searchLocal` ([]) and `execRpc` (`''`).
|
||||
- `try { await runKernelFromSource(...) } finally { await session.cleanup() }` — cleanup runs **`runKernelShutdownHooks`**, **`stopBareInitd`**, fish TTY teardown.
|
||||
|
||||
**`boot-splash.js`** — TTY splash (disabled when `stdout` is not a TTY or `BARE_OS_NO_SPLASH=1`): full-screen clear, Braille spinner, elapsed boot timer, progress bar vs `BARE_OS_BOOT_TIMEOUT_MS` (default 60s), rotating title color, status lines. `prepareForKernel()` clears again and shows the cursor before the fish shell.
|
||||
|
||||
**`bootFromPeers(disk, store, swarm, splash)`**
|
||||
|
||||
- `disk.read(0)` → `parseMbr`.
|
||||
- For each key: `Hyperdrive(store, driveKey)`, `ready()`, replicate on all `disk.peers`’ mux streams, join drive discovery, `findingPeers` + `swarm.flush`, poll up to 30×200ms for `/boot/init.js`.
|
||||
- On success: `initPersonalDrive`, `splash.prepareForKernel()`, `executeKernel`.
|
||||
|
||||
**`main()`**
|
||||
|
||||
- `resolveStdio()` → `createBootSplash`, `splash.start()` (initial clear).
|
||||
- `Corestore(bootStorePath())`, `Hyperswarm`, `SwarmDisk`, join `topicKey()`.
|
||||
- Wait until `disk.peers.size > 0` or **`BARE_OS_BOOT_TIMEOUT_MS`** elapses (default **60000**). There is **no local seed fallback**; without peers, boot fails.
|
||||
- `Promise.race` between `bootFromPeers` and the remaining time within the same deadline so the whole network boot finishes within the limit.
|
||||
- **`finally`**: `swarm.destroy()` first, then close drives and `store` (each in try/catch).
|
||||
- **`exitHostProcess`**: `Bare.exit` or `process.exit`.
|
||||
|
||||
**Entry**: `main().catch(…)`.
|
||||
|
||||
### 12.4 [packages/bare-os-booter/lib/swarm-disk.js](packages/bare-os-booter/lib/swarm-disk.js)
|
||||
|
||||
**`SwarmDisk` class**
|
||||
|
||||
**State:** `localRAM`, `peers` (Set of `{ chan, mux, socket, id }`), `pendingReads`, `pendingSearches`, `pendingRpc`, counters, `drive`, `personalDrive`, `os`.
|
||||
|
||||
**`initPersonalDrive(store, swarm, Hyperdrive)`**
|
||||
|
||||
- `store.namespace('bare-os-personal-v1')`, new `Hyperdrive(localStore)`, ensure writable, log id prefix, `swarm.join(personalDrive.discoveryKey)`.
|
||||
|
||||
**`addPeer(mux, socket)`**
|
||||
|
||||
- Builds `context` with `onread` / `ondata` / `ongossip` / `onsearchreq` / `onsearchres` / `onrpcreq` / `onrpcres` wired to Protomux messages **0–6** (same order as seeder + hyper-os style): read request, data, gossip buffer, search req/res, RPC req/res.
|
||||
- `chan.open()`, track peer, handshake-based `peer.id`, remove peer on `mux.stream` `close`.
|
||||
- If `this.drive` / `this.personalDrive` set, `replicate(mux.stream, { live: true, download: true })` for system drive.
|
||||
|
||||
**`read(index)`**
|
||||
|
||||
- If `localRAM.has(index)`, return cached.
|
||||
- Else broadcast message 0 to all peers, single consumer callback from message 1, 10s timeout.
|
||||
|
||||
**`search(query)`**
|
||||
|
||||
- Fan-out message 3 to all peers with shared id (actually each peer gets same id from counter — **one id per `search()` call**, registered in `pendingSearches`; concurrent searches could collide in id space; documented as current behavior).
|
||||
|
||||
### 12.5 [packages/bare-os-booter/lib/kernel-runner.js](packages/bare-os-booter/lib/kernel-runner.js)
|
||||
|
||||
- **`AsyncFunction`** = `Object.getPrototypeOf(async function () {}).constructor`.
|
||||
|
||||
**`runKernelFromSource(source, ctx)`**
|
||||
|
||||
- `new AsyncFunction('ctx', source + guard + 'return start(ctx)')` where guard checks `typeof start === 'function'`.
|
||||
|
||||
**`runBinCommand(ctx, argv)`**
|
||||
|
||||
- If **`argv[0]`** is **`git`** (or a POSIX path whose basename is `git`, but not `./git` or `../git`), **delegates** to **`runGitCli`** in [`git-cli.js`](packages/bare-os-booter/lib/git-cli.js).
|
||||
- If **`argv[0]`** is **`curl`** under the same basename rules, **delegates** to **`runCurlCli`** in [`curl-cli.js`](packages/bare-os-booter/lib/curl-cli.js) (HTTP client via global **`fetch`** when available, else **bare-fetch**, else **bare-https** on Pear/Bare; manual **`curl(1)`** in the merged JSON DB).
|
||||
- If **`argv[0]`** is **`wget`** under the same basename rules, **delegates** to **`runWgetCli`** in [`wget-cli.js`](packages/bare-os-booter/lib/wget-cli.js) (HTTP download via Fetch / **bare-fetch**; manual **`wget(1)`** in the merged JSON DB).
|
||||
- If `argv[0]` contains `/`, resolves with `ctx.vfs.resolveLogical`, `route`, loads script bytes from the routed Hyperdrive (`get` with `follow`).
|
||||
- Else walks `$PATH` (`ctx.vfs.env.PATH`, default `/bin`), joining each directory with `unix-path-resolve(dir, cmd)` (not three-argument resolve), loads from **system** `ctx.drive` only.
|
||||
- Builds `AsyncFunction('ctx','argv', ...)` with the script source plus `if (typeof run === 'function') await run(ctx, argv)` (top-level statements run first; optional `run` matches `/bin` utilities).
|
||||
- Unknown command: `ctx.console.log('unknown command: ...')`.
|
||||
|
||||
**`resolveBinInPath(ctx, name)`** — returns the first **`PATH`** hit on the system drive (absolute `/bin/...` path string) or **`null`**; used by shell **`command -v`** / **`type`**.
|
||||
|
||||
### 12.6 [packages/bare-os-booter/lib/vfs.js](packages/bare-os-booter/lib/vfs.js)
|
||||
|
||||
**`createVfs(systemDrive, personalDrive, env, mntRef?, vfsOptions?)`**
|
||||
|
||||
- **Logical paths** under `$HOME` (booter default `/home/guest`; after `login`, `/home/<pubkey-prefix>`) map to the **personal** Hyperdrive under `/.bare-os/home/<basename>/…`; **`/var/log`** and **`/tmp`** map to **`/.bare-os/var/log/…`** and **`/.bare-os/tmp/…`** with the same basename. Read-only synthetic **`/proc`** and **`/sys`** (optional **`vfsOptions`** for version/cmdline, quotas JSON, net/disk stubs, **`/run/bare-os/*`** text providers, mount map, etc.). All other absolute paths use the **system** drive (read-mostly OS image).
|
||||
- **`resolveLogical(p)`** — `unix-path-resolve(cwd, p)` so cwd + relative segments work (the `unix-path-resolve` package only accepts two path arguments).
|
||||
- **API**: `getcwd`, `chdir` (rejects regular files), `readFile`, `writeFile` / `unlink` (personal only), `exists`, `readdir`, `stat` / `lstat`, `readlink`, `symlink`, `chmod`, `mkdir` (recursive via `.bareos_empty` marker), `rmdir` (empty dirs; marker-aware), `rm` (recursive tree walk), `route`, `resolveLogical`, `env`, **`watch(logicalPath)`** (Hyperdrive-backed paths only; throws on pseudo **`/proc`**/**`/sys`**/**`/run`**/**`/dev`** and on virtual **`$HOME`**, **`/var`**, **`/mnt`** roots).
|
||||
- **Hyperdrive quirk**: `entry` / `get` / `exists` use `std(path, false)` and **throw** on path `'/'` (`Invalid filename: /`). The VFS special-cases drive path `'/'` (logical `/` and personal `$HOME` root) for `chdir`, `stat`, `exists`, `isRegularFile`, and blocks `readFile`/`put`/`del` on that key.
|
||||
- **Bare / Pear**: do not rely on global `TextEncoder` / `TextDecoder` in booter `lib/*.js`; this tree uses **`b4a`** for UTF-8 where needed (pseudo `/proc` content, symlink size in `vfs-posix-meta.js`, `systemctl` log tailing, etc.).
|
||||
|
||||
### 12.7 [packages/bare-os-booter/lib/shell.js](packages/bare-os-booter/lib/shell.js)
|
||||
|
||||
- **`defaultShellAliases`** — includes `ll`, `la`, `l`, `..`, `...` as the baseline merged from **`~/.barerc`**.
|
||||
- **`tokenize` / `expandWord` / `parsePipeline`** — POSIX-ish words, `'...'`, `"..."`, `\`, `|`, `||`, `&&`, `;`, `>`, `>>`, `<`; `$VAR` and `${VAR}`; pipelines split on `|`; **`;`** splits lists; **`&&`** / **`||`** short-circuit using **`ctx.exitCode`** (left-associative).
|
||||
- **`execShellLine(ctx, line)`** — semicolon-separated lists, then per segment AND-OR chains of pipelines; leading `NAME=value` assignments (blocked for `ctx.shellReadonlyVars`), redirections, builtins `alias`, **`barerc`** (`barerc reload` re-parses `~/.barerc` and reapplies theme), `unalias`, `cd`, `export`, `unset`, `readonly`, `umask`, `:`, `command`, `type`, `login`, `logout`, `exit`, else `runBinCommand`. `command -v`/`-V` and `type` use **`resolveBinInPath`**. `login`/`logout` call the same `ctx.applyRegister` / `ctx.applyUnlock` / `ctx.applyLogout` hooks as `/bin/login` and `/bin/logout`. Captures `console.log` for pipes and file redirection; `>` / `>>` target paths via `ctx.vfs.writeFile` (personal tree). Returns `'exit'` when the `exit` builtin runs. Lone **`&`** (job control) is rejected with a clear error. After each completed line (except empty input), **`syncBareOsExitStatusEnv`** writes **`ctx.exitCode`** to **`vfs.env.BARE_OS_EXIT_STATUS`**; **`expandWord`** maps **`$?`** / **`${?}`** to that value.
|
||||
|
||||
### 12.8 [packages/bare-os-booter/lib/identity-account.js](packages/bare-os-booter/lib/identity-account.js)
|
||||
|
||||
- On-disk **`/.bare/account` (v2)**: magic `BAREOS01`, version `2`, 32-byte Ed25519 public key (bare-crypto), 16-byte PBKDF2 salt, 4-byte iteration count (big-endian), ChaCha20-Poly1305 seal of the 64-byte Ed25519 private key material (nonce + ciphertext + tag). Passphrase stretching: **PBKDF2-SHA256** (`210000` iterations by default). **v1** (libsodium) files are rejected with a message to run `login --new`.
|
||||
- **`encodeAccount` / `decodeAccount` / `encodeNewAccount`**, **`sealBytes` / `openBytes`**, **`vaultKeyFromSecret`**, **`hashUtf8Path`** — shared by `identity-session.js` (vault snapshots use the same AEAD).
|
||||
|
||||
### 12.9 [packages/bare-os-booter/lib/identity-session.js](packages/bare-os-booter/lib/identity-session.js)
|
||||
|
||||
- **`applyGuestEnv` / `applyUnlockedEnv`** — set `ctx.vfs.env` (`BARE_OS_PUBLIC_KEY`, `BARE_OS_IDENTITY`, `USER`, `HOME`, derived `UID`/`GID` from pubkey hash for logged-in users) and `vfs.chdir` to the new home. **`applyUnlockedEnv`** calls **`loadBarerc`** after unlock (**`createSkeletonIfMissing: true`** on first login) so **`~/.barerc`** applies without restarting the session.
|
||||
- **`registerIdentity` / `unlockIdentity` / `logoutIdentity` / `saveVaultToDrive`** — personal Hyperdrive persistence and encrypted vault index under `/.bare/vault/`.
|
||||
|
||||
### 12.10 Package `bare-os-coreutils`
|
||||
|
||||
- **[packages/bare-os-coreutils/lib/commands.mjs](packages/bare-os-coreutils/lib/commands.mjs)** — **`COREUTILS_COMMANDS`**: authoritative sorted `/bin` names for **`build.mjs`** and the manual database builder (keeps the image and **`man`** coverage in sync).
|
||||
- **[packages/bare-os-coreutils/build.mjs](packages/bare-os-coreutils/build.mjs)** — `export async function build()`: runs **`scripts/build-man-db.mjs`** (validates **`man/pages/*.json`**, writes **`kernel/share/man/man.json`** and the same path under **`packages/bare-os-seeder/kernel/share/man/`**); then for each command concatenates `lib/runtime.js`, optional **`preamble`** libs (**`md5sum`** → **`lib/md5.js`**, **`sed`** → **`lib/sed-engine.js`**, **`awk`** → **`lib/awk-engine.js`**, **`jq`** → **`lib/jq-engine.js`**, **`man`** → **`lib/man-render.js`**, **`ls`** / **`dircolors`** → lscolors helpers, **`edit`** / **`nano`** → **`lib/edit-*.js`** + shared TUI), then **`src/<name>.js`** (**`nano`** reuses **`src/edit.js`**); writes to **`kernel/bin/<name>`** and **`packages/bare-os-seeder/kernel/bin/<name>`**. CLI: **`node build.mjs`** when executed as main.
|
||||
- **Manual pages** — Authoring: **`packages/bare-os-coreutils/man/pages/<name>.json`**; schema: **`man/schema.json`**. Optional **`examples`** (cheat.sh-style) and **`descriptionMode`**: **`preserve`** for preformatted text. **`scripts/ingest-handbook-for-man.mjs`** merges every **`handbook/*.md`** as **`man(7)`** at build time (**`man handbook`**, **`man handbook-01-introduction`**, …). Regenerate JSON stubs with **`node packages/bare-os-coreutils/scripts/seed-man-pages.mjs`**. Runtime: **`/bin/man`** reads **`/share/man/man.json`**. **Handbook:** [handbook/10-manpages-and-online-help.md](handbook/10-manpages-and-online-help.md).
|
||||
- **Commands** (sources under **`src/`**, same order as **`COREUTILS_COMMANDS`** in [`commands.mjs`](packages/bare-os-coreutils/lib/commands.mjs)): `arch`, `awk`, `base32`, `base64`, `basename`, `basenc`, `cat`, `chgrp`, `chmod`, `chown`, `cksum`, `clear`, `comm`, `cp`, `crontab`, `cut`, `date`, `df`, `dir`, `dirname`, `dircolors`, `du`, `edit`, `echo`, `env`, `exit`, `expand`, `expr`, `factor`, `false`, `find`, `fmt`, `fold`, `getconf`, `git-pear`, `grep`, `groups`, `head`, `hdms`, `help`, `hostid`, `hostname`, `id`, `install`, `join`, `jq`, `ln`, `login`, `logout`, `logname`, `ls`, `man`, `md5sum`, `mkdir`, `mkfifo`, `mktemp`, `mv`, `nano`, `nl`, `nproc`, `numfmt`, `od`, `paste`, `pathchk`, `pr`, `printenv`, `printf`, `pwd`, `readlink`, `realpath`, `rev`, `rm`, `rmdir`, `savevault`, `sed`, `seq`, `sha1sum`, `sha256sum`, `sha512sum`, `shuf`, `sleep`, `sort`, `split`, `stat`, `sum`, `sync`, `tac`, `tail`, `tee`, `test`, `theme`, `time`, `touch`, `tr`, `truncate`, `true`, `tsort`, `tty`, `uname`, `uniq`, `unlink`, `unexpand`, `uptime`, `users`, `vdir`, `wc`, `which`, `who`, `whoami`, `xargs`, `yes` (**111** built names). The interactive TTY editor is **`edit`**; **`nano`** is the same built script under **`/bin/nano`**, and the default shell maps **`nano` → `edit`** (see **`defaultShellAliases`** in [`shell.js`](packages/bare-os-booter/lib/shell.js)). Each built script begins with **`BARE_OS_BIN_API`** in the concatenated prelude; root **`pretest`** runs **[`scripts/verify-kernel-seeder-parity.mjs`](scripts/verify-kernel-seeder-parity.mjs)** to keep **`kernel/bin/*`** and **`packages/bare-os-seeder/kernel/bin/*`** in sync and to require that pragma on every staged binary. Scripts are plain **`async function run(ctx, argv)`** using **`ctx.vfs`**, **`ctx.drive`**, **`ctx.b4a`**, **`ctx.console`**, optional **`bareStdin(ctx)`**, optional **`ctx.runBinCommand`** — no ESM **`import`** in **`src/`** (Bare-safe **`AsyncFunction`** load). **`dir`** / **`vdir`** delegate to **`ls -C`** / **`ls -l`**. **Booter-delegated** (stubs under **`kernel/bin/`**, logic in **`packages/bare-os-booter/lib/`**): **`systemctl`**, **`journalctl`** (bare-initd control; **`bare-initctl`** alias; see [handbook/04-the-booter-runtime.md](handbook/04-the-booter-runtime.md)). **Narrative reference:** [handbook/09-posix-utilities-shell-and-vfs.md](handbook/09-posix-utilities-shell-and-vfs.md).
|
||||
|
||||
### 12.11 [packages/bare-os-booter/test.js](packages/bare-os-booter/test.js) and [test.identity.js](packages/bare-os-booter/test.identity.js)
|
||||
|
||||
- **`scripts.test`** — `brittle-bare test.identity.js` then `brittle-node test.js` (bare-crypto’s native addon runs under Bare only; the main suite still uses Node for Hyperdrive + `node:fs`).
|
||||
|
||||
**[test.js](packages/bare-os-booter/test.js)** — **`testCorestoreDir(name)`** under `__dirname/.test-data/`.
|
||||
|
||||
Tests: `runKernelFromSource`, `runBinCommand`, `createStreamLineReader`, Hyperdrive roundtrip, `createVfs`, shell tokenizer/exec, tier-1 `cat`. Uses `node:fs`, `node:path`, `node:url`.
|
||||
|
||||
**[test.identity.js](packages/bare-os-booter/test.identity.js)** — identity account v2 codec roundtrip and wrong-passphrase failure (`bare-crypto`).
|
||||
|
||||
### 12.12 Seeder: coreutils build hook
|
||||
|
||||
- **[packages/bare-os-seeder/index.js](packages/bare-os-seeder/index.js)** — when not on Pear (`import.meta.url` is `file:`), dynamic `import('../bare-os-coreutils/build.mjs')` then `await build()`. Pear has no sibling `bare-os-coreutils` in the bundle; use pre-built files under vendored `kernel/bin/`.
|
||||
|
||||
---
|
||||
|
||||
## 13. End-to-end data flow
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Seeder as bare_os_seeder
|
||||
participant Swarm as Hyperswarm
|
||||
participant Booter as bare_os_booter
|
||||
participant Sys as System_Hyperdrive
|
||||
participant Pers as Personal_Hyperdrive
|
||||
|
||||
Seeder->>Sys: stage kernel files and MBR key in RAM map
|
||||
Seeder->>Swarm: join topic plus drive discovery
|
||||
Booter->>Swarm: join topic
|
||||
Booter->>Seeder: Protomux bare_os_v1
|
||||
Booter->>Seeder: read block 0 MBR
|
||||
Booter->>Sys: open with key replicate
|
||||
Booter->>Pers: new writable drive namespace
|
||||
Booter->>Booter: AsyncFunction start ctx from init.js
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 14. Environment variables (complete list)
|
||||
|
||||
| Variable | Used by | Meaning |
|
||||
| ------------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| `BARE_OS_KERNEL_ROOT` | Seeder | Absolute path to kernel tree (default: `repo/kernel`) |
|
||||
| `BARE_OS_HOST_DATA` | paths | Base directory for host state (default `~/.bare-os`; Corestore dirs live under `corestore/`) |
|
||||
| `BARE_OS_SEED_STORE` | Seeder | Corestore directory (default: `~/.bare-os/corestore/seeder`) |
|
||||
| `BARE_OS_BOOT_STORE` | Booter | Corestore for boot side (default: `~/.bare-os/corestore/booter`) |
|
||||
| `BARE_OS_BOOT_TIMEOUT_MS` | Booter | Wall-clock budget for peer wait + network boot (default `60000`) |
|
||||
| `BARE_OS_NO_SPLASH` | Booter | If `1`, skip TTY splash (plain logs / non-TTY behavior unchanged) |
|
||||
| `BARE_OS_LOCAL_SEED` | paths | Overrides local seed path helper (`defaultLocalSeedCorestorePath`); booter does not local-boot |
|
||||
| `BARE_OS_SKIP_REPL` | Booter | If `1`, readline returns null — non-interactive exit |
|
||||
| `BARE_OS_BOOT_TRACE` | Stock kernel (`init.js`) | If `1` or `true`, log each boot phase duration on stderr as `[boot] phase: Nms`; if `json`, log `{"phase":"…","ms":n}` per phase; **`ndjson`** adds **`sessionId`** / **`ts`** (same shape as `ctx.bareOsEmitBootEvent`) |
|
||||
| `MANWIDTH` | `/bin/man` | Wrap width for manual text (default `72`; minimum `40`) |
|
||||
| `NO_COLOR` | `/bin/man` | If set, disable ANSI bold for section headings on a TTY |
|
||||
|
||||
**Host → session passthrough** (booter copies into **`shellEnv`** when the host sets a non-empty value): `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`, `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_IMAGE_DIGEST`, `BARE_OS_EXEC_MAX_DEPTH`, `BARE_OS_IPC_MAX_BYTES`, `BARE_OS_VFS_WATCH`, `BARE_OS_BOOT_ALLOWLIST`, `BARE_OS_PEAR_CHANNEL`, `BARE_OS_PEAR_RELEASE`, `PEAR_CHANNEL`, **`BARE_OS_FIND_EXEC_MAX`** (cap for **`find -exec`/`-ok`**), **`BARE_OS_YES_MAX_LINES`**, **`BARE_OS_SHUF_MAX_LINES`**, **`BARE_OS_SPLIT_MAX_FILES`**, **`BARE_OS_NPROC`** (override for **`/bin/nproc`**), **`TERM`**, **`COLORTERM`** (terminal capability hints for colorized tools).
|
||||
|
||||
**Session env (set by booter, not user configuration):** `USER`, `LOGNAME`, `HOME`, `PWD`, `UID`, `GID`, `GROUP`, `BARE_OS_IDENTITY` (`guest` or `unlocked`), `BARE_OS_CTX_API_VERSION`, `BARE_OS_SESSION_ID`, `BARE_OS_BOOT_PROFILE_RESOLVED`, and when unlocked `BARE_OS_PUBLIC_KEY` (hex Ed25519 public key).
|
||||
|
||||
**Theme and color (from `~/.barerc`, `/bin/theme`, and `applyBareOsThemeFromEnv`):**
|
||||
|
||||
| Variable | Meaning |
|
||||
| ---------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `BARE_OS_THEME` | Preset name (`default`, `nord`, `dracula`, …). Set by `theme <name>` in `~/.barerc` or `/bin/theme set`. |
|
||||
| `BARE_OS_COLOR_DEPTH` | `truecolor` (default), `256` / `8bit`, or `16` / `8` / `ansi`. Downgrades truecolor **`BARE_OS_COLOR_*`** REPL sequences only; `LS_COLORS` strings stay as in the preset or `dircolors` output. |
|
||||
| `BARE_OS_COLOR_PROMPT`, `COMMAND`, `PATH`, `ENVSET`, `ENVUNSET`, `GHOST`, `SEARCH` | ANSI open sequences for fish readline (set by the active theme). |
|
||||
| `LS_COLORS` | GNU-style `ls` coloring; filled from the preset unless already set or **`BARE_OS_LS_COLORS_LOCKED=1`**. |
|
||||
| `BARE_OS_DIRCOLORS` | Path to a dircolors-format file; when set, theme apply parses it (for the current `TERM`) into `LS_COLORS`. |
|
||||
| `NO_COLOR` | When set, disables color in `ls` and other tools that honor it. |
|
||||
|
||||
---
|
||||
|
||||
## 14a. POSIX userland appendix (implemented vs gaps)
|
||||
|
||||
| Area | Status |
|
||||
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| **VFS** | Two-drive unified paths; **`$HOME`** maps to the personal Hyperdrive; writable mounts under **`/mnt`** when HDMS allows. **`mkdir`/`rmdir`**, **`chmod`** (octal + symbolic subset), **`symlink`/`readlink`**, **`stat`/`lstat`**, **`rm`** recursive, **`watch()`** on Hyperdrive paths (optional host **`BARE_OS_VFS_WATCH=0`** to disable). Synthetic **`/proc`**, **`/sys`**, **`/run`**, **`/dev`** for introspection (quotas JSON, boot JSON, initd snapshot, etc.). Empty dirs use **`.bareos_empty`** (same idea as `git-fs-adapter`). |
|
||||
| **Shell** | Pipelines (pipe between commands), list separator **`;`**, short-circuit logical-**AND** / logical-**OR** between commands, redirects **`>`** / **`>>`** / **`<`**, quoting, **`$VAR`** / **`${VAR}`**, **`$?`** / **`${?}`** (from **`BARE_OS_EXIT_STATUS`**), builtins: **`alias`**, **`unalias`**, **`cd`**, **`export`**, **`unset`**, **`readonly`**, **`umask`**, **`:`**, **`command`**, **`type`**, **`login`**, **`logout`**, **`exit`**. Branching uses **`ctx.exitCode`**. Bounded pipeline capture; optional boot-snippet allowlist (**`BARE_OS_BOOT_ALLOWLIST`** + **`/etc/bare-os/boot.allow`**). No full POSIX **`sh`** grammar. |
|
||||
| **Ownership** | Display and permission checks use **`UID`/`GID`** and mode bits; **`chown`/`chgrp`** update **`metadata.bareOs`** on the **personal** writable tree (not a multi-user host kernel). |
|
||||
| **Utilities** | Tier-1 JS **`/bin`** (**~111** commands; see §12.10): text tools include **`paste`**, **`split`**, **`tac`**, **`rev`**, **`expand`**, **`unexpand`**, **`fold`**, **`fmt`**, **`comm`**, **`join`**, **`pr`**, **`yes`** (line-capped via **`BARE_OS_YES_MAX_LINES`** / **`getconf`**), **`shuf`** (capped via **`BARE_OS_SHUF_MAX_LINES`**), **`tsort`**, **`factor`**, **`expr`** (integer-focused subset), **`numfmt`** (**`--to=iec`** / **`--to=si`**). Checksums: **`md5sum`** (bundled MD5), **`sha1sum`**, **`sha256sum`**, **`sha512sum`** (Web Crypto where available), **`sum`**, **`base32`**, **`basenc`** (**`--base16`**). Files: **`truncate`**, **`unlink`**, **`install`**, **`df`** (synthetic Hyperdrive row; **`-h`** human sizes), **`sync`** (no-op). Session stubs: **`arch`**, **`groups`**, **`hostid`**, **`nproc`**, **`uptime`**, **`users`**, **`who`**. Plus earlier parity: **`man`**, **`sed`**, **`awk`**, **`cp`** (**`-u`/`-v`/`-p`**), **`mv`**, **`find`** (**`-regex`**, **`-exec`/`-ok`**, **`BARE_OS_FIND_EXEC_MAX`**), **`mktemp`**, **`git-pear`**, **`cksum`**, **`getconf`** (includes pipeline / cap names + **`-a`**), **`xargs`**, **`dircolors`**, **`theme`**, **`ls`**, **`uniq`**, **`realpath`**, **`base64`**, **`rm`** **`-d`**, **`stat`** **`%F`**. **`dir`** / **`vdir`** call **`ls`**. Large **`sed`/`awk`** are not byte-identical to GNU on all inputs. **`mkfifo`** → **`/run/bare-os/ipc/`**. Online help: **`/share/man/man.json`** and **`man`**. |
|
||||
|
||||
**Handbook:** [handbook/09-posix-utilities-shell-and-vfs.md](handbook/09-posix-utilities-shell-and-vfs.md) — narrative catalog, engine notes, and Issue 7 alignment. **Manual pages:** [handbook/10-manpages-and-online-help.md](handbook/10-manpages-and-online-help.md).
|
||||
|
||||
Reference: Open Group POSIX.1-2017 utilities index; GNU coreutils (external) for common flag expectations where Bare aims to be similar.
|
||||
|
||||
---
|
||||
|
||||
## 15. What is intentionally out of scope in this repo
|
||||
|
||||
- **No** `node_modules` documentation (upstream packages).
|
||||
- **No** line-by-line `package-lock.json` (machine-generated).
|
||||
- **No** committed host Corestore trees, legacy `data/`, or `.test-data/` binary stores (runtime artifacts).
|
||||
|
||||
---
|
||||
|
||||
## 16. Version and tooling summary
|
||||
|
||||
| Tool | Role |
|
||||
| ----------------- | ------------------------------------------------------------ |
|
||||
| Node.js 20+ | Install, `brittle-node` tests, `node index.js` dev runs |
|
||||
| Bare ≥2 (engines) | Intended runtime for `pear run` / `bare index.js` |
|
||||
| Prettier | Format/lint at root |
|
||||
| Brittle | Test runner (`brittle-bare` protocol, `brittle-node` booter) |
|
||||
| GitHub Actions | `npm ci` + `npm test` on `main` |
|
||||
|
||||
This file was generated to satisfy **full** source documentation for the **bare-operating-system** first-party tree as of the commit that added `DOCUMENTATION.md`.
|
||||
# Documentation (moved)
|
||||
|
||||
The file-by-file inventory that lived here is now split under **[`docs/reference/`](docs/reference/README.md)**. Start at **[`docs/reference/README.md`](docs/reference/README.md)** for the index and links to every topic.
|
||||
|
||||
| Old section | New file |
|
||||
| ----------- | -------- |
|
||||
| §§1–8 | [`docs/reference/repo-layout-and-root.md`](docs/reference/repo-layout-and-root.md) |
|
||||
| §9 | [`docs/reference/kernel-image.md`](docs/reference/kernel-image.md) |
|
||||
| §10 | [`docs/reference/package-bare-os-protocol.md`](docs/reference/package-bare-os-protocol.md) |
|
||||
| §11 | [`docs/reference/package-bare-os-seeder.md`](docs/reference/package-bare-os-seeder.md) |
|
||||
| §§12.1–12.9 | [`docs/reference/package-bare-os-booter.md`](docs/reference/package-bare-os-booter.md) |
|
||||
| §§12.10–12.12 | [`docs/reference/package-bare-os-coreutils-and-ci.md`](docs/reference/package-bare-os-coreutils-and-ci.md) |
|
||||
| §13 | [`docs/reference/architecture-data-flow.md`](docs/reference/architecture-data-flow.md) |
|
||||
| §14, §14a | [`docs/reference/environment-and-posix-appendix.md`](docs/reference/environment-and-posix-appendix.md) |
|
||||
| §§15–16 | [`docs/reference/out-of-scope-and-tooling.md`](docs/reference/out-of-scope-and-tooling.md) |
|
||||
|
||||
**Docs hub:** [`docs/README.md`](docs/README.md) · **Handbook:** [`handbook/README.md`](handbook/README.md) · **Developer guide:** [`developer-guide/README.md`](developer-guide/README.md)
|
||||
|
||||
Reference in New Issue
Block a user