TNT-Flo/bare-operating-system
1
0
Fork 0
forked from snxraven/bare-operating-system
Code Pull Requests Activity

Update man to add the manual guide

Browse Source
This commit is contained in:
Raven Scott
2026-04-03 05:28:49 -04:00
parent 11cac45df6
commit 2d26a0b8d1
174 changed files with 17092 additions and 198 deletions
Download Patch File Download Diff File Expand all files Collapse all files
handbook/04-the-booter-runtime.md
+5 -1
View File
@@ -39,6 +39,10 @@ Cleanup path closes swarm/drives and calls **`session.cleanup()`**, which runs *
Virtual listings include **`/home`** (session-specific) and **`/mnt`** when HDMS mounts exist.
**Directories:** **`vfs.mkdir(path, { recursive })`** and **`vfs.rmdir(path)`** implement POSIX-like tree creation and removal using a **`.bareos_empty`** marker file for empty directories (aligned with **`git-fs-adapter`**). See [Chapter 9](09-posix-utilities-shell-and-vfs.md).
**`ctx.runBinCommand(argv)`** — same resolution as external commands in the shell; exposed for utilities such as **`/bin/time`**.
---
## Shell and kernel runner
@@ -46,7 +50,7 @@ Virtual listings include **`/home`** (session-specific) and **`/mnt`** when HDMS
**`execShellLine`** (`lib/shell.js`):
- Tokenizes words, quotes, escapes, **`$VAR`**, pipelines **`|`**, redirections **`>` / `>>` / `<`**.
- Builtins: **`alias`**, **`unalias`**, **`cd`**, **`export`**, **`login`**, **`logout`**, **`exit`** — plus external commands via **`runBinCommand`**.
- Builtins: **`alias`**, **`unalias`**, **`cd`**, **`export`**, **`unset`**, **`readonly`**, **`umask`**, **`:`**, **`command`**, **`type`**, **`login`**, **`logout`**, **`exit`** — plus external commands via **`runBinCommand`**. **`readonly`** blocks **`export`** and assignment writes to the same name; **`command -v` / `-V`** and **`type`** use **`resolveBinInPath`** for **`PATH`** lookup.
- First-word **aliases** (defaults like **`ll` → `ls -la`**) expand after **`$VAR`** substitution; **`alias`** / **`unalias`** match the restricted **`~/.barerc`** syntax (not full POSIX **`sh`**).
- Pipes capture **`console.log`** into the next stage or a string sink.
handbook/06-kernel-and-binaries.md
+43 -31
View File
@@ -25,13 +25,17 @@ The **prompt** (`[user@host:path] > `) is applied by the booter’s readline lay
```
packages/bare-os-coreutils/lib/runtime.js
+
(optional) packages/bare-os-coreutils/lib/<engine>.js ← sed-engine, awk-engine
+
packages/bare-os-coreutils/src/<cmd>.js
↓ (build.mjs)
↓ (build.mjs, see preamble map)
kernel/bin/<cmd>
packages/bare-os-seeder/kernel/bin/<cmd> ← Pear vendored copy
```
**Rule:** no `import` in `src/*.js` — only `async function run(ctx, argv)` (shared helpers live in **`lib/runtime.js`**).
**Rule:** no `import` in `src/*.js` — only `async function run(ctx, argv)` (shared helpers live in **`lib/runtime.js`**). Large **`sed`** and **`awk`** bodies live in **`lib/*-engine.js`** and are prepended at build time (same global scope as **`run`**).
**Full POSIX-style catalog, stubs, and divergence notes:** [Chapter 9 — POSIX utilities, shell, and VFS](09-posix-utilities-shell-and-vfs.md).
### File metadata and permissions (not full POSIX)
@@ -41,34 +45,42 @@ Hyperdrive entries carry optional **`metadata.bareOs`** (mode, uid, gid, names,
## Command reference (summary)
| Command | Role |
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `basename`, `dirname` | Path manipulation |
| `cat`, `head`, `tail`, `nl` | Text |
| `clear` | ANSI clear screen |
| `crontab` | `-l` list, `-r` remove, `<file>` install (`~/.crontab`; writes need login) |
| `date` | Date/time |
| `echo`, `printf`-like simplicity | Args to stdout |
| `env`, `printenv` | Environment |
| `exit` | Sets exit code / session end via booter |
| `false`, `true` | Status |
| `grep` | Line filter: `-E`/`-F`, `-i`, `-v`, `-n`, `-c`, `-l`, `-q`, `-s`, `-e`, `-f`, `-H`/`-h`; JS `RegExp`, not full GNU/PCRE |
| `hdms` | Hyperdrive management CLI |
| `help` | Lists builtins + `/bin` |
| `hostname` | Host string |
| `id`, `whoami`, `tty` | Identity / TTY |
| `login`, `logout` | Account session |
| `ls` | Lists directories; **hides `.*` unless `-a`**; **`-l`** uses real mode, owner, group, mtime from VFS stat |
| `chmod` | Octal mode only (e.g. **`chmod 644 file`**) on the personal drive; updates stored metadata + executable bit |
| `pathchk` | Path sanity |
| `pwd` | Logical cwd |
| `rm` | Remove files; **`-r`/`-R`/`--recursive`** for directories, **`-f`/`--force`** (bundled **`-rf`**) — uses VFS tree walk + `del` per entry |
| `savevault` | Encrypted vault snapshot |
| `seq`, `sleep`, `sort` | Misc |
| `test`, `[` | Conditionals (as implemented) |
| `touch` | Create/empty files |
| `uname` | OS string |
| `wc`, `which` | Text / PATH lookup |
| Command | Role |
| ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `basename`, `dirname` | Path manipulation |
| `cat`, `head`, `tail`, `nl` | Text |
| `clear` | ANSI clear screen |
| `crontab` | `-l` list, `-r` remove, `<file>` install (`~/.crontab`; writes need login) |
| `date` | Date/time |
| `echo`, `printf`-like simplicity | Args to stdout |
| `env`, `printenv` | Environment |
| `exit` | Sets exit code / session end via booter |
| `false`, `true` | Status |
| `grep` | Line filter: `-E`/`-F`, `-i`, `-v`, `-n`, `-c`, `-l`, `-q`, `-s`, `-e`, `-f`, `-H`/`-h`; JS `RegExp`, not full GNU/PCRE |
| `hdms` | Hyperdrive management CLI |
| `help` | Lists builtins + `/bin` |
| `hostname` | Host string |
| `id`, `whoami`, `tty` | Identity / TTY |
| `login`, `logout` | Account session |
| `ls` | Lists directories; **hides `.*` unless `-a`**; **`-l`** uses real mode, owner, group, mtime from VFS stat |
| `chmod` | **Octal** (e.g. **`644`**) or **symbolic** (e.g. **`u+rw`**) on writable drives; updates stored metadata + executable bit |
| `mkdir`, `rmdir` | **`mkdir -p`**; empty dirs use **`.bareos_empty`** (see ch. 9) |
| `cp`, `mv`, `ln` | **`cp -R`**, **`mv`** (copy+delete trees), **`ln -s`** only (no hard links) |
| `stat`, `readlink` | File metadata and symlink targets |
| `printf`, `cut`, `tr`, `od` | Formatting and text transforms (ASCII-oriented **`tr`**) |
| `sed`, `awk` | Large JavaScript engines in **`lib/*-engine.js`** — not byte-identical to GNU/POSIX everywhere; see ch. 9 |
| `tee`, `find`, `du`, `cksum` | Pipe tee, limited **`find`**, **`du -k`**, POSIX CRC **`cksum`** |
| `time`, `logname` | Wall-clock **`time`** via **`ctx.runBinCommand`**; identity string |
| `xargs`, `getconf`, `chown`, `chgrp`, `mkfifo` | Stubs with explicit “not supported” messages |
| `pathchk` | Path sanity |
| `pwd` | Logical cwd |
| `rm` | Remove files; **`-r`/`-R`/`--recursive`** for directories, **`-f`/`--force`** (bundled **`-rf`**) — uses VFS tree walk + `del` per entry |
| `savevault` | Encrypted vault snapshot |
| `seq`, `sleep`, `sort` | Misc |
| `test`, `[` | Conditionals (as implemented) |
| `touch` | Create/empty files |
| `uname` | OS string |
| `wc`, `which` | Text / PATH lookup |
Exact flags vary—read each **`src/<cmd>.js`** for truth.
@@ -89,4 +101,4 @@ Update **`kernel/init.js`** and **`packages/bare-os-seeder/kernel/init.js`** if
---
[← Identity and HDMS](05-identity-vault-and-hdms.md) · [Handbook home](README.md) · [Next: Operations →](07-operations-and-development.md)
[← Identity and HDMS](05-identity-vault-and-hdms.md) · [Handbook home](README.md) · [POSIX utilities & shell (detail) →](09-posix-utilities-shell-and-vfs.md) · [Next: Operations →](07-operations-and-development.md)
handbook/07-operations-and-development.md
+1 -1
View File
@@ -117,4 +117,4 @@ Prettier config: **no semicolons**, **single quotes** (`.prettierrc`).
---
[← Kernel and binaries](06-kernel-and-binaries.md) · [Handbook home](README.md)
[← Kernel and binaries](06-kernel-and-binaries.md) · [Handbook home](README.md) · [Next: Git on Bare OS →](08-git-on-bare-os.md) · [POSIX alignment (detail) →](09-posix-utilities-shell-and-vfs.md)
handbook/08-git-on-bare-os.md
+4
View File
@@ -17,3 +17,7 @@ The `git` command in this project is **not** the GNU Git binary. It is a small C
- Use **`git --help`** inside Bare OS for the supported subcommand list.
- Unsupported subcommands print a short message; for full API behavior, see the [isomorphic-git documentation](https://isomorphic-git.org/docs/en/next/alphabetic).
---
[← Operations and development](07-operations-and-development.md) · [Handbook home](README.md) · [Next: POSIX utilities and shell →](09-posix-utilities-shell-and-vfs.md)
handbook/09-posix-utilities-shell-and-vfs.md
+175
View File
@@ -0,0 +1,175 @@
# Chapter 9 — POSIX-style utilities, shell builtins, and VFS alignment
Bare OS targets a **usable subset** of [POSIX.1-2017](https://pubs.opengroup.org/onlinepubs/9699919799/toc.htm) **XCU** (utilities) and shell-like behavior. It does **not** implement a full POSIX kernel, process model, job control, or a complete **`sh`**. This chapter documents what ships today, how it differs from the standard, and where to look in source.
**Normative reference:** Open Group **Issue 7** — use the online utilities index for intended semantics; Bare behavior may intentionally diverge where Hyperdrive or the single-process runtime makes full compliance impossible.
---
## 1. Executive summary: what is _not_ POSIX here
| Expectation (full POSIX) | Bare OS reality |
| ---------------------------------------------- | ------------------------------------------------------------------------------- |
| **`sh`** grammar (`if`, `for`, `&&`, `\|`, …) | Line-at-a-time shell: builtins + `/bin` only; no compound commands. |
| **Processes, `fork`, pipes as OS primitives** | Pipelines are simulated by capturing **`console.log`** into the next command. |
| **`chown` / `chgrp` / real UIDs across users** | Single-session identity; metadata carries **uid/gid** for display and checks. |
| **FIFOs, `mknod`, real devices** | Not available; **`mkfifo`** is a documented stub. |
| **`xargs` spawning arbitrary programs** | Stub only — use the shell to build argument lists. |
| **`getconf` / `sysconf`** | Stub — no host kernel sysconf surface. |
| **Byte-identical `sed` / `awk` / `grep`** | JavaScript engines; regex and edge cases differ from GNU or strict POSIX. |
For the **`/bin` build contract** (no `import`, `AsyncFunction` load), see [Chapter 6](06-kernel-and-binaries.md).
---
## 2. VFS: directories, metadata, and empty folders
**[`packages/bare-os-booter/lib/vfs.js`](../packages/bare-os-booter/lib/vfs.js)** exposes a unified path space over the **system** and **personal** Hyperdrives (see [Chapter 4](04-the-booter-runtime.md)).
### 2.1 Empty directories (`.bareos_empty`)
Hyperdrive does not always behave like a POSIX directory tree. Empty directories are represented by a hidden marker file **`.bareos_empty`**, consistent with **[`git-fs-adapter.js`](../packages/bare-os-booter/lib/git-fs-adapter.js)** and [Chapter 8 — Git](08-git-on-bare-os.md). **`readdir`** on the raw VFS may list that name; **`git`** paths filter it.
### 2.2 `mkdir` and `rmdir`
- **`vfs.mkdir(path, { recursive })`** — creates directories by writing **`dirname/.bareos_empty`**. **`-p` / `--parents`** is implemented by **`/bin/mkdir`**.
- **`vfs.rmdir(path)`** — removes a directory only if it has **no entries other than** `.bareos_empty` (and removes the marker).
### 2.3 `chmod` (octal and symbolic)
**`/bin/chmod`** accepts:
- **Octal** modes (e.g. **`644`**, **`0755`**) — passed through to **`vfs.chmod`** (permission bits; type bits come from the existing entry).
- **Symbolic** modes (e.g. **`u+rw`**, **`go-w`**) — a supported subset of POSIX symbolic **`chmod`**; see **`packages/bare-os-coreutils/src/chmod.js`**.
There is **no** **`chown`** / **`chgrp`** that changes stored ownership in a multi-user sense; stubs explain the limitation.
### 2.4 Copy and move
- **`cp`** — **`-R`/`-r`** recursive copy; follows the same marker convention (skips copying **`.bareos_empty`** as a separate “file” where appropriate).
- **`mv`** — copy-tree + **`vfs.rm`** on the source (no single-key atomic rename API in the VFS).
---
## 3. Shell builtins (`packages/bare-os-booter/lib/shell.js`)
Beyond **`alias`**, **`unalias`**, **`cd`**, **`export`**, **`login`**, **`logout`**, **`exit`**:
| Builtin | Behavior |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **`unset`** | Removes variables from **`vfs.env`**; refuses **readonly** names (POSIX-style error). |
| **`readonly`** | Marks names readonly; **`readonly NAME=value`** sets and locks. Blocks **`export`** and leading assignments on readonly keys. |
| **`umask`** | With an argument, sets **`env.UMASK`** (octal string); without, prints the current mask (default **022** if unset). |
| **`:`** | No-op (exit status 0). |
| **`command`** | **`-v`** / **`-V`**: prints **builtin** name or resolved **`PATH`** location via **`resolveBinInPath`**. Otherwise runs **`runBinCommand`** with the remaining words (external commands only for that path). |
| **`type`** | **`type NAME`** — “builtin” vs resolved **`/bin/...`** path or “not found”. |
**`~/.barerc`** remains **restricted** ( **`export`**, **`alias`**, **`unalias`**, comments only) — see [Chapter 4](04-the-booter-runtime.md).
---
## 4. Booter `ctx` helpers
- **`ctx.runBinCommand(argv)`** — same resolution as the shell’s external dispatch ( **`PATH`** on the system drive, `*.js` in **`$PWD`**, explicit paths). Used by **`/bin/time`** to run another utility and report wall time.
- **`resolveBinInPath(ctx, name)`** in **`kernel-runner.js`** — used by **`command -v`** / **`type`**.
---
## 5. `/bin` utilities (catalog)
Sources: **`packages/bare-os-coreutils/src/<name>.js`**. **Authoritative list:** **`packages/bare-os-coreutils/build.mjs`**.
### 5.1 Filesystem and links
| Command | Notes |
| -------------- | ------------------------------------------------------------------------------------------------------------------------ |
| **`mkdir`** | **`-p` / `--parents`** for recursive create. |
| **`rmdir`** | Empty directories only (marker-aware). |
| **`cp`** | **`-R`/`-r`/`--recursive`** for trees. |
| **`mv`** | Multi-source → directory; recursive directory moves via copy + delete. |
| **`ln`** | **Symbolic links only** (**`-s`**): hard links are not supported on Hyperdrive entries. |
| **`stat`** | Human-readable **`stat`**-style block (not full **`stat -c`** format strings). |
| **`readlink`** | **`-n`** requested in argv; output still goes through **`console.log`** (trailing newline behavior may differ from GNU). |
### 5.2 Text and binary viewing
| Command | Notes |
| --------- | ----------------------------------------------------------------------- |
| **`cut`** | **`-d`** delimiter, **`-f`** field list (numeric and ranges). |
| **`tr`** | **`-d`** delete set, or **set1** **set2** mapping (byte/char oriented). |
| **`od`** | Hex-ish dump (fixed width); not full POSIX **`od`** flag matrix. |
| **`tee`** | **`-a`** append; duplicates stdin to files and stdout. |
| **`sed`** | Large subset — see §6. |
| **`awk`** | Substantial interpreter — see §7. |
### 5.3 Discovery and measurement
| Command | Notes |
| ------------- | -------------------------------------------------------------------------------------------------------- |
| **`find`** | **`-maxdepth`**, **`-name`** (glob-to-regex), **`-type`** **`f`**/**`d`**/**`l`**. |
| **`du`** | **`-k`** for 1024-byte blocks; otherwise 512-byte units (POSIX-ish). |
| **`cksum`** | **POSIX / Open Group CRC** + length + name (matches common **`cksum`** on BSD/macOS for the same bytes). |
| **`printf`** | Subset of **`printf(1)`** conversions (**`%s`**, **`%d`**, **`%o`**, **`%x`**, etc.). |
| **`logname`** | Prints **`LOGNAME`** / **`USER`** / **`guest`**. |
| **`time`** | Times **`ctx.runBinCommand`** for the rest of the line; prints **`real`** to stderr. |
### 5.4 Intentional stubs (fail with a clear message)
| Command | Reason |
| ------------------------ | -------------------------------------------------------------------------------- |
| **`xargs`** | No safe generic “spawn any argv” from **`/bin`** in this runtime; use the shell. |
| **`getconf`** | No **`sysconf`** path. |
| **`chown`**, **`chgrp`** | Ownership changes not modeled for multi-user Hyperdrive. |
| **`mkfifo`** | No FIFO VFS. |
All other commands from **`build.mjs`** not listed here follow the summaries in [Chapter 6](06-kernel-and-binaries.md) or their **`src/*.js`** files.
---
## 6. `sed` implementation
**Engine:** **`packages/bare-os-coreutils/lib/sed-engine.js`** (prepended before **`src/sed.js`** at build time).
**CLI:** **`sed`** supports **`-n`**, **`-E`/`-r`**, multiple **`-e`**, **`-f`**, and operands as files or stdin.
**Broadly supported:** line addresses (**`#`**, **`$`**, **`/re/`**, ranges, **`first~step`**), **`s///`** with common flags (**`g`**, **`p`**, digit), **`y///`**, **`d`/`D`/`p`/`P`/`n`/`N`**, hold space (**`h`/`H`/`g`/`G`/`x`**), **`b`/`t`/`:label`**, **`q`**, **`r`/`w`**, **`=`**, **`l`**, **`a`/`i`/`c`** (backslash forms). **`r`** reads paths via a preload scan + **`vfs.readFile`**; **`w`** appends via **`vfs.writeFile`**.
**Not guaranteed:** full GNU **`sed`** extensions, every POSIX corner case (e.g. all **`s`** flag combinations, locale collation), or **`s`** delimiter edge cases identical to every implementation.
---
## 7. `awk` implementation
**Engine:** **`packages/bare-os-coreutils/lib/awk-engine.js`** (prepended before **`src/awk.js`**).
**CLI:** **`-F`**, **`-v name=value`** (implemented as a synthetic **`BEGIN`** assignment), **`-f`**, program string, then optional input files (stdin if none).
**Broadly supported:** **`BEGIN`/`END`**, regex and expression patterns, **`print`/`printf`** with redirection to files, **`if`/`while`/`for`/`for (i in arr)`**, arrays, **`next`/`exit`**, many builtins (**`length`**, **`substr`**, **`index`**, **`split`**, **`sprintf`**, **`sub`/`gsub`**, **`match`**, **`int`**, **`tolower`/`toupper`**, **`rand`/`srand`**), **`ENVIRON["VAR"]`**, user-defined **`function`**.
**Known limitations:** **`/`** in expressions is always a regex literal in the lexer (division is ambiguous in real **`awk`** — use spaces or refactor); **`getline`** from files is incomplete; **`print`** to files is queued and flushed per statement batch — fine for typical scripts but not identical to every **`awk`** I/O timing. Not **gawk**-compatible for extensions.
---
## 8. Coreutils build: preamble map
**[`build.mjs`](../packages/bare-os-coreutils/build.mjs)** concatenates:
1. **`lib/runtime.js`**
2. Optional extra libs from the **`preamble`** map (**`sed` → `sed-engine.js`**, **`awk` → `awk-engine.js`**)
3. **`src/<cmd>.js`**
There is still **no `import`** in **`src/*.js`** — large utilities are **vendored as plain script** chunks in **`lib/`**.
---
## 9. Where to read next
- [Chapter 6 — Kernel and `/bin` summary](06-kernel-and-binaries.md)
- [Chapter 4 — Shell and VFS routing](04-the-booter-runtime.md)
- [Chapter 10 — Manual pages (`man`) and online help](10-manpages-and-online-help.md)
- [DOCUMENTATION.md §12.6–§12.10](../DOCUMENTATION.md) — file-level inventory
- [bare-os-coreutils README](../packages/bare-os-coreutils/README.md) — build and command contract
---
[← Git on Bare OS](08-git-on-bare-os.md) · [Handbook home](README.md) · [Manual pages →](10-manpages-and-online-help.md)
handbook/10-manpages-and-online-help.md
+112
View File
@@ -0,0 +1,112 @@
# Chapter 10 — Manual pages (`man`) and online help
Bare OS ships a **`man(1)`**-style viewer backed by a **JSON manual database** on the system Hyperdrive, not `troff`, `mandoc`, or `groff`. This matches the project’s model: utilities are **`AsyncFunction`** scripts, and documentation must load without a host typesetter.
---
## Purpose
- **Familiar UX:** Users expect **`man ls`**, **`man -k pattern`** (apropos), and **`man -f name`** (whatis).
- **Shippable:** Pages live at **`/share/man/man.json`** (staged from **`kernel/share/man/man.json`**), merged at build time from **`packages/bare-os-coreutils/man/pages/*.json`**.
- **Verifiable:** The build fails if any **`/bin`** command from [`lib/commands.mjs`](../packages/bare-os-coreutils/lib/commands.mjs) lacks a page.
---
## Sections
| Section | Content |
| ------- | ------- |
| **1** | User commands — every name in **`COREUTILS_COMMANDS`**, including **`man`** itself. |
| **1** | **`bare-os-shell`** — one manual for **all** interactive shell builtins (`cd`, `export`, …), so we do not maintain dozens of one-line stubs. |
| **7** | **Handbook** — every **`handbook/*.md`** file is merged at build time as **`man(7)`** (POSIX “miscellaneous”). TOC: **`man handbook`** or **`man 7 bare-os-handbook`** (alias **`handbook`**). Chapters: **`man handbook-01-introduction`**, **`man 7 handbook-02-blueprints`**, … **`mermaid`** diagrams are omitted in the terminal view; open the Markdown in the repo for figures. |
**`git`** is not a `/bin` script (it is delegated in the booter to **`git-cli.js`**), but it still has a **section 1** page **`git`** in the same database.
---
## CLI surface (`/bin/man`)
| Invocation | Behavior |
| ---------- | -------- |
| `man` | Short usage and pointer to **`man -l`**. |
| `man name` | Show manual for **`name`** (any section if the name is unique, e.g. **`man ls`** or **`man handbook`**). |
| `man 1 name` / `man 7 name` | Require that section; fails if the page lives in another section (e.g. **`man 7 ls`** fails). |
| `man -l` | List **`name(section)`** for every page, sorted by name. |
| `man -k word` | Apropos: pages whose keywords / title / name match **`word`** (substring, case-insensitive). |
| `man -f name` | Whatis: one-line **`name(section) - title`** for an exact **`name`** match. |
**Environment**
| Variable | Effect |
| -------- | ------ |
| **`MANWIDTH`** | Wrap width for prose (default **72**, minimum **40**). |
**Exit status**
| Code | Meaning |
| ---- | ------- |
| **0** | Success (page shown or list empty for **`man -k`** with no matches). |
| **1** | Page not found or **`man.json`** missing on the system drive. |
| **2** | Invalid usage. |
---
## JSON page model
Authoritative schema: **[`packages/bare-os-coreutils/man/schema.json`](../packages/bare-os-coreutils/man/schema.json)**.
Each **`man/pages/<name>.json`** describes one page:
- **`name`**, **`section`**, **`title`** — NAME header.
- **`synopsis`** — string array (usage lines).
- **`description`** — multi-sentence DESCRIPTION.
- **`options`** — `{ "flag": string, "meaning": string }[]`.
- **`environment`**, **`files`** — optional string arrays.
- **`exitStatus`**, **`diagnostics`** — optional string arrays.
- **`seeAlso`** — `{ "name": string, "section": number }[]`.
- **`bareOsNotes`** — optional string; POSIX / GNU divergence.
- **`keywords`** — lowercase tokens for **`man -k`**.
- **`aliases`** — optional alternate lookup names (e.g. **`sh-builtins`** → **`bare-os-shell`**).
- **`stub`** — if true, the command is a stub or intentionally limited.
- **`examples`** — optional array of **`{ "caption"?: string, "code": string }`** (cheat.sh–style: short label + copy-paste command; **`code`** may use newlines for multi-line snippets). Rendered under an **EXAMPLES** heading after **OPTIONS**. **`bare-os-shell`** builtins may also carry per-builtin **`examples`** with the same shape.
- **`descriptionMode`** — **`"wrap"`** (default) or **`"preserve"`**. Handbook pages use **`preserve`** so line breaks and tables stay readable.
**`man -k`** also indexes **caption** text from **`examples`** so searches like “clone” can surface **`git`**.
The merged **`man.json`** adds **`schemaVersion`**, **`generatedAt`**, **`pages`**, **`index`** (name → page index), and **`apropos`** (keyword → page indices) for fast lookup.
---
## Build pipeline
1. **`npm run build -w bare-os-coreutils`** runs **`build.mjs`**, which calls **`scripts/build-man-db.mjs`**.
2. **`build-man-db.mjs`** loads every **`man/pages/<cmd>.json`** for **`COREUTILS_COMMANDS`**, plus **`git.json`** and **`bare-os-shell.json`**, then **`scripts/ingest-handbook-for-man.mjs`** appends one **`man(7)`** page per **`handbook/*.md`** (Markdown → plain text). It validates everything, then writes **`kernel/share/man/man.json`** and mirrors to **`packages/bare-os-seeder/kernel/share/man/man.json`**.
3. The **seeder** stages **`kernel/`** recursively; paths under **`kernel/share/...`** become **`/share/...`** on the system drive ([`packages/bare-os-seeder/index.js`](../packages/bare-os-seeder/index.js)).
4. **`/bin/man`** reads **`ctx.drive.get('/share/man/man.json')`**. There is **no embedded fallback** in v1 — the image must include the merged file.
---
## Relationship to **`help`**
**`/bin/help`** prints a **compact one-screen** list of builtins and **`/bin`** names. **`man`** is the **long-form** reference. Users are encouraged to run **`man handbook`** for the full narrative handbook, **`man bare-os-shell`** for builtins, and **`man <command>`** for **`/bin`** utilities.
---
## Authoring workflow
1. Add or edit **`packages/bare-os-coreutils/man/pages/<name>.json`**.
2. Run **`npm run build -w bare-os-coreutils`** (or **`node packages/bare-os-coreutils/scripts/build-man-db.mjs`**).
3. If a new **`/bin`** command is added, add **`name.json`**, add the name to **`lib/commands.mjs`**, and extend **`src/<name>.js`** — the build will fail until the page exists.
---
## Future work
- **`PAGER`** / scrollable view on TTY.
- **`man -w`** printing the logical path **`/share/man/man.json`** (or per-page anchors).
- HTML export for Pear / browser shells.
- Section **7** overview pages and i18n.
---
[← Chapter 9 — POSIX utilities, shell, VFS](09-posix-utilities-shell-and-vfs.md) · [Handbook home](README.md)
handbook/README.md
+12 -10
View File
@@ -16,16 +16,18 @@ This project is **experimental research software**: a distributed **system image
## Reading order
| Chapter | Topic |
| ------------------------------------------------------------------- | --------------------------------------------------- |
| [01 — Introduction](01-introduction.md) | Goals, vocabulary, Holepunch stack |
| [02 — Blueprints](02-blueprints.md) | Layered architecture, trust, diagrams |
| [03 — Protocol and disk](03-protocol-and-disk.md) | MBR, swarm, Protomux, SwarmDisk |
| [04 — The booter runtime](04-the-booter-runtime.md) | `ctx`, VFS, shell, kernel runner, initd, cron, REPL |
| [05 — Identity, vault, HDMS](05-identity-vault-and-hdms.md) | Guest vs user, `/.bare/account`, extra drives |
| [06 — Kernel and binaries](06-kernel-and-binaries.md) | `/boot/init.js`, coreutils catalog |
| [07 — Operations and development](07-operations-and-development.md) | Env vars, npm scripts, CI, Pear, troubleshooting |
| [08 — Git on Bare OS](08-git-on-bare-os.md) | isomorphic-git, VFS fs adapter, HTTP modes |
| Chapter | Topic |
| ----------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| [01 — Introduction](01-introduction.md) | Goals, vocabulary, Holepunch stack |
| [02 — Blueprints](02-blueprints.md) | Layered architecture, trust, diagrams |
| [03 — Protocol and disk](03-protocol-and-disk.md) | MBR, swarm, Protomux, SwarmDisk |
| [04 — The booter runtime](04-the-booter-runtime.md) | `ctx`, VFS, shell, kernel runner, initd, cron, REPL |
| [05 — Identity, vault, HDMS](05-identity-vault-and-hdms.md) | Guest vs user, `/.bare/account`, extra drives |
| [06 — Kernel and binaries](06-kernel-and-binaries.md) | `/boot/init.js`, coreutils catalog |
| [07 — Operations and development](07-operations-and-development.md) | Env vars, npm scripts, CI, Pear, troubleshooting |
| [08 — Git on Bare OS](08-git-on-bare-os.md) | isomorphic-git, VFS fs adapter, HTTP modes |
| [09 — POSIX utilities, shell, VFS](09-posix-utilities-shell-and-vfs.md) | XCU-style `/bin`, `sed`/`awk`, builtins, `mkdir`, stubs, divergence from Issue 7 |
| [10 — Manual pages and online help](10-manpages-and-online-help.md) | `man(1)`, `/share/man/man.json`, schema, build, relationship to `help` |
---