Raven Scott
+65
-16
@@ -20,9 +20,7 @@ bare-operating-system/
|
||||
│ └── ci.yml # GitHub Actions CI
|
||||
├── kernel/ # Files staged into the system Hyperdrive
|
||||
│ ├── init.js
|
||||
│ ├── bin/
|
||||
│ │ ├── echo
|
||||
│ │ └── help
|
||||
│ ├── bin/ # Tier-1 utilities (built from bare-os-coreutils)
|
||||
│ └── etc/
|
||||
│ └── os-release
|
||||
└── packages/
|
||||
@@ -34,6 +32,11 @@ bare-operating-system/
|
||||
│ └── lib/
|
||||
│ ├── messages.js
|
||||
│ └── channel.js
|
||||
├── bare-os-coreutils/ # Sources + build → kernel/bin/* and seeder copy
|
||||
│ ├── package.json
|
||||
│ ├── build.mjs
|
||||
│ ├── lib/runtime.js
|
||||
│ └── src/*.js
|
||||
├── bare-os-seeder/ # Publishes OS drive + MBR
|
||||
│ ├── package.json
|
||||
│ ├── index.js
|
||||
@@ -47,7 +50,9 @@ bare-operating-system/
|
||||
└── lib/
|
||||
├── paths.js
|
||||
├── swarm-disk.js
|
||||
└── kernel-runner.js
|
||||
├── kernel-runner.js
|
||||
├── vfs.js # Two-drive path routing ($HOME → personal drive)
|
||||
└── shell.js # POSIX-ish line parser + builtins
|
||||
```
|
||||
|
||||
---
|
||||
@@ -60,6 +65,7 @@ bare-operating-system/
|
||||
| `private` | `true` — not published as a single npm package |
|
||||
| `type` | `module` — ESM |
|
||||
| `workspaces` | `["packages/*"]` — npm workspaces for the three packages |
|
||||
| `scripts.pretest` | Runs `npm run build -w bare-os-coreutils` before tests |
|
||||
| `scripts.test` | Runs `npm run test --workspaces --if-present` |
|
||||
| `scripts.format` | `prettier --write .` |
|
||||
| `scripts.lint` | `prettier --check .` |
|
||||
@@ -269,12 +275,13 @@ Pear-safe path resolution (same idea as Holepunch [pear-rti](https://github.com/
|
||||
**`main()`**
|
||||
|
||||
1. Optional `console.clear()`.
|
||||
2. `Corestore(corestorePath())`, `Hyperdrive(store)`, `ready()`.
|
||||
3. `stageKernelTree`.
|
||||
4. `localRAM = Map`, `buildMbr(drive.key)`, `localRAM.set(0, mbr)`.
|
||||
5. `Hyperswarm`, on `connection`: `Protomux(socket)`, `setupSeedChannel(mux, localRAM, stream => drive.replicate(stream))`.
|
||||
6. `swarm.join(topicKey())`, `swarm.join(drive.discoveryKey)`, `flush()`.
|
||||
7. Logs topic prefix hex, full drive key hex, Corestore path.
|
||||
2. Dynamic import of `../bare-os-coreutils/build.mjs` and `await build()` (emit `/bin` scripts into `kernel/` and seeder copy).
|
||||
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)`.
|
||||
|
||||
@@ -313,7 +320,8 @@ Pear-safe path resolution (same idea as Holepunch [pear-rti](https://github.com/
|
||||
|
||||
**`executeKernel(disk, store, swarm, initSource)`** (`store`/`swarm` unused but kept for signature symmetry / future use)
|
||||
|
||||
- Builds `ctx`: `disk`, `drive`, `personalDrive`, `console`, `b4a`, `topic: topicKey()`, `readLine`, `execLine` → `runBinCommand(disk.drive, parts, ctx)`.
|
||||
- Builds `shellEnv` (`HOME`, `PATH=/bin`, `USER`, `PWD`, `SHELL`, `0`) and `createVfs(drive, personalDrive, shellEnv)` → `ctx.vfs` (same `env` object as `ctx.env`).
|
||||
- Builds `ctx`: `disk`, `drive`, `personalDrive`, `vfs`, `env`, `console`, `b4a`, `topic: topicKey()`, `readLine`, `execLine` → `execShellLine(ctx, line)` (returns `'ok'` or `'exit'`).
|
||||
- Sets `disk.os` with stub `searchLocal` ([]) and `execRpc` (`''`).
|
||||
- `runKernelFromSource(b4a.toString(initSource), ctx)`.
|
||||
|
||||
@@ -370,23 +378,51 @@ Pear-safe path resolution (same idea as Holepunch [pear-rti](https://github.com/
|
||||
|
||||
- `new AsyncFunction('ctx', source + guard + 'return start(ctx)')` where guard checks `typeof start === 'function'`.
|
||||
|
||||
**`runBinCommand(drive, argv, ctx)`**
|
||||
**`runBinCommand(ctx, argv)`**
|
||||
|
||||
- Loads `/bin/<argv[0]>`, builds `AsyncFunction('ctx','argv', ...)` requiring `run` function, invokes `run(ctx, argv)`.
|
||||
- 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', ...)` requiring `run`, invokes `run(ctx, argv)`.
|
||||
- Unknown command: `ctx.console.log('unknown command: ...')`.
|
||||
|
||||
### 12.6 [packages/bare-os-booter/test.js](packages/bare-os-booter/test.js)
|
||||
### 12.6 [packages/bare-os-booter/lib/vfs.js](packages/bare-os-booter/lib/vfs.js)
|
||||
|
||||
**`createVfs(systemDrive, personalDrive, env)`**
|
||||
|
||||
- **Logical paths** under `$HOME` (default `/home/user`) map to the **personal** Hyperdrive; 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` (file vs directory via entry + shallow children).
|
||||
|
||||
### 12.7 [packages/bare-os-booter/lib/shell.js](packages/bare-os-booter/lib/shell.js)
|
||||
|
||||
- **`tokenize` / `expandWord` / `parsePipeline`** — POSIX-ish words, `'...'`, `"..."`, `\`, `|`, `>`, `>>`, `<`; `$VAR` and `${VAR}`; pipelines split on `|`.
|
||||
- **`execShellLine(ctx, line)`** — per-simple-command: leading `NAME=value` assignments, redirections, builtins `cd`, `export`, `exit`, else `runBinCommand`. Captures `console.log` for pipes and file redirection; `>` / `>>` target paths via `ctx.vfs.writeFile` (personal tree). Returns `'exit'` when the `exit` builtin runs.
|
||||
|
||||
### 12.8 Package `bare-os-coreutils`
|
||||
|
||||
- **[packages/bare-os-coreutils/build.mjs](packages/bare-os-coreutils/build.mjs)** — `export async function build()`: concatenates `lib/runtime.js` + each `src/<name>.js`, writes to `kernel/bin/<name>` and `packages/bare-os-seeder/kernel/bin/<name>`. CLI: `node build.mjs` when executed as main.
|
||||
- **Tier-1 commands** (sources under `src/`): `ls`, `pwd`, `cat`, `test`, `basename`, `dirname`, `wc`, `head`, `tail`, `uname`, `pathchk`, `echo`, `help`. Scripts are plain `async function run(ctx, argv)` using `ctx.vfs`, `ctx.b4a`, `ctx.console`, optional `bareStdin(ctx)` — no ESM `import` (Bare-safe `AsyncFunction` load).
|
||||
|
||||
### 12.9 [packages/bare-os-booter/test.js](packages/bare-os-booter/test.js)
|
||||
|
||||
- **`testCorestoreDir(name)`** — unique directory under `__dirname/.test-data/` (must exist parent via `mkdirSync`).
|
||||
|
||||
Tests:
|
||||
|
||||
1. **`runKernelFromSource`** with inline `start` pushing to `ctx.calls`.
|
||||
2. **`runBinCommand`** with `/bin/hello` script pushing joined argv to `ctx.out`; `store.close()`, `rmSync` dir.
|
||||
3. **Hyperdrive** put/get `/boot/init.js` on Corestore; `drive.close()`, `rmSync`.
|
||||
2. **`runBinCommand`** with `/bin/hello` and full `ctx` (`createVfs` + system/personal drives).
|
||||
3. **`createStreamLineReader`** newline behavior.
|
||||
4. **Hyperdrive** put/get `/boot/init.js`.
|
||||
5. **`createVfs`** — write under `$HOME` lands on personal drive only.
|
||||
6. **Shell** — `tokenize`, `expandWord`, `execShellLine` (`cd`, external from `/bin`).
|
||||
7. **Tier-1 `cat`** — loads concatenated script from repo `kernel/bin/cat`.
|
||||
|
||||
Uses Node builtins: `node:fs`, `node:path`, `node:url`.
|
||||
|
||||
### 12.10 Seeder: coreutils build hook
|
||||
|
||||
- **[packages/bare-os-seeder/index.js](packages/bare-os-seeder/index.js)** — at start of `main()`, dynamic `import('../bare-os-coreutils/build.mjs')` then `await build()` so staging always picks up emitted `/bin` scripts.
|
||||
|
||||
---
|
||||
|
||||
## 13. End-to-end data flow
|
||||
@@ -424,6 +460,19 @@ 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.8). `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.
|
||||
|
||||
---
|
||||
|
||||
## 15. What is intentionally out of scope in this repo
|
||||
|
||||
- **No** `node_modules` documentation (upstream packages).
|
||||
|
||||
Reference in New Issue
Block a user