snxraven/bare-operating-system
1
1
Fork 1
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity
Files
e2b721d19faab3c3155e8e02dde4b77431a03b7d
bare-operating-system/packages/bare-os-seeder/kernel/lib/bare
T
History
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
..
bundles
HS Updates
2026-04-24 08:39:22 -04:00
bare-module-lock.json
Kernel Updates
2026-04-03 23:21:30 -04:00
bare-module-manifest.json
Holesail Service Daemon + Bin Client
2026-04-09 20:42:54 -04:00
manifest.json
chore(plan): cancel end-to-end seeder-to-booter smoke harness task
2026-04-26 22:28:21 -04:00
README.md
Updates to MD
2026-04-25 23:18:44 -04:00
shell-completion.json
complete shell 100-item plan across parser, execution, security, and docs
2026-04-26 23:17:20 -04:00

README.md

/lib/bare (system image)

Self-contained ctx.bare support on the system Hyperdrive: Holepunch Bare packages bundled as IIFE scripts the booter can execute without a traditional Node module graph on the drive.

Documentation: Developer guide ch.12 · bare-os-bare-libs package README.

On this page

What gets staged

  • bare-module-manifest.json — Copy of the booter manifest (same keys and packages as host resolution). Tells the runtime which logical module names exist.
  • manifest.json — Drive loader index: bundles lists IIFE paths that assign into globalThis.__bare_os_stdlib__; bundleStats counts attempted bundles; bundleDiagnostics lists each bundle’s byte size (same data as docs/audit/bundle-health.json).
  • bundles/*.js — One esbuild IIFE per catalog entry. The bare-libs build is fail-fast (esbuild errors abort; no stub placeholders). Stale ***.js** left from older tiered builds are pruned on each successful build. Regenerate with npm run build -w bare-os-bare-libs (updates docs/audit/bundle-health.json).

At boot the booter runs drive bundles first, then (unless BARE_OS_BARE_HOST_IMPORTS=0) fills any missing keys via host import() so development iterations can patch a single package without re-seeding the entire drive.

Boot order: drive bundles vs host imports

  1. Seeded bundles win for keys they actually populate — they are part of the trusted image, same class as /bin.
  2. Host imports run only for keys still missing after bundle evaluation, keeping local checkout workflows fast.
  3. Disabling host imports (BARE_OS_BARE_HOST_IMPORTS=0) approximates production Pear behavior where only the drive contents exist.

Environment toggles

The authoritative list is in the environment appendix. Names that operators mention most often alongside /lib/bare:

  • BARE_OS_BARE_HOST_IMPORTS — Set to 0 / false to forbid host **import()** fallback (drive-only resolution).
  • Related Pear ctx.bare toggles and HTTP allow lists are documented in PEAR-RUN.md and the booter package reference.

Trust model

Trusted image only: executing these bundles is equivalent to running seeded /bin utilities. Do not copy arbitrary third-party IIFEs into kernel/lib/bare/bundles/ without reviewing them the same way you would review a new setuid binary on a Unix system.

Regenerating bundles

  1. Edit packages/bare-os-booter/lib/bare-module-manifest.json or bundle sources under packages/bare-os-bare-libs/ as needed.
  2. Run npm run build -w bare-os-bare-libs — output lands in kernel/lib/bare/ (and CI expects packages/bare-os-seeder/kernel/ to match kernel/ byte-for-byte afterward).
  3. Mirror kernel/ into packages/bare-os-seeder/kernel/ (same tree) so scripts/verify-kernel-seeder-parity.mjs passes — typically rsync -a --delete kernel/ packages/bare-os-seeder/kernel/ from the repo root after init/bundle changes.
  4. Re-run the seeder so peers replicate the updated system drive.

Order with coreutils: from repo root, prefer npm run build -w bare-os-coreutils && npm run build -w bare-os-bare-libs && npm run bundle:kernel before parity check (matches root pretest).

When builds fail

Esbuild prints the failing ctxKey and package. Fix bare-module-manifest.json, adjust build.mjs (plugins, platform), or mark the entry optional / bundle: false when host-only resolution is intended. npm run smoke:bare-manifest guards required imports listed in the manifest smoke list.

CI: scripts/verify-bundle-health.mjs checks docs/audit/bundle-health.json against on-disk sizes; scripts/verify-bundle-markers.mjs and scripts/verify-bundle-throws.mjs gate incomplete-looking substrings / Error messages. scripts/sanitize-bare-bundles.mjs (run from this build) normalizes known upstream HTTP helpers, stream-base-class messages, and ICO encode paths so docs/audit/bundle-marker-allowlist.json and docs/audit/bundle-throw-allowlist.json stay empty.

Note: This file is copied to kernel/lib/bare/README.md (and the vendored seeder tree) by bare-os-bare-libs build. Links are written for the kernel/lib/bare/ path; verify-doc-links skips this template path because its on-disk location differs.

Reference in New Issue View Git Blame Copy Permalink