stacktrace-cli 0.9.0__tar.gz → 0.11.0__tar.gz

stacktrace_cli-0.11.0/.agents/skills/release-stacktrace/SKILL.md

@@ -0,0 +1,249 @@
+---
+name: release-stacktrace
+description: Use when cutting a new stacktrace-cli PyPI release. Walks through version bump, release-notes drafting, pre-flight checks, tag, and push — enforces the publish-pypi.yml notes-file gate so the GitHub Releases page can't silently drift from PyPI.
+---
+
+# release-stacktrace
+
+End-to-end release procedure for the `stacktrace-cli` distribution.
+`.github/workflows/publish-pypi.yml` enforces the machine-checkable gates
+(tag on main, tag matches both version strings, notes file present, four
+CI gates green). This skill is the human-side counterpart: it drafts the
+notes with judgment, runs the pre-flight checks, and pushes the tag.
+
+**Announce at start:** "I'm using the release-stacktrace skill to cut a new
+stacktrace-cli release."
+
+## When to invoke
+
+User says any of: "cut a release", "ship 0.0.N", "release stacktrace",
+"tag a new version", or starts editing `pyproject.toml`'s version field
+in this repo.
+
+## Inputs
+
+1. **Target version** (e.g. `0.1.0`). Inferred from `pyproject.toml` if
+   the user already bumped it; otherwise ask.
+2. **Theme** — the H1 line of the notes file. Ask the user; a commit log
+   can't infer it.
+
+## Procedure
+
+### Step 1. Pre-flight checks
+
+Run from the repo root. Stop and ask if any fails — do not "fix" a dirty
+tree or out-of-sync main automatically, those signal in-flight work.
+
+```bash
+git rev-parse --abbrev-ref HEAD                    # must be main
+git status --porcelain                             # must be empty
+git fetch --tags origin
+git rev-parse --verify "v<version>" 2>/dev/null    # MUST FAIL — tag must not exist
+test "$(git rev-parse HEAD)" = "$(git rev-parse origin/main)"
+```
+
+The `release_gate` marker is **not** run here: `test_release_readiness.py`'s
+share of it requires `openaca`/`openaidr` pinned exactly, which is not true of
+a normal checkout (both float on `>=` between releases) and is only made true
+by Step 4. Running it against an unpinned tree would fail on every release,
+not just a broken one. It runs at the end of Step 4, once its precondition
+holds.
+
+PyPI versions are immutable, including yanked ones. If `<version>` is
+already on PyPI, the only path forward is a new version number:
+
+```bash
+curl -s https://pypi.org/pypi/stacktrace-cli/json | python3 -c 'import json,sys; print(sorted(json.load(sys.stdin)["releases"]))'
+```
+
+### Step 2. Gather the commit log
+
+```bash
+prev_tag=$(git describe --tags --abbrev=0)         # empty on the first release
+git log --oneline "${prev_tag}..HEAD"
+```
+
+Raw material only — do not dump it into the notes file verbatim.
+
+### Step 3. Draft `docs/releases/v<version>.md`
+
+Follow the shape of the existing files in `docs/releases/`:
+
+```markdown
+# <version> — <theme>
+
+## Highlights
+
+- **<Theme A>.** 1-3 sentences pitched at someone who installs the CLI.
+  Reference ADRs by number when a design doc backs the change.
+- **Bug fixes.** Combine small fixes into one bullet, comma-separated.
+
+## Install
+
+`uv tool install stacktrace-cli==<version>` or `pip install stacktrace-cli==<version>`.
+
+## Compatibility
+
+<Behavior changes existing users will notice. Say "pre-alpha, no
+back-compat hedging" while that's still true.>
+```
+
+**Judgment guidelines (apply ruthlessly):**
+
+- **Group by theme, not by commit.** Five commits adding one capability
+  are one bullet.
+- **Lead with user-visible impact**, not implementation.
+- **Cut chore/format/docs-only and release-machinery commits.** They
+  aren't release-visible.
+- **Acknowledge breaking changes explicitly** under `## Compatibility` —
+  a renamed subcommand or changed output shape goes there.
+
+Show the draft to the user and iterate until they agree it captures what
+shipped.
+
+### Step 4. Bump the version, pin workspace dependencies, and gate
+
+`pyproject.toml`'s `version`, `src/stacktrace/__init__.py`'s
+`__version__` and the `--version` console block in `README.md` are three
+separate copies of the version string. The workflow fails the build if the
+first two disagree with the tag. Move them together:
+
+```bash
+sed -i.bak 's/^version = ".*"/version = "<version>"/' pyproject.toml && rm pyproject.toml.bak
+sed -i.bak 's/^__version__ = ".*"/__version__ = "<version>"/' src/stacktrace/__init__.py && rm src/stacktrace/__init__.py.bak
+```
+
+`openaca` and `openaidr` are developed alongside this package and float on
+`>=` during normal development, but a prior release will have left them
+pinned exactly with `==` (see below), which would stop `uv lock` from ever
+resolving a newer release. Loosen both back to a floor first — the
+replacement matches either operator, so this is safe to run whether the tree
+is currently floating or still pinned from last time:
+
+```bash
+sed -i.bak -E 's/^    "openaca(>=|==)[^"]*"/    "openaca>=0"/' pyproject.toml && rm pyproject.toml.bak
+sed -i.bak -E 's/^    "openaidr(>=|==)[^"]*"/    "openaidr>=0"/' pyproject.toml && rm pyproject.toml.bak
+uv lock                                            # refresh uv.lock, now free to pick the newest release
+uv run stacktrace --version                        # sanity: prints <version>
+```
+
+Paste that exact output over the console block under `## Installation` in
+`README.md`. `readme = "README.md"` makes that file the PyPI long description,
+and a description is baked into the artifact at upload — releases being
+immutable, a stale line there is only ever corrected by burning the next
+version number, which is what 0.3.1 was for. The block sat at `0.2.1` through
+three releases before anything checked it;
+`tests/test_readme_examples_are_real_output.py` now fails the build when it
+drifts, so this is a step you are reminded of rather than one you must
+remember.
+
+Now pin both to whatever `uv lock` just resolved — the one point in the
+procedure where the lockfile has just picked the newest available versions
+and a release is actually being cut:
+
+```bash
+openaca_version=$(grep -A1 '^name = "openaca"' uv.lock | grep version | cut -d'"' -f2)
+openaidr_version=$(grep -A1 '^name = "openaidr"' uv.lock | grep version | cut -d'"' -f2)
+sed -i.bak -E "s/^    \"openaca(>=|==)[^\"]*\"/    \"openaca==${openaca_version}\"/" pyproject.toml && rm pyproject.toml.bak
+sed -i.bak -E "s/^    \"openaidr(>=|==)[^\"]*\"/    \"openaidr==${openaidr_version}\"/" pyproject.toml && rm pyproject.toml.bak
+uv lock                                            # refresh uv.lock for the exact pin
+uv run pytest -m release_gate
+```
+
+By marker, not by file: a second `release_gate` test can be added anywhere
+under `tests/` (as `tests/telemetry/test_release_gate.py` was, checking that
+PostHog's project key is set) and this command picks it up without the skill
+needing to name it. The gate is not covered by `.github/workflows/publish-pypi.yml`,
+which runs the default `uv run pytest -q` — and `pyproject.toml`'s `addopts`
+excludes `release_gate` from that default run on purpose (it fails throughout
+normal development, before this step pins the floors and, for the PostHog key,
+before Micheal fills it in). This skill is the only place any `release_gate`
+test runs before a tag is pushed, so skipping it here, or naming only one file
+here, is the one way an unpinned `openaidr`/`openaca` requirement or an unset
+PostHog key reaches PyPI. Stop and ask if it fails.
+
+### Step 5. Release-prep commit + PR
+
+If the user's original request did not explicitly ask to cut, ship, or
+publish a release, stop before the push and ask. Editing the version
+field is enough to invoke this skill; it is not permission to publish.
+
+```bash
+git checkout -b release/<version>
+git add pyproject.toml uv.lock src/stacktrace/__init__.py docs/releases/v<version>.md
+git status --porcelain          # inspect anything still unstaged; stage intentionally or stop
+git commit -m "release: <version> — <theme>"
+git push -u origin release/<version>
+```
+
+Opening the PR needs its own explicit ask. Then:
+
+```bash
+gh pr create --title "release: <version>" --body "Release prep for <version>.
+
+- Bumps \`pyproject.toml\` and \`__version__\` to <version>
+- Adds release notes at \`docs/releases/v<version>.md\`
+- After merge: tag \`v<version>\` on main and push to trigger PyPI publish + GitHub Release"
+```
+
+Surface the PR URL. **Stop here.** The user reviews and merges.
+
+### Step 6. After merge: tag + push
+
+After the user confirms the PR merged, on a clean main:
+
+```bash
+git checkout main
+git pull --ff-only
+git tag v<version>
+git push origin v<version>
+```
+
+The tag-triggered run registers asynchronously, so `--limit 1` can grab a
+stale earlier run. Poll for the run tied to the tagged commit:
+
+```bash
+tag_sha=$(git rev-parse "v<version>^{commit}")
+run_id=""
+until [ -n "$run_id" ]; do
+  run_id=$(gh run list --repo stacktrace-ai/stacktrace \
+    --workflow publish-pypi.yml --commit "$tag_sha" \
+    --json databaseId --jq '.[0].databaseId // empty')
+  [ -z "$run_id" ] && sleep 5
+done
+gh run watch --repo stacktrace-ai/stacktrace "$run_id"
+```
+
+### Step 7. Verify
+
+```bash
+curl -s https://pypi.org/pypi/stacktrace-cli/json | python3 -c 'import json,sys; print(sorted(json.load(sys.stdin)["releases"]))'
+gh release view v<version> --repo stacktrace-ai/stacktrace --json name,body
+uvx --from stacktrace-cli==<version> stacktrace --version    # installs from PyPI, must print <version>
+```
+
+All three must succeed. If any fails, surface the workflow run URL rather
+than guessing.
+
+## Failure modes this prevents
+
+1. **On PyPI but not on GitHub Releases.** The workflow's notes-file gate
+   runs before publish: no notes file at the tag → no PyPI upload.
+2. **Notes file is a raw commit dump.** Step 3's judgment guidelines.
+3. **Tagging a non-main commit.** The workflow's "Verify tag is on main".
+4. **Tag ≠ `pyproject.toml` version, or `__version__` drift.** Two
+   separate workflow steps; Step 4 keeps them moving together.
+5. **Forgetting to refresh `uv.lock`.** `uv sync --frozen` fails in the
+   build job; Step 4 bumps the lock to avoid the round-trip.
+
+## What this skill does NOT do
+
+- **Doesn't publish to PyPI directly.** The workflow does, via Trusted
+  Publishing (OIDC). There is no PyPI token anywhere in this repo, and
+  none should be added.
+- **Doesn't create the GitHub Release directly.** The workflow's
+  `release-github` job does, from the notes file.
+- **Doesn't write a CHANGELOG.md.** The convention is per-release files
+  under `docs/releases/`.
+- **Doesn't yank.** PyPI versions are immutable; a broken release is
+  fixed by shipping the next version, not by re-uploading.

stacktrace_cli-0.11.0/.github/workflows/bedrock-live.yml

@@ -0,0 +1,55 @@
+# Live Bedrock test in the sandbox account. Run by hand from the Actions tab.
+# Credentials come from GitHub's OIDC token, exchanged for a one-hour session
+# on a role that can only call Bedrock and read the invocation-logs bucket
+# (integrations/bedrock/tofu/ci.tf). No AWS key is stored anywhere.
+name: bedrock-live
+
+on:
+  workflow_dispatch:
+    inputs:
+      ref:
+        description: Branch, tag or SHA holding the test to run. Dispatch from main; this is what gets checked out.
+        required: false
+        default: main
+      model:
+        description: Inference profile ID. Empty picks a Claude Sonnet profile.
+        required: false
+        default: ""
+
+permissions:
+  id-token: write
+  contents: read
+
+jobs:
+  live:
+    runs-on: ubuntu-latest
+    # The role trusts only jobs in this environment.
+    environment: bedrock-sandbox
+    timeout-minutes: 30
+    steps:
+      # GitHub dispatches only workflows on the default branch, and only to
+      # other refs after a first run, so the test's ref is an input instead.
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ inputs.ref }}
+      - uses: astral-sh/setup-uv@v6
+      - uses: aws-actions/configure-aws-credentials@v4
+        with:
+          role-to-assume: ${{ vars.BEDROCK_ROLE_ARN }}
+          aws-region: ${{ vars.BEDROCK_REGION || 'us-east-1' }}
+          role-duration-seconds: 3600
+      - run: uv sync
+      - name: Call each Bedrock API, read the logs back, run the rules
+        run: >
+          uv run --with boto3 python integrations/bedrock/live_test.py
+          --bucket "${{ vars.BEDROCK_LOGS_BUCKET }}"
+          --region "${{ vars.BEDROCK_REGION || 'us-east-1' }}"
+          ${{ inputs.model && format('--model {0}', inputs.model) || '' }}
+          --out bedrock-live
+      # Synthetic traffic only: scripted calls and a fake token.
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: bedrock-live
+          path: bedrock-live/
+          retention-days: 3

stacktrace_cli-0.11.0/.github/workflows/guard-staging.yml

@@ -0,0 +1,143 @@
+name: guard-staging
+
+# Build the LiteLLM and Envoy staging images (each with Stacktrace Guard),
+# deploy them to their ECS Express services in the sandbox account, and
+# smoke-test all three: LiteLLM, Envoy, and the subscription service, which
+# runs the LiteLLM image with its subscription config. Manual only.
+# Infrastructure: infra/guard-staging.
+# Credentials come from GitHub OIDC; no AWS key is stored. Variables live on the
+# litellm-staging environment: AWS_DEPLOY_ROLE_ARN, ECR_REPOSITORY_URL,
+# ENVOY_ECR_REPOSITORY_URL, SUBSCRIPTION_ECR_REPOSITORY_URL, ECS_CLUSTER,
+# ECS_SERVICE, ENVOY_SERVICE, SUBSCRIPTION_SERVICE, LOG_GROUP, MASTER_KEY_SECRET,
+# STAGING_ENDPOINT, ENVOY_ENDPOINT, SUBSCRIPTION_ENDPOINT, GUARD_MODE.
+
+on:
+  workflow_dispatch:
+    inputs:
+      ref:
+        description: Branch, tag or commit to deploy
+        required: true
+        default: main
+
+permissions:
+  id-token: write
+  contents: read
+
+concurrency:
+  group: guard-staging
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    environment: litellm-staging
+    timeout-minutes: 45
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ inputs.ref }}
+
+      - uses: aws-actions/configure-aws-credentials@v4
+        with:
+          role-to-assume: ${{ vars.AWS_DEPLOY_ROLE_ARN }}
+          aws-region: us-east-1
+
+      - uses: docker/setup-buildx-action@v3
+
+      - name: Build and push
+        env:
+          REPO: ${{ vars.ECR_REPOSITORY_URL }}
+          ENVOY_REPO: ${{ vars.ENVOY_ECR_REPOSITORY_URL }}
+          SUB_REPO: ${{ vars.SUBSCRIPTION_ECR_REPOSITORY_URL }}
+        run: |
+          aws ecr get-login-password | docker login --username AWS --password-stdin "${REPO%%/*}"
+          sha=$(git rev-parse --short HEAD)
+          # Layers are cached in each image's own ECR repository under the
+          # buildcache tag, so a fresh runner reuses the LiteLLM install. A
+          # missing or unreadable cache only makes the build slower.
+          cache() { echo "--cache-from type=registry,ref=$1:buildcache" \
+            "--cache-to type=registry,ref=$1:buildcache,mode=max,image-manifest=true,oci-mediatypes=true"; }
+          # shellcheck disable=SC2046
+          docker buildx build --push $(cache "$REPO") -f infra/guard-staging/images/litellm/Dockerfile \
+            -t "$REPO:$sha" -t "$REPO:staging" -t "$SUB_REPO:$sha" -t "$SUB_REPO:staging" .
+          # shellcheck disable=SC2046
+          docker buildx build --push $(cache "$ENVOY_REPO") -f infra/guard-staging/images/envoy/Dockerfile \
+            -t "$ENVOY_REPO:$sha" -t "$ENVOY_REPO:staging" .
+
+      - name: Roll all three services onto the new images
+        run: |
+          # Inline, not a script in the checkout: the checkout is the deploy ref,
+          # which may predate any helper. Each update's own deployment id is
+          # kept, and that deployment must be the service's only one, with every
+          # task running and rolloutState COMPLETED (or none, as services-stable
+          # allows). Express Mode rolls a failed canary back to the old revision,
+          # which then looks stable too; ours being gone from the list, or
+          # FAILED, fails the step. aws ecs wait services-stable allows only 10
+          # minutes and the first rollout took 9.5, so this waits up to 25, and
+          # on any failure prints each service's latest ECS events.
+          cluster="${{ vars.ECS_CLUSTER }}"
+          services=("${{ vars.ECS_SERVICE }}" "${{ vars.ENVOY_SERVICE }}" "${{ vars.SUBSCRIPTION_SERVICE }}")
+          declare -A ours
+          for s in "${services[@]}"; do
+            ours[$s]=$(aws ecs update-service --cluster "$cluster" --service "$s" \
+              --force-new-deployment --output text \
+              --query "service.deployments[?status=='PRIMARY'] | [0].id")
+            if [ -z "${ours[$s]}" ] || [ "${ours[$s]}" = None ]; then
+              # Without it a rollback to the old revision would pass as stable.
+              echo "::error::$s: update-service named no PRIMARY deployment, so a rollback can't be told apart"
+              exit 1
+            fi
+            echo "$s: deployment ${ours[$s]}"
+          done
+          events() {
+            for s in "${services[@]}"; do
+              echo "--- $s: latest events"
+              aws ecs describe-services --cluster "$cluster" --services "$s" \
+                --query 'services[0].events[:10].[createdAt,message]' --output text
+            done
+          }
+          deadline=$(( $(date +%s) + 1500 ))
+          while :; do
+            pending=0
+            for s in "${services[@]}"; do
+              read -r deployments primary state running desired <<< "$(aws ecs describe-services \
+                --cluster "$cluster" --services "$s" --output text \
+                --query 'services[0].[length(deployments), deployments[0].id, deployments[0].rolloutState, runningCount, desiredCount]')"
+              if [ "$primary" != "${ours[$s]}" ]; then
+                echo "::error::$s: our deployment ${ours[$s]} is gone; $primary is primary (rolled back)"
+                events; exit 1
+              fi
+              if [ "$state" = FAILED ]; then
+                echo "::error::$s: rollout FAILED"; events; exit 1
+              fi
+              if [ "$deployments" = 1 ] && [ "$running" = "$desired" ] \
+                && { [ "$state" = COMPLETED ] || [ "$state" = None ]; }; then
+                continue
+              fi
+              pending=1
+              echo "wait  $s: $deployments deployment(s), $state, $running/$desired running"
+            done
+            [ "$pending" = 0 ] && { echo "all stable on this run's deployments"; break; }
+            if [ "$(date +%s)" -ge "$deadline" ]; then
+              echo "::error::not stable after 25 minutes"; events; exit 1
+            fi
+            sleep 20
+          done
+
+      - name: Smoke test all three
+        env:
+          MODE: ${{ vars.GUARD_MODE }}
+          LOG_GROUP: ${{ vars.LOG_GROUP }}
+        run: |
+          MASTER_KEY=$(aws secretsmanager get-secret-value --secret-id "${{ vars.MASTER_KEY_SECRET }}" \
+            --query SecretString --output text)
+          echo "::add-mask::$MASTER_KEY"
+          fail=0
+          for endpoint in "${{ vars.STAGING_ENDPOINT }}" "${{ vars.ENVOY_ENDPOINT }}"; do
+            echo "== $endpoint"
+            ENDPOINT="$endpoint" MASTER_KEY="$MASTER_KEY" infra/guard-staging/smoke.sh || fail=1
+          done
+          echo "== ${{ vars.SUBSCRIPTION_ENDPOINT }} (subscription)"
+          ENDPOINT="${{ vars.SUBSCRIPTION_ENDPOINT }}" MASTER_KEY="$MASTER_KEY" SUBSCRIPTION=1 \
+            infra/guard-staging/smoke.sh || fail=1
+          exit $fail

stacktrace_cli-0.11.0/.github/workflows/publish-pypi.yml

@@ -0,0 +1,178 @@
+name: Publish PyPI
+
+# Publishes the `stacktrace-cli` distribution to PyPI from version Git tags.
+#
+# One-time PyPI setup (done once, by a human, before the first tag):
+# 1. On https://pypi.org/manage/account/publishing/, add a *pending*
+#    Trusted Publisher (pending, because the project does not exist on
+#    PyPI until the first successful upload):
+#      - PyPI Project Name: stacktrace-cli
+#      - Owner: stacktrace-ai
+#      - Repository name: stacktrace
+#      - Workflow name: publish-pypi.yml
+#      - Environment name: pypi
+# 2. Create the `pypi` environment on this repo (the name must match the
+#    publisher config exactly, or the OIDC exchange is rejected).
+# 3. Publish by pushing a tag whose name matches pyproject.toml's version,
+#    e.g. `git tag v0.0.1 && git push origin v0.0.1`.
+#
+# No PyPI token is needed, and none should be added. `pypa/gh-action-pypi-publish`
+# exchanges the GitHub OIDC token for a short-lived, scope-limited PyPI publish
+# token — nothing long-lived sits in repo secrets waiting to leak.
+#
+# Workflow-injection safety: no step consumes user/PR-controlled input.
+# GITHUB_REF_NAME is GitHub-injected (the tag name) and can only contain
+# git-ref-safe characters.
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Verify tag is on main
+        run: |
+          git fetch --no-tags origin +refs/heads/main:refs/remotes/origin/main
+          if ! git merge-base --is-ancestor HEAD refs/remotes/origin/main; then
+            echo "::error::Tagged commit $(git rev-parse --short HEAD) is not reachable from origin/main. Release tags must be cut from main."
+            exit 1
+          fi
+
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+          # Match pyproject.toml `requires-python` and ci.yml.
+          python-version: "3.11"
+
+      - name: Sync deps
+        run: uv sync --frozen
+
+      - name: Verify tag matches package version
+        run: |
+          package_version="$(uv run python -c 'import tomllib; print(tomllib.load(open("pyproject.toml", "rb"))["project"]["version"])')"
+          tag_version="${GITHUB_REF_NAME#v}"
+          if [ "$package_version" != "$tag_version" ]; then
+            echo "::error::tag $GITHUB_REF_NAME does not match pyproject.toml version $package_version"
+            exit 1
+          fi
+
+      - name: Verify __version__ matches package version
+        # `--version` output comes from src/stacktrace/__init__.py, not
+        # pyproject.toml. If the two drift, PyPI ships a wheel whose CLI
+        # reports a version that doesn't exist — and PyPI versions are
+        # immutable, so the only fix is burning another version number.
+        run: |
+          dunder_version="$(uv run python -c 'import stacktrace; print(stacktrace.__version__)')"
+          tag_version="${GITHUB_REF_NAME#v}"
+          if [ "$dunder_version" != "$tag_version" ]; then
+            echo "::error::stacktrace.__version__ is $dunder_version but the tag is $GITHUB_REF_NAME. Bump both together."
+            exit 1
+          fi
+
+      - name: Verify release notes file exists
+        # Fail BEFORE PyPI publish if no notes file is committed. PyPI
+        # publishes are immutable — a missing notes file caught after
+        # publish would mean shipping to PyPI while leaving the GitHub
+        # Releases page silently inconsistent. The release-stacktrace
+        # skill writes this file during the release prep PR.
+        run: |
+          notes_path="docs/releases/${GITHUB_REF_NAME}.md"
+          if [ ! -f "$notes_path" ]; then
+            echo "::error::missing release notes file at $notes_path. The release-stacktrace skill drafts this file from the commit log; run it before tagging."
+            exit 1
+          fi
+
+      - name: Ruff check
+        run: uv run ruff check .
+
+      - name: Ruff format check
+        run: uv run ruff format --check .
+
+      - name: Pyright
+        run: uv run pyright
+
+      - name: Pytest
+        run: uv run pytest -q
+
+      - name: Build package
+        run: uv build
+
+      - name: Check package metadata
+        # twine >=7 required: hatchling emits `Metadata-Version: 2.5` (PEP 794),
+        # and twine 6.2.0 and earlier hard-cap recognized metadata versions at
+        # 2.4, so they reject a perfectly valid wheel. Unpinned `uvx twine` can
+        # resolve an older cached twine from the uv cache this workflow warms.
+        run: uvx --from 'twine>=7' twine check dist/*
+
+      - name: Upload package artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package
+          path: dist/*
+          retention-days: 7
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/stacktrace-cli/
+    permissions:
+      contents: read
+      id-token: write  # required for Trusted Publishing (OIDC)
+    steps:
+      - name: Download package artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package
+          path: dist
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  release-github:
+    # Create the GitHub Release object so the Releases page reflects what
+    # actually shipped. Runs only after PyPI publish succeeds — if PyPI
+    # failed there's no reason to advertise the release on GitHub. The
+    # notes file's presence was verified in the build job, so the only
+    # failure modes here are gh/API errors.
+    needs: publish
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write  # gh release create writes the release
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ github.ref }}
+          fetch-depth: 1
+
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          TAG: ${{ github.ref_name }}
+        run: |
+          notes_path="docs/releases/${TAG}.md"
+          # The first H1 line in the notes file becomes the Release title.
+          title="$(grep -m1 '^# ' "$notes_path" | sed 's/^# //' || true)"
+          if [ -z "$title" ]; then
+            title="$TAG"
+          fi
+          # Mark PEP 440 pre-releases (aN/bN/rcN suffix) as GitHub prereleases.
+          # `gh release create` defaults to "latest stable" otherwise.
+          prerelease_flag=""
+          if [[ "$TAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+(a|b|rc)[0-9]+$ ]]; then
+            prerelease_flag="--prerelease"
+          fi
+          gh release create "$TAG" \
+            --title "$title" \
+            --notes-file "$notes_path" \
+            --verify-tag \
+            $prerelease_flag

stacktrace_cli-0.11.0/.gitignore

@@ -0,0 +1,15 @@
+dist/
+build/
+*.egg-info/
+__pycache__/
+.venv/
+
+# Local git worktrees
+.worktrees/
+
+# Local research handoffs, kept on disk and out of the repo.
+HANDOFF-*.md
+
+# Observation adapter workspace
+node_modules/
+*.tgz