Raven Scott
+28
-23
@@ -12,6 +12,9 @@ bare-operating-system/
|
||||
├── 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 … 07-operations-and-development.md
|
||||
├── LICENSE # Apache-2.0 notice
|
||||
├── .gitignore # Ignore rules
|
||||
├── .prettierrc # Prettier formatting defaults
|
||||
@@ -94,6 +97,8 @@ No runtime dependencies at the root; all stack deps live in workspace packages.
|
||||
|
||||
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 (repo-root `data/`), 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)
|
||||
@@ -296,15 +301,15 @@ Pear-safe path resolution (same idea as Holepunch [pear-rti](https://github.com/
|
||||
|
||||
### 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` |
|
||||
| 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 |
|
||||
| `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.
|
||||
|
||||
@@ -467,15 +472,15 @@ sequenceDiagram
|
||||
|
||||
## 14. Environment variables (complete list)
|
||||
|
||||
| Variable | Used by | Meaning |
|
||||
| ---------------------- | ------- | --------------------------------------------------------------------- |
|
||||
| `BARE_OS_KERNEL_ROOT` | Seeder | Absolute path to kernel tree (default: `repo/kernel`) |
|
||||
| `BARE_OS_SEED_STORE` | Seeder | Corestore directory (default: `repo/data/corestore-seeder`) |
|
||||
| `BARE_OS_BOOT_STORE` | Booter | Corestore for boot side (default: `repo/data/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 |
|
||||
| Variable | Used by | Meaning |
|
||||
| ------------------------- | ------- | ---------------------------------------------------------------------------------------------- |
|
||||
| `BARE_OS_KERNEL_ROOT` | Seeder | Absolute path to kernel tree (default: `repo/kernel`) |
|
||||
| `BARE_OS_SEED_STORE` | Seeder | Corestore directory (default: `repo/data/corestore-seeder`) |
|
||||
| `BARE_OS_BOOT_STORE` | Booter | Corestore for boot side (default: `repo/data/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 |
|
||||
|
||||
**Session env (set by booter, not user configuration):** `USER`, `LOGNAME`, `HOME`, `PWD`, `UID`, `GID`, `GROUP`, `BARE_OS_IDENTITY` (`guest` or `unlocked`), and when unlocked `BARE_OS_PUBLIC_KEY` (hex Ed25519 public key).
|
||||
|
||||
@@ -483,12 +488,12 @@ sequenceDiagram
|
||||
|
||||
## 14a. POSIX userland appendix (implemented vs gaps)
|
||||
|
||||
| Area | Status |
|
||||
|------|--------|
|
||||
| **VFS** | Two-drive unified paths; `$HOME` → personal Hyperdrive; mutations outside `$HOME` rejected. |
|
||||
| **Shell** | Quoting, `|`, `>`/`>>`/`<`, `cd`, `export`, `exit`, `$VAR` / `${VAR}`, `$PATH` for `/bin` discovery. No `&&`/`||`, job control, or full POSIX `sh` grammar. |
|
||||
| **Hyperdrive limits** | No real `chmod`/`chown`; executable bit only via `put(..., { executable })` where supported. |
|
||||
| **Utilities** | Tier-1 JS ports in `/bin` (see §12.10). `test` sets `ctx.exitCode`; the shell does not yet branch on it for `&&`. |
|
||||
| Area | Status |
|
||||
| --------------------- | ----------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | --- | ------------------------------------------- |
|
||||
| **VFS** | Two-drive unified paths; `$HOME` → personal Hyperdrive; mutations outside `$HOME` rejected. |
|
||||
| **Shell** | Quoting, ` | `, `>`/`>>`/`<`, `cd`, `export`, `exit`, `$VAR` / `${VAR}`, `$PATH`for`/bin`discovery. No`&&`/` | | `, job control, or full POSIX `sh` grammar. |
|
||||
| **Hyperdrive limits** | No real `chmod`/`chown`; executable bit only via `put(..., { executable })` where supported. |
|
||||
| **Utilities** | Tier-1 JS ports in `/bin` (see §12.10). `test` sets `ctx.exitCode`; the shell does not yet branch on it for `&&`. |
|
||||
|
||||
Reference: GNU coreutils sources (external) for flag behavior; POSIX.1 utilities for intended semantics.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user