ci(astro): publish via Trusted Publisher OIDC

Workflow at .github/workflows/publish-astro.yml triggered via 'gh workflow run publish-astro.yml -F bump=<kind>'. Handles version bump, type-check, tests, build, tarball smoke (with stray-.ts and import-resolution checks), npm publish via OIDC (no stored tokens — npm exchanges the GitHub OIDC token for a short-lived publish credential at the moment of publish, gated by the Trusted Publisher config on npmjs.com), commit-back to main, tag v<x.y.z>-astro, GitHub release with auto-generated notes.

Updates /publish-astro skill to drive the workflow instead of running npm publish locally. The user-facing flow shrinks to: pre-flight checks → 'gh workflow run' → 'gh run watch' → verify via direct registry curl.

Local 'npm publish' is now a documented dead-end: only this workflow file running on main can pass npm's claim check, by design.

Author: MajorTal

.claude/commands/publish-astro.md

@@ -1,116 +1,97 @@
-# /publish-astro — Publish @run402/astro to npm
+# /publish-astro — Publish @run402/astro to npm via OIDC
 
-Publish the `@run402/astro` Astro integration package from `astro/` in this repo. Unlike `@run402/sdk`, `run402` CLI, and `run402-mcp` (which lockstep via `/publish`), `@run402/astro` has its own versioning cadence because it's a framework adapter, not part of the core SDK release train.
+Trigger the canonical publish pipeline at `.github/workflows/publish-astro.yml`. The workflow handles version bump, smoke test, npm publish (via OIDC Trusted Publisher — no stored tokens), commit-back, tag, and GitHub release. This skill is your local-machine wrapper around `gh workflow run`.
 
-> **`@run402/functions` is published from the private gateway monorepo** (`kychee-com/run402-private` via `/publish-functions`). This skill is only for `@run402/astro`.
+> **Why CI-driven not local-publish:** `@run402/astro` uses npm's Trusted Publisher OIDC federation. The npm package's settings page lists this repository, branch, and workflow filename as a trusted publisher. Any publish attempted from anywhere else (a developer laptop, a fork, a different workflow file) fails the npm-side claim check. The whole point of OIDC is to remove the "do you have a token" question — only this workflow file running on main can publish.
+>
+> **One bootstrap exception:** v0.1.0 was published manually with an OTP-elevated automation token because npm requires the package to exist before a Trusted Publisher can be configured. That bootstrap is done and never repeats; from 0.1.1 onwards, all publishes go through this skill → this workflow.
 
-Stop on any failure. Do NOT skip checks.
+> **`@run402/functions` is published from a different repo** (`kychee-com/run402-private` via `/publish-functions`). This skill is only for `@run402/astro`.
+>
+> **`run402-mcp`, `run402` CLI, and `@run402/sdk`** ship via `/publish` (lockstep). This skill is independent of that release train.
 
-## When to publish
+Stop on any failure. Do NOT skip checks.
 
-- New `<Image>` component prop, integration option, or behavior change → publish
-- Bug fix to the resolver / scanner / uploader / picture-builder → publish patch
-- Compat fix for a new Astro major version → publish minor (after testing against the new major)
-- Documentation-only README fix → publish at your discretion (no functional change)
+## Pre-flight (local, before triggering the workflow)
 
-The package has **no runtime relationship with the gateway** — there is no equivalent of `@run402/functions`'s "gateway redeploy alone propagates the fix." A consumer must bump their `@run402/astro` dependency to see any change.
+These run on your machine to catch obvious problems before the workflow burns Actions minutes:
 
-## Pre-publish checks
+1. **On `main`, in sync with `origin/main`.** `git rev-parse --abbrev-ref HEAD` must be `main`. `git fetch origin main && git rev-list --count HEAD..origin/main` must be `0`. If not, stop and tell the user. The workflow itself enforces `if: github.ref == 'refs/heads/main'`, but catching the mismatch locally avoids a wasted run.
+2. **Working tree clean** (`git status`). Uncommitted changes don't go to the workflow — they'd be invisible to the publish. If the user has work in flight that they want included in the publish, commit + push it first.
+3. **Unit tests pass:** `npm test --workspace=astro`. Expect ~50 tests, 0 failures. The workflow re-runs these but a local pre-check gives fast feedback.
+4. **Type-check clean:** `npx tsc --noEmit -p astro`. Empty output = clean.
+5. **Confirm npm Trusted Publisher is configured.** Open https://www.npmjs.com/package/@run402/astro/access in a browser and confirm the "Trusted Publishers" section lists this repo + workflow. If the section is empty, the publish step will fail with 401 — stop and ask the user to configure it before proceeding (org `kychee-com`, repo `run402`, workflow filename `publish-astro.yml`, no environment).
 
-1. **On main, in sync with origin/main.** `git rev-parse --abbrev-ref HEAD` must be `main`. `git fetch origin main && git rev-list --count HEAD..origin/main` must be `0`. If not, stop and tell the user.
-2. **Working tree clean** (`git status`). Stop if not.
-3. **Unit tests pass:** `npm test --workspace=astro`. Expect 50+ tests, 0 failures.
-4. **Type-check clean:** `npx tsc --noEmit -p astro`. No output = clean.
-5. **Build the package:** `npm run build --workspace=astro`. Confirms `dist/` is current.
+If any local check fails, stop and tell the user.
 
-If any step fails, stop and tell the user.
+## Choose the bump kind
 
-## Version bump
+Ask the user: **patch, minor, or major.**
 
-1. Ask the user: **patch, minor, or major.**
-   - Patch (`0.1.0 → 0.1.1`): bug fix, no surface change.
-   - Minor (`0.1.0 → 0.2.0`): new prop, new integration option, or new optional behavior. Backwards-compatible.
-   - Major (`0.1.0 → 1.0.0` or `1.0.0 → 2.0.0`): breaking prop change, removed option, or behavior change that requires consumer code changes. v0.x → v1.x is the "stable surface" promotion.
-2. Read current version from `astro/package.json`.
-3. Compute target: apply bump kind. Apply directly to `astro/package.json` (use Edit, not `npm version` — `npm version` from inside a workspace can have surprising lockfile behavior).
-4. `npm install --package-lock-only` from repo root to sync `package-lock.json`.
+- **Patch** (`0.1.0 → 0.1.1`): bug fix, no surface change. Example: blurhash decoder crash on edge case, error message wording.
+- **Minor** (`0.1.0 → 0.2.0`): new prop, new integration option, or new optional behavior. Backwards-compatible. Example: new `placeholder="dominantColor"` mode, support for AVIF variants when they ship in v1.50.
+- **Major** (`0.x → 1.0` or `1.x → 2.0`): breaking prop change, removed option, or behavior change that requires consumer code changes. Example: removing `priority` in favor of `fetchpriority`, changing the variant URL format. Reserve `1.0` for the "stable surface" promotion when the prop API is locked.
 
-## Tarball smoke test
+## Trigger the workflow
 
-`npm test` runs against source, not the packed tarball. Pack it and verify the entry points resolve:
+The workflow does ALL the publish work — version bump, smoke test, npm publish, commit-back to main, tag, GitHub release. You just trigger it:
 
 ```
-SMOKE=/tmp/smoke-astro-<new_version> && rm -rf $SMOKE && mkdir $SMOKE
-(cd astro && npm pack --pack-destination $SMOKE)
-mkdir $SMOKE/astro && tar xzf $SMOKE/run402-astro-<new_version>.tgz -C $SMOKE/astro
-(cd $SMOKE/astro/package && npm install --omit=dev --before=9999-12-31)
-node -e "import('$SMOKE/astro/package/dist/index.js').then(m => console.log('OK', typeof m.run402)).catch(e => { console.error('FAIL', e.message); process.exit(1) })"
+gh workflow run publish-astro.yml -F bump=<patch|minor|major> -R kychee-com/run402
 ```
 
-Expect `OK function`. The script exits non-zero on any failure.
-
-**Also verify the .astro component file ships:**
+For a dry-run that builds + smoke-tests without publishing (useful when validating a workflow change):
 
 ```
-ls $SMOKE/astro/package/src/Image.astro
+gh workflow run publish-astro.yml -F bump=patch -F dry_run=true -R kychee-com/run402
 ```
 
-Must print the path. If the file is missing, the `files` allowlist in `package.json` is broken — do not publish.
+The dry run still bumps the local version on the runner and packs the tarball, but skips the publish + commit + tag + release steps. Useful for "does the bumped version pack right?" testing.
+
+## Watch the workflow
 
-**Also verify the tarball does NOT include source `.ts` files:**
+Find the run ID and watch:
 
 ```
-find $SMOKE/astro/package -name "*.ts" -not -name "*.d.ts" | head
+RUN_ID=$(gh run list -w publish-astro.yml -R kychee-com/run402 --limit 1 --json databaseId --jq '.[0].databaseId')
+gh run watch "$RUN_ID" -R kychee-com/run402 --exit-status
 ```
 
-Should print nothing (only `.d.ts` types ship). Source `.ts` files in the tarball means `files` allowlist is wrong.
+`--exit-status` makes the watch command exit non-zero if the workflow fails — useful for chaining into a verification step.
 
-**About `--before=9999-12-31`:** if the user's global npm has a `before` date pinned (supply-chain mitigation), the scratch install needs this flag to bypass it for `/tmp` installs. Do **not** suggest removing the global config.
+## Verify post-publish
 
-## Commit and publish
+After the workflow completes successfully:
 
-1. Stage and commit the version bump:
+1. **Verify the new version is live:**
    ```
-   git add astro/package.json package-lock.json
-   git commit -m "chore(astro): bump @run402/astro to v<new_version>"
+   curl -sS "https://registry.npmjs.org/@run402/astro/<new_version>" | jq -r .version
    ```
-2. Publish:
-   ```
-   cd astro && npm publish --access public
-   ```
-   The `publishConfig.access: public` field is set in `package.json`, so the explicit flag is redundant but harmless. The tarball contains `dist/`, `src/Image.astro`, and `README.md` only (per the `files` allowlist; `node_modules`, tests, and `*.test.*` are excluded).
+   The user's local npm may have a `--before` date pin set as a supply-chain mitigation that filters out newly-published packages from `npm view`. Use direct `curl` to confirm registry state. If the user wants to see it via `npm view`, they need `--before=9999-12-31` (do NOT suggest changing their global config).
 
-## Post-publish
-
-1. `git push` to push the version bump commit.
-2. Create a git tag:
-   ```
-   git tag v<new_version>-astro && git push --tags
+2. **Confirm provenance attestation:**
    ```
-   Use the `-astro` suffix because the other public-repo packages (`run402-mcp`, `run402`, `@run402/sdk`) have their own tag scheme; this clarifies which package the tag belongs to.
-3. Create a GitHub release (public repo):
+   curl -sS "https://registry.npmjs.org/@run402/astro/<new_version>" | jq '.dist.attestations'
    ```
-   gh release create v<new_version>-astro -R kychee-com/run402 --notes "..."
-   ```
-   Write a human-readable summary naming user-facing changes. Don't rely on auto-generated notes.
-4. **Verify live on npm:**
-   ```
-   npm view @run402/astro@<new_version> version
-   ```
-   Should print the new version. May take up to a minute to propagate.
-5. **Update `documentation.md`** if the prop surface or integration options changed. The doc serves as the canonical reference for the public repo. Commit + push.
-6. **Update `llms-full.txt` in the private repo** (`kychee-com/run402-private` at `site/llms-full.txt`) if the Astro integration section needs to point at a new version or document a new feature. The site at https://run402.com/llms-full.txt is regenerated from there; trigger a redeploy after the update:
-   ```
-   gh workflow run deploy-site.yml -R kychee-com/run402-private
-   ```
-7. Print a summary:
+   Should return a non-null object. If null, OIDC didn't kick in and the publish silently fell back to anonymous — investigate.
+
+3. **Print summary** for the user:
    - Published version
-   - npm URL: `https://www.npmjs.com/package/@run402/astro`
-   - GitHub release URL
+   - npm URL: `https://www.npmjs.com/package/@run402/astro/v/<new_version>`
+   - Workflow run URL
+   - GitHub release URL: `https://github.com/kychee-com/run402/releases/tag/v<new_version>-astro`
 
 ## What this skill does NOT do
 
-- Does NOT bump `mcp`, `cli`, or `sdk`. Those lockstep via `/publish`.
-- Does NOT bump `@run402/functions`. That lives in the private gateway monorepo and ships via `/publish-functions` there.
-- Does NOT trigger any gateway redeploy. There is no gateway-side dependency on this package.
-- Does NOT migrate consumer projects. After publishing, consumers (Kychon, etc.) update their `@run402/astro` dependency on their own cadence.
+- Does NOT publish locally via `npm publish`. The Trusted Publisher OIDC trust ONLY accepts publishes from THIS workflow file on `main`. Attempting a local publish would fail the npm-side claim check (or succeed only if the user has an unrelated bypass-2FA token, which defeats the whole point).
+- Does NOT bump `mcp`, `cli`, `sdk` — those lockstep via `/publish`.
+- Does NOT bump `@run402/functions` — that lives in the private gateway monorepo.
+- Does NOT pull a release branch — the workflow operates on `main` directly. Use a feature branch for the code change, merge to main, then run this skill.
+- Does NOT prompt for an OTP or token. If you ever see the workflow asking for one, the Trusted Publisher config drifted — fix the npm-side config rather than reverting to token auth.
+
+## Troubleshooting
+
+- **Workflow fails at `Publish to npm` with 401 or 403:** Trusted Publisher config doesn't match. Check the npm package access page — org / repo / workflow filename must exactly match this workflow's metadata.
+- **Workflow fails at `Commit version bump` with permission denied:** Repo Settings → Actions → General → Workflow permissions → must be "Read and write." The default GITHUB_TOKEN's permissions are read-only unless this is flipped.
+- **Workflow fails at `Tarball smoke test` after a successful publish-in-progress:** the tarball was generated incorrectly. Recover by manually patching `astro/package.json` to bump the version back (workflow had already bumped locally on the runner but not committed) and re-run. The npm-side already-published version blocks re-publish, which is the safety net.
+- **`npm view` returns 404 right after a successful publish:** almost always the user's `--before` date pin filtering, not a real propagation issue. Confirm with the direct `curl` against `registry.npmjs.org`.