stacktrace-cli 0.3.0__tar.gz → 0.3.1__tar.gz

{stacktrace_cli-0.3.0 → stacktrace_cli-0.3.1}/.agents/skills/release-stacktrace/SKILL.md

@@ -102,9 +102,10 @@ shipped.
 
 ### Step 4. Bump the version, pin workspace dependencies, and gate
 
-`pyproject.toml`'s `version` and `src/stacktrace_cli/__init__.py`'s
-`__version__` are separate sources; the workflow fails the build if they
-disagree with the tag. Move them together:
+`pyproject.toml`'s `version`, `src/stacktrace_cli/__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
@@ -125,6 +126,16 @@ uv lock                                            # refresh uv.lock, now free t
 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:

stacktrace_cli-0.3.1/.claude/skills/release-stacktrace/SKILL.md

@@ -0,0 +1 @@
+../../../.agents/skills/release-stacktrace/SKILL.md

{stacktrace_cli-0.3.0 → stacktrace_cli-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: stacktrace-cli
-Version: 0.3.0
+Version: 0.3.1
 Summary: CLI for Stacktrace — Detection and Response platform for AI Agents.
 Project-URL: Homepage, https://stacktrace.ai
 Author-email: "Stacktrace AI, Inc" <founders@stacktrace.ai>
@@ -49,7 +49,7 @@ Requires Python 3.11 or newer.
 
 ```console
 $ stacktrace --version
-stacktrace 0.2.1 (openaca 0.6.0)
+stacktrace 0.3.1 (openaca 0.6.0)
 ```
 
 ## Quick start

{stacktrace_cli-0.3.0 → stacktrace_cli-0.3.1}/README.md

@@ -24,7 +24,7 @@ Requires Python 3.11 or newer.
 
 ```console
 $ stacktrace --version
-stacktrace 0.2.1 (openaca 0.6.0)
+stacktrace 0.3.1 (openaca 0.6.0)
 ```
 
 ## Quick start

stacktrace_cli-0.3.1/docs/releases/v0.3.1.md

@@ -0,0 +1,38 @@
+# 0.3.1 — the README says what the CLI says
+
+A documentation fix, and the test that keeps it fixed. Nothing in the pipeline
+moved; `0.3.1` behaves exactly as `0.3.0` does.
+
+The `stacktrace --version` block in `README.md` read `stacktrace 0.2.1` while
+the wheel beside it was `0.3.0`. Because `readme = "README.md"` makes that file
+the PyPI long description, the project page for 0.2.2, 0.2.3 and 0.3.0 each
+opened with a console block contradicting the release it described.
+
+## Highlights
+
+- **The README's version example is now asserted against the CLI.** The block
+  is produced by invoking `--version` and must appear in `README.md` verbatim,
+  so the line cannot drift from the build again — it joins the sessions example,
+  which has been checked this way for some time. The flag is invoked rather than
+  its text rebuilt from `__version__`, which also puts the `openaca` half of the
+  line under the same check.
+
+- **The guard runs in the gate that publishes.** It sits in
+  `tests/test_readme_examples_are_real_output.py` rather than in
+  `test_release_readiness.py`, whose `release_gate` marker is deselected by
+  `addopts` — a check placed there would not be collected by the `pytest` step
+  the publish workflow runs.
+
+## Install
+
+`uv tool install stacktrace-cli==0.3.1` or `pip install stacktrace-cli==0.3.1`.
+
+## Compatibility
+
+No behaviour changes. The 0.3.0 rename of `--escalate` to `--reasoning` is the
+last one that needed anything of you; see `docs/releases/v0.3.0.md` if you are
+coming from 0.2.3.
+
+The 0.3.0 project page on PyPI still shows the stale `0.2.1` line. A PyPI
+description is baked into the artifact at upload and releases are immutable, so
+that page cannot be corrected in place — this release is the correction.

{stacktrace_cli-0.3.0 → stacktrace_cli-0.3.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "stacktrace-cli"
-version = "0.3.0"
+version = "0.3.1"
 description = "CLI for Stacktrace — Detection and Response platform for AI Agents."
 readme = "README.md"
 requires-python = ">=3.11"

{stacktrace_cli-0.3.0 → stacktrace_cli-0.3.1}/src/stacktrace_cli/__init__.py

@@ -1,3 +1,3 @@
 """The `stacktrace` command-line interface — detection and response for AI agents."""
 
-__version__ = "0.3.0"
+__version__ = "0.3.1"

{stacktrace_cli-0.3.0 → stacktrace_cli-0.3.1}/tests/test_readme_examples_are_real_output.py

@@ -27,7 +27,9 @@ from datetime import UTC, datetime
 from pathlib import Path
 
 import detector_session_fixture as fx
+from click.testing import CliRunner
 
+from stacktrace_cli.cli import main
 from stacktrace_cli.sessions.access import SessionView
 from stacktrace_cli.sessions.render import render_text as render_sessions_text
 
@@ -67,3 +69,31 @@ def test_the_sessions_example_is_what_the_sessions_renderer_prints() -> None:
     )
     rendered = render_sessions_text(SessionView(sessions=(session,)), include_content=True)
     assert rendered.strip() in _readme()
+
+
+def test_the_version_example_is_what_the_version_flag_prints() -> None:
+    """The README's `--version` block is a third copy of the version string.
+
+    `pyproject.toml` and `__version__` are kept together by two steps of the
+    publish workflow, which fail the build when either disagrees with the tag.
+    Nothing watched this block, so it sat at `0.2.1` while 0.2.2, 0.2.3 and
+    0.3.0 shipped past it — and because `readme = "README.md"` makes this file
+    the PyPI long description, every one of those releases published a landing
+    page whose first console block contradicted the wheel beside it. A PyPI
+    description is baked into the artifact at upload and releases are
+    immutable, so a stale line there cannot be edited afterwards; it is only
+    ever corrected by burning the next version number.
+
+    Asserted by invoking the flag rather than by rebuilding its text from
+    `__version__`, so the openaca half is covered too: a reassembled string
+    would restate the f-string in `cli.py` and certify itself.
+
+    This lives here and not in `test_release_readiness.py` because that module
+    is marked `release_gate`, and `addopts` deselects the marker — the
+    `uv run pytest -q` step that guards the publish would never collect it.
+    """
+    printed = CliRunner().invoke(main, ["--version"], prog_name="stacktrace").output
+    assert printed.strip() in _readme(), (
+        f"README.md does not contain the line `stacktrace --version` prints "
+        f"({printed.strip()!r}); the console block under ## Installation has drifted"
+    )

{stacktrace_cli-0.3.0 → stacktrace_cli-0.3.1}/uv.lock

@@ -690,7 +690,7 @@ wheels = [
 
 [[package]]
 name = "stacktrace-cli"
-version = "0.3.0"
+version = "0.3.1"
 source = { editable = "." }
 dependencies = [
     { name = "click" },

stacktrace_cli-0.3.0/.claude/skills/release-stacktrace/SKILL.md

@@ -1,194 +0,0 @@
----
-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)"
-```
-
-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 both version strings together
-
-`pyproject.toml`'s `version` and `src/stacktrace_cli/__init__.py`'s
-`__version__` are separate sources; the workflow fails the build if they
-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_cli/__init__.py && rm src/stacktrace_cli/__init__.py.bak
-uv lock                                            # refresh uv.lock
-uv run stacktrace --version                        # sanity: prints <version>
-```
-
-### 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_cli/__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.