**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:
**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/engines/md5.js`**, **`sed`**, **`awk`**, **`jq`**, **`man`**, lscolors, **`edit`**/**`nano`** TUI under **`lib/edit/`**), 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`**.
@@ -35,11 +35,11 @@ Or `node packages/bare-os-coreutils/build.mjs`.
## 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`**).
**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`**. **188** 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/shell.js`**). Both require a real TTY (**`stdout.isTTY`**).
**`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/`** 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/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`** 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/baretop-snapshot.js`**, **`lib/baretop/baretop-ui-helpers.js`**, or **`lib/baretop/baretop-tui.js`**.
-`droppedRefreshPct p50 < 10%` with default `BARE_TOP_UI_MIN_MS=0`
**`agent`** is the in-guest **ReAct** coding agent (default **QVAC** via **`ctx.bareOsQvac*`**; optional OpenAI-compatible **REST**). Full guest admin by default (denylist). Preamble pulls in **`lib/agent-*.js`**, **`agent-workspace.js`** (**`~/.agent/workspace/*.md`** loader), **`agent-skills.js`** (compact skill index + **`read_skill`** / **`create_skill`**), **`agent-web-fetch.js`**, **`agent-tools.js`**, **`agent-tui.js`**, **`agent-grok-port.js`** (see **`build.mjs`** **`preamble.agent`**). Config and secrets live under `**~/.agent/**` on the **personal** drive (**`man agent`**). Inspect CLI: **`skills`**, **`todos`**, **`plan`**, **`undo`**, **`hooks`**, **`history`**, **`rewind`**, **`export`**, **`remember`**, **`recap`**. Discord **`/agent`** shares that session. **Markdown soul files** default from [`share/agent-workspace/`](share/agent-workspace/) (also staged to **`kernel/share/agent-workspace/`** on build). REST 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`**.
**`agent`** is the in-guest **ReAct** coding agent (default **QVAC** via **`ctx.bareOsQvac*`**; optional OpenAI-compatible **REST**). Full guest admin by default (denylist). Preamble pulls in **`lib/agent/`** (**`agent-workspace.js`** **`~/.agent/workspace/*.md`** loader, **`agent-skills.js`** compact skill index + **`read_skill`** / **`create_skill`**, **`agent-web-fetch.js`**, **`agent-tools.js`**, **`agent-tui.js`**, **`agent-grok-port.js`** — see **`build.mjs`** **`preamble.agent`**). Config and secrets live under `**~/.agent/**` on the **personal** drive (**`man agent`**). Inspect CLI: **`skills`**, **`todos`**, **`plan`**, **`undo`**, **`hooks`**, **`history`**, **`rewind`**, **`export`**, **`remember`**, **`recap`**. Discord **`/agent`** shares that session. **Markdown soul files** default from [`share/agent-workspace/`](share/agent-workspace/) (also staged to **`kernel/share/agent-workspace/`** on build). REST 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/edit/chat-tui.js`** preamble; **`man chat`**). **`summon`** is the first-party text web browser (**`lib/summon/`**; 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.
**`sed`** / **`awk`** use large interpreters in **`lib/engines/sed-engine.js`** and **`lib/engines/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.
"description":"P2P App Store client for Bare OS. Installs packages from pear:// links by copying the release Hyperdrive tree into ~/.appstore/packages/ (or /mnt/appstore when the appstore HDMS drive is mounted). install uses lib/appstore-pear.js: prefers a local HDMS mount with the same key, otherwise opens an ephemeral readonly HDMS mount and mirrors files over VFS. launch runs the materialized entry script (package.json main, usually sources/index.js) in the guest shell via ctx.console. Requires login for remote pear:// fetch. See docs/guides/guest-pear-and-appstore-workflow.md.",
"description":"P2P App Store client for Bare OS. Installs packages from pear:// links by copying the release Hyperdrive tree into ~/.appstore/packages/ (or /mnt/appstore when the appstore HDMS drive is mounted). install uses lib/pear/appstore-pear.js: prefers a local HDMS mount with the same key, otherwise opens an ephemeral readonly HDMS mount and mirrors files over VFS. launch runs the materialized entry script (package.json main, usually sources/index.js) in the guest shell via ctx.console. Requires login for remote pear:// fetch. See docs/guides/guest-pear-and-appstore-workflow.md.",
"description":"Documents BARE_OS_BARE_MODULES and BARE_OS_BARE_DRIVE_BUNDLES for the booter ctx.bare registry. In-image scripts (AsyncFunction) use ctx.bare.<key> instead of import(). Keys come from host dynamic import of packages listed in packages/bare-os-booter/lib/bare-module-manifest.json, then optional merge from trusted IIFE bundles under /lib/bare/bundles/ on the system image (see manifest.json there). The booter also attaches ctx.bare.discordJS from vendored bare-discord-js (official discord.js on Bare) unless BARE_OS_DISCORD=0. Set BARE_OS_BARE_MODULES=0 to omit ctx.bare entirely. Set BARE_OS_BARE_DRIVE_BUNDLES=0 to skip executing drive bundles (host imports only). Rebuild bundles with npm run build -w bare-os-bare-libs.",
"description":"Documents BARE_OS_BARE_MODULES and BARE_OS_BARE_DRIVE_BUNDLES for the booter ctx.bare registry. In-image scripts (AsyncFunction) use ctx.bare.<key> instead of import(). Keys come from host dynamic import of packages listed in packages/bare-os-booter/lib/ctx/bare-module-manifest.json, then optional merge from trusted IIFE bundles under /lib/bare/bundles/ on the system image (see manifest.json there). The booter also attaches ctx.bare.discordJS from vendored bare-discord-js (official discord.js on Bare) unless BARE_OS_DISCORD=0. Set BARE_OS_BARE_MODULES=0 to omit ctx.bare entirely. Set BARE_OS_BARE_DRIVE_BUNDLES=0 to skip executing drive bundles (host imports only). Rebuild bundles with npm run build -w bare-os-bare-libs.",
"bareOsNotes":"Engine: lib/jq-engine.js from @sscots/jqjs (mwh/jqjs). Missing vs C jq: try/catch, user-defined functions, recurse, many builtins, modules, full Unicode. See upstream jqjs README for the feature matrix.",
"bareOsNotes":"Engine: lib/engines/jq-engine.js from @sscots/jqjs (mwh/jqjs). Missing vs C jq: try/catch, user-defined functions, recurse, many builtins, modules, full Unicode. See upstream jqjs README for the feature matrix.",
"description":"Pear development tools inside Bare OS (ctx.pear surface). init scaffolds a project; stage writes .pear/stage/ (sources, bundles, stage.json) using ctx.pear/ctx.bare pack tools when enabled; release publishes the stage tree to a writable HDMS mount and prints pear:// links (no host Pear CLI required); seed flushes Hyperswarm for the release drive. Requires identity unlock (login) for release/seed. Implementation: packages/bare-os-coreutils/src/pear.js, lib/pear-stage.js, lib/pear-release.js. See docs/guides/guest-pear-and-appstore-workflow.md.",
"description":"Pear development tools inside Bare OS (ctx.pear surface). init scaffolds a project; stage writes .pear/stage/ (sources, bundles, stage.json) using ctx.pear/ctx.bare pack tools when enabled; release publishes the stage tree to a writable HDMS mount and prints pear:// links (no host Pear CLI required); seed flushes Hyperswarm for the release drive. Requires identity unlock (login) for release/seed. Implementation: packages/bare-os-coreutils/src/pear.js, lib/pear/pear-stage.js, lib/pear/pear-release.js. See docs/guides/guest-pear-and-appstore-workflow.md.",
'Stream editor with a subset of POSIX sed. Large engine is vendored in lib/sed-engine.js.',
'Stream editor with a subset of POSIX sed. Large engine is vendored in lib/engines/sed-engine.js.',
keywords:['sed','stream','edit','substitute'],
seeAlso:[
{name:'awk',section:1},
@@ -454,7 +454,7 @@ EXTRA.sed = {
}
EXTRA.awk={
description:
'Pattern-directed scanning and processing. Engine in lib/awk-engine.js; not full POSIX awk.',
'Pattern-directed scanning and processing. Engine in lib/engines/awk-engine.js; not full POSIX awk.',
keywords:['awk','pattern','field','script'],
seeAlso:[
{name:'sed',section:1},
@@ -605,7 +605,7 @@ EXTRA.jq = {
{name:'awk',section:1}
],
bareOsNotes:
'Engine: lib/jq-engine.js from @sscots/jqjs (mwh/jqjs). Missing vs C jq: try/catch, user-defined functions, recurse, many builtins, modules, full Unicode. See upstream jqjs README for the feature matrix.',
'Engine: lib/engines/jq-engine.js from @sscots/jqjs (mwh/jqjs). Missing vs C jq: try/catch, user-defined functions, recurse, many builtins, modules, full Unicode. See upstream jqjs README for the feature matrix.',
'Documents BARE_OS_BARE_MODULES and BARE_OS_BARE_DRIVE_BUNDLES for the booter ctx.bare registry. In-image scripts (AsyncFunction) use ctx.bare.<key> instead of import(). Keys come from host dynamic import of packages listed in packages/bare-os-booter/lib/bare-module-manifest.json, then optional merge from trusted IIFE bundles under /lib/bare/bundles/ on the system image (see manifest.json there). Set BARE_OS_BARE_MODULES=0 to omit ctx.bare entirely. Set BARE_OS_BARE_DRIVE_BUNDLES=0 to skip executing drive bundles (host imports only). Rebuild bundles with npm run build -w bare-os-bare-libs.',
'Documents BARE_OS_BARE_MODULES and BARE_OS_BARE_DRIVE_BUNDLES for the booter ctx.bare registry. In-image scripts (AsyncFunction) use ctx.bare.<key> instead of import(). Keys come from host dynamic import of packages listed in packages/bare-os-booter/lib/ctx/bare-module-manifest.json, then optional merge from trusted IIFE bundles under /lib/bare/bundles/ on the system image (see manifest.json there). Set BARE_OS_BARE_MODULES=0 to omit ctx.bare entirely. Set BARE_OS_BARE_DRIVE_BUNDLES=0 to skip executing drive bundles (host imports only). Rebuild bundles with npm run build -w bare-os-bare-libs.',
@@ -16,7 +16,7 @@ Use when the user wants to install, launch, update, or manage packages from the
- **App Store drive** — Optional HDMS label `appstore` at `/mnt/appstore`; falls back to `~/.appstore/`.
- **Registry** — `registry.json` lists installed packages and `pearLink` values.
- **Materialization** — `lib/appstore-pear.js` copies the release tree into `packages/<name>/` (from local HDMS mount or ephemeral readonly fetch).
- **Materialization** — `lib/pear/appstore-pear.js` copies the release tree into `packages/<name>/` (from local HDMS mount or ephemeral readonly fetch).
- **Launch** — Runs `sources/<main>` in the guest shell (output on `ctx.console`).
## End-to-end flow (with pear-dev)
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
