Raven Scott
014c70ad09
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)
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;bareOsReadBareTopSnapshotbatches/proc/bare_os/*reads forbaretopswarm-disk.js— Peer mux, MBR/read RPC, replication hookskernel-runner.js—runKernelFromSource,runBinCommand,resolveBinInPath(PATH on system drive);git/curl/wgetdelegatesvfs.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 includenano→edit**(TTY editor),**top→baretop**and**btop→baretop(session monitor)bare-os-theme-presets.js— Named themes (BARE_OS_THEME),applyBareOsThemeFromEnv,BARE_OS_COLOR_DEPTHdowngrades for REPL colorsbare-os-ipc.js— FIFOs, JSON-RPC (pushJson/takeJson, token + line limits), fan-out pub/sub,statsbare-os-abort.js—raceWithAbortAndTimeoutforexecLine/readLine/ VFS /runBinCommandbare-os-http-policy.js— Optional HTTP allow/deny lists for wrappedctx.httpFetchbare-os-ctx-api.js/bare-os-ctx.d.ts— Semantic version of thectxcontract + optional TypeScript shapesbare-os-runtime-caps.js— Frozen caps: pipeline limits,quotas, pseudo paths,featuresflags- **
bare-os-ctx-bare.js/bare-module-manifest.json/bare-module-manifest.data.mjs**—ctx.barehost imports + optional/lib/bare/drive bundle merge; Pear loads the manifest from generatedbare-module-manifest.data.mjs(see PEAR-RUN.md, Developer guide ch.12) identity-session.js/identity-account.js— Guest vs unlocked user,/.bare/account, vaulthdms-manager.js— Extra Hyperdrives, mounts under/mnt, Autopass pair/invitebare-initd.js— Service registry, unit drop-ins,units.dfragments, 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-holesaildefault chainbare-os-www-initd.js/bare-os-www-holesail.js— Initd unitbare-os-www: static**GET/HEAD**HTTP for**~/.www** (default127.0.0.1:8088); idempotent managed Holesail rowbare-www-<port>in~/.holesail/state.json(BARE_OS_HOLESAIL_STATE) with persistedseed/key(see handbook § bare-holesail)bare-os-ssh-holesail.js— Afterbare-opensshlisten, merges**bare-ssh-<port>**into the same managedstate.json(BARE_OS_SSH_HOLESAIL); post-login ensure frombare-user-session-stack.jsif sshd started beforebare-holesailbare-cron.js—/etc/bare-os/crontab,~/.crontab,~/.config/bare-os/timers/*.timer(OnCalendar=,EveryMs=,**OnInactiveSec=**/**Persistent=**), minute scheduler,ctx.execLinejobsbare-os-delegate-concurrent.js— Optional in-flight caps (BARE_OS_DELEGATE_MAX_CONCURRENT, per-kind**BARE_OS_DELEGATE_*_MAX_CONCURRENT**) around host delegatesrepl-session.js— Fish-style TTY line editor, syncedconsole, cleanup →stopBareInitdcompletion-engine.js— Tab completion context (parseCompletionContext), man/PATH/VFS/proc collectors, ranking,ctx.bareOsRegisterCompleterboot-splash.js— Centered TTY boot splash (responsive frame, bar, log); cursor hidden untilprepareForKernel()fish-readline.js— History, ghost text, Fish-style completion menu / keyscli-readline.js,resolve-stdio.js,debug-repl.js— Stdio and debug toolingpaths.js— Pear-safe package root and Corestore pathbare-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— OverridesdefaultLocalSeedCorestorePath(booter does not local-boot)BARE_OS_BOOT_TIMEOUT_MS— Total time to find peers + load kernel (default60000)BARE_OS_NO_SPLASH— Disable TTY splashBARE_OS_SKIP_REPL— Non-interactive kernel (readLine→ null)BARE_OS_FISH— Set0to disable fish-style editorBARE_OS_COMPACT_MENU—1/trueforces 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 ofbare-module-manifest.jsonvsbare-module-manifest.data.mjs- Root
npm run verify:manifest-data— ensures JSON and.data.mjsstay in sync (runs inpretest)
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.
See also
- Developer guide — Bare modules
- Handbook — Booter runtime
- Booter reference §12 —
packages/bare-os-coreutils/lib/commands.mjsis the authoritative/binname list