| 1 | # First-party plugin marketplace |
| 2 | |
| 3 | Codewhale includes an offline snapshot of the `codewhale` catalog in the same |
| 4 | marketplace store consumed by the terminal, Extensions, recommendations, and |
| 5 | Runtime API. It lists Computer Use, WhaleWiki, Whalesong, Cloudflare Docs, and the |
| 6 | Codewhale skill bundle. Browsing does not fetch or execute anything. |
| 7 | |
| 8 | ```text |
| 9 | /plugin marketplace list |
| 10 | /plugin marketplace show codewhale |
| 11 | /plugin marketplace install codewhale whalewiki |
| 12 | /plugin show whalewiki |
| 13 | /plugin trust whalewiki |
| 14 | /plugin enable whalewiki |
| 15 | /plugin update whalewiki |
| 16 | ``` |
| 17 | |
| 18 | Review the manifest and capabilities before trust and enablement. Installation |
| 19 | uses the existing size-limited, traversal-safe installer and starts disabled |
| 20 | and untrusted. An update with changed bytes requires review again. Official |
| 21 | catalog provenance grants no execution or network permission. Removing the |
| 22 | catalog persists the choice and leaves installed plugins untouched; a locally |
| 23 | added catalog named `codewhale` takes precedence over the bundled snapshot. |
| 24 | |
| 25 | The bundle source uses a gzip tarball URL with `#path=plugins/whalewiki` (or |
| 26 | `#path=skills`). The fragment selects exactly one bundle inside the shared |
| 27 | repository archive. Only that subtree is installed. Empty paths, traversal, |
| 28 | ambiguous roots, links, oversized archives, and changed plugin identities are |
| 29 | rejected. The install receipt preserves the source, including its selector, |
| 30 | so `/plugin update` retains the same bundle selector and reviewed revision. |
| 31 | |
| 32 | ## Keeping the repositories current |
| 33 | |
| 34 | | Content | Authoritative source | Copies to check | |
| 35 | | --- | --- | --- | |
| 36 | | Catalog, WhaleWiki, Whalesong, Cloudflare Docs | `Hmbown/codewhale-plugin-marketplace` | Core catalog snapshot | |
| 37 | | Bundled skills | Core active catalog and `crates/tui/assets/skills` | Marketplace `skills` and `skills/upstream.json` | |
| 38 | | Computer Use | `Hmbown/codewhale-cu-plugin` | Marketplace plugin and Core bundled runtime | |
| 39 | |
| 40 | The `Marketplace connection` workflow validates the exact catalog revision on |
| 41 | catalog changes. Its weekly and manual runs compare the current public |
| 42 | marketplace, bundled snapshot, skills, and Computer Use runtime. Drift fails |
| 43 | the check with a maintenance instruction; it does not rewrite user installs |
| 44 | or grant new permissions. It uses read-only repository access. |
| 45 | |
| 46 | For each intentional update, review the upstream diff, synchronize the |
| 47 | source-owned copies, and run the marketplace checks: |
| 48 | |
| 49 | ```sh |
| 50 | # From codewhale-plugin-marketplace, with sibling source checkouts: |
| 51 | # After committing canonical skill changes, when intentionally updating skills: |
| 52 | npm run sync:skills |
| 53 | npm run check -- --core ../codewhale |
| 54 | npm run check:cu-sync |
| 55 | npm test && npm run check:web |
| 56 | ``` |
| 57 | |
| 58 | Commit the reviewed marketplace changes, then update Core from that committed |
| 59 | revision (the generator never copies an uncommitted marketplace document): |
| 60 | |
| 61 | ```sh |
| 62 | # From codewhale: |
| 63 | python3 scripts/sync-marketplace.py --marketplace ../codewhale-plugin-marketplace |
| 64 | python3 scripts/sync-marketplace.py --marketplace ../codewhale-plugin-marketplace --check |
| 65 | npm test && npm run check:web |
| 66 | ``` |
| 67 | |
| 68 | Review the generated snapshot and rebuild Core. Its provenance records the |
| 69 | exact marketplace commit, and each generated bundle URL pins that immutable |
| 70 | revision. A later marketplace change requires refreshing the Core snapshot and |
| 71 | rebuilding; an existing pinned install does not silently follow `main`. Push the |
| 72 | reviewed marketplace revision before publishing a Core release that references it. Hosted CI must be green for the |
| 73 | actual published revisions; local checks do not prove a public URL works. |
| 74 | |
| 75 | Skill wording changes also need behavioral evaluation before claiming better |
| 76 | outcomes. See [Skill evaluation](SKILL_EVALUATION.md). |
| 77 |