ci(publish): add SHA-pinned OIDC PyPI publish workflow

Triggers:
  - push to any `v*` tag auto-publishes.
  - workflow_dispatch lets you (re)publish an existing tag manually
    (e.g. backfilling v0.2.1 which shipped before this workflow).

Details:
- Trusted Publisher (OIDC) via pypa/gh-action-pypi-publish — no long-lived
  PyPI token stored in GitHub. All third-party actions SHA-pinned.
- Build step sanity-checks that pyproject.toml's version matches the tag
  when triggered by a tag push. Skipped for workflow_dispatch.
- Uses `environment: pypi` so PyPI's environment-scoped Trusted Publisher
  binding works (see TODOS.md for the one-time PyPI setup instructions).

No PyPI upload happens on this commit — the workflow only runs on tag
push or manual dispatch.

Author: simonsysun

.github/workflows/publish.yml

@@ -0,0 +1,87 @@
+name: Publish to PyPI
+
+# Triggers:
+#   - Pushing any tag matching `v*` auto-publishes that ref to PyPI.
+#   - `workflow_dispatch` lets you (re)publish an existing tag manually,
+#     useful for backfilling a tag that shipped before this workflow
+#     existed (e.g. v0.2.1) or for retrying a failed publish.
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: "Existing tag to publish (e.g. v0.2.1). Leave blank to use the branch HEAD."
+        required: false
+        type: string
+        default: ""
+
+jobs:
+  build:
+    name: Build sdist + wheel
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+        with:
+          # workflow_dispatch may override with a specific tag; otherwise
+          # use the ref that triggered the workflow (tag push = that tag).
+          ref: ${{ github.event.inputs.tag != '' && github.event.inputs.tag || github.ref }}
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@e4db8464a088ece1b920f60402e813ea4de65b8f # v4
+
+      - name: Build distributions
+        run: uv build
+
+      - name: Sanity-check version matches tag
+        # When triggered by a tag push, ensure pyproject.toml version matches
+        # the tag name. Skipped for workflow_dispatch (where we assume the
+        # invoker knows what they're doing).
+        if: github.event_name == 'push'
+        run: |
+          TAG_VERSION="${GITHUB_REF_NAME#v}"
+          PKG_VERSION=$(grep -E '^version = ' pyproject.toml | head -1 | sed -E 's/version = "([^"]+)"/\1/')
+          echo "Tag: v${TAG_VERSION}   pyproject: ${PKG_VERSION}"
+          if [ "$TAG_VERSION" != "$PKG_VERSION" ]; then
+            echo "::error::Tag v${TAG_VERSION} does not match pyproject version ${PKG_VERSION}"
+            exit 1
+          fi
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+          retention-days: 7
+
+  publish:
+    name: Publish to PyPI (OIDC)
+    needs: build
+    runs-on: ubuntu-latest
+    # `environment` is required by PyPI's Trusted Publisher if one was
+    # configured with an environment name. We use `pypi` as the
+    # convention. If you set a different name on PyPI, update it here.
+    environment:
+      name: pypi
+      url: https://pypi.org/project/seeklink/
+    permissions:
+      # Required for PyPI Trusted Publishing (OIDC) — the action exchanges
+      # this for a short-lived PyPI upload token, so no long-lived API
+      # secret is ever stored in GitHub.
+      id-token: write
+    steps:
+      - name: Download artifacts
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # v1.14.0
+        # No `password:` input — Trusted Publishing via OIDC.
+        with:
+          packages-dir: dist/

TODOS.md

@@ -33,9 +33,16 @@ Currently freshness warnings only appear in the cold-start CLI path (`seeklink s
 
 ## Infrastructure
 
-### PyPI v0.2 publishing
-Publish v0.2.0 to PyPI. v0.1.0 is already there (manually published).
-When setting this up, prefer a [Trusted Publisher (OIDC)](https://docs.pypi.org/trusted-publishers/) flow via a SHA-pinned `pypa/gh-action-pypi-publish` action instead of a long-lived API token. One-time config; removes the "what if the token leaks" supply-chain class entirely.
+### PyPI publishing (in progress)
+`.github/workflows/publish.yml` (v0.2.1+) ships an OIDC-based Trusted Publisher flow via a SHA-pinned `pypa/gh-action-pypi-publish@v1.14.0`. Future tags matching `v*` will auto-publish once the Trusted Publisher has been registered on PyPI. One-time PyPI-side setup:
+
+1. Log in to https://pypi.org/manage/project/seeklink/settings/publishing/
+2. Add a new **trusted publisher** with:
+   - Owner: `simonsysun`
+   - Repository name: `seeklink`
+   - Workflow filename: `publish.yml`
+   - Environment name: `pypi`
+3. Trigger the workflow once for v0.2.1 via `gh workflow run publish.yml -f tag=v0.2.1` (or via the GitHub Actions UI with the `tag` input set to `v0.2.1`).
 
 ### Multi-vault daemon support
 Current daemon binds to a single socket (`~/.rhizome/seeklink.sock`) regardless of vault. If multiple vaults need concurrent daemons, hash the vault path into the socket name. Deferred until multi-vault is a real use case.