snxraven/bare-operating-system
1
1
Fork 1
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

Updates

Browse Source
This commit is contained in:
Raven Scott
2026-04-03 20:33:24 -04:00
parent ae6b7f8652
commit e58a9f99d6
184 changed files with 1636 additions and 109 deletions
Download Patch File Download Diff File Expand all files Collapse all files
DOCUMENTATION.md
+17 -13
View File
@@ -329,7 +329,7 @@ Pear-safe path resolution (same idea as Holepunch [pear-rti](https://github.com/
### 12.3 [packages/bare-os-booter/index.js](packages/bare-os-booter/index.js)
**Imports** — Hyperswarm, Protomux, protocol, `./lib/swarm-disk.js`, `./lib/kernel-runner.js`, `./lib/vfs.js`, `./lib/shell.js`, `./lib/paths.js`, stdio/readline/repl/boot-splash helpers, `./lib/identity-session.js`.
**Imports** — Hyperswarm, Protomux, protocol, `./lib/swarm-disk.js`, `./lib/kernel-runner.js`, `./lib/vfs.js`, `./lib/shell.js`, `./lib/paths.js`, `./lib/bare-os-ipc.js`, `./lib/bare-os-runtime-caps.js`, stdio/readline/repl/boot-splash helpers, `./lib/identity-session.js`.
**`bootStorePath()`** — `defaultBootCorestorePath(_pkg, import.meta.url)`.
@@ -341,10 +341,12 @@ Pear-safe path resolution (same idea as Holepunch [pear-rti](https://github.com/
**`executeKernel(disk, store, swarm, initSource)`** (`store`/`swarm` unused but kept for signature symmetry / future use)
- Builds `shellEnv` with **guest** defaults: `USER`/`LOGNAME`=`guest`, `HOME`/`PWD`=`/home/guest`, `UID`/`GID`=`65534`, `BARE_OS_IDENTITY=guest`, `BARE_OS_EXIT_STATUS`=`0`, `BARE_OS_CTX_API_VERSION`, `PATH=/bin`, `SHELL`, `HOSTNAME`, `0`. When the host sets **`BARE_OS_PIPELINE_MAX_STAGES`**, **`BARE_OS_PIPELINE_MAX_BYTES`**, **`BARE_OS_PIPELINE_MAX_LINES`**, **`BARE_OS_BOOT_PROFILE`**, or **`BARE_OS_ONBOOT`**, those values are copied into `shellEnv`. `createVfs(drive, personalDrive, shellEnv, vfsMountRef, { procSnapshot, bootStartedMs, initdRunText })` → `ctx.vfs` (same `env` object as `ctx.env`). Optional **`bootStartedMs`** and **`initdRunText`** feed synthetic **`/proc/uptime`** and **`/run/bare-os/units`**.
- Builds `shellEnv` with **guest** defaults: `USER`/`LOGNAME`=`guest`, `HOME`/`PWD`=`/home/guest`, `UID`/`GID`=`65534`, `BARE_OS_IDENTITY=guest`, `BARE_OS_EXIT_STATUS`=`0`, `BARE_OS_CTX_API_VERSION`, `PATH=/bin`, `SHELL`, `HOSTNAME`, `0`. When the host sets any of the keys listed in **§14** under “host → session passthrough,” those values are copied into `shellEnv`. Sets **`BARE_OS_BOOT_PROFILE_RESOLVED`** from **`BARE_OS_BOOT_PROFILE`** or the first line of **`/etc/bare-os/profile`**, and **`BARE_OS_SESSION_ID`** (random UUID). Seeds **`/run/bare-os/boot.json`** fields **`imageDigest`**, **`pearChannel`**, **`pearRelease`** from **`BARE_OS_IMAGE_DIGEST`**, **`BARE_OS_PEAR_CHANNEL`** / **`PEAR_CHANNEL`**, **`BARE_OS_PEAR_RELEASE`** when present.
- **`createBareOsIpc({ maxFifoBytes })`** ([`bare-os-ipc.js`](packages/bare-os-booter/lib/bare-os-ipc.js)) — FIFOs under **`/run/bare-os/ipc/<name>`**; optional JSON helpers when caps expose **`features.ipcRpcJson`**.
- **`createVfs(drive, personalDrive, shellEnv, vfsMountRef, vfsOptions)`** → `ctx.vfs` (same `env` object as `ctx.env`). **`vfsOptions`** supply **`procSnapshot`**, dynamic **`/proc/*`** and **`/sys/*`** text (quotas JSON, net/disk stubs, session stats), **`bootProfileText`**, **`sessionText`**, **`initdRunText`**, **`bootReadyJsonText`**, mount map for **`/proc/mounts`**, **`bootStartedMs`** for **`/proc/uptime`**, etc. Exposes **`vfs.watch(logicalPath)`** for Hyperdrive-backed paths when **`BARE_OS_VFS_WATCH`** is not **`0`**.
- **`applyGuestEnv(ctx)`** then **`ensureGuestHome(ctx)`** — normalizes `ctx.identity` and seeds `/.bare/` (and a guest marker) on the personal drive.
- **`createReadLine()`** always resolves stdio first and returns `stdout` (may be `null`) alongside `readLine` so the kernel can write to the **same** stream as the REPL (including `bare-stdio` under Pear).
- Builds `ctx`: **`bareOsCtxApiVersion`** (from [`bare-os-ctx-api.js`](packages/bare-os-booter/lib/bare-os-ctx-api.js)), **`bareOsRuntimeCaps`** (frozen snapshot from [`bare-os-runtime-caps.js`](packages/bare-os-booter/lib/bare-os-runtime-caps.js): pipeline limits, pseudo path list, feature flags), `disk`, `drive`, `personalDrive`, `vfs`, `env`, `console`, `b4a`, `topic: topicKey()`, `readLine`, **`writeScreen(str)`**, `execLine` → `execShellLine(ctx, line)` (returns `'ok'` or `'exit'`; updates **`BARE_OS_EXIT_STATUS`** in **`vfs.env`**; bare **`exit`** line sets status then **`requestBooterExit`**), **`runBinCommand(argv)`** → delegates to **`runBinCommand(this, argv)`** from `kernel-runner.js` (for `/bin/time` and similar), plus identity hooks for `/bin` and builtins:
- Builds `ctx`: **`bareOsCtxApiVersion`** (from [`bare-os-ctx-api.js`](packages/bare-os-booter/lib/bare-os-ctx-api.js)), **`bareOsRuntimeCaps`** (frozen snapshot from [`bare-os-runtime-caps.js`](packages/bare-os-booter/lib/bare-os-runtime-caps.js): pipeline limits, **`quotas`**, pseudo path list, feature flags such as **`vfsWatch`**, **`ipcRpcJson`**, **`initdSocketActivation`**), **`bareOsIpc`**, `disk`, `drive`, `personalDrive`, `vfs`, `env`, `console`, `b4a`, `topic: topicKey()`, `readLine`, **`writeScreen(str)`**, **`bareOsSubscribeBootEvent`** / **`bareOsEmitBootEvent`**, **`bareOsSubscribeHdmsLifecycle`**, **`bareOsAwaitInitdUnits`**, **`bareOsPublishBootReady`**, `execLine` → wraps **`execShellLine`** with optional **audit** (**`BARE_OS_AUDIT`**, **`BARE_OS_AUDIT_JSON`**, redaction), **`execLine` depth cap** (**`BARE_OS_EXEC_MAX_DEPTH`**), then the shell (returns `'ok'` or `'exit'`; updates **`BARE_OS_EXIT_STATUS`** in **`vfs.env`**; bare **`exit`** line sets status then **`requestBooterExit`**), **`runBinCommand(argv)`** → delegates to **`runBinCommand(this, argv)`** from `kernel-runner.js` (for `/bin/time` and similar), plus identity hooks for `/bin` and builtins:
- **`applyUnlock(passphrase)`** — load `/.bare/account`, decrypt, unlock session.
- **`applyRegister(passphrase)`** — create account file, unlock.
- **`applyLogin({ publicKey, secretKey })`** — set session from an already-decoded keypair.
@@ -410,7 +412,7 @@ Pear-safe path resolution (same idea as Holepunch [pear-rti](https://github.com/
**`runBinCommand(ctx, argv)`**
- If **`argv[0]`** is **`git`** (or a POSIX path whose basename is `git`, but not `./git` or `../git`), **delegates** to **`runGitCli`** in [`git-cli.js`](packages/bare-os-booter/lib/git-cli.js).
- If **`argv[0]`** is **`curl`** under the same basename rules, **delegates** to **`runCurlCli`** in [`curl-cli.js`](packages/bare-os-booter/lib/curl-cli.js) (HTTP client via Fetch / **bare-fetch**; manual **`curl(1)`** in the merged JSON DB).
- If **`argv[0]`** is **`curl`** under the same basename rules, **delegates** to **`runCurlCli`** in [`curl-cli.js`](packages/bare-os-booter/lib/curl-cli.js) (HTTP client via global **`fetch`** when available, else **bare-fetch**, else **bare-https** on Pear/Bare; manual **`curl(1)`** in the merged JSON DB).
- If **`argv[0]`** is **`wget`** under the same basename rules, **delegates** to **`runWgetCli`** in [`wget-cli.js`](packages/bare-os-booter/lib/wget-cli.js) (HTTP download via Fetch / **bare-fetch**; manual **`wget(1)`** in the merged JSON DB).
- If `argv[0]` contains `/`, resolves with `ctx.vfs.resolveLogical`, `route`, loads script bytes from the routed Hyperdrive (`get` with `follow`).
- Else walks `$PATH` (`ctx.vfs.env.PATH`, default `/bin`), joining each directory with `unix-path-resolve(dir, cmd)` (not three-argument resolve), loads from **system** `ctx.drive` only.
@@ -423,9 +425,9 @@ Pear-safe path resolution (same idea as Holepunch [pear-rti](https://github.com/
**`createVfs(systemDrive, personalDrive, env, mntRef?, vfsOptions?)`**
- **Logical paths** under `$HOME` (booter default `/home/guest`; after `login`, `/home/<pubkey-prefix>`) map to the **personal** Hyperdrive under `/.bare-os/home/<basename>/…`; **`/var/log`** and **`/tmp`** map to **`/.bare-os/var/log/…`** and **`/.bare-os/tmp/…`** with the same basename. Read-only synthetic **`/proc`** and **`/sys`** (optional **`vfsOptions.procSnapshot`** for version/cmdline text). All other absolute paths use the **system** drive (read-mostly OS image).
- **Logical paths** under `$HOME` (booter default `/home/guest`; after `login`, `/home/<pubkey-prefix>`) map to the **personal** Hyperdrive under `/.bare-os/home/<basename>/…`; **`/var/log`** and **`/tmp`** map to **`/.bare-os/var/log/…`** and **`/.bare-os/tmp/…`** with the same basename. Read-only synthetic **`/proc`** and **`/sys`** (optional **`vfsOptions`** for version/cmdline, quotas JSON, net/disk stubs, **`/run/bare-os/*`** text providers, mount map, etc.). All other absolute paths use the **system** drive (read-mostly OS image).
- **`resolveLogical(p)`** — `unix-path-resolve(cwd, p)` so cwd + relative segments work (the `unix-path-resolve` package only accepts two path arguments).
- **API**: `getcwd`, `chdir` (rejects regular files), `readFile`, `writeFile` / `unlink` (personal only), `exists`, `readdir`, `stat` / `lstat`, `readlink`, `symlink`, `chmod`, `mkdir` (recursive via `.bareos_empty` marker), `rmdir` (empty dirs; marker-aware), `rm` (recursive tree walk), `route`, `resolveLogical`, `env`.
- **API**: `getcwd`, `chdir` (rejects regular files), `readFile`, `writeFile` / `unlink` (personal only), `exists`, `readdir`, `stat` / `lstat`, `readlink`, `symlink`, `chmod`, `mkdir` (recursive via `.bareos_empty` marker), `rmdir` (empty dirs; marker-aware), `rm` (recursive tree walk), `route`, `resolveLogical`, `env`, **`watch(logicalPath)`** (Hyperdrive-backed paths only; throws on pseudo **`/proc`**/**`/sys`**/**`/run`**/**`/dev`** and on virtual **`$HOME`**, **`/var`**, **`/mnt`** roots).
- **Hyperdrive quirk**: `entry` / `get` / `exists` use `std(path, false)` and **throw** on path `'/'` (`Invalid filename: /`). The VFS special-cases drive path `'/'` (logical `/` and personal `$HOME` root) for `chdir`, `stat`, `exists`, `isRegularFile`, and blocks `readFile`/`put`/`del` on that key.
- **Bare / Pear**: do not rely on global `TextEncoder` / `TextDecoder` in booter `lib/*.js`; this tree uses **`b4a`** for UTF-8 where needed (pseudo `/proc` content, symlink size in `vfs-posix-meta.js`, `systemctl` log tailing, etc.).
@@ -450,7 +452,7 @@ Pear-safe path resolution (same idea as Holepunch [pear-rti](https://github.com/
- **[packages/bare-os-coreutils/lib/commands.mjs](packages/bare-os-coreutils/lib/commands.mjs)** — **`COREUTILS_COMMANDS`**: authoritative sorted `/bin` names for **`build.mjs`** and the manual database builder (keeps the image and **`man`** coverage in sync).
- **[packages/bare-os-coreutils/build.mjs](packages/bare-os-coreutils/build.mjs)** — `export async function build()`: runs **`scripts/build-man-db.mjs`** (validates **`man/pages/*.json`**, writes **`kernel/share/man/man.json`** and the same path under **`packages/bare-os-seeder/kernel/share/man/`**); then for each command concatenates `lib/runtime.js`, optional **`preamble`** libs (`sed` → `lib/sed-engine.js`, `awk` → `lib/awk-engine.js`, **`man`** → `lib/man-render.js`), then `src/<name>.js`; writes to `kernel/bin/<name>` and `packages/bare-os-seeder/kernel/bin/<name>`. CLI: `node build.mjs` when executed as main.
- **Manual pages** — Authoring: **`packages/bare-os-coreutils/man/pages/<name>.json`**; schema: **`man/schema.json`**. Optional **`examples`** (cheat.sh-style) and **`descriptionMode`**: **`preserve`** for preformatted text. **`scripts/ingest-handbook-for-man.mjs`** merges every **`handbook/*.md`** as **`man(7)`** at build time (**`man handbook`**, **`man handbook-01-introduction`**, …). Regenerate JSON stubs with **`node packages/bare-os-coreutils/scripts/seed-man-pages.mjs`**. Runtime: **`/bin/man`** reads **`/share/man/man.json`**. **Handbook:** [handbook/10-manpages-and-online-help.md](handbook/10-manpages-and-online-help.md).
- **Commands** (sources under `src/`, same order as **`COREUTILS_COMMANDS`**): `awk`, `basename`, `cat`, `chgrp`, `chmod`, `chown`, `cksum`, `clear`, `cp`, `crontab`, `cut`, `date`, `dirname`, `du`, `echo`, `env`, `exit`, `false`, `find`, `getconf`, `grep`, `head`, `hdms`, `help`, `hostname`, `id`, `jq`, `ln`, `login`, `logout`, `logname`, `ls`, `man`, `mkdir`, `mkfifo`, `mv`, `nl`, `od`, `pathchk`, `printenv`, `printf`, `pwd`, `readlink`, `rm`, `rmdir`, `savevault`, `sed`, `seq`, `sleep`, `sort`, `stat`, `tail`, `tee`, `test`, `time`, `touch`, `tr`, `true`, `tty`, `uname`, `wc`, `which`, `whoami`, `xargs`. Scripts are plain `async function run(ctx, argv)` using `ctx.vfs`, `ctx.drive`, `ctx.b4a`, `ctx.console`, optional `bareStdin(ctx)`, optional `ctx.runBinCommand` — no ESM `import` in `src/` (Bare-safe `AsyncFunction` load). **Booter-delegated** (stubs under `kernel/bin/`, logic in `packages/bare-os-booter/lib/`): `systemctl`, `journalctl` (bare-initd control; `bare-initctl` alias; see [handbook/04-the-booter-runtime.md](handbook/04-the-booter-runtime.md)). **Narrative reference:** [handbook/09-posix-utilities-shell-and-vfs.md](handbook/09-posix-utilities-shell-and-vfs.md).
- **Commands** (sources under `src/`, same order as **`COREUTILS_COMMANDS`** in [`commands.mjs`](packages/bare-os-coreutils/lib/commands.mjs)): `awk`, `basename`, `cat`, `chgrp`, `chmod`, `chown`, `cksum`, `clear`, `cp`, `crontab`, `cut`, `date`, `dirname`, `du`, `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`, `nl`, `od`, `pathchk`, `printenv`, `printf`, `pwd`, `readlink`, `rm`, `rmdir`, `savevault`, `sed`, `seq`, `sleep`, `sort`, `stat`, `tail`, `tee`, `test`, `time`, `touch`, `tr`, `true`, `tty`, `uname`, `wc`, `which`, `whoami`, `xargs`. Each built script begins with **`BARE_OS_BIN_API`** in the concatenated prelude; root **`pretest`** runs **[`scripts/verify-kernel-seeder-parity.mjs`](scripts/verify-kernel-seeder-parity.mjs)** to keep **`kernel/bin/*`** and **`packages/bare-os-seeder/kernel/bin/*`** in sync and to require that pragma on every staged binary. Scripts are plain `async function run(ctx, argv)` using `ctx.vfs`, `ctx.drive`, `ctx.b4a`, `ctx.console`, optional `bareStdin(ctx)`, optional `ctx.runBinCommand` — no ESM `import` in `src/` (Bare-safe `AsyncFunction` load). **Booter-delegated** (stubs under `kernel/bin/`, logic in `packages/bare-os-booter/lib/`): `systemctl`, `journalctl` (bare-initd control; `bare-initctl` alias; see [handbook/04-the-booter-runtime.md](handbook/04-the-booter-runtime.md)). **Narrative reference:** [handbook/09-posix-utilities-shell-and-vfs.md](handbook/09-posix-utilities-shell-and-vfs.md).
### 12.11 [packages/bare-os-booter/test.js](packages/bare-os-booter/test.js) and [test.identity.js](packages/bare-os-booter/test.identity.js)
@@ -502,11 +504,13 @@ sequenceDiagram
| `BARE_OS_NO_SPLASH` | Booter | If `1`, skip TTY splash (plain logs / non-TTY behavior unchanged) |
| `BARE_OS_LOCAL_SEED` | paths | Overrides local seed path helper (`defaultLocalSeedCorestorePath`); booter does not local-boot |
| `BARE_OS_SKIP_REPL` | Booter | If `1`, readline returns null — non-interactive exit |
| `BARE_OS_BOOT_TRACE` | Stock kernel (`init.js`) | If `1` or `true`, log each boot phase duration on stderr as `[boot] phase: Nms`; if `json`, log `{"phase":"…","ms":n}` per phase |
| `BARE_OS_BOOT_TRACE` | Stock kernel (`init.js`) | If `1` or `true`, log each boot phase duration on stderr as `[boot] phase: Nms`; if `json`, log `{"phase":"…","ms":n}` per phase; **`ndjson`** adds **`sessionId`** / **`ts`** (same shape as `ctx.bareOsEmitBootEvent`) |
| `MANWIDTH` | `/bin/man` | Wrap width for manual text (default `72`; minimum `40`) |
| `NO_COLOR` | `/bin/man` | If set, disable ANSI bold for section headings on a TTY |
**Session env (set by booter, not user configuration):** `USER`, `LOGNAME`, `HOME`, `PWD`, `UID`, `GID`, `GROUP`, `BARE_OS_IDENTITY` (`guest` or `unlocked`), and when unlocked `BARE_OS_PUBLIC_KEY` (hex Ed25519 public key).
**Host → session passthrough** (booter copies into `shellEnv` when the host sets a non-empty value): `BARE_OS_PIPELINE_MAX_STAGES`, `BARE_OS_PIPELINE_MAX_BYTES`, `BARE_OS_PIPELINE_MAX_LINES`, `BARE_OS_BOOT_PROFILE`, `BARE_OS_ONBOOT`, `BARE_OS_BOOT_STRICT`, `BARE_OS_RC_D_SKIP`, `BARE_OS_BOOT_MINIMAL`, `BARE_OS_BOOT_SKIP`, `BARE_OS_BOOT_TRACE`, `BARE_OS_KERNEL_SELFTEST`, `BARE_OS_SELFTEST_FORMAT`, `BARE_OS_AUDIT`, `BARE_OS_AUDIT_JSON`, `BARE_OS_AUDIT_REDACT`, `BARE_OS_IMAGE_DIGEST`, `BARE_OS_EXEC_MAX_DEPTH`, `BARE_OS_IPC_MAX_BYTES`, `BARE_OS_VFS_WATCH`, `BARE_OS_BOOT_ALLOWLIST`, `BARE_OS_PEAR_CHANNEL`, `BARE_OS_PEAR_RELEASE`, `PEAR_CHANNEL`.
**Session env (set by booter, not user configuration):** `USER`, `LOGNAME`, `HOME`, `PWD`, `UID`, `GID`, `GROUP`, `BARE_OS_IDENTITY` (`guest` or `unlocked`), `BARE_OS_CTX_API_VERSION`, `BARE_OS_SESSION_ID`, `BARE_OS_BOOT_PROFILE_RESOLVED`, and when unlocked `BARE_OS_PUBLIC_KEY` (hex Ed25519 public key).
---
@@ -514,10 +518,10 @@ sequenceDiagram
| Area | Status |
| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **VFS** | Two-drive unified paths; **`$HOME`** maps to the personal Hyperdrive; writable mounts under **`/mnt`** when HDMS allows. **`mkdir`/`rmdir`**, **`chmod`** (octal + symbolic subset), **`symlink`/`readlink`**, **`stat`/`lstat`**, **`rm`** recursive. Empty dirs use **`.bareos_empty`** (same idea as `git-fs-adapter`). |
| **Shell** | Pipelines (pipe between commands), list separator **`;`**, short-circuit logical-**AND** / logical-**OR** between commands, redirects **`>`** / **`>>`** / **`<`**, quoting, **`$VAR`** / **`${VAR}`**, **`$?`** / **`${?}`** (from **`BARE_OS_EXIT_STATUS`**), builtins: **`alias`**, **`unalias`**, **`cd`**, **`export`**, **`unset`**, **`readonly`**, **`umask`**, **`:`**, **`command`**, **`type`**, **`login`**, **`logout`**, **`exit`**. Branching uses **`ctx.exitCode`**. No job control, functions, or full POSIX **`sh`** grammar. |
| **Ownership** | Display and permission checks use **`UID`/`GID`** and mode bits; **`chown`/`chgrp`** are stubs (no multi-user ownership changes). |
| **Utilities** | Tier-1 JS **`/bin`** (see §12.10): includes **`man`**, **`sed`**, **`awk`**, **`cp`**, **`mv`**, **`find`** (**`-maxdepth`**, **`-mindepth`**, **`-name`**, **`-type`**), **`cksum`**, **`getconf`** (fixed variable table + **`-a`**), **`xargs`** (bounded; **`ctx.runBinCommand`**; **`-0`**, **`-n`**), etc. Large **`sed`/`awk`** are not byte-identical to GNU on all inputs. **`mkfifo`** is a stub. Online help: **`/share/man/man.json`** and **`man`**. |
| **VFS** | Two-drive unified paths; **`$HOME`** maps to the personal Hyperdrive; writable mounts under **`/mnt`** when HDMS allows. **`mkdir`/`rmdir`**, **`chmod`** (octal + symbolic subset), **`symlink`/`readlink`**, **`stat`/`lstat`**, **`rm`** recursive, **`watch()`** on Hyperdrive paths (optional host **`BARE_OS_VFS_WATCH=0`** to disable). Synthetic **`/proc`**, **`/sys`**, **`/run`**, **`/dev`** for introspection (quotas JSON, boot JSON, initd snapshot, etc.). Empty dirs use **`.bareos_empty`** (same idea as `git-fs-adapter`). |
| **Shell** | Pipelines (pipe between commands), list separator **`;`**, short-circuit logical-**AND** / logical-**OR** between commands, redirects **`>`** / **`>>`** / **`<`**, quoting, **`$VAR`** / **`${VAR}`**, **`$?`** / **`${?}`** (from **`BARE_OS_EXIT_STATUS`**), builtins: **`alias`**, **`unalias`**, **`cd`**, **`export`**, **`unset`**, **`readonly`**, **`umask`**, **`:`**, **`command`**, **`type`**, **`login`**, **`logout`**, **`exit`**. Branching uses **`ctx.exitCode`**. Bounded pipeline capture; optional boot-snippet allowlist (**`BARE_OS_BOOT_ALLOWLIST`** + **`/etc/bare-os/boot.allow`**). No full POSIX **`sh`** grammar. |
| **Ownership** | Display and permission checks use **`UID`/`GID`** and mode bits; **`chown`/`chgrp`** update **`metadata.bareOs`** on the **personal** writable tree (not a multi-user host kernel). |
| **Utilities** | Tier-1 JS **`/bin`** (see §12.10): includes **`man`**, **`sed`**, **`awk`**, **`cp`**, **`mv`**, **`find`** (**`-maxdepth`**, **`-mindepth`**, **`-depth`**, **`-name`**, **`-type`**), **`mktemp`**, **`git-pear`**, **`cksum`**, **`getconf`** (fixed variable table + **`-a`**), **`xargs`** (bounded; **`ctx.runBinCommand`**; **`-0`**, **`-n`**), etc. Large **`sed`/`awk`** are not byte-identical to GNU on all inputs. **`mkfifo`** creates in-memory FIFOs under **`/run/bare-os/ipc/`**. Online help: **`/share/man/man.json`** and **`man`**. |
**Handbook:** [handbook/09-posix-utilities-shell-and-vfs.md](handbook/09-posix-utilities-shell-and-vfs.md) — narrative catalog, engine notes, and Issue 7 alignment. **Manual pages:** [handbook/10-manpages-and-online-help.md](handbook/10-manpages-and-online-help.md).