bare-operating-system/docs/reference/package-bare-os-coreutils-and-ci.md

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

Former DOCUMENTATION.md §§12.10–12.12. Reference index →

12.10 Package bare-os-coreutils

• 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 — 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.
• 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 (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 (QVAC / REST ReAct coding agent + 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. REST agent uses ctx.httpFetch like delegated curl / wget (HTTP: curl and wget); QVAC stays on ctx.bareOsQvac*. 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). Each built script begins with BARE_OS_BIN_API in the concatenated prelude; root pretest runs 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). Narrative reference: handbook/09-posix-utilities-shell-and-vfs.md. Package overview: bare-os-coreutils README.

12.11 Booter tests (test.*.js) and test.identity.js

• scripts.test — brittle-bare test.identity.js then brittle-node on the topic files (test.kernel.js, test.vfs.js, test.shell.js, test.initd-fish.js, test.coreutils.js, test.runtime.js, plus net/SSH/QVAC/TUI files). bare-crypto’s native addon runs under Bare only; the main suite still uses Node for Hyperdrive + node:fs.

Shared helpers — test/_helpers.js exports testCorestoreDir(name) (under the package .test-data/), testCtx, readBuiltBin, and the former mega-suite imports. Topic files cover runKernelFromSource, runBinCommand, createStreamLineReader, Hyperdrive roundtrip, createVfs, shell tokenizer/exec, and tier-1 /bin contracts.

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 — 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/.