Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

docs: make live catalog publishing setup reviewable

dee09b56877d44f
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 8f9a1ef02..fae83ddb8 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -121,7 +121,8 @@ You do not need permission to build a harness or share its repository. Choose th
author or upstream project. The catalog publisher generates the listing from those files.
The [publishing examples](store/README.md#publish-a-harness) show the exact metadata for both routes.
-A merge to `main` publishes the live catalog automatically. Running clients pick it up within
+The live catalog is published independently of client releases; see the
+[publication setup](store/README.md#live-catalog). Running clients pick up a published catalog within
minutes; no app or CLI release is needed for a new harness or viewer that uses the existing
package format. The catalog describes packages; installation still happens when someone chooses
Get. Installed packages are not silently replaced.
@@ -168,7 +169,7 @@ Security reports go through [SECURITY.md](SECURITY.md).
currently run manually through **Actions → CI → Run workflow**; a PR does not automatically
exercise the app, real engines, or hardware. Report those checks separately.
5. **Merge and release.** PRs are squash-merged. Rebase on the latest `main` when needed to keep
- the diff readable. Harness catalog changes publish automatically after merge. App, CLI, and
+ the diff readable. Harness catalog changes use the independent catalog publisher. App, CLI, and
firmware releases have their own schedules.
## Conventions across this repository
diff --git a/store/README.md b/store/README.md
index 1c3170f8f..8e4ec574d 100644
--- a/store/README.md
+++ b/store/README.md
@@ -148,17 +148,26 @@ Built-in entries derive this field from the manifest automatically.
A package that is one folder of a bigger repository names it with `"path"`; install then fetches
that folder alone. Run the conformance check and include a real example in the PR; the full test
-suite is currently triggered manually. Once merged, the catalog publisher lists it automatically.
+suite is currently triggered manually. Once merged, the next catalog publication lists it.
The app offers the tile before the package is installed. `verified: true` marks built-in packages;
community packages show their source on install.
### Live catalog
-Package changes merged into `main` trigger
-[`Publish Store catalog`](../.github/workflows/publish-store-catalog.yml). It validates the complete
-catalog, checks viewer dependencies, pins built-in packages to the source commit, and writes one
-`catalog.json` to the `store-catalog` branch. It uses GitHub only; it does not build or release the
-app, run package setup scripts, or access cloud infrastructure. Authors do not edit a generated index.
+The live catalog is published independently of app and CLI releases. The publisher validates
+the complete catalog, checks viewer dependencies, pins built-in packages to the source commit,
+and writes one `catalog.json` to the `store-catalog` branch. It uses GitHub only; it does not build
+or release the app, run package setup scripts, or access cloud infrastructure. Authors do not
+edit a generated index.
+
+**Automation setup is pending.** The ready-to-install
+[workflow](tools/publish-store-catalog.workflow.yml) belongs at
+`.github/workflows/publish-store-catalog.yml`. A maintainer with permission to write workflow
+files can copy it there to publish automatically after package changes merge to `main`.
+It uses pinned official actions, limits write permission to the publishing job, and never runs
+on pull requests or forks. Until installed, a maintainer can publish from a clean, current
+`main` checkout with `node store/tools/catalog.mjs --publish`, supplying `GITHUB_TOKEN` with
+repository contents-write access.
The CLI reads that public JSON over HTTPS, using conditional requests and a five-minute cache.
Concurrent requests share one fetch. An open Store asks connected machines again every minute;
diff --git a/store/tools/publish-store-catalog.workflow.yml b/store/tools/publish-store-catalog.workflow.yml
new file mode 100644
index 000000000..689617a71
--- /dev/null
+++ b/store/tools/publish-store-catalog.workflow.yml
@@ -0,0 +1,46 @@
+name: Publish Store catalog
+
+on:
+ push:
+ branches: [main]
+ paths:
+ - 'store/agents/**'
+ - 'store/viewers/**'
+ - 'store/registry/**'
+ - 'store/tools/catalog.mjs'
+ - 'cli/scripts/lib/dshRegistry.mjs'
+ - '.github/workflows/publish-store-catalog.yml'
+ workflow_dispatch:
+
+permissions:
+ contents: read
+
+concurrency:
+ group: publish-store-catalog
+ cancel-in-progress: false
+
+jobs:
+ publish:
+ # Runs only trusted, merged source. Never executes a pull request or a fork.
+ if: github.repository == 'autonomous-ai/openharness' && github.ref == 'refs/heads/main'
+ runs-on: ubuntu-latest
+ timeout-minutes: 5
+ permissions:
+ contents: write
+ steps:
+ # Immutable official action commits, verified against the v7 tags.
+ # The checkout does not retain credentials in Git configuration.
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+ with:
+ ref: main
+ persist-credentials: false
+ - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
+ with:
+ node-version: '22.23.2'
+ # No dependency install, package setup, release tags, or cloud access.
+ # The script writes only catalog.json on the store-catalog branch using
+ # a fast-forward ref update. It never modifies main or installed packages.
+ - name: Validate and publish catalog metadata
+ env:
+ GITHUB_TOKEN: ${{ github.token }}
+ run: node store/tools/catalog.mjs --publish