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 lib/*-engine.js or lib/man-render.js chunks (see preamble in build.mjs — sed, awk, man), 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.

awk, basename, cat, chgrp, chmod, chown, cksum, clear, cp, crontab, cut, date, dirname, dircolors, du, edit, echo, env, exit, false, find, getconf, git-pear, grep, head, hdms, help, hostname, id, jq, ln, login, logout, logname, ls, man, mkdir, mkfifo, mktemp, mv, nano, nl, od, pathchk, printenv, printf, pwd, readlink, rm, rmdir, savevault, sed, seq, sleep, sort, stat, tail, tee, test, theme, time, touch, tr, true, tty, uname, wc, which, whoami, xargs

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

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.

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

Recent parity / UX: tail -f (watch or poll; BARE_OS_TAIL_F_* env), head/tail -c and + line/byte offsets, sort -n/-r/-u/-f, 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. Phase 2 adds cat -n/-A, env -i, touch -a/-m/-d/-r, mkdir -m, grep -r, sort -k/-t, cp/mv -L/-P, readlink -f, rmdir -p, du -a/-L, find -mtime/-newer/-prune/-empty/-delete (gated), stat --format, cut -s, tr [:class:], richer od/nl/seq/pathchk/printf/time, and bareOsBinWrite for captured NUL output in tests.

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.
• DOCUMENTATION.md §12.10 (may lag the command list; lib/commands.mjs is authoritative).