feat: add PyPI publish workflow (beta + stable via OIDC)

[tommed]

Summary

• Adds .github/workflows/publish.yml — a four-job publish pipeline triggered on release: [published] events
• Validates that the GitHub release tag matches pyproject.toml version, and that the pre-release flag is consistent with the version string (e.g. b/a/rc suffix)
• Re-runs the full CI suite (lint, type check, tests, notebooks, coverage ≥80%) against the exact tagged SHA before building
• Builds .whl + .tar.gz via poetry build, uploads as a workflow artefact
• Publishes to TestPyPI automatically (no gate), then to PyPI behind a human-approval environment gate
• Authentication uses PyPI Trusted Publishers (OIDC) — no API tokens stored in GitHub Secrets
• Adds bump, build, and publish-check Makefile targets for the local release workflow

One-time setup required before first publish

1. PyPI Trusted Publisher — on both pypi.org and test.pypi.org: Owner=phasenexa, Repo=nexa-bidkit, Workflow=publish.yml, Environment=pypi / testpypi
2. GitHub Environments — create testpypi (no rules) and pypi (required reviewer: yourself) in Repo Settings → Environments

Release developer workflow

# Beta
make bump version=1.0.0b1
git add pyproject.toml && git commit -m "chore: bump version to 1.0.0b1"
git push
# Create GitHub pre-release tagged v1.0.0b1

# Stable
make bump version=1.0.0
git add pyproject.toml && git commit -m "chore: bump version to 1.0.0"
git push
# Create GitHub stable release tagged v1.0.0

Pipeline: validate → ci → build → publish-testpypi → [approval] → publish-pypi

Test plan

• Merge and create a GitHub pre-release tagged v{current-version}b1 to exercise the full pipeline end-to-end
• Verify test.pypi.org/project/nexa-bidkit shows the new version
• Approve the pypi environment gate and verify pypi.org/project/nexa-bidkit
• Confirm pip install nexa-bidkit==X.Y.Zb1 requires --pre; stable install works without it
• Test make publish-check tag=vX.Y.Z catches a mismatched tag locally

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!