| 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, the |
| 6 | Codewhale skill bundle, and Codewhale for Chrome (Chromewhale). Browsing does |
| 7 | not fetch or execute anything. |
| 8 | |
| 9 | ```text |
| 10 | /plugin marketplace list |
| 11 | /plugin marketplace show codewhale |
| 12 | /plugin marketplace install codewhale whalewiki |
| 13 | /plugin show whalewiki |
| 14 | /plugin trust whalewiki |
| 15 | /plugin enable whalewiki |
| 16 | /plugin update whalewiki |
| 17 | ``` |
| 18 | |
| 19 | Review the manifest and capabilities before trust and enablement. Installation |
| 20 | uses the existing size-limited, traversal-safe installer and starts disabled |
| 21 | and untrusted. An update with changed bytes requires review again. Official |
| 22 | catalog provenance grants no execution or network permission. Removing the |
| 23 | catalog persists the choice and leaves installed plugins untouched; a locally |
| 24 | added catalog named `codewhale` takes precedence over the bundled snapshot. |
| 25 | |
| 26 | The bundle source uses a gzip tarball URL with `#path=plugins/whalewiki` (or |
| 27 | `#path=skills`). The fragment selects exactly one bundle inside the shared |
| 28 | repository archive. Only that subtree is installed. Empty paths, traversal, |
| 29 | ambiguous roots, links, oversized archives, and changed plugin identities are |
| 30 | rejected. The install receipt preserves the source, including its selector, |
| 31 | so `/plugin update` retains the same bundle selector and reviewed revision. |
| 32 | |
| 33 | ## Built-in Computer Use across upgrades |
| 34 | |
| 35 | Computer Use also ships inside the binary as a built-in bundle. Each build |
| 36 | writes its own copy under `$CODEWHALE_HOME/builtin-plugins`, so an upgrade |
| 37 | presents it as a new bundle. Your review carries over when the capability |
| 38 | hash is unchanged: a bundle you trusted and enabled stays trusted and enabled |
| 39 | on the new build. When the capabilities changed, it shows |
| 40 | `capabilities-changed` and stays off until you review it again with |
| 41 | `/plugin show computer-use` and `/plugin trust computer-use`. If you revoked |
| 42 | trust after your most recent review, nothing carries and the new build waits |
| 43 | for a fresh review; once you review a build again, later upgrades carry that |
| 44 | review. User and workspace plugins never carry trust: changed bytes |
| 45 | always need review. |
| 46 | |
| 47 | ## Chromewhale |
| 48 | |
| 49 | Chromewhale (listed as "Codewhale for Chrome") is in the catalog bundled with |
| 50 | Core from marketplace revision `ae3dd22` on, where its checks pass on macOS, |
| 51 | Linux and Windows. It is a developer preview: installing the plugin does not |
| 52 | install the browser side, so you load its bundled Chrome extension unpacked |
| 53 | yourself. It then reads and acts on the tab you are looking at, one granted |
| 54 | site at a time. Like every catalog entry, it installs disabled and untrusted |
| 55 | until you review it. |
| 56 | |
| 57 | ## Keeping the repositories current |
| 58 | |
| 59 | | Content | Authoritative source | Copies to check | |
| 60 | | --- | --- | --- | |
| 61 | | Catalog, WhaleWiki, Whalesong, Cloudflare Docs | `codewhale-hq/codewhale-plugin-marketplace` | Core catalog snapshot | |
| 62 | | Bundled skills | Core active catalog and `crates/tui/assets/skills` | Marketplace `skills` and `skills/upstream.json` | |
| 63 | | Computer Use | `Hmbown/codewhale-cu-plugin` | Marketplace plugin and Core bundled runtime | |
| 64 | |
| 65 | The `Marketplace connection` workflow validates the exact catalog revision on |
| 66 | catalog changes. Its weekly and manual runs compare the current public |
| 67 | marketplace, bundled snapshot, skills, and Computer Use runtime. Drift fails |
| 68 | the check with a maintenance instruction; it does not rewrite user installs |
| 69 | or grant new permissions. It uses read-only repository access. |
| 70 | |
| 71 | For each intentional update, review the upstream diff, synchronize the |
| 72 | source-owned copies, and run the marketplace checks: |
| 73 | |
| 74 | ```sh |
| 75 | # From codewhale-plugin-marketplace, with sibling source checkouts: |
| 76 | # After committing canonical skill changes, when intentionally updating skills: |
| 77 | npm run sync:skills |
| 78 | npm run check -- --core ../codewhale |
| 79 | npm run check:cu-sync |
| 80 | npm test && npm run check:web |
| 81 | ``` |
| 82 | |
| 83 | Commit the reviewed marketplace changes, then update Core from that committed |
| 84 | revision (the generator never copies an uncommitted marketplace document): |
| 85 | |
| 86 | ```sh |
| 87 | # From codewhale: |
| 88 | python3 scripts/sync-marketplace.py --marketplace ../codewhale-plugin-marketplace |
| 89 | python3 scripts/sync-marketplace.py --marketplace ../codewhale-plugin-marketplace --check |
| 90 | npm test && npm run check:web |
| 91 | ``` |
| 92 | |
| 93 | Review the generated snapshot and rebuild Core. Its provenance records the |
| 94 | exact marketplace commit, and each generated bundle URL pins that immutable |
| 95 | revision. A later marketplace change requires refreshing the Core snapshot and |
| 96 | rebuilding; an existing pinned install does not silently follow `main`. Push the |
| 97 | reviewed marketplace revision before publishing a Core release that references it. Hosted CI must be green for the |
| 98 | actual published revisions; local checks do not prove a public URL works. |
| 99 | |
| 100 | Core's Computer Use copy (`crates/tui/plugins/computer-use`) is a runtime and |
| 101 | tests subset of the upstream repository. Copy the upstream files Core already |
| 102 | carries, plus any new runtime module the server imports and its tests, from the |
| 103 | reviewed upstream commit. Keep the three deliberate Core variants |
| 104 | (`package.json`, `README.md`, `tests/manifest.test.mjs`) and bump their version |
| 105 | to match. Record the commit in `crates/tui/plugins/computer-use.upstream-sha`. |
| 106 | Add each new runtime file to `COMPUTER_USE_FILES` in |
| 107 | `crates/tui/src/plugins/builtin.rs`. The |
| 108 | `computer_use_embed_list_matches_the_vendored_runtime_tree` test fails when |
| 109 | the two disagree. Then run `npm test` in the vendored directory. |
| 110 | |
| 111 | Skill wording changes also need behavioral evaluation before claiming better |
| 112 | outcomes. See [Skill evaluation](SKILL_EVALUATION.md). |
| 113 |