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)

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.

arch, awk, base32, base64, basename, basenc, cat, chgrp, chmod, chown, cksum, clear, comm, cp, crontab, curl, cut, date, df, dir, dirname, dircolors, du, edit, echo, env, exit, expand, expr, factor, false, find, fmt, fold, getconf, git-pear, grep, groups, head, hdms, help, hostid, hostname, id, install, join, jq, ln, login, logout, logname, ls, man, md5sum, mkdir, mkfifo, mktemp, mv, nano, nl, nproc, numfmt, od, paste, pathchk, pr, printenv, printf, pwd, readlink, realpath, rev, rm, rmdir, savevault, sed, seq, sha1sum, sha256sum, sha512sum, shuf, sleep, sort, split, stat, sum, sync, tac, tail, tee, test, theme, time, timeout, touch, tr, truncate, true, tsort, tty, uname, uniq, unlink, unexpand, uptime, users, vdir, wc, wget, which, who, whoami, xargs, yes

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

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 minimal /bin scripts (see src/curl.js, src/wget.js) so which, ls /bin, and parity checks see them; the booter delegates to the real Fetch-based clients in bare-os-booter before those scripts run.

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