fix: unblock the release and make the registry publish retryable (#26)

Co-authored-by: Claude <noreply@anthropic.com>

Author: wittjosiah

.github/workflows/release.yml

@@ -7,6 +7,10 @@ name: Release
 #  - with none left, publishes the bumped plugins to npm (which also tags each version) and then to
 #    the AT Protocol registry via `dx registry publish`.
 #
+# Dispatching with `registry_only` skips npm and republishes the current versions to the registry, so
+# a registry failure can be retried without a version bump — npm is append-only, so a plain re-run
+# would find its half already done and never reach the registry.
+#
 # Plugins carry independent version lines (`fixed: []`), but share one Version Packages PR, so a
 # release ships whatever accumulated since the last one — independent numbers, coupled timing.
 #
@@ -20,6 +24,11 @@ on:
   push:
     branches: [main]
   workflow_dispatch:
+    inputs:
+      registry_only:
+        description: 'Republish current versions to the registry only, skipping npm. Retries a failed registry publish.'
+        type: boolean
+        default: false
 
 permissions:
   contents: write
@@ -72,6 +81,7 @@ jobs:
       # `changeset publish` pushes to npm and tags each released version; `publishedPackages` then
       # reports exactly what this run released, which drives the registry publish below.
       - id: changesets
+        if: ${{ !inputs.registry_only }}
         uses: changesets/action@v1
         with:
           # dxos-bot's PAT, not GITHUB_TOKEN: GitHub's recursion guard parks every `pull_request` run
@@ -86,9 +96,13 @@ jobs:
 
       # npm is the library channel; the registry is what Composer installs from. Both ship the same
       # version, from different build outputs — dist/ for npm, out/ for the registry.
+      # Runs on a `registry_only` dispatch even though nothing was published in that run: npm is
+      # append-only, so once a version is up the release cannot be replayed to reach the registry
+      # half, and this is the half that talks to two external services.
       - name: Publish released plugins to the registry
-        if: steps.changesets.outputs.published == 'true'
+        if: ${{ inputs.registry_only || steps.changesets.outputs.published == 'true' }}
         env:
+          ALL: ${{ inputs.registry_only }}
           # Pinned to a pkg.pr.new preview: npm's @dxos/cli@0.10.0 is broken (its binary embeds an
           # absolute path to the machine that built it). Override with the DX_CLI_PACKAGE repo
           # variable, and drop the default once a working CLI is on npm. Installing the single
@@ -102,16 +116,19 @@ jobs:
           # Fail fast on a broken CLI rather than part-way through publishing.
           dx --version
 
-          # Publish only what this run released; the registry rejects a re-publish of an unchanged
-          # version, but relying on that would hide a genuine mistake.
-          node -e '
-            const fs = require("fs");
-            const released = new Set(JSON.parse(process.env.PUBLISHED).map((p) => p.name));
-            const dirs = fs.readdirSync("packages")
-              .filter((dir) => fs.existsSync(`packages/${dir}/package.json`))
-              .filter((dir) => released.has(JSON.parse(fs.readFileSync(`packages/${dir}/package.json`, "utf8")).name));
-            fs.writeFileSync("released-dirs.txt", dirs.map((dir) => `packages/${dir}`).join("\n"));
-          '
+          # pnpm resolves the workspace glob and reports `private`, so the publishable set never has
+          # to be re-derived here. A `registry_only` retry takes all of them, since `publishedPackages`
+          # is empty in a run that published nothing.
+          pnpm list --recursive --depth=-1 --json \
+            | jq -r --argjson all "${ALL:-false}" --argjson published "${PUBLISHED:-[]}" '
+                ($published | map(.name)) as $names
+                | .[]
+                | select(.name and (.private | not))
+                | select($all or (.name as $name | $names | any(. == $name)))
+                | .path
+              ' > released-dirs.txt
+
+          echo "Publishing $(grep -c . released-dirs.txt || true) plugin(s) to the registry."
 
           while read -r dir; do
             [ -n "${dir}" ] || continue

AGENTS.md

@@ -139,6 +139,8 @@ whatever accumulated. See [RELEASING.md](./RELEASING.md) for the full flow and t
   CI. Plugins reach Composer via `dx registry publish`; npm is the secondary channel.
 - A publishable plugin needs the `ts-vite-build` tag (`:build`, the npm library) and the `vite` tag
   (`:bundle`, the registry artifact), and its `exports`/`imports` maps must point at what `:build`
-  emits.
+  emits. It also needs `repository.url` in its `package.json`: npm validates the provenance statement
+  against that field, and rejects the publish without it. `pnpm check-packages-published` enforces
+  both this and the `private` rule above.
 - PR titles use Conventional Commits: `feat(tictactoe): …`, `fix: …`, `refactor: …`, `docs: …`.
 - Before committing, run `git status` and account for every modified/untracked file.

RELEASING.md

@@ -15,7 +15,7 @@ tsconfig.base.json     # shared compiler options (each plugin extends it)
 .prototools            # pinned toolchain (proto/moon/node/pnpm), matching the dxos monorepo
 .moon/                 # workspace.yml, toolchains.yml, tasks.yml (shared build/typecheck/dev/preview)
 .changeset/            # pending changesets
-scripts/               # set-sdk.mjs, changeset-all.mjs
+scripts/               # set-sdk.mjs, changeset-all.mjs, check-packages-published.mjs
 ```
 
 Each plugin's `@dxos/*` deps resolve from `catalog:dxos`, so the whole SDK moves as one unit.
@@ -70,6 +70,20 @@ Releases are recorded as git tags rather than a branch — `changeset publish` c
 that is not yet ready to publish stays `private: true`; `privatePackages.tag` is enabled so those
 are still versioned and tagged.
 
+### Retrying a half-finished release
+
+The two channels can fail independently, and only one of them is replayable by re-running the
+workflow. npm is append-only — `changeset publish` skips versions already on the registry — so once
+npm has accepted a version, a plain re-run finds nothing to publish, reports nothing released, and
+never reaches the registry step. That would leave the registry permanently a version behind with no
+way back short of a version bump.
+
+Dispatch **Release** with `registry_only` to republish the current versions to the registry alone,
+skipping npm entirely. Use it whenever the registry half fails, or after fixing the plugin's
+`dx.config.ts` / bundle. `dx registry publish` rejects an unchanged version, so if a retry reports a
+duplicate the release already landed there — confirm with `dx registry records` and, if a record
+genuinely needs replacing, remove it first with `dx registry unpublish --key <key>`.
+
 ## Keeping up with the SDK
 
 The SDK ships as one unit; bump it via the `dxos` catalog (one place).
@@ -127,12 +141,12 @@ Composer catches up.
 
 ## CI
 
-| Workflow              | Trigger            | Does                                                                              |
-| --------------------- | ------------------ | --------------------------------------------------------------------------------- |
-| `check.yml`           | PR / push / queue  | format, lint, build (npm library), bundle (registry artifact + manifest), test    |
-| `sdk-nightly.yml`     | nightly / dispatch | open/update the SDK upgrade PR from latest pkg.pr.new                             |
-| `sdk-npm-release.yml` | dispatch (version) | pin catalog to npm + release-together changeset → PR                              |
-| `release.yml`         | push to `main`     | Changesets version PR → tag + `dx registry publish` per released plugin (guarded) |
+| Workflow              | Trigger                   | Does                                                                                                                         |
+| --------------------- | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `check.yml`           | PR / push / queue         | format, lint, build (npm library), bundle (registry artifact + manifest), test                                               |
+| `sdk-nightly.yml`     | nightly / dispatch        | open/update the SDK upgrade PR from latest pkg.pr.new                                                                        |
+| `sdk-npm-release.yml` | dispatch (version)        | pin catalog to npm + release-together changeset → PR                                                                         |
+| `release.yml`         | push to `main` / dispatch | Changesets version PR → npm + `dx registry publish` per released plugin (guarded); `registry_only` retries the registry half |
 
 ## Secrets / prerequisites
 
@@ -143,6 +157,12 @@ Composer catches up.
     keep it `private: true` until then, or `changeset publish` fails and takes the rest of the release
     with it (the registry publish is gated on its output). `pnpm check-packages-published` enforces
     this in CI.
+  - **Every publishable plugin needs `repository.url` in its `package.json`**, pointing at this
+    repository. Provenance is on (`NPM_CONFIG_PROVENANCE`), and npm validates the signed statement
+    against that field — a missing one is rejected with `E422 … "repository.url" is ""` _after_ the
+    signature has been written to the transparency log, so the release is already lost by the time it
+    surfaces. `pnpm check-packages-published` fails on this too, comparing against
+    `GITHUB_REPOSITORY`.
 - `ATPROTO_HANDLE` + `ATPROTO_APP_PASSWORD` — a verified publisher identity for the release workflow
   (or wire `dx account login` for the DPoP path).
 - `GH_DXOS_BOT_PAT` — dxos-bot's PAT (`contents: write` + `pull-requests: write`), used by every

packages/tictactoe/package.json

@@ -2,6 +2,11 @@
   "name": "@dxos/plugin-tictactoe",
   "version": "0.10.1",
   "description": "Tic-Tac-Toe plugin for DXOS Composer.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dxos/plugins.git",
+    "directory": "packages/tictactoe"
+  },
   "type": "module",
   "imports": {
     "#capabilities": {

scripts/check-packages-published.mjs

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
 
 //
-// Fails when a publishable plugin has never been published to npm.
+// Fails when a publishable plugin would break `changeset publish` — because npm has never seen it,
+// or because its `repository.url` cannot back a provenance statement.
 //
 // `changeset publish` publishes every non-private package, and npm rejects a first-ever publish that
 // has no trusted publisher configured — which fails the release for every other plugin in the same
@@ -13,24 +14,59 @@
 // publisher are set up together (see AGENTS.md).
 //
 
-import { readFileSync, readdirSync, existsSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { relative } from 'node:path';
 
 const NPM_REGISTRY = 'https://registry.npmjs.org';
 const RETRIES = 2;
 
-const publishable = readdirSync('packages')
-  .map((dir) => `packages/${dir}/package.json`)
-  .filter((file) => existsSync(file))
-  .flatMap((file) => {
-    let pkg;
-    try {
-      pkg = JSON.parse(readFileSync(file, 'utf8'));
-    } catch {
-      return [];
-    }
+// pnpm owns which directories are packages (the `packages` glob in pnpm-workspace.yaml) and reports
+// the `private` flag, so neither has to be re-derived here — and the workspace root, being private,
+// drops out with everything else not meant for npm.
+const workspace = JSON.parse(
+  execFileSync('pnpm', ['list', '--recursive', '--depth=-1', '--json'], { encoding: 'utf8' }),
+);
+
+const publishable = workspace
+  .filter((project) => project.name && !project.private)
+  .map((project) => ({
+    name: project.name,
+    file: `${relative(process.cwd(), project.path)}/package.json`,
+    repository: JSON.parse(readFileSync(`${project.path}/package.json`, 'utf8')).repository,
+  }))
+  .sort((left, right) => left.name.localeCompare(right.name));
+
+// npm verifies a provenance statement against the published `repository.url`, so a package without
+// one is rejected at publish time (E422) after the signature has already been logged — and the
+// release is over by then. `git+…`/`.git` are the conventional spelling; npm compares the bare URL.
+const normalize = (url) =>
+  typeof url === 'string'
+    ? url
+        .replace(/^git\+/, '')
+        .replace(/\.git$/, '')
+        .replace(/\/$/, '')
+    : '';
+
+// Set for every GitHub Actions run; locally there is nothing to compare against, so presence alone
+// is checked.
+const expected = process.env.GITHUB_REPOSITORY ? `https://github.com/${process.env.GITHUB_REPOSITORY}` : undefined;
+
+const misdeclared = publishable.filter(({ repository }) => {
+  const url = normalize(repository?.url);
+  return url === '' || (expected !== undefined && url !== expected);
+});
 
-    return !pkg.name || pkg.private ? [] : [{ file, name: pkg.name }];
-  });
+if (misdeclared.length > 0) {
+  console.error('ERROR: these plugins are publishable but cannot produce a valid provenance statement.');
+  console.error(`Set \`repository.url\` in each package.json to ${expected ?? 'this repository'}`);
+  console.error('(the `git+https://….git` form is fine — npm normalises it). See RELEASING.md.');
+  console.error('');
+  for (const { name, file, repository } of misdeclared) {
+    console.error(`  ${name} (${file}) — repository.url is ${JSON.stringify(repository?.url ?? null)}`);
+  }
+  process.exit(1);
+}
 
 const isPublished = async (name) => {
   const url = `${NPM_REGISTRY}/${encodeURIComponent(name)}`;
@@ -65,7 +101,7 @@ if (unpublished.length > 0) {
   console.error('Set `"private": true` until the first publish, then configure npm trusted publishing');
   console.error('(OIDC) for the package and drop the flag. See AGENTS.md.');
   console.error('');
-  for (const { name, file } of unpublished.sort((a, b) => a.name.localeCompare(b.name))) {
+  for (const { name, file } of unpublished) {
     console.error(`  ${name} (${file})`);
   }
   process.exit(1);