Files

T

Raven Scott e2b721d19f complete shell 100-item plan across parser, execution, security, and docs

Implement the full BareOS shell roadmap end-to-end, including grammar/tokenization
diagnostics, expansion/runtime hardening, execution graph tooling, builtins/job-control
stability, policy/sandbox controls, and release/traceability documentation updates.

- Add shell grammar baseline and diagnostics primitives:
  - introduce `docs/reference/shell-grammar.md` with lexer modes and EBNF contract
  - add rich diagnostic tokenizer output (mode + span metadata) via `tokenizeBareShellLineDetailed`
  - export structured parse snapshot helpers (`bareOsShellAstSnapshot`) and shell error kinds
  - add determinism coverage for tokenizer and AST snapshot outputs

- Harden expansion semantics and guardrails:
  - enforce expansion byte budgets (`BARE_OS_SHELL_EXPANSION_MAX_BYTES`)
  - add expansion trace hooks (`BARE_OS_SHELL_EXPANSION_TRACE`) with stage-level rows
  - add expansion recursion depth limits (`BARE_OS_SHELL_EXPANSION_MAX_DEPTH`)
  - tighten POSIX-mode arithmetic invalid-token diagnostics
  - preserve declared expansion ordering and document it in code/docs

- Extend redirection/pipeline execution model:
  - add normalized redirection planner (`planShellRedirections`) independent of side effects
  - add execution graph builder/debug surface (`buildShellExecutionGraph`)
  - support `<<-` operator in tokenizer/parser paths
  - add pipeline stage timeout safety (`BARE_OS_SHELL_PIPELINE_STAGE_TIMEOUT_MS`)
  - keep pipefail/pipestatus behavior verified with integration tests

- Improve builtins and control-flow reliability:
  - expand `read` builtin support:
    - `-r` raw mode
    - `-d` single-char delimiter
    - `-t` timeout semantics
  - refine wait/jobs semantics:
    - stable `jobs -l` parseable format expectations
    - synthetic pid mapping (`wait 410x`) and `wait all` support
  - keep trap registration/listing behavior deterministic and test-covered
  - add trap signal dispatch helper (`dispatchShellTrapSignal`) with normalization

- Add security and policy enforcement hooks:
  - command deny/allow policy gates:
    - `BARE_OS_SHELL_DENY_COMMANDS`
    - `BARE_OS_SHELL_ALLOW_COMMANDS`
  - sandbox mode (`BARE_OS_SHELL_SANDBOX`) to block external command execution
  - redirect path safety guard (`BARE_OS_SHELL_REDIRECT_GUARD`) for pseudo-path/traversal risks
  - emit structured shell audit event rows (`ctx.shellAuditEvents`) for start/error/finish

- Improve interactive UX resilience:
  - add prompt-hook timeout protection in fish readline:
    - `resolveShellPromptHookSegment`
    - env control `BARE_OS_SHELL_PROMPT_HOOK_TIMEOUT_MS`
  - ensure prompt segment resolution is non-blocking and safe on timeout/error

- Add reliability/performance artifacts and shell fast lane:
  - add `scripts/bench-shell-phases.mjs` for shell microbench sanity checks
  - add `scripts/gen-shell-reliability-report.mjs` and generate reliability JSON artifact
  - add root scripts:
    - `test:shell-fast`
    - `bench:shell`
    - `report:shell-reliability`

- Expand shell-focused docs and traceability:
  - add:
    - `docs/reference/shell-unsupported-behavior.md`
    - `docs/reference/shell-troubleshooting.md`
  - add contributor guides:
    - `developer-guide/17-how-to-add-shell-builtin.md`
    - `developer-guide/18-how-to-add-shell-grammar-feature.md`
  - update indexes/traceability/release gate docs:
    - `docs/reference/README.md`
    - `docs/reference/posix-issue7-traceability.md`
    - `docs/reference/environment-and-posix-appendix.md`
    - `docs/release-checklist.md`
    - `developer-guide/README.md`
    - `scripts/README.md`

- Add and update shell regression tests in `packages/bare-os-booter/test.js` for:
  - tokenizer spans/modes and deterministic output
  - AST snapshot schema/shape
  - redirection planner and execution graph behavior
  - expansion trace and strict arithmetic paths
  - `<<-` support
  - pipeline stage timeout handling
  - `read` delimiter/raw/timeout semantics
  - jobs/wait parseability and selection semantics
  - trap dispatch and normalization behavior
  - policy/sandbox/redirect-guard/audit-event pathways

Validation:
- `npm run test -w bare-os-booter`
- `npm run test:shell-bracket -w bare-os-booter`
- `npm run test:shell-fast`
- `npm run report:shell-reliability`

2026-04-26 23:17:20 -04:00

fixtures

feat(booter): POSIX/P2P roadmap — profile 1.0.14, ctx 1.50.0, docs & tests

2026-04-05 13:50:07 -04:00

lib

complete shell 100-item plan across parser, execution, security, and docs

2026-04-26 23:17:20 -04:00

scripts

feat(terminal): align clear and fish TTY with xterm.js scrollback behavior

2026-04-25 02:00:44 -04:00

CHANGELOG.md

Updates to MD

2026-04-25 23:18:44 -04:00

CLI_PARITY.md

chore(plan): cancel end-to-end seeder-to-booter smoke harness task

2026-04-26 22:28:21 -04:00

index.js

chore(plan): cancel end-to-end seeder-to-booter smoke harness task

2026-04-26 22:28:21 -04:00

package.json

further shell updates

2026-04-26 16:24:57 -04:00

README.md

Updates to MD

2026-04-25 23:18:44 -04:00

t.s

Updates

2026-04-03 16:29:27 -04:00

test.bare-holesail-managed.js

Stabilize Keys on login

2026-04-22 20:48:16 -04:00

test.bare-holesail.js

Holesail Service Daemon + Bin Client

2026-04-09 20:42:54 -04:00

test.bare-openssh-pty.js

Normalize embedded newlines to CRLF in SSH child ctx console log/error so

2026-04-09 00:53:45 -04:00

test.bare-openssh-sftp.js

fix(openssh): widen SFTP path policy and return real dir/file metadata

2026-04-21 16:44:31 -04:00

test.bare-os-bind-fallback.js

feat(booter): ephemeral port fallback on EADDRINUSE

2026-04-23 20:39:50 -04:00

test.bare-os-chat-roundtrip.js

Fix Mux Pair

2026-04-22 05:48:24 -04:00

test.bare-os-chat-service.js

feat(p2p): introduce shared p2p transport/service stack and launch swarmtop, meshdrop, taskmesh, peernote, and hypershell-board

2026-04-26 07:48:55 -04:00

test.bare-os-chat-wire.js

Chat updates

2026-04-21 20:43:06 -04:00

test.bare-os-ssh-holesail.js

chore(plan): cancel end-to-end seeder-to-booter smoke harness task

2026-04-26 22:28:21 -04:00

test.bare-os-www.js

chore(plan): cancel end-to-end seeder-to-booter smoke harness task

2026-04-26 22:28:21 -04:00

test.bare-smoke.js

chore(plan): cancel end-to-end seeder-to-booter smoke harness task

2026-04-26 22:28:21 -04:00

test.hrpc-allowlist.js

Expand bounded awk/expr/test toward Issue 7; refresh man, profile 1.0.18,

2026-04-05 23:01:54 -04:00

test.identity-session.js

chore(plan): cancel end-to-end seeder-to-booter smoke harness task

2026-04-26 22:28:21 -04:00

test.identity.js

chore(plan): cancel end-to-end seeder-to-booter smoke harness task

2026-04-26 22:28:21 -04:00

test.js

complete shell 100-item plan across parser, execution, security, and docs

2026-04-26 23:17:20 -04:00

test.peer-system-seed.js

chore(plan): cancel end-to-end seeder-to-booter smoke harness task

2026-04-26 22:28:21 -04:00

test.peer-visibility-proc.js

fix(swarmtop): expose and render full peer identity/details from proc surfaces

2026-04-26 08:02:37 -04:00

test.shell-bracket-smoke.mjs

further shell updates

2026-04-26 16:24:57 -04:00

test.socket-scm-rights.js

CI/docs: placeholder-baseline --check, seeder↔kernel sync script and docs,

2026-04-05 14:45:01 -04:00

test.txt

Updates

2026-04-03 16:29:27 -04:00

test.vfs-bare-guest-deny.js

chore(plan): cancel end-to-end seeder-to-booter smoke harness task

2026-04-26 22:28:21 -04:00

text.txt

Updates

2026-04-03 16:29:27 -04:00

w.t

Updates

2026-04-03 16:29:27 -04:00

README.md

bare-os-booter

Pear / Bare application that boots from the network only: joins the same Hyperswarm topic as the seeder, reads MBR block 0 from peers, opens the system Hyperdrive (and a personal namespaced drive), replicates, then runs /boot/init.js with a rich ctx (VFS, shell, identity, HDMS, initd services). After successful boot, eligible nodes can mirror the same block 0 and captured seed RPC snapshots for later cold joiners.

There is no local seed fallback — a running seeder (or another peer with the image, including an eligible booted helper) must be reachable within BARE_OS_BOOT_TIMEOUT_MS.

When to use: run the booter to consume the replicated image and start an interactive session (typical dev: second terminal with npm run os:booter). In peer-assisted mode it can also improve availability for other cold booters after it is up.

Documentation: Concepts — Two drives · Booter reference · Shell completion + Fish REPL · Developer guide §2 — ctx · CHANGELOG (bareOsCtxApiVersion).

Run

# repo root (links node_modules for Pear)
npm run os:booter

Or:

cd packages/bare-os-booter
node index.js

Major subsystems (lib/)

index.js — Swarm, SwarmDisk, boot timeout, executeKernel, ctx assembly, boot/audit/env passthrough; bareOsReadBareTopSnapshot batches /proc/bare_os/* reads for baretop
swarm-disk.js — Peer mux, MBR/read RPC, replication hooks
kernel-runner.js — runKernelFromSource, runBinCommand, resolveBinInPath (PATH on system drive); git / curl / wget delegates
vfs.js — Two-drive routing; mkdir/rmdir (.bareos_empty), chmod, symlink, pseudo /proc//sys, watch, …
shell.js — Tokenize, pipelines, redirections, builtins (barerc, unset, readonly, umask, command, type, …), execShellLine, loadBarerc; default aliases include nano → edit** (TTY editor), **top → baretop** and **btop → baretop (session monitor)
bare-os-theme-presets.js — Named themes (BARE_OS_THEME), applyBareOsThemeFromEnv, BARE_OS_COLOR_DEPTH downgrades for REPL colors
bare-os-ipc.js — FIFOs, JSON-RPC (pushJson/takeJson, token + line limits), fan-out pub/sub, stats
bare-os-abort.js — raceWithAbortAndTimeout for execLine / readLine / VFS / runBinCommand
bare-os-http-policy.js — Optional HTTP allow/deny lists for wrapped ctx.httpFetch
bare-os-ctx-api.js / bare-os-ctx.d.ts — Semantic version of the ctx contract + optional TypeScript shapes
bare-os-runtime-caps.js — Frozen caps: pipeline limits, quotas, pseudo paths, features flags
**bare-os-ctx-bare.js / bare-module-manifest.json / bare-module-manifest.data.mjs** — ctx.bare host imports + optional /lib/bare/ drive bundle merge; Pear loads the manifest from generated bare-module-manifest.data.mjs (see PEAR-RUN.md, Developer guide ch.12)
identity-session.js / identity-account.js — Guest vs unlocked user, /.bare/account, vault
hdms-manager.js — Extra Hyperdrives, mounts under /mnt, Autopass pair/invite
bare-initd.js — Service registry, unit drop-ins, units.d fragments, socket-activation, IdleSec= idle stop, **ConditionPathExists=** / **AssertPathExists=**, ReadinessPath / exec: polling, DAG snapshot /proc/bare_os/initd_graph.json, mobile suspend/resume order, startBareInitd, kernel-logger, bare-os-www → bare-holesail default chain
bare-os-www-initd.js / bare-os-www-holesail.js — Initd unit bare-os-www: static **GET/HEAD** HTTP for **~/.www** (default 127.0.0.1:8088); idempotent managed Holesail row bare-www-<port> in ~/.holesail/state.json ( BARE_OS_HOLESAIL_STATE ) with persisted seed / key (see handbook § bare-holesail)
bare-os-ssh-holesail.js — After bare-openssh listen, merges **bare-ssh-<port>** into the same managed state.json ( BARE_OS_SSH_HOLESAIL); post-login ensure from bare-user-session-stack.js if sshd started before bare-holesail
bare-cron.js — /etc/bare-os/crontab, ~/.crontab, ~/.config/bare-os/timers/*.timer (OnCalendar=, EveryMs=, **OnInactiveSec=** / **Persistent=**), minute scheduler, ctx.execLine jobs
bare-os-delegate-concurrent.js — Optional in-flight caps (BARE_OS_DELEGATE_MAX_CONCURRENT, per-kind **BARE_OS_DELEGATE_*_MAX_CONCURRENT**) around host delegates
repl-session.js — Fish-style TTY line editor, synced console, cleanup → stopBareInitd
completion-engine.js — Tab completion context (parseCompletionContext), man/PATH/VFS/proc collectors, ranking, ctx.bareOsRegisterCompleter
boot-splash.js — Centered TTY boot splash (responsive frame, bar, log); cursor hidden until prepareForKernel()
fish-readline.js — History, ghost text, Fish-style completion menu / keys
cli-readline.js, resolve-stdio.js, debug-repl.js — Stdio and debug tooling
paths.js — Pear-safe package root and Corestore path
bare-os-pear-ipc-registry.js — Well-known Pear IPC channel names; JSON at /proc/bare_os/pear_ipc.json

Environment

BARE_OS_HOST_DATA — Base directory for host state (default ~/.bare-os)
BARE_OS_BOOT_STORE — Corestore directory (default ~/.bare-os/corestore/booter)
BARE_OS_LOCAL_SEED — Overrides defaultLocalSeedCorestorePath (booter does not local-boot)
BARE_OS_BOOT_TIMEOUT_MS — Total time to find peers + load kernel (default 60000)
BARE_OS_NO_SPLASH — Disable TTY splash
BARE_OS_SKIP_REPL — Non-interactive kernel (readLine → null)
BARE_OS_FISH — Set 0 to disable fish-style editor
BARE_OS_COMPACT_MENU — 1 / true forces inline tab cycling (no dropdown menu)
HYPERSWARM_BOOTSTRAP — Optional comma-separated bootstrap nodes (HDMS / replication)

Copied from host into the guest session when set (non-exhaustive; see environment variables reference and CHANGELOG.md): BARE_OS_PIPELINE_MAX_STAGES, BARE_OS_PIPELINE_MAX_BYTES, BARE_OS_PIPELINE_MAX_LINES, BARE_OS_PIPELINE_ABS_MAX_BYTES, BARE_OS_PIPELINE_ABS_MAX_LINES, BARE_OS_SHELL_STREAMING, BARE_OS_SHELL_STREAMING_MULT, BARE_OS_STREAMING_MULTIPLIER, BARE_OS_SHELL_PARAM_EXPANSION, 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_BOOT_ALLOWLIST, BARE_OS_EXEC_MAX_DEPTH, BARE_OS_EXEC_LINE_BUDGET_MS, BARE_OS_TIMER_BUDGET_MS, BARE_OS_IPC_MAX_BYTES, BARE_OS_IPC_MAX_CHANNELS, BARE_OS_POSIX_MQ_MAX_MSGS, BARE_OS_POSIX_MQ_MSG_BYTES, BARE_OS_IPC_RPC_TOKEN, BARE_OS_IPC_FANOUT, BARE_OS_IPC_JSON_MAX_BYTES, BARE_OS_HTTP_ALLOWLIST, BARE_OS_HTTP_DENYLIST, BARE_OS_TLS_PIN_SHA256, BARE_OS_VFS_WATCH, BARE_OS_VFS_MAX_OPEN, BARE_OS_IMAGE_DIGEST, BARE_OS_TELEMETRY_NDJSON, BARE_OS_TELEMETRY_OTEL_JSONL, BARE_OS_TELEMETRY_OTEL, BARE_OS_PROC_POLL_MS, BARE_OS_DELEGATE_MAX_PER_MIN, BARE_OS_DELEGATE_AUDIT_ONLY, BARE_OS_PEAR_CHANNEL, BARE_OS_PEAR_RELEASE, BARE_OS_BARE_MODULES, BARE_OS_BARE_DRIVE_BUNDLES, TERM, COLORTERM, PEAR_CHANNEL.

Tests

npm test -w bare-os-booter

brittle-bare test.identity.js — crypto account codec (Bare)
brittle-node test.js — Hyperdrive, VFS, shell, kernel runner, cron matchers, etc.; includes parity of bare-module-manifest.json vs bare-module-manifest.data.mjs
Root npm run verify:manifest-data — ensures JSON and .data.mjs stay in sync (runs in pretest)

Pear staging

pear.stage.include is node_modules (flat mirror of the repo root hoist under this package, via scripts/ensure-pear-node-modules.mjs) so Bare resolves **node_modules/<pkg>** in released bundles. Run that script from the repo root before pear run (see root README). After changing bare-module-manifest.json or running sync:bare-manifest, confirm npm run verify:manifest-data passes, then **pear stage / pear release** so Pear ships an up-to-date bare-module-manifest.data.mjs.

README.md

bare-os-booter

Run

Major subsystems (lib/)

Environment

Tests

Pear staging

See also