bare-operating-system/packages/bare-os-coreutils

bare-os-coreutils

Build step, not a runtime library: validates and merges man/pages/*.json** into **kernel/share/man/man.json** (see **scripts/build-man-db.mjs**), then concatenates **lib/runtime.js**, optional preamble chunks (see **preamble** in **build.mjs** — e.g. **md5sum** → **lib/md5.js**, **sed**, **awk**, **jq**, **man**, lscolors, **edit**/**nano** TUI), then each **src/<command>.js, and writes standalone scripts to:

• kernel/bin/<command> — staged into the system Hyperdrive as /bin/*
• packages/bare-os-seeder/kernel/bin/<command> — vendored copy for Pear bundles (seeder has no sibling bare-os-coreutils at runtime)

When to use: run npm run build -w bare-os-coreutils** whenever you change **src/*.js**, **lib/commands.mjs**, or **man/pages/*** so **kernel/bin/*** and **man.json** stay in sync before **pretest** or **pear run.

Documentation: Concepts — POSIX · Developer guide — extending /bin · Coreutils reference · Handbook ch.9.

Command contract

Each src/*.js file must define:

async function run(ctx, argv) {
  /* ... */
}

No top-level import — commands are loaded by the booter via AsyncFunction for Bare/Pear compatibility. The concatenated prelude starts with /* BARE_OS_BIN_API … */** so **scripts/verify-kernel-seeder-parity.mjs** can verify staged **kernel/bin/*. Use ctx.vfs, ctx.console, ctx.b4a, ctx.drive, bareStdin(ctx) from the prelude where needed. Optional ctx.bareOsBinWrite(Uint8Array|string)** captures raw bytes (e.g. NUL-terminated output) when **process.stdout.write** is absent (see **bareOsEmitRaw** in **lib/runtime.js).

Build

From the monorepo root:

npm run build -w bare-os-coreutils

Or node packages/bare-os-coreutils/build.mjs.

CI / tests: root pretest runs this build so kernel/bin exists before workspace tests.

Commands (authoritative list)

Source of truth: lib/commands.mjs** — **COREUTILS_COMMANDS** (imported by **build.mjs** and **scripts/build-man-db.mjs**). Each name must have **man/pages/<name>.json**. 157 Tier-1 commands in the current tree (**sshd’s /bin body is emitted by bare-os-openssh**); root **pretest** runs **verify-man-coverage.mjs** against this list (do not hand-maintain a duplicate comma-separated inventory here—use **lib/commands.mjs**, **ls /bin** in the guest, or **man -k).

edit** is a full-screen TTY buffer editor (syntax highlighting, search, save). **nano** is built from the same **src/edit.js** with the same **lib/edit-*.js** preamble; **/bin/nano** exists for familiarity, and the stock shell alias **nano → edit** routes **nano** to that utility (see **packages/bare-os-booter/lib/shell.js**). Both require a real TTY (**stdout.isTTY).

baretop** is the stock **top** alias target: a multi-tab TTY dashboard over **/proc/bare_os/*** (session metrics, Pear, replication, initd, scrollable overview, process tree/sort, optional mouse, …). **btop** is the same bundle as **/bin/baretop** (short name); the stock shell alias **btop → baretop** matches **nano → edit**. The booter may expose **ctx.bareOsReadBareTopSnapshot** (optional **{ lite: true }**) to batch-read the same mirrors **baretop** would **vfs.readFile** individually; the return value can include **metricsLiveText** so **metrics_live.json** need not be read twice. **BARE_TOP_INCREMENTAL=2** enables experimental line-diff redraws; **BARE_TOP_LAYOUT_AUTO=1** picks a wide split on large terminals. Rebuild **kernel/bin/baretop** and **kernel/bin/btop** with **node packages/bare-os-coreutils/build.mjs** after editing **lib/baretop-snapshot.js**, **lib/baretop-ui-helpers.js**, or **lib/baretop-tui.js.

agent** is the OpenAI-compatible HTTPS assistant (ReAct-style tools, TTY streaming). Preamble pulls in **lib/agent-*.js**, **agent-workspace.js** (**~/.agent/workspace/*.md** loader), **agent-skills.js** (compact skill index + **read_skill**), **agent-web-fetch.js**, **agent-tools.js**, **agent-tui.js** (see **build.mjs** **preamble.agent**). Config and secrets live under **~/.agent/** on the personal drive (**man agent). Markdown soul files default from share/agent-workspace/ (also staged to kernel/share/agent-workspace/** on build). Outbound HTTPS uses **ctx.httpFetch** (same **BARE_OS_HTTP_ALLOWLIST** / **BARE_OS_HTTP_DENYLIST** as delegated **curl** / **wget**); the **web_fetch** tool needs every target host allowlisted alongside your API origin. Maintainer smoke under the Bare runtime: from repo root **npm run smoke:agent-web-fetch:bare (scripts/smoke-agent-web-fetch-bare.mjs). chat** is separate: swarm / Protomux text chat (**lib/chat-tui.js** preamble; **man chat).

ls prepends bare-os-lscolors for LS_COLORS** / dircolors parsing. **dircolors** and **theme** integrate with the booter’s **bare-os-theme-presets.js (see docs/themes/README.md).

grep** uses JavaScript **RegExp** (and **-F** fixed strings); POSIX/GNU-like subset (including **-x**, **-m**, **-o** among common flags). It is not PCRE- or GNU-bit-identical; use **-F when literals must not be treated as regex.

sed** / **awk** use large interpreters in **lib/sed-engine.js** and **lib/awk-engine.js — capable, but not guaranteed to match every POSIX or GNU edge case; treat parity as best-effort.

curl** and **wget** ship as **/bin** scripts (see **src/curl.js**, **src/wget.js**) so **which**, **ls /bin**, and parity checks see them; the booter delegates to Fetch-based clients in **bare-os-booter** first, and **ctx.bareOsRunCurlCli / ctx.bareOsRunWgetCli** run the same implementation if a script is executed directly. **openssl**, **ssh-keygen**, and **tar** use matching **ctx.bareOsRun*** hooks backed by **openssl-cli.js**, **ssh-keygen-cli.js**, and **tar-cli.js in the booter.

mkfifo** creates simulated named pipes under **/run/bare-os/ipc/<name>** (in-memory; see booter VFS). **getconf** and **xargs implement a documented Bare-specific subset (see src/getconf.js, src/xargs.js).

Pipelines: the shell sets ctx.bareOsStdoutCaptured** when a command’s stdout is captured (pipe or **>** / **>>**). **ls** prints one name per line in short mode in that case (GNU-like), so **ls | grep** / **sort** / **wc see one record per line.

GNU-style text / data utilities (bounded where needed): paste**, **split** (**BARE_OS_SPLIT_MAX_FILES**), **tac**, **rev**, **expand**, **unexpand**, **fold**, **fmt**, **comm**, **join**, **pr**, **yes** (**BARE_OS_YES_MAX_LINES**), **shuf** (**BARE_OS_SHUF_MAX_LINES**), **tsort**, **factor**, **expr**, **numfmt**. Checksums / encodings: **md5sum**, **sha1sum**, **sha256sum**, **sha512sum**, **sum**, **base32**, **basenc --base16**. Files / stubs: **truncate**, **unlink**, **install**, **df**, **sync**, **dir**/**vdir** (delegate to **ls**), **arch**, **groups**, **hostid**, **nproc**, **uptime**, **users**, **who.

Earlier parity / UX: tail -f** (watch or poll; **BARE_OS_TAIL_F_*** env), **head/tail -c** and **+ line/byte offsets, sort -n/-r/-u/-f/-k/-t**, **sort -c/-C** (check), **-s** (stable), **-o**, **wc -l/-w/-c**, **grep -A/-B/-C** and **--color**, **date +FORMAT** (strftime-like subset), **test** integer compares and **-h/-L**, **xargs -I**, **find -iname/-print0**, **du -h**, **basename -a/-s**, **dirname -z**, **cat -n/-A**, **env -i**, **env -S / --env-file** (with **BARE_OS_ENV_DASH_S=1**), **touch -a/-m/-d/-r**, **mkdir -m**, **grep -r**, **cp/mv -L/-P**, **readlink -f**, **rmdir -p**, **du -a/-L**, **find -mtime/-newer/-prune/-empty/-delete** (gated), **stat --format**, **uniq**, **realpath**, **base64**, **rm -d**, **cut -s**, **tr [:class:]**, richer **od/nl/seq/pathchk/printf/time**, and **bareOsBinWrite** for captured NUL output in tests. Cap names for **getconf** include **BARE_OS_FIND_EXEC_MAX**, **BARE_OS_YES_MAX_LINES**, **BARE_OS_SHUF_MAX_LINES**, **BARE_OS_SPLIT_MAX_FILES.

See handbook §6 — Kernel and /bin, handbook §9 — POSIX alignment, and handbook §10 — man and online help.

See also

• kernel/README.md — where built artifacts live in the source tree.
• Coreutils build reference (may lag the command list; lib/commands.mjs is authoritative).