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)
This commit is contained in:
Raven Scott
@@ -355,7 +355,7 @@ The list below is one **bullet per variable** in the form **name — component
|
||||
- **Errno vocabulary** — `**/proc/bare_os/syscalls.json**` `**errnoHints**` and `**errnoAlignment**` document Linux-style integers (same family as **libuv** / **Holepunch `bare-fs**` binding `error.code` strings). Utilities such as `mkdir` print `errno: message` on stderr when the caught error exposes a string `code` (for example `EEXIST`, `EACCES`), matching the vocabulary in `errnoHints`. Simulated logical FDs (`**BARE_OS_POSIX_FD_SIM`**) use `EBADF`, `EAGAIN`, `EINVAL`, `ENOSYS`, `EOPNOTSUPP` consistently; `fcntl` cooperative `F_SETLK` returns `EAGAIN` when contended; `F_SETLKW` does the same unless `BARE_OS_POSIX_FCNTL_BLOCKING_WAIT` is set (then `ETIMEDOUT` when `BARE_OS_FCNTL_LOCK_WAIT_MS_MAX` elapses). Cooperative waits are not kernel futexes: callers may see an `**EINTR`-shaped note** when a blocking wait is interrupted by policy rather than a real signal. `**fcntl`** `**O_APPEND**`/`**O_NONBLOCK**` bit masks align with `**bare-fs**` open-flag shapes when the host resolves native FS errors.
|
||||
- **Shell** — Pipelines, `**;**`, `**&&**` / `— — **`, redirects, quoting, `**$VAR`**, `$?`, optional `${VAR:-word}` / `${VAR#prefix}` when `BARE*OS_SHELL_PARAM_EXPANSION=1`, `jobs` / `fg` / `wait`, optional background `&` segments, builtins including bounded `if`, `while`, `for`, `case` (caps `BARE_OS_SHELL_LOOP_MAX`, `BARE_OS_SHELL_CASE_MAX_BRANCHES`). Optional bounded `$(…)` when `BARE_OS_SHELL_CMDSUBST=1`; optional larger pipeline capture via `BARE_OS_SHELL_STREAMING` / `BARE_OS_SHELL_STREAMING_MULT`. Branching uses `ctx.exitCode`. Bounded pipeline capture (`**BARE_OS_PIPELINE*\*`**, `ctx.bareOsRuntimeCaps`); optional boot-snippet allowlist (*`*BARE_OS_BOOT_ALLOWLIST`** + `**/etc/bare-os/boot.allow`**). No subshells or full POSIX `**sh`.
|
||||
- **Ownership** — Display and permission checks use `**UID`/`GID**` and mode bits; `**chown`/`chgrp**` update `**metadata.bareOs**` on the **personal** writable tree (not a multi-user host kernel).
|
||||
- **Utilities** — Tier-1 JS `**/bin`** (**179** commands; authoritative list `**COREUTILS_COMMANDS`** in `**packages/bare-os-coreutils/lib/commands.mjs**`; `**sshd**`/`**bare-sshd**` binaries come from `**bare-os-openssh**`; see [§12.10](package-bare-os-coreutils-and-ci.md#1210-package-bare-os-coreutils)): text tools include `**paste**`, `**split**`, `**tac**`, `**rev**`, `**expand**`, `**unexpand**`, `**fold**`, `**fmt**`, `**comm**`, `**cmp**`, `**join**`, `**pr**`, `**yes**` (line-capped via `**BARE_OS_YES_MAX_LINES**` / `**getconf**`), `**shuf**` (capped via `**BARE_OS_SHUF_MAX_LINES**`), `**tsort**`, `**factor**`, `**expr**` (integer-focused subset), `**numfmt**` (`**--to=iec**` / `**--to=si**`). Checksums: `**md5sum**` (bundled MD5), `**sha1sum**`, `**sha224sum**` (bundled SHA-224), `**sha256sum**`, `**sha384sum**`, `**sha512sum**` (Web Crypto where available), `**sum**`, `**base32**`, `**basenc**` (`**--base16**`). Files: `**truncate**`, `**unlink**`, `**install**`, `**df**` (synthetic Hyperdrive row; `**-h**` human sizes), `**sync**` (no-op), `**timeout**` (wall-clock cap; exit **124** on timeout when `**BARE_OS_FEATURE_ABORT_TIMEOUT`** is advertised). Session stubs: `**arch**`, `**groups**`, `**hostid**`, `**nproc**`, `**uptime**`, `**users**`, `**who**`. Plus earlier parity: `**man**`, `**sed**` (including `**-z**`, `**BARE_OS_SED_NULL_MAX_RECORDS**`), `**awk**`, `**grep**` (`**-r**` with `**--include`/`--exclude`/`--exclude-dir**`, `**BARE_OS_GREP_FILTER_MAX**`), `**cp**` (`**-u`/`-v`/`-p**`), `**mv**`, `**find**` (`**-regex**`, `**-exec`/`-ok**`, `**BARE_OS_FIND_EXEC_MAX**`), `**mktemp**`, `**git-pear**`, `**cksum**`, `**getconf**` (static name table plus live `**vfs.env**` overrides for caps; `**-a**`), `**xargs**` (`**-P**` cap raised via `**BARE_OS_XARGS_MAX_PROCS**`, hard max **32**), `**getfacl`** / `**setfacl**` (POSIX-style ACL **view/edit** against synthetic `**/.bare_acl.json`** sidecars; see handbook ch.9), `**dircolors**`, `**theme**`, `**ls**`, `**uniq**`, `**realpath**`, `**base64**`, `**rm**` `**-d**`, `**stat**` `**%F**`. `**dir**` / `**vdir**` call `**ls**`. Large `**sed`/`awk**` are not byte-identical to GNU on all inputs. `**mkfifo**` → `**/run/bare-os/ipc/**`; optional logical process groups via `**ctx.bareOsIpc.assignProcessGroup**` / `**signalProcessGroup**` (POSIX `**setpgid**` / `**killpg**` analog for IPC routing). Machine-readable per-command POSIX hints: stock `**/etc/bare-os/posix_utilities.json**` (path echoed in `**/proc/bare_os_features**` and `**metrics_live**`). Online help: `**/share/man/man.json**` and `**man**`.
|
||||
- **Utilities** — Tier-1 JS `**/bin`** (**183** commands; authoritative list `**COREUTILS_COMMANDS`** in `**packages/bare-os-coreutils/lib/commands.mjs**`; `**sshd**`/`**bare-sshd**` binaries come from `**bare-os-openssh**`; see [§12.10](package-bare-os-coreutils-and-ci.md#1210-package-bare-os-coreutils)): text tools include `**paste**`, `**split**`, `**tac**`, `**rev**`, `**expand**`, `**unexpand**`, `**fold**`, `**fmt**`, `**comm**`, `**cmp**`, `**join**`, `**pr**`, `**yes**` (line-capped via `**BARE_OS_YES_MAX_LINES**` / `**getconf**`), `**shuf**` (capped via `**BARE_OS_SHUF_MAX_LINES**`), `**tsort**`, `**factor**`, `**expr**` (integer-focused subset), `**numfmt**` (`**--to=iec**` / `**--to=si**`). Checksums: `**md5sum**` (bundled MD5), `**sha1sum**`, `**sha224sum**` (bundled SHA-224), `**sha256sum**`, `**sha384sum**`, `**sha512sum**` (Web Crypto where available), `**sum**`, `**base32**`, `**basenc**` (`**--base16**`). Files: `**truncate**`, `**unlink**`, `**install**`, `**df**` (synthetic Hyperdrive row; `**-h**` human sizes), `**sync**` (no-op), `**timeout**` (wall-clock cap; exit **124** on timeout when `**BARE_OS_FEATURE_ABORT_TIMEOUT`** is advertised). Session stubs: `**arch**`, `**groups**`, `**hostid**`, `**nproc**`, `**uptime**`, `**users**`, `**who**`. Plus earlier parity: `**man**`, `**sed**` (including `**-z**`, `**BARE_OS_SED_NULL_MAX_RECORDS**`), `**awk**`, `**grep**` (`**-r**` with `**--include`/`--exclude`/`--exclude-dir**`, `**BARE_OS_GREP_FILTER_MAX**`), `**cp**` (`**-u`/`-v`/`-p**`), `**mv**`, `**find**` (`**-regex**`, `**-exec`/`-ok**`, `**BARE_OS_FIND_EXEC_MAX**`), `**mktemp**`, `**git-pear**`, `**cksum**`, `**getconf**` (static name table plus live `**vfs.env**` overrides for caps; `**-a**`), `**xargs**` (`**-P**` cap raised via `**BARE_OS_XARGS_MAX_PROCS**`, hard max **32**), `**getfacl`** / `**setfacl**` (POSIX-style ACL **view/edit** against synthetic `**/.bare_acl.json`** sidecars; see handbook ch.9), `**dircolors**`, `**theme**`, `**ls**`, `**uniq**`, `**realpath**`, `**base64**`, `**rm**` `**-d**`, `**stat**` `**%F**`. `**dir**` / `**vdir**` call `**ls**`. Large `**sed`/`awk**` are not byte-identical to GNU on all inputs. `**mkfifo**` → `**/run/bare-os/ipc/**`; optional logical process groups via `**ctx.bareOsIpc.assignProcessGroup**` / `**signalProcessGroup**` (POSIX `**setpgid**` / `**killpg**` analog for IPC routing). Machine-readable per-command POSIX hints: stock `**/etc/bare-os/posix_utilities.json**` (path echoed in `**/proc/bare_os_features**` and `**metrics_live**`). Online help: `**/share/man/man.json**` and `**man**`.
|
||||
- **Process tooling note** — `**ps`** and `**kill**` operate on Bare OS synthetic process rows (`pid` 1..3 for kernel/booter/shell); they do not target host OS processes.
|
||||
- **Additional utility coverage** — `**dd`** (block-copy subset) and `**logger**` (structured append to `**/var/log/messages**`) are available as Tier-1 commands.
|
||||
- **Mount tooling note** — `**mount`** / `**umount**` are Hyperdrive/HDMS-backed commands for `/mnt/<label>` and are not host-kernel mount syscalls.
|
||||
|
||||
@@ -812,3 +812,98 @@ Second batch of the same governed program. Traceability: [developer-guide/kernel
|
||||
| 98 | Chaos safe-mode rollback integration test doc | done |
|
||||
| 99 | Release gate benchmark regression script | done |
|
||||
| 100 | Program batch B table + verify-kernel-program-roadmap-table.mjs CI | done |
|
||||
|
||||
---
|
||||
|
||||
## Kernel program backlog — batch C (100 items, in progress)
|
||||
|
||||
Third batch of the governed kernel program (post word-11 + 200-item baseline). Traceability: [developer-guide/kernel-program.md](../../developer-guide/kernel-program.md), **`/proc/bare_os/kernel_program.json`** (planned schema **3** or adjunct-only), `bareOsCtxApiVersion` **TBD on first real surface** (target ≥1.55). New items here should be small, testable with existing harnesses, and accompanied by a matching agent skill update when they touch developer workflow.
|
||||
|
||||
Use the **`kernel-program-extension`** skill (seeded) + `bareos-code-change` + `docs-contract-update` before editing. Always add the roadmap row **first**.
|
||||
|
||||
| # | Item | Status |
|
||||
| ---: | --- | --- |
|
||||
| 1 | Batch C section + kernel-program-extension agent skill (this row) | done — skill with full Bare/Pear runtime constraints research notes + cross-refs |
|
||||
| 2 | kernel-program proc schema 3 + programVersion 3 bump (minimal adjunct) | done — bare-os-kernel-program-proc.js + batchC field |
|
||||
| 3 | new operatorSketch: bareOsEmitKernelProgramOperatorHint + env | planned |
|
||||
| 4 | Batch C verifier v2 (300-item table support + roadmap table count) | done — verify-kernel-program-roadmap-table.mjs generalized (skips A, enforces B + future completed batches) |
|
||||
| 5 | kernel.ext.d 'provides' semver field + resolver support | planned |
|
||||
| 6 | Wasm kernel bridge expansion (posix_fadvise + select fds when enabled) | planned |
|
||||
| 7 | kernel-program-benchmark-harness v2 (add batch C timing suite) | planned |
|
||||
| 8 | operatorSketches in /proc/bare_os/kernel_program.json documented | planned |
|
||||
| 9 | kernel-program-release-gate.mjs extended for Batch C items | planned |
|
||||
| 10 | All future Batch C items must reference local bare-* clones at BARE_OS_HOLEPUNCH_CLONES_ROOT for guest-safe APIs (research captured in kernel-program-extension skill) | done — research + skill notes |
|
||||
| 11 | First real non-doc Batch C item (chosen from Streams G/H/I or new, designed against bare-fs / bare-worker / bare-crypto etc. as appropriate) + full pretest | planned |
|
||||
|
||||
See also the **Streams** (G–S) tracked under word 11 for concrete work items that can graduate into Batch C rows with owners.
|
||||
|
||||
See also [kernel-extensions.md](kernel-extensions.md) and [package-bare-os-protocol.md](package-bare-os-protocol.md).
|
||||
|
||||
---
|
||||
|
||||
## Kernel program backlog — batch D (100 items)
|
||||
|
||||
Fourth batch of the governed kernel program. Builds on word-11 baseline, schema 3 proc, and early Batch C foundations (including the P2P App Store design in `docs/design/p2p-app-store.md`).
|
||||
|
||||
Traceability: [developer-guide/kernel-program.md](../../developer-guide/kernel-program.md), **`/proc/bare_os/kernel_program.json`** schema **3**, `bareOsCtxApiVersion` target **≥1.55**.
|
||||
|
||||
All items must follow the updated process: start with `read_skill kernel-program-extension`, update this table first, prefer small verifiable increments, and update the `kernel-program-extension` skill when developer workflow is affected.
|
||||
|
||||
### Theme: P2P App Store (major thread for Batch D)
|
||||
|
||||
See the full design at [docs/design/p2p-app-store.md](../../docs/design/p2p-app-store.md). This is one of the primary application-layer features planned for this batch.
|
||||
|
||||
| # | Item | Status |
|
||||
| ---: | --- | --- |
|
||||
| 1 | App Store drive convention + HDMS label `appstore` + basic registry schema v1 | planned |
|
||||
| 2 | `/bin/appstore` skeleton (list, info, search via pkg-swarm-index) | planned |
|
||||
| 3 | New agent skill `skills/appstore/SKILL.md` (discovery + safe install guidance) | planned |
|
||||
| 4 | HDMS auto-mount of appstore drive on session/login | planned |
|
||||
| 5 | Full user-app install flow (manifest resolution + materialization into store drive) | planned |
|
||||
| 6 | Service manifest + automatic initd unit generation from installed packages | planned |
|
||||
| 7 | `appstore launch` + integration with existing Pear/appctl/peerctl paths | planned |
|
||||
| 8 | Signed extension manifest format + verification for store-sourced kernel extensions | planned |
|
||||
| 9 | Gated `appstore install --kernel-ext` + boot policy fields (pins, review status) | planned |
|
||||
| 10 | Appstore-sourced extensions loaded with distinct source tag + audit trail | planned |
|
||||
| 11 | `/proc/bare_os/appstore.json` + related virtual files | planned |
|
||||
| 12 | `ctx.bareOsAppstore*` surface (install, list, drive reference, extension registration) | planned |
|
||||
| 13 | Multi-index support + curated vs community channels in discovery | planned |
|
||||
| 14 | Agent-driven "recommended for your workload" installation flows | planned |
|
||||
|
||||
### Theme: Pear Development Environment (ctx.pear + /bin/pear) — new 2026 thread
|
||||
|
||||
See full plan and design at [docs/design/ctx-pear-surface-and-bare-audit-plan.md](../../docs/design/ctx-pear-surface-and-bare-audit-plan.md) and audit notes in `docs/audit/ctx-bare-audit-notes.md`.
|
||||
|
||||
This thread delivers the ability to create, stage, release, and seed real Pear applications from inside a booted Bare OS guest (closing the loop with the P2P App Store).
|
||||
|
||||
| # | Item | Status |
|
||||
| ---: | --- | --- |
|
||||
| 1 | Add `pearEntries` tier to manifest + parallel loading in booter (`loadPearModuleManifest`) | done |
|
||||
| 2 | `buildPearCtxObjectFromHost` + `ctx.pear` exposure on guest context | done |
|
||||
| 3 | `/bin/pear` skeleton command (info, list, basic stage stub) + man page | done |
|
||||
| 4 | `pear-dev` agent skill (autonomous Pear dev workflows) + seed list update | done |
|
||||
| 5 | Cross-skill integration: `pear-dev` + `appstore` skills recognize each other | done |
|
||||
| 6 | Richer `/bin/pear` subcommands (`init`, `stage` awareness, basic bundle hooks) | done |
|
||||
| 7 | Host delegate strategy for heavy Pear operations (sidecar IPC, signing, seeding) | planned |
|
||||
| 8 | HDMS convention for `pear-dev` drive (parallel to `appstore` label) | planned |
|
||||
| 9 | `pear release` / `pear seed` that can target App Store drives or direct swarms | planned |
|
||||
| 10 | Full verification, Batch D roadmap items, zero-TODO polish, agent-assisted review | planned |
|
||||
|
||||
### Other Themes (to be expanded)
|
||||
|
||||
Additional major themes for the remaining ~86 items in Batch D will be added iteratively. Current candidate themes (drawn from remaining Streams G–S and post-word-11 maturation needs):
|
||||
|
||||
- Agent Ecosystem 2.0 (autonomy, memory, skill marketplace)
|
||||
- Coreutils & Shell Completeness (advanced job control, process substitution, etc.)
|
||||
- Initd / Timer / Service Maturity
|
||||
- Workers, Sandbox & Subprocess Accounting
|
||||
- Security & Zero-Trust Phase 2
|
||||
- Observability & Diagnostics 2.0
|
||||
- bare-* Dual-Target Tooling & Ecosystem
|
||||
- Documentation, DX & Onboarding
|
||||
- Reliability, Testing & Chaos Engineering
|
||||
- Wasm & Extension Ecosystem Hardening
|
||||
|
||||
New rows will be added under the appropriate theme as they are proposed via the `kernel-program-extension` skill + this table.
|
||||
|
||||
See also the design document for the P2P App Store as an example of how larger features are broken into governed items.
|
||||
|
||||
Reference in New Issue
Block a user