Pear Apps work

2026-05-26 23:45:54 +00:00
parent ab3f091671
commit 21580f21bc
28 changed files with 4740 additions and 764 deletions
@@ -60,20 +60,19 @@ run_command "appstore info simple-file-share"
 run_command "appstore install my-p2p-app --yes"
 ```

-**Install from explicit P2P link:**
+**Install from explicit P2P link (copies release tree from HDMS / swarm):**
 ```
-run_command "appstore install keet pear://<key>/stable --yes"
+run_command "appstore install my-p2p-app pear://0.<length>.<key> --yes"
 ```

-**Uninstall:**
-```
-run_command "appstore uninstall my-p2p-app"
-```
-
-**Launch an installed package:**
+**Launch (runs sources/index.js in the guest shell — prints app output):**
 ```
 run_command "appstore launch my-p2p-app"
-run_command "appstore launch my-p2p-app --checkout staged"
+```
+
+**Refresh after a new pear release:**
+```
+run_command "appstore update my-p2p-app"
 ```

 **When user asks to install something:**
@@ -1,72 +1,74 @@
-# pear-dev Skill
+---
+name: pear-dev
+version: 0.2.0
+description: Create, stage, build, release, and seed Pear applications entirely from inside a booted Bare OS using ctx.pear and /bin/pear.
+tags: [pear, p2p, build, bundle, stage, release, seed, ctx.pear, development]
+---

-**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]
+# pear-dev Skill

 ## 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
+Use this skill whenever the user (or another agent) wants Pear development work inside Bare OS:
+- Scaffold a new Pear app (`pear init`)
+- Stage / bundle an app for deployment (`pear stage`)
+- Publish to a real `pear://` link from the guest shell (`pear release`)
+- Keep the release replicating (`pear seed`)
+- Inspect what Pear tooling is available via `ctx.pear`
+- Integrate Pear app creation with the P2P App Store

-## Core Capabilities Available Right Now
+## Core Capabilities

- `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)
+- `ctx.pear` — Pear development surface (when `BARE_OS_BARE_MODULES` is enabled):
+  - `ctx.pear.pearBuild`, `ctx.pear.pearBundle`, `ctx.pear.pearRef`
+  - `ctx.pear.bareBundleCompile`, `ctx.pear.bareBundleEvaluate`
+- `/bin/pear` command:
+  - `pear help` | `pear info` | `pear list`
+  - `pear init [dir]` — scaffold project skeleton
+  - `pear stage [dir]` — write `<project>/.pear/stage/` (sources + bundle)
+  - `pear release [dir]` — publish stage to HDMS Hyperdrive, print `pear://` links
+  - `pear seed [dir]` — swarm flush / replication for the release drive
+  - `pear build` / `pear bundle` — aliases for `pear stage`

-Full `init` / `stage` / `release` / `seed` end-to-end will be completed across the remaining plan items.
+## End-to-End Workflow (Guest Shell Only)

-## Recommended Workflows (Current State)
+The full pipeline runs inside the Bare OS shell. No host-side `pear stage` / `pear release` is required.

-### 1. Discover what Pear tooling is available
 ```bash
-pear list
-pear info
+pear init
+cd ~/pear-projects/my-pear-app
+pear stage
+login                    # unlock identity vault if not already logged in
+pear release
+pear seed
 ```

-### 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.
+**Requirements for release/seed:**
+- Identity unlocked (`login`) so HDMS is active
+- Prior successful `pear stage` (`.pear/stage/stage.json` must exist)

-### 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.
+Release creates (or reuses) a writable HDMS mount `pear-<app-name>` at `/mnt/pear-<app-name>/`, mirrors the staged tree there, and writes `.pear/release.json` with `pearLink` and `versionedLink`.

-## Safety & Limitations (Be Honest)
+## Recommended Agent Loop

- 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.
+1. `run_command "pear list"` — confirm ctx.pear tools loaded
+2. `run_command "pear init"` or scaffold in project dir
+3. `run_command "pear stage ."`
+4. Ensure user is logged in (HDMS active); if guest, prompt `login`
+5. `run_command "pear release ."`
+6. `run_command "pear seed ."` for replication
+7. Optional: `appstore install <name> <pear://link> --yes`

-## Future Vision (What We Are Building Toward)
+## Safety & Limits

- 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.
+- Release drives live on the user's personal HDMS namespace (same trust model as `hdms create`).
+- Re-release overwrites files on the release mount by path; stale paths are not purged automatically.
+- `pear seed` is best-effort swarm flush — not a guarantee of wide replication.
+- Do not claim host Pear sidecar is needed for release; the guest `/bin/pear` path is authoritative.

 ## 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).
+- Plan: `docs/design/ctx-pear-surface-and-bare-audit-plan.md`
+- Staging: `packages/bare-os-coreutils/lib/pear-stage.js`
+- Release: `packages/bare-os-coreutils/lib/pear-release.js`
+- Command: `packages/bare-os-coreutils/src/pear.js`
@@ -1,6 +1,6 @@
 {
  "schemaVersion": 1,
-  "generatedAt": "2026-05-26T23:16:52.758Z",
+  "generatedAt": "2026-05-26T23:42:58.565Z",
  "pages": [
    {
      "name": "agent",