snxraven/bare-operating-system
1
1
Fork 1
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity
Files
014c70ad099a1bdf28a9723a23ac1d6451a5b293
bare-operating-system/packages/bare-os-seeder/kernel/lib/bare
T
History
Raven Scott 014c70ad09 feat: introduce ctx.pear surface and /bin/pear for in-OS Pear development 
Complete the full planned effort for the detailed ctx.bare code audit
and the new ctx.pear surface, delivering the ability to create, stage,
and integrate real Pear applications from within a booted Bare OS.

### Audit (ctx.bare)
- Performed exhaustive code audit of bare-os-ctx-bare.js (host import
  path, drive bundle eval + require.addon wrappers, referrer workarounds).
- Inventoried all manifest/bundle verifiers and related scripts.
- Researched manifest format, implicit tiering model, and dual loading
  strategy (JSON + .data.mjs).
- Deep analysis of the local Holepunch clone (bare-* and pear-* packages)
  to identify realistic guest vs host-delegate boundaries.
- Full cross-reference of call sites, greps, and historical pain points
  (pear:// referrer resolution, nativeHint handling, addon stubs).

### Implementation (ctx.pear)
- Added `pearEntries` tier to bare-module-manifest.json with initial
  high-value packages (pear-build, pear-bundle, pear-ref, etc.).
- Implemented `loadPearModuleManifest()` and `buildPearCtxObjectFromHost()`.
- Wired ctx.pear exposure through the booter into the guest context.
- Updated TypeScript definitions (`bare-os-ctx.d.ts`).

### User-Facing Surface
- Created full `/bin/pear` command with `help`, `info`, `list`, `init`
  (functional skeleton creation), and improved `stage` subcommands.
- Registered as Tier-1 command (now 183 total commands).
- Added man page and rebuilt coreutils (kernel + seeder).

### Agent Autonomy
- Created production-quality `pear-dev` agent skill.
- Added to skill seed list with cross-references to the appstore skill.

### P2P App Store Integration
- Updated appstore skill with explicit Pear development synergy section.
- Updated p2p-app-store design doc to document the new closed loop.
- Added cross-references in both skills and design documents.

### Verification & Hygiene
- Created `scripts/verify-pear-module-manifest-data.mjs`.
- Enhanced `verify-pear-no-static-node-import.mjs` with explicit pear
  command coverage.
- Integrated new verifier into release-checklist and agent hints.
- Performed comprehensive zero-TODO/scaffolding sweep across all new
  Pear artifacts (clean).
- Multiple full verification harness runs (all green).

### Documentation & Governance
- Added complete "Pear Development Environment" thread to feature-roadmap.md.
- Updated developer guide (Chapter 12).
- Maintained living plan document and detailed audit notes with full
  Implementation Log throughout.
- Updated command counts across READMEs and supporting docs.

All changes follow project governance:
- Bare-only guest constraints strictly observed
- Verifier-first discipline maintained
- Living plan + audit documents kept as single source of truth
- Production quality bar matching the completed P2P App Store feature

Plan items 04–21 completed.

See:
- docs/design/ctx-pear-surface-and-bare-audit-plan.md
- docs/audit/ctx-bare-audit-notes.md (full audit + implementation log)
2026-05-26 17:54:06 -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
Close the BareOS shell + Fish REPL roadmap tracker and ship the remaining
2026-04-27 00:41:06 -04:00
README.md
Updates to MD
2026-04-25 23:18:44 -04:00
shell-completion.json
feat: introduce ctx.pear surface and /bin/pear for in-OS Pear development
2026-05-26 17:54:06 -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