Catalog format 2, validation CI and contributor docs

.github/workflows/validate-catalog.yml

@@ -0,0 +1,63 @@
+name: Validate catalog
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+env:
+  # Orca commit whose validator and legacy export the catalog is checked with. Bump it deliberately.
+  ORCA_REF: 7f05eec8e9af8da6736110b478ea4c41ed4ae69e
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - name: Check out catalog
+        uses: actions/checkout@v4
+        with:
+          path: catalog
+          # Why full history: releases pin the last commit that changed each plugin directory.
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Check out Orca
+        uses: actions/checkout@v4
+        with:
+          repository: stablyai/orca
+          ref: ${{ env.ORCA_REF }}
+          path: orca
+          persist-credentials: false
+
+      - uses: pnpm/action-setup@v4
+        with:
+          package_json_file: orca/package.json
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          cache: pnpm
+          cache-dependency-path: orca/pnpm-lock.yaml
+
+      # Why no install scripts: the validator needs only the JavaScript dependencies, not Electron.
+      - name: Install Orca validator
+        working-directory: orca
+        run: |
+          pnpm install --frozen-lockfile --ignore-scripts
+          pnpm run build:packages
+
+      - name: Check plugins/ release entries are current
+        working-directory: catalog
+        env:
+          ORCA_DIR: ${{ github.workspace }}/orca
+        run: node scripts/release-entry.mjs
+
+      - name: Validate catalog, releases, images and orca-marketplace.json
+        working-directory: catalog
+        env:
+          ORCA_DIR: ${{ github.workspace }}/orca
+        run: node scripts/check-catalog.mjs

CONTRIBUTING.md

@@ -0,0 +1,92 @@
+# Adding or updating a plugin
+
+This repository holds Orca's official plugin catalog and the official plugins themselves.
+`orca-catalog.json` pins every release to an exact commit and a hash of the plugin's files. Orca
+refuses to install bytes that differ from what is listed.
+
+- **Official plugins** (published by `stablyai`) live in `plugins/<name>/`, one directory each.
+  Orca installs only that directory, so changing one plugin never changes another's hash.
+- **Community plugins** stay in their authors' own repositories. List them in the community
+  directory; don't copy their code here.
+
+The field reference is in Orca's
+[catalog reference](https://github.com/stablyai/orca/blob/main/docs/reference/plugin-catalog.md)
+and the
+[plugin author guide](https://github.com/stablyai/orca/blob/main/docs/reference/plugin-authoring.md).
+
+You need a checkout of [Orca](https://github.com/stablyai/orca) with dependencies installed
+(`pnpm install`, then `pnpm run build:packages`). Below, `ORCA_DIR` is its path. CI uses the Orca
+commit in `ORCA_REF` of `.github/workflows/validate-catalog.yml`.
+
+## 1. Change the plugin and commit it
+
+Use manifest format 2 (`"manifestVersion": 2`) and choose the lowest `execution` profile that
+fits: `data` for themes, syntaxes and translations; `declarative` for commands, shortcuts and
+recipes; `sandboxed-ui` for panels; `trusted-worker` only when you need code running in Orca.
+Keep a `LICENSE` file in the plugin directory and set `license` in the manifest to match.
+
+Bump `version` in `orca-plugin.json` for any change to a plugin that has already been merged:
+a released version is never rebuilt with different bytes.
+
+- **New official plugin:** create `plugins/<name>/` and add an entry to `orca-catalog.json` with
+  `id` (`<publisher>.<id>` from the manifest), `source`
+  (`{"kind": "git", "url": "https://github.com/stablyai/orca-plugins.git", "ref": "main", "path": "plugins/<name>"}`),
+  a `description`, `categories` and `"releases": []`.
+
+Commit the plugin change on its own. The release pins the last commit that changed the plugin's
+directory, and a commit cannot name itself.
+
+## 2. Write the release entry
+
+```sh
+ORCA_DIR=/path/to/orca node scripts/release-entry.mjs --write
+```
+
+For every directory in `plugins/`, this runs Orca's validator and writes the release it prints
+(version, commit, `contentHash`, execution profile, minimum Orca, contributions, capabilities,
+file types) into `orca-catalog.json`. A new version goes **first** in `releases`; an unchanged
+version is updated in place. Don't edit these fields by hand: CI recomputes them and fails when
+they are stale. Commit `orca-catalog.json`.
+
+When a release raises `engines.orca`, keep the previous release listed beneath it. Older Orca
+installs the first release it supports, so removing the old one leaves those users with nothing
+to install.
+
+You may add display-only fields to a release: `changelog`, `updatedAt`, `license`, `homepage`,
+`themePreview`, `images`. The script keeps them.
+
+## 3. Add a cover image (recommended)
+
+Put images under `assets/<plugin id>/` and reference them from the release's `images`, with
+`path`, `alt` text, `sha256`, `width` and `height`. Limits:
+
+| Image | Formats | Size |
+| --- | --- | --- |
+| icon | PNG, WEBP, square | at least 128×128, at most 256 KB |
+| cover | PNG, JPEG, WEBP | at least 800×500 (1600×1000 recommended), at most 1024 KB |
+| screenshots (up to 6) | PNG, JPEG, WEBP | at least 1280×800, at most 1536 KB |
+
+Images must be static, show the real plugin, and not imitate Orca's trust badges. CI fails on any
+file under `assets/` that no release references.
+
+## 4. Check locally
+
+Orca builds released before catalog format 2 read only `orca-marketplace.json`. Don't edit it.
+Plugins in `plugins/` are left out of it, because those builds cannot install a subdirectory;
+older builds keep the original listings. Run the same checks CI runs:
+
+```sh
+ORCA_DIR=/path/to/orca node scripts/release-entry.mjs
+ORCA_DIR=/path/to/orca node scripts/check-catalog.mjs
+```
+
+If `check-catalog.mjs` says `orca-marketplace.json` is out of date, regenerate it with
+`--write-legacy` rather than editing it.
+
+## 5. Open a pull request
+
+CI checks that every release in `plugins/` is current, validates the catalog with Orca's own
+validator and fetches every listed commit to recompute its `contentHash`. It also checks images
+and that `orca-marketplace.json` matches the export. An
+Orca maintainer then reviews the plugin against [REVIEW_POLICY.md](REVIEW_POLICY.md). Say in
+the PR what the plugin does and, for anything above `data`, why it needs that profile.

README.md

@@ -0,0 +1,39 @@
+# Orca plugins
+
+The official plugin catalog for [Orca](https://github.com/stablyai/orca), and the source of the
+official plugins. Orca reads the catalog to show the plugins you can install from Settings →
+Plugins.
+
+| Path | What it is |
+| --- | --- |
+| `plugins/<name>/` | Official plugins, one directory each, with its own manifest and licence. |
+| `orca-catalog.json` | Read by Orca builds that support catalog format 2. Each release is pinned to an exact commit and file hash. |
+| `orca-marketplace.json` | Read by older Orca builds. Frozen: it keeps the original listings, which install from each plugin's old repository, including plugins later dropped from `orca-catalog.json` (such as Orca Navigation Shortcuts). |
+| `legacy-v1-only.json` | The ids in `orca-marketplace.json` that the export does not produce. |
+| `assets/` | Listing images referenced by releases. |
+| `scripts/release-entry.mjs` | Prints and checks the catalog release of every plugin in `plugins/`. |
+| `scripts/check-catalog.mjs` | Validates the catalog, every release, images and `orca-marketplace.json`. |
+
+## Official plugins
+
+| Plugin | Directory | What it adds |
+| --- | --- | --- |
+| Orca Midnight | `plugins/midnight-theme` | A dark app theme |
+| Nord for Orca | `plugins/nord-theme` | A cool, low-contrast app theme |
+| Orca OLED | `plugins/oled-theme` | A true-black app theme and terminal theme |
+| Dusk & Ember Themes | `plugins/dusk-ember` | A dark and a light app theme, with matching terminal themes |
+| Orca Minimal Icons | `plugins/minimal-icons` | A monochrome file icon theme |
+| Solarized Terminal | `plugins/solarized-terminal` | Solarized Dark terminal colors |
+| Gleam Language | `plugins/gleam` | Highlighting for `.gleam` files |
+| Prisma Syntax | `plugins/prisma` | Prisma-aware highlighting for `.prisma` files |
+| Excalidraw | `plugins/excalidraw` | An editor for `.excalidraw` diagrams |
+| Multipass VM Recipes | `plugins/multipass-recipes` | Disposable Multipass VM workspaces |
+
+Community plugins live in their authors' own repositories. The catalog can list them, but their
+code is not copied here.
+
+- To add or update a plugin, see [CONTRIBUTING.md](CONTRIBUTING.md).
+- To learn how plugins are reviewed and taken down, see [REVIEW_POLICY.md](REVIEW_POLICY.md).
+
+Every pull request is checked by `.github/workflows/validate-catalog.yml`, which runs Orca's own
+validator at a pinned Orca commit.

REVIEW_POLICY.md

@@ -0,0 +1,56 @@
+# Review policy
+
+## Who merges
+
+At launch, only Orca maintainers merge into this repository. Every new plugin and every new
+release needs a maintainer's review and a green CI run. No release is merged on CI alone.
+
+This repository holds only official plugins, in `plugins/<name>/`, published under `stablyai`.
+Community plugins stay in their authors' own repositories and are listed in the community
+directory, not copied here.
+
+## Checklist
+
+CI proves that each release in `plugins/` is current, that every release is the exact bytes at
+its pinned commit, and that the listing matches the manifest. A reviewer checks what CI cannot:
+
+- [ ] **Lowest execution profile that fits.** `data` for themes, syntaxes and translations;
+      `declarative` for commands, shortcuts and recipes; `sandboxed-ui` only for panels;
+      `trusted-worker` only when the plugin needs code running in Orca. Ask for a lower profile
+      when the contributions allow it.
+- [ ] **Capabilities are justified.** Each requested capability is explained and used.
+- [ ] **No impersonation.** The name, publisher, description and images don't pose as Orca, as
+      an "official" or "verified" plugin, or as another project or company the author doesn't
+      represent. Only Orca maintainers publish under `stablyai` or use the `official` category.
+- [ ] **Licence present.** The plugin directory has its own `LICENSE` file, and the manifest's
+      `license` matches it.
+- [ ] **Version bumped.** A change to a plugin that is already merged raises its `version`, so a
+      released version never gets different bytes. `release-entry.mjs --write` updates a release
+      in place when the version is unchanged, which is only right before first merge.
+- [ ] **Honest images.** Icons, covers and screenshots show the real plugin, with accurate alt
+      text. No fake trust badges, ratings, download counts or Orca interface chrome that suggests
+      endorsement.
+- [ ] **No bundled binaries.** The release has no compiled executables, native modules, or
+      obfuscated or minified code that can't be reviewed. Generated JavaScript is acceptable only
+      when its source is in the same repository.
+- [ ] **Extra scrutiny for `trusted-worker`.** These plugins run code with full access to the
+      machine. Read the worker source, check what it sends over the network and what it runs,
+      and confirm that the publisher is who they say they are. Re-review on every release, not
+      just the first.
+- [ ] **Updates.** A new release that raises its profile or asks for new capabilities is
+      reviewed like a new plugin. Orca asks users to approve it again, but the catalog should not
+      offer it unreviewed.
+
+## Takedown
+
+When a listed plugin turns out to be malicious, deceptive or broken:
+
+1. Open a PR that removes its entry, or the bad releases, from `orca-catalog.json`, and
+   regenerate `orca-marketplace.json`. This stops new installs.
+2. Orca maintainers add the plugin's `<publisher>.<id>` to Orca's plugin kill list, served from
+   `https://onorca.dev/plugins/kill-list.json`, with a short reason and optionally an advisory
+   URL. Orca reads that list and disables copies that are already installed, which removing the
+   catalog entry alone does not do.
+
+Report a suspected malicious plugin privately to the Orca maintainers rather than in a public
+issue.

legacy-v1-only.json

@@ -0,0 +1,12 @@
+{
+  "note": "Listings kept in orca-marketplace.json for Orca builds that predate catalog format 2. They install each plugin from its original repository at v1.0.0. The export leaves out plugins in plugins/ (a source.path), so these stay as they are; never add new ones.",
+  "ids": [
+    "stablyai.orca-midnight-theme",
+    "stablyai.orca-workflow-skills",
+    "stablyai.orca-nord-theme",
+    "stablyai.orca-minimal-icons",
+    "stablyai.orca-solarized-terminal",
+    "stablyai.orca-multipass-recipes",
+    "stablyai.orca-navigation-shortcuts"
+  ]
+}