# 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](../../docs/concepts/posix-stance.md) · [Developer guide — extending `/bin`](../../developer-guide/06-extending-bin-coreutils.md) · [Coreutils reference](../../docs/reference/package-bare-os-coreutils-and-ci.md) · [Handbook ch.9](../../handbook/09-posix-utilities-shell-and-vfs.md) · [Guest Pear + App Store](../../docs/guides/guest-pear-and-appstore-workflow.md) (`pear`, `appstore` preambles: `pear-stage.js`, `pear-release.js`, `appstore-pear.js`).

## Command contract

Each `src/*.js` file must define:

```js
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**:

```bash
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`**. **186** 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:

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

or inside the package:

```bash
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/`](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`](../../scripts/smoke-agent-web-fetch-bare.mjs)). **`chat`** is separate: swarm / Protomux text chat (**`lib/chat-tui.js`** preamble; **`man chat`**). **`summon`** is the first-party text web browser (**`lib/summon-*.js`**; page JS via **`ctx.bare.bareVm`** / **`bare-vm`**; **`ctx.httpFetch`**; TTY uses **`ctx.tui.run`** with a cell buffer). Headless: **`summon dump|links|get URL`**. See [summon.md](../../docs/reference/summon.md) and **`man summon`**.

**`ls`** prepends **[`bare-os-lscolors`](../bare-os-lscolors/bare-os-lscolors.js)** for **`LS_COLORS`** / dircolors parsing. **`dircolors`** and **`theme`** integrate with the booter’s **`bare-os-theme-presets.js`** (see [docs/themes/README.md](../../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/06-kernel-and-binaries.md), [handbook §9 — POSIX alignment](../../handbook/09-posix-utilities-shell-and-vfs.md), and [handbook §10 — `man` and online help](../../handbook/10-manpages-and-online-help.md).

## See also

- [kernel/README.md](../../kernel/README.md) — where built artifacts live in the source tree.
- [Coreutils build reference](../../docs/reference/package-bare-os-coreutils-and-ci.md#1210-package-bare-os-coreutils) (may lag the command list; **`lib/commands.mjs`** is authoritative).