# bare-os-coreutils, tests, and seeder build hook

Former **DOCUMENTATION.md** §§12.10–12.12. [Reference index →](README.md)

### 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).
- **POSIX utility index (optional image file)** — **`kernel/etc/bare-os/posix_utilities.json`** carries machine-readable per-command notes when staged; the booter echoes **`utilitiesIndexPath`** in **`/proc/bare_os_features`** and coalesced **`metrics_live`** (see handbook ch.9).
- **Commands** — The authoritative sorted list is **`COREUTILS_COMMANDS`** in [`commands.mjs`](../../packages/bare-os-coreutils/lib/commands.mjs) (count and names change with releases; **do not** paste the full inventory into prose here). Each Tier-1 name has **`src/<name>.js`** (or a mapped source such as **`nano`** → **`src/edit.js`**) and a matching `**man/pages/<name>.json**`. Notable **large preambles** (see **`preamble`** in **`build.mjs`**): **`edit`** / **`nano`** (shared TUI stack), **`baretop`** / **`btop`**, **`agent`** (OpenAI-compatible assistant + **`web_fetch`** and related **`lib/agent-*.js`**), **`chat`** (swarm chat TUI + **`lib/chat-tui.js`**), **`irc`** (Libera TLS TUI), **`summon`** (text HTML/CSS browser + **`lib/summon-*.js`**), **`md5sum`**, **`sed`**, **`awk`**, **`jq`**, **`man`**, **`ls`** / **`dircolors`**. **`agent`** uses **`ctx.httpFetch`** like delegated **`curl`** / **`wget`** ([HTTP: curl and wget](http-curl-and-wget.md)). 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). Package overview: [bare-os-coreutils README](../../packages/bare-os-coreutils/README.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/`.