Docs+handbook

2026-04-03 03:12:44 -04:00
parent d794c87b32
commit 7435f4b353
16 changed files with 1044 additions and 33 deletions
@@ -0,0 +1,41 @@
+# bare-os-coreutils
+
+**Build step**, not a runtime library: concatenates a tiny shared prelude (`lib/runtime.js`) with 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:
+
+```js
+async function run(ctx, argv) {
+  /* ... */
+}
+```
+
+No top-level `import` — commands are loaded by the booter via `AsyncFunction` for Bare/Pear compatibility. Use `ctx.vfs`, `ctx.console`, `ctx.b4a`, `ctx.drive`, `bareStdin(ctx)` from the prelude where needed.
+
+## 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 (current)
+
+`basename`, `cat`, `clear`, `crontab`, `date`, `dirname`, `echo`, `env`, `exit`, `false`, `head`, `hdms`, `help`, `hostname`, `id`, `login`, `logout`, `ls`, `nl`, `pathchk`, `printenv`, `pwd`, `rm`, `savevault`, `seq`, `sleep`, `sort`, `tail`, `test`, `touch`, `true`, `tty`, `uname`, `wc`, `which`, `whoami`
+
+See [handbook command reference](../../handbook/06-kernel-and-binaries.md) for behavior notes (e.g. `ls -a`, `crontab` identity gating).
+
+## See also
+
+- [kernel/README.md](../../kernel/README.md) — where built artifacts live in the source tree.
+- [DOCUMENTATION.md](../../DOCUMENTATION.md) §12.10 (may lag the command list; this README and `build.mjs` are authoritative).