Update man to add the manual guide
This commit is contained in:
Raven Scott
+22
-13
@@ -14,7 +14,7 @@ bare-operating-system/
|
||||
├── DOCUMENTATION.md # This file
|
||||
├── handbook/ # Narrative handbook (chapters + diagrams)
|
||||
│ ├── README.md # Index + links to chapters
|
||||
│ ├── 01-introduction.md … 07-operations-and-development.md
|
||||
│ ├── 01-introduction.md … 09-posix-utilities-shell-and-vfs.md
|
||||
├── LICENSE # Apache-2.0 notice
|
||||
├── .gitignore # Ignore rules
|
||||
├── .prettierrc # Prettier formatting defaults
|
||||
@@ -39,6 +39,7 @@ bare-operating-system/
|
||||
│ ├── 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
|
||||
@@ -335,7 +336,7 @@ Pear-safe path resolution (same idea as Holepunch [pear-rti](https://github.com/
|
||||
- Builds `shellEnv` with **guest** defaults: `USER`/`LOGNAME`=`guest`, `HOME`/`PWD`=`/home/guest`, `UID`/`GID`=`65534`, `BARE_OS_IDENTITY=guest`, `PATH=/bin`, `SHELL`, `HOSTNAME`, `0`. `createVfs(drive, personalDrive, shellEnv)` → `ctx.vfs` (same `env` object as `ctx.env`).
|
||||
- **`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`: `disk`, `drive`, `personalDrive`, `vfs`, `env`, `console`, `b4a`, `topic: topicKey()`, `readLine`, **`writeScreen(str)`**, `execLine` → `execShellLine(ctx, line)` (returns `'ok'` or `'exit'`), plus identity hooks for `/bin` and builtins:
|
||||
- Builds `ctx`: `disk`, `drive`, `personalDrive`, `vfs`, `env`, `console`, `b4a`, `topic: topicKey()`, `readLine`, **`writeScreen(str)`**, `execLine` → `execShellLine(ctx, line)` (returns `'ok'` or `'exit'`), **`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.
|
||||
@@ -403,19 +404,21 @@ Pear-safe path resolution (same idea as Holepunch [pear-rti](https://github.com/
|
||||
- Builds `AsyncFunction('ctx','argv', ...)` requiring `run`, invokes `run(ctx, argv)`.
|
||||
- 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)`**
|
||||
|
||||
- **Logical paths** under `$HOME` (booter default `/home/guest`; after `login`, `/home/<pubkey-prefix>`) 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).
|
||||
- **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`.
|
||||
- **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.
|
||||
|
||||
### 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`, `login`, `logout`, `exit`, else `runBinCommand`. `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.
|
||||
- **`execShellLine(ctx, line)`** — per-simple-command: leading `NAME=value` assignments (blocked for `ctx.shellReadonlyVars`), redirections, builtins `alias`, `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.
|
||||
|
||||
### 12.8 [packages/bare-os-booter/lib/identity-account.js](packages/bare-os-booter/lib/identity-account.js)
|
||||
|
||||
@@ -429,8 +432,10 @@ Pear-safe path resolution (same idea as Holepunch [pear-rti](https://github.com/
|
||||
|
||||
### 12.10 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.
|
||||
- **Commands** (sources under `src/`, list in `build.mjs`): `basename`, `cat`, `clear`, `crontab`, `date`, `dirname`, `echo`, `env`, `exit`, `false`, `grep`, `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`. Scripts are plain `async function run(ctx, argv)` using `ctx.vfs`, `ctx.drive`, `ctx.b4a`, `ctx.console`, optional `bareStdin(ctx)` — no ESM `import` (Bare-safe `AsyncFunction` load).
|
||||
- **[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 (`sed` → `lib/sed-engine.js`, `awk` → `lib/awk-engine.js`, **`man`** → `lib/man-render.js`), then `src/<name>.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`**): `awk`, `basename`, `cat`, `chgrp`, `chmod`, `chown`, `cksum`, `clear`, `cp`, `crontab`, `cut`, `date`, `dirname`, `du`, `echo`, `env`, `exit`, `false`, `find`, `getconf`, `grep`, `head`, `hdms`, `help`, `hostname`, `id`, `ln`, `login`, `logout`, `logname`, `ls`, `man`, `mkdir`, `mkfifo`, `mv`, `nl`, `od`, `pathchk`, `printenv`, `printf`, `pwd`, `readlink`, `rm`, `rmdir`, `savevault`, `sed`, `seq`, `sleep`, `sort`, `stat`, `tail`, `tee`, `test`, `time`, `touch`, `tr`, `true`, `tty`, `uname`, `wc`, `which`, `whoami`, `xargs`. 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). **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)
|
||||
|
||||
@@ -481,6 +486,8 @@ sequenceDiagram
|
||||
| `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 |
|
||||
| `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 |
|
||||
|
||||
**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).
|
||||
|
||||
@@ -488,14 +495,16 @@ 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; writable mounts under `/mnt` when HDMS allows. **`mkdir`/`rmdir`**, **`chmod`** (octal + symbolic subset), **`symlink`/`readlink`**, **`stat`/`lstat`**, **`rm`** recursive. Empty dirs use **`.bareos_empty`** (same idea as `git-fs-adapter`). |
|
||||
| **Shell** | Pipelines `\|`, redirects `>`/`>>`/`<`, quoting, `$VAR`/`${VAR}`, builtins: **`alias`**, **`unalias`**, **`cd`**, **`export`**, **`unset`**, **`readonly`**, **`umask`**, **`:`**, **`command`**, **`type`**, **`login`**, **`logout`**, **`exit`**. No **`&&`/`||`**, job control, functions, or full POSIX **`sh`** grammar. |
|
||||
| **Ownership** | Display and permission checks use **`UID`/`GID`** and mode bits; **`chown`/`chgrp`** are stubs (no multi-user ownership changes). |
|
||||
| **Utilities** | Tier-1 JS **`/bin`** (see §12.10): includes **`man`**, **`sed`**, **`awk`**, **`cp`**, **`mv`**, **`find`**, **`cksum`**, etc. Large **`sed`/`awk`** are not byte-identical to GNU on all inputs. **`xargs`**, **`getconf`**, **`mkfifo`** are stubs. **`test`** sets **`ctx.exitCode`**; the shell does not branch on it for **`&&`**. Online help: **`/share/man/man.json`** and **`man`**. |
|
||||
|
||||
Reference: GNU coreutils sources (external) for flag behavior; POSIX.1 utilities for intended semantics.
|
||||
**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.
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user