pdd-cli 0.0.241__tar.gz → 0.0.243__tar.gz

pdd_cli-0.0.243/.env.example

@@ -0,0 +1,18 @@
+# LLM API Keys (at least one required)
+OPENAI_API_KEY=your-openai-api-key
+GOOGLE_API_KEY=your-google-api-key
+ANTHROPIC_API_KEY=your-anthropic-api-key
+
+# Additional LLM Providers (optional)
+DEEPSEEK_API_KEY=your-deepseek-api-key
+FIREWORKS_API_KEY=your-fireworks-api-key
+GROQ_API_KEY=your-groq-api-key
+TOGETHER_API_KEY=your-together-api-key
+
+# Vertex AI (optional - for Gemini via GCP)
+VERTEX_CREDENTIALS=/path/to/service-account.json
+VERTEX_PROJECT=your-gcp-project-id
+VERTEX_LOCATION=us-central1
+
+# PDD Configuration
+PDD_PATH=/path/to/your/pdd

pdd_cli-0.0.243/.gitattributes

@@ -0,0 +1,21 @@
+# Ensure shell scripts always use LF line endings
+*.sh text eol=lf
+tests/*.sh text eol=lf
+pdd-local.sh text eol=lf
+
+# Python files should use LF line endings
+*.py text eol=lf
+
+# Ensure other text files use appropriate line endings
+*.md text
+*.txt text
+*.json text
+*.prompt text
+
+# Binary files
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.gif binary
+*.ico binary
+*.pdf binary

pdd_cli-0.0.243/.github/workflows/auto-heal.yml

@@ -0,0 +1,346 @@
+name: auto-heal
+
+# Required status check on `main`. Posts a check named "auto-heal" against
+# the PR head SHA via the Checks API so it appears on the PR regardless of
+# whether the trigger was a PR event or a /heal comment.
+#
+# Compute runs in pdd_cloud's GCP project (prompt-driven-development-stg)
+# via Cloud Build using a pre-staged build-context tarball. This workflow
+# only dispatches the build and surfaces its status; no LLM or PEM
+# secrets ever land on a GitHub-Actions runner.
+#
+# ---- Two distinct GitHub Apps ----
+# These MUST be different Apps (separation of duty):
+#   App A — `pdd-cloud-auth-reader`: Metadata: Read on promptdriven/pdd_cloud
+#     only. Used HERE to authorize the requester. PEM stored in this repo's
+#     GHA secrets (PDD_CLOUD_APP_ID, PDD_CLOUD_APP_PRIVATE_KEY).
+#   App B — `prompt-driven-github-staging` (existing): write perms on
+#     promptdriven/pdd. Used INSIDE the Cloud Build to push the heal commit
+#     back to the PR branch. PEM stored only in GCP Secret Manager
+#     (gemini-dispatch-gh-app-private-key).
+#
+# ---- Security boundaries ----
+# - `pull_request_target` runs workflow code from main, never from PR head,
+#   so a fork PR cannot modify the auth gate. PR code only runs inside
+#   Cloud Build, which has no access to this workflow's GHA secrets.
+# - The dispatcher SA is impersonable ONLY by this exact workflow file at
+#   refs/heads/main (WIF attribute_condition + principalSet pinning to
+#   attribute.workflow_ref). Any new workflow on this repo cannot mint a
+#   token for the dispatcher SA.
+# - Fork PRs short-circuit BEFORE the App token is minted; "neutral" check
+#   conclusion lets them merge (treated as passing by branch protection)
+#   without an actual heal.
+# - Every event-derived value is passed through `env:` and read via shell
+#   variables — never interpolated directly into `run:` blocks. Markdown
+#   summaries are built from workflow-controlled values only.
+
+on:
+  pull_request_target:
+    types: [opened, synchronize, reopened, ready_for_review]
+  issue_comment:
+    types: [created]
+
+permissions:
+  contents: read
+  pull-requests: read
+  checks: write
+  id-token: write   # Workload Identity Federation to GCP
+
+# Do NOT cancel in-progress runs. Cancelling a required check mid-flight
+# muddies merge semantics; let parallel runs race for the latest SHA's check.
+# Cancelled-then-success on an older SHA does not affect protection on the
+# newer SHA, so there is no abuse vector to consider.
+concurrency:
+  group: auto-heal-${{ github.event.pull_request.number || github.event.issue.number }}
+  cancel-in-progress: false
+
+jobs:
+  heal:
+    # Non-draft PR events, or a /heal comment on a PR (issue-comment events
+    # for issues that aren't PRs are filtered out). `startsWith('/heal')`
+    # also matches /healthcheck — the pre-flight step rejects false positives
+    # before any privileged work runs.
+    if: |
+      (github.event_name == 'pull_request_target'
+        && github.event.pull_request.draft == false) ||
+      (github.event_name == 'issue_comment'
+        && github.event.action == 'created'
+        && github.event.issue.pull_request != null
+        && startsWith(github.event.comment.body, '/heal'))
+    runs-on: ubuntu-latest
+    timeout-minutes: 60
+    steps:
+      - name: Pre-flight (validate trigger + resolve PR)
+        id: pf
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          EVENT_NAME: ${{ github.event_name }}
+          BODY: ${{ github.event.comment.body }}
+          PR_NUMBER_FROM_PR: ${{ github.event.pull_request.number }}
+          PR_HEAD_SHA_FROM_PR: ${{ github.event.pull_request.head.sha }}
+          PR_HEAD_REPO_FROM_PR: ${{ github.event.pull_request.head.repo.full_name }}
+          REQUESTER_FROM_PR: ${{ github.event.pull_request.user.login }}
+          ISSUE_NUMBER: ${{ github.event.issue.number }}
+          REQUESTER_FROM_COMMENT: ${{ github.event.comment.user.login }}
+          REPO: ${{ github.repository }}
+        run: |
+          set -euo pipefail
+          # For issue_comment, require /heal as a standalone first token on
+          # the first line. Rejects /healthcheck, /healz, etc.
+          if [ "$EVENT_NAME" = "issue_comment" ]; then
+            # tr -d '\r' guards against CRLF line endings that some clients
+            # may submit (GitHub doesn't contractually normalize to LF).
+            first_token=$(printf '%s' "$BODY" | head -n1 | tr -d '\r' | awk '{print $1}')
+            if [ "$first_token" != "/heal" ]; then
+              echo "Comment first token '$first_token' is not '/heal'; ignoring."
+              echo "skip=true" >> "$GITHUB_OUTPUT"
+              exit 0
+            fi
+          fi
+
+          if [ "$EVENT_NAME" = "pull_request_target" ]; then
+            pr_number="$PR_NUMBER_FROM_PR"
+            pr_head_sha="$PR_HEAD_SHA_FROM_PR"
+            pr_head_repo="$PR_HEAD_REPO_FROM_PR"
+            requester="$REQUESTER_FROM_PR"
+          else
+            pr_number="$ISSUE_NUMBER"
+            pr_meta=$(gh api "repos/$REPO/pulls/$pr_number" \
+              --jq '[.head.sha, (.head.repo.full_name // "")] | @tsv')
+            pr_head_sha=$(printf '%s' "$pr_meta" | cut -f1)
+            pr_head_repo=$(printf '%s' "$pr_meta" | cut -f2)
+            requester="$REQUESTER_FROM_COMMENT"
+          fi
+
+          if [ -z "$pr_number" ] || [ -z "$pr_head_sha" ] || [ -z "$requester" ]; then
+            echo "::error::Failed to resolve PR fields (number=$pr_number sha=$pr_head_sha requester=$requester)"
+            exit 1
+          fi
+
+          fork=false
+          if [ "$pr_head_repo" != "$REPO" ]; then
+            fork=true
+          fi
+
+          trusted_app_requester=false
+          if [ "$EVENT_NAME" = "pull_request_target" ] &&
+             [ "$fork" = "false" ] &&
+             [ "$requester" = "prompt-driven-github[bot]" ]; then
+            trusted_app_requester=true
+          fi
+
+          {
+            echo "skip=false"
+            echo "fork=$fork"
+            echo "trusted_app_requester=$trusted_app_requester"
+            echo "pr_number=$pr_number"
+            echo "pr_head_sha=$pr_head_sha"
+            echo "pr_head_repo=$pr_head_repo"
+            echo "requester=$requester"
+          } >> "$GITHUB_OUTPUT"
+
+      - name: Post check_run (in_progress) on PR head SHA
+        if: steps.pf.outputs.skip != 'true'
+        id: check_start
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          PR_HEAD_SHA: ${{ steps.pf.outputs.pr_head_sha }}
+          REPO: ${{ github.repository }}
+          RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
+        run: |
+          set -euo pipefail
+          check_id=$(gh api -X POST \
+            "repos/$REPO/check-runs" \
+            -f name='auto-heal' \
+            -f head_sha="$PR_HEAD_SHA" \
+            -f status='in_progress' \
+            -f details_url="$RUN_URL" \
+            --jq .id)
+          echo "check_id=$check_id" >> "$GITHUB_OUTPUT"
+
+      # Short-circuit fork PRs BEFORE minting any App token. Auto-heal pushes
+      # commits back to the PR branch which is impossible on a fork; "neutral"
+      # is treated as passing by GitHub branch protection, so fork PRs are
+      # not permanently blocked from merging.
+      - name: Short-circuit fork PRs (neutral conclusion)
+        if: steps.pf.outputs.skip != 'true' && steps.pf.outputs.fork == 'true'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          REPO: ${{ github.repository }}
+          CHECK_ID: ${{ steps.check_start.outputs.check_id }}
+          RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
+        run: |
+          set -euo pipefail
+          # Summary is built from workflow-controlled values only. Never
+          # interpolate event-derived strings (PR title, comment body, branch
+          # names) into rendered markdown on a check.
+          gh api -X PATCH "repos/$REPO/check-runs/$CHECK_ID" \
+            -f status='completed' \
+            -f conclusion='neutral' \
+            -f "output[title]=auto-heal skipped (fork PR)" \
+            -f "output[summary]=Fork PRs are not auto-healed because the heal pushes commits to the PR branch (not possible across forks). [Workflow run]($RUN_URL)."
+
+      - name: Mint pdd_cloud App token
+        if: steps.pf.outputs.skip != 'true' && steps.pf.outputs.fork == 'false'
+        id: app_token
+        # SHA-pinned to v3.1.1 (https://github.com/actions/create-github-app-token/releases/tag/v3.1.1)
+        uses: actions/create-github-app-token@1b10c78c7865c340bc4f6099eb2f838309f1e8c3
+        with:
+          app-id: ${{ secrets.PDD_CLOUD_APP_ID }}
+          private-key: ${{ secrets.PDD_CLOUD_APP_PRIVATE_KEY }}
+          owner: promptdriven
+          repositories: pdd_cloud
+
+      - name: Authorize requester (must be pdd_cloud collaborator)
+        if: steps.pf.outputs.skip != 'true' && steps.pf.outputs.fork == 'false'
+        env:
+          GH_TOKEN: ${{ steps.app_token.outputs.token }}
+          REQUESTER: ${{ steps.pf.outputs.requester }}
+          TRUSTED_APP_REQUESTER: ${{ steps.pf.outputs.trusted_app_requester }}
+        run: |
+          set -euo pipefail
+          if [ -z "$REQUESTER" ]; then
+            echo "::error::requester unresolved; refusing to authorize"
+            exit 1
+          fi
+          # Generated internal PRs are authored by prompt-driven-github[bot],
+          # a GitHub App identity that cannot be a repository collaborator.
+          # Pre-flight only marks this exact requester as trusted on
+          # non-fork pull_request_target events. Human /heal comments still
+          # go through the pdd_cloud collaborator check below.
+          if [ "$TRUSTED_APP_REQUESTER" = "true" ]; then
+            echo "authorized: $REQUESTER is the trusted generated-PR App identity"
+            exit 0
+          fi
+          # 204 = is a collaborator. 404 = not a collaborator.
+          # Anything else = fail loud (don't silently confuse denial with
+          # API/transport errors).
+          # NOTE: NO ?affiliation=direct — App-token queries treat that
+          # filter strictly, and it excludes org-owners-with-admin-via-org
+          # who SHOULD be authorized. The unfiltered endpoint returns 204
+          # for any kind of collaborator (direct, team, outside, org owner),
+          # which is what the auth model wants.
+          http_code=$(gh api -i \
+            "repos/promptdriven/pdd_cloud/collaborators/$REQUESTER" \
+            2>/dev/null | head -n1 | awk '{print $2}' || true)
+          case "$http_code" in
+            204|200)
+              echo "authorized: $REQUESTER is a pdd_cloud collaborator"
+              ;;
+            404)
+              echo "::error::$REQUESTER is not a pdd_cloud collaborator; auto-heal blocked. A pdd_cloud collaborator must comment '/heal' to authorize."
+              exit 1
+              ;;
+            *)
+              echo "::error::pdd_cloud collaborator check returned HTTP '$http_code'; refusing to authorize. Likely transient — retry, or verify the App's installation and Metadata:Read permission."
+              exit 1
+              ;;
+          esac
+
+      - name: Authenticate to GCP via Workload Identity Federation
+        if: steps.pf.outputs.skip != 'true' && steps.pf.outputs.fork == 'false'
+        # SHA-pinned to v3.0.0 (https://github.com/google-github-actions/auth/releases/tag/v3.0.0)
+        uses: google-github-actions/auth@7c6bc770dae815cd3e89ee6cdf493a5fab2cc093
+        with:
+          workload_identity_provider: projects/590888610376/locations/global/workloadIdentityPools/github-actions/providers/github
+          service_account: pdd-public-heal-dispatcher@prompt-driven-development-stg.iam.gserviceaccount.com
+
+      - name: Set up gcloud
+        if: steps.pf.outputs.skip != 'true' && steps.pf.outputs.fork == 'false'
+        # SHA-pinned to v3.0.1 (https://github.com/google-github-actions/setup-gcloud/releases/tag/v3.0.1)
+        uses: google-github-actions/setup-gcloud@aa5489c8933f4cc7a4f7d45035b3b1440c9c10db
+
+      - name: Submit Cloud Build (async)
+        if: steps.pf.outputs.skip != 'true' && steps.pf.outputs.fork == 'false'
+        id: gcb_submit
+        env:
+          PR_NUMBER: ${{ steps.pf.outputs.pr_number }}
+        run: |
+          set -euo pipefail
+          # gcloud builds submit reads --config from the LOCAL filesystem
+          # (not from inside the GCS source tarball). Extract the cloudbuild
+          # config from the staged tarball into a temp dir first. The
+          # extracted scripts also stay on the runner, but they're the same
+          # 5 files cloudbuild itself unpacks at build time — not pdd_cloud
+          # source.
+          ctx_dir=$(mktemp -d)
+          trap 'rm -rf "$ctx_dir"' EXIT
+          gsutil cp gs://pdd-stg-build-contexts/auto-heal-pr-latest.tgz "$ctx_dir/source.tgz"
+          tar -xzf "$ctx_dir/source.tgz" -C "$ctx_dir"
+          # Use our own bucket for source staging so the dispatcher SA
+          # doesn't need access to the default `<project>_cloudbuild`
+          # bucket (which is restricted by org policy on this project).
+          # No --gcs-log-dir: cloudbuild-pdd-cli-auto-heal-pr.yaml sets
+          # `options.logging: CLOUD_LOGGING_ONLY` which conflicts with a
+          # GCS log bucket; logs go to Cloud Logging.
+          build_id=$(gcloud builds submit \
+            gs://pdd-stg-build-contexts/auto-heal-pr-latest.tgz \
+            --project=prompt-driven-development-stg \
+            --config="$ctx_dir/cloudbuild-pdd-cli-auto-heal-pr.yaml" \
+            --gcs-source-staging-dir=gs://pdd-stg-build-contexts/_staging \
+            --substitutions=_PUBLIC_PR_NUMBER="$PR_NUMBER" \
+            --async \
+            --format='value(id)')
+          echo "build_id=$build_id" >> "$GITHUB_OUTPUT"
+          echo "Cloud Build $build_id submitted; polling for completion."
+
+      - name: Wait for Cloud Build to complete
+        if: steps.pf.outputs.skip != 'true' && steps.pf.outputs.fork == 'false'
+        env:
+          BUILD_ID: ${{ steps.gcb_submit.outputs.build_id }}
+        run: |
+          set -euo pipefail
+          while true; do
+            status=$(gcloud builds describe "$BUILD_ID" \
+              --project=prompt-driven-development-stg \
+              --format='value(status)')
+            case "$status" in
+              SUCCESS)
+                echo "Cloud Build $BUILD_ID succeeded"
+                exit 0
+                ;;
+              FAILURE|INTERNAL_ERROR|TIMEOUT|CANCELLED|EXPIRED)
+                echo "::error::Cloud Build $BUILD_ID conclusion: $status"
+                exit 1
+                ;;
+              QUEUED|WORKING|PENDING)
+                sleep 30
+                ;;
+              *)
+                echo "Unknown Cloud Build status '$status'; continuing to poll"
+                sleep 30
+                ;;
+            esac
+          done
+
+      - name: Finalize check_run
+        if: always() && steps.check_start.outputs.check_id && steps.pf.outputs.fork == 'false'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          REPO: ${{ github.repository }}
+          CHECK_ID: ${{ steps.check_start.outputs.check_id }}
+          STATUS: ${{ job.status }}
+          BUILD_ID: ${{ steps.gcb_submit.outputs.build_id }}
+          RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
+        run: |
+          set -euo pipefail
+          # Map every non-success outcome to "failure" so branch protection
+          # has unambiguous semantics. Cancelled / timed-out runs must not
+          # silently allow merge.
+          case "$STATUS" in
+            success) conclusion=success ;;
+            *)       conclusion=failure ;;
+          esac
+          # Summary is built from workflow-controlled values only. Never
+          # interpolate event-derived strings into rendered markdown.
+          if [ -n "${BUILD_ID:-}" ]; then
+            summary="auto-heal $conclusion. Cloud Build: $BUILD_ID. [Workflow run]($RUN_URL)."
+          else
+            summary="auto-heal $conclusion (build did not start). [Workflow run]($RUN_URL)."
+          fi
+          gh api -X PATCH \
+            "repos/$REPO/check-runs/$CHECK_ID" \
+            -f status='completed' \
+            -f conclusion="$conclusion" \
+            -f "output[title]=auto-heal $conclusion" \
+            -f "output[summary]=$summary"

pdd_cli-0.0.243/.github/workflows/pdd-secrets-dispatch.yml

@@ -0,0 +1,126 @@
+name: PDD Secrets Dispatch
+
+on:
+  repository_dispatch:
+    types: [pdd-secrets]
+
+jobs:
+  provide-secrets:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install Dependencies
+        run: pip install cryptography requests
+
+      - name: Encrypt and Send Secrets
+        shell: python
+        env:
+          SECRETS_CONTEXT: ${{ toJSON(secrets) }}
+          PAYLOAD_CONTEXT: ${{ toJSON(github.event.client_payload) }}
+          WORKER_PUBLIC_KEY: |
+            -----BEGIN PUBLIC KEY-----
+            MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAwLc2Vn2VErKtvPa27Iek
+            ePSZuWdagaiA9wfce4+4GR3aDNCsv24btyttNapgqO1pkB7mVATp4WJCD7F3CDMU
+            ddDsi07PReXJrdMp+/IC0eGblHPPpJyZOh/5ZoIo2oJPOHjGWwEQO75JgT8jtvUh
+            L2o7lYuFS1BwMQpdHifpxDWdn8yXo6SvV7k0UISEWKn5sa4gcalOhYiEjFUNt4pt
+            a7/HJQQu6K3AJKoUT8eTsftV5o1SHP0C8wB85hOehdzEM5uSpCb6aZ/cVqU38z15
+            NjqEVabaUquswZwHQ1aHmK+CktX0KfBKa/DYk4ZqW1gMGXgakbj6lsDTcPXzWUtm
+            jwIDAQAB
+            -----END PUBLIC KEY-----
+        run: |
+          import os, json, base64
+          import secrets as stdlib_secrets
+          import requests
+          from cryptography.hazmat.primitives import serialization, hashes
+          from cryptography.hazmat.primitives.asymmetric import padding
+          from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+          from cryptography.hazmat.backends import default_backend
+
+          def encrypt_and_send():
+              try:
+                  # 1. Parse inputs
+                  secrets_map = json.loads(os.environ.get("SECRETS_CONTEXT", "{}"))
+                  payload = json.loads(os.environ.get("PAYLOAD_CONTEXT", "{}"))
+                  public_key_pem = os.environ.get("WORKER_PUBLIC_KEY")
+
+                  job_id = payload.get("job_id")
+                  callback_url = payload.get("callback_url")
+                  callback_token = payload.get("callback_token")
+                  required_keys = payload.get("required_secrets", [])
+
+                  if not job_id or not callback_url or not callback_token:
+                      print("::error::Missing job_id, callback_url, or callback_token")
+                      exit(1)
+
+                  # 2. Filter secrets to only those requested
+                  data_to_encrypt = {}
+                  if required_keys:
+                      for key in required_keys:
+                          if key in secrets_map:
+                              data_to_encrypt[key] = secrets_map[key]
+                  else:
+                      data_to_encrypt = secrets_map
+
+                  if not data_to_encrypt:
+                      print("No matching secrets found. Sending empty payload.")
+
+                  json_data = json.dumps(data_to_encrypt).encode("utf-8")
+
+                  # 3. Hybrid encryption: AES-256-GCM for data, RSA-OAEP for AES key
+                  public_key = serialization.load_pem_public_key(
+                      public_key_pem.encode("utf-8"),
+                      backend=default_backend()
+                  )
+
+                  aes_key = stdlib_secrets.token_bytes(32)
+                  iv = stdlib_secrets.token_bytes(12)
+
+                  aesgcm = AESGCM(aes_key)
+                  ciphertext = aesgcm.encrypt(iv, json_data, None)
+
+                  encrypted_key = public_key.encrypt(
+                      aes_key,
+                      padding.OAEP(
+                          mgf=padding.MGF1(algorithm=hashes.SHA256()),
+                          algorithm=hashes.SHA256(),
+                          label=None
+                      )
+                  )
+
+                  envelope = {
+                      "version": 2,
+                      "encrypted_key": base64.b64encode(encrypted_key).decode(),
+                      "iv": base64.b64encode(iv).decode(),
+                      "ciphertext": base64.b64encode(ciphertext).decode(),
+                  }
+
+                  encrypted_b64 = base64.b64encode(
+                      json.dumps(envelope).encode()
+                  ).decode()
+
+                  # 4. POST encrypted secrets back to worker
+                  response = requests.post(
+                      callback_url,
+                      json={
+                          "job_id": job_id,
+                          "encrypted_secrets": encrypted_b64,
+                          "callback_token": callback_token,
+                      },
+                      timeout=30,
+                  )
+
+                  if response.status_code == 200:
+                      print(f"Successfully sent secrets for job {job_id}")
+                  else:
+                      print(f"::error::Callback failed: {response.status_code} {response.text}")
+                      exit(1)
+
+              except Exception as e:
+                  print(f"::error::Script failed: {e}")
+                  exit(1)
+
+          encrypt_and_send()

pdd_cli-0.0.243/.github/workflows/release.yml

@@ -0,0 +1,87 @@
+name: Publish to PyPI
+
+on:
+  workflow_dispatch:
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  publish-testpypi:
+    if: github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    environment: pypi-test-publish
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build sdist and wheel
+        run: |
+          python -m pip install --upgrade pip build twine
+          python -m build
+
+      - name: Verify artifacts
+        run: python -m twine check dist/*
+
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+          skip-existing: true
+          attestations: true
+
+  publish-pypi:
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    environment: pypi-publish
+    permissions:
+      contents: write
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build sdist and wheel
+        run: |
+          python -m pip install --upgrade pip build twine
+          python -m build
+
+      - name: Verify artifacts
+        run: python -m twine check dist/*
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          skip-existing: true
+          attestations: true
+
+      - name: Create GitHub Release with auto-notes (idempotent)
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          tag="${{ github.ref_name }}"
+          if gh release view "$tag" >/dev/null 2>&1; then
+            echo "GitHub Release $tag already exists; skipping."
+          else
+            gh release create "$tag" --generate-notes --verify-tag --target main
+          fi