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. 153 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.

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).