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

Baretop performance baseline

Run the repeatable baseline from repo root:

npm run perf:baretop -w bare-os-coreutils

or inside the package:

node ./test/baretop-perf-baseline.test.mjs

KPI envelope tracked in baseline lane:

• fetchMs (snapshot fetch wall time): rolling p50 / p95
• composeMs (frame compose cost): rolling p50 / p95
• emitMs (terminal emit cost): rolling p50 / p95
• emitBytes (bytes written/frame): rolling p50 / p95
• droppedRefreshPct (draws skipped by UI throttling): rolling p50 / p95
• startup-to-first-frame latency (start=...ms in profile footer)

Expected development-range targets (local machine, non-SSH):

• composeMs p95 < 40ms on fixture runs
• emitMs p95 < 10ms in synthetic tests
• droppedRefreshPct p50 < 10% with default BARE_TOP_UI_MIN_MS=0

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