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
@@ -0,0 +1,72 @@
|
||||
# pear-dev Skill
|
||||
|
||||
**name:** pear-dev
|
||||
**description:** Create, stage, build, and release real Pear applications entirely from inside a booted Bare OS using the new `ctx.pear` surface and `/bin/pear` command.
|
||||
**tags:** [pear, p2p, build, bundle, stage, release, ctx.pear, development]
|
||||
|
||||
## When to Use This Skill
|
||||
|
||||
Use this skill whenever the user (or another agent) wants to do Pear development work inside Bare OS:
|
||||
- Scaffold a new Pear app (`pear init` equivalent)
|
||||
- Stage / bundle an app for deployment
|
||||
- Inspect what Pear tooling is currently available via `ctx.pear`
|
||||
- Integrate Pear app creation with the P2P App Store (materialize + launch workflows)
|
||||
- Autonomous "create → stage → test → release to my HDMS store" loops
|
||||
|
||||
## Core Capabilities Available Right Now
|
||||
|
||||
- `ctx.pear` — the new Pear development surface (exposed when `BARE_OS_BARE_MODULES` is enabled).
|
||||
- `ctx.pear.pearBuild` → from `pear-build` package
|
||||
- `ctx.pear.pearBundle` → from `pear-bundle` package
|
||||
- `ctx.pear.pearRef`, `ctx.pear.bareBundleCompile`, `ctx.pear.bareBundleEvaluate`
|
||||
- `/bin/pear` command (real binary after coreutils build):
|
||||
- `pear help`
|
||||
- `pear info`
|
||||
- `pear list` ← shows exactly what is live on `ctx.pear`
|
||||
- `pear stage` / `pear build` (currently informative stub pointing at ctx.pear)
|
||||
|
||||
Full `init` / `stage` / `release` / `seed` end-to-end will be completed across the remaining plan items.
|
||||
|
||||
## Recommended Workflows (Current State)
|
||||
|
||||
### 1. Discover what Pear tooling is available
|
||||
```bash
|
||||
pear list
|
||||
pear info
|
||||
```
|
||||
|
||||
### 2. Basic autonomous development loop (v1)
|
||||
The agent should:
|
||||
1. Use `run_command "pear list"` to see current surface.
|
||||
2. Explain to the user what is and isn't fully wired yet.
|
||||
3. For real work, guide the user to use the exposed `ctx.pear.pearBuild` / `ctx.pear.pearBundle` directly from JS (via `run_js_script`) until the higher-level `pear stage` command is complete.
|
||||
4. Once staging is real, the loop becomes: create project → `pear stage` → verify output → optionally push to HDMS App Store.
|
||||
|
||||
### 3. Integration with P2P App Store
|
||||
After a Pear app is staged/bundled, the natural next step is usually:
|
||||
- `appstore install ./my-staged-pear-app` (or via pear:// link once materialization is wired)
|
||||
- Then launch via the App Store or directly with Pear primitives.
|
||||
|
||||
## Safety & Limitations (Be Honest)
|
||||
|
||||
- This is early in the implementation of the full ctx.pear plan.
|
||||
- Many high-value operations (full release to a swarm, seeding, talking to a live Pear sidecar for `pear release`) still require a host Pear sidecar (delegation pattern, same as peerctl).
|
||||
- Do **not** claim that `pear stage` or `pear init` are fully functional until the corresponding plan items are marked complete and verifiers pass.
|
||||
- Never suggest running untrusted Pear apps outside the existing sandbox/worker model.
|
||||
|
||||
## Future Vision (What We Are Building Toward)
|
||||
|
||||
- Complete `pear init`, `pear stage`, `pear bundle`, `pear release`, `pear seed` subcommands.
|
||||
- Dedicated `pear-dev` HDMS drive convention (similar to `appstore` label).
|
||||
- Rich autonomous agent workflows that can create production-grade Pear apps, stage them, test them, and publish them to the user's personal P2P App Store without the user typing a single command.
|
||||
- Deep integration so "I want a new P2P notes app" → agent uses this skill + appstore skill end-to-end.
|
||||
|
||||
## Files & References
|
||||
|
||||
- Implementation plan: `docs/design/ctx-pear-surface-and-bare-audit-plan.md`
|
||||
- Audit notes: `docs/audit/ctx-bare-audit-notes.md`
|
||||
- Command source: `packages/bare-os-coreutils/src/pear.js`
|
||||
- Manifest tier: `packages/bare-os-booter/lib/bare-module-manifest.json` (pearEntries section)
|
||||
- ctx surface: `packages/bare-os-booter/lib/bare-os-ctx-bare.js` (buildPearCtxObjectFromHost)
|
||||
|
||||
Keep this skill updated as the Pear surface matures. The goal is production-grade autonomous Pear development inside Bare OS (matching the standard set by the appstore skill after its 50-round polish).
|
||||
Reference in New Issue
Block a user