chore: adopt the portfolio Python project standard

[pofallon]

Applies the get2knowio Python Project Standard — toolchain, gates, and release shape — to Hangar, along with the build-surface and hatch-vcs standards it depends on.

Reviewing tip: 68 of the 85 changed files are a one-time ruff format pass. git diff -w or reviewing everything except backend/src/** and backend/tests/** gets you the substance.

Verified

All four gates green on both matrix legs — 310 tests, format/lint/types clean, coverage floor met on 3.12 and 3.14. The image builds and reports a tag-derived version with no git history in the runtime layer.

What changed

Toolchain & packaging — hatch-vcs versioning, dev tooling moved to PEP 735 [dependency-groups], [tool.uv] exclude-newer, requires-python bounded at >=3.12,<3.15.

Build surface — new root mise.toml with the seven canonical verbs (mise tasks, no justfile). CI now runs mise run setup / mise run check and spells out no gate inline. ruff format --check is gated for the first time; ruff moves to the standard explicit select list and stops ignoring E501.

CI — exercises both ends of requires-python. The version-free Backend job stays the required status check and gates on the matrix, so an interpreter bump never invalidates branch protection.

Supply chain & release — permissions: + concurrency: on 5/5 workflows (was 1/5); Dependabot groups production minor/patch too; release.yml gains a test gate and a GitHub Release with generated notes.

Bugs found while applying it

• Version drift: pyproject.toml said 0.3.11, src/hangar/__init__.py said 0.1.0. Exactly the class hatch-vcs closes.
• The matrix could have lied. uv sync silently reuses an existing .venv regardless of the mise pin — my first "3.12" run was actually 3.14. backend:setup now binds --python to the resolved interpreter.
• Node pinned twice, differently: devcontainer said 22; CI, mise and the Dockerfile said 26.
• Pre-release detection was broken: the old contains(ref_name, '-') test would have published v1.0.0rc1 as :latest. Now matches both PEP 440 canonical and dashed forms.
• A lint autofix broke typing: ruff's C416 rewrite of a SQLAlchemy row comprehension to dict() dropped row typing; .tuples() satisfies both gates.

Decisions worth a second opinion

Coverage floor is 89, and the 3.12/3.14 gap turned out to be a measurement bug (fixed in a145d2f). The suite originally reported 87% on 3.14 but 80% on 3.12. That was not a behavioural difference:

1. branch = true was set in the coverage config.
2. coverage's sysmon core doesn't support branch coverage before Python 3.14, so 3.12 silently fell back to the older sys.settrace core.
3. sys.settrace can't see code running in the worker thread Starlette's TestClient drives the app from — so every FastAPI BackgroundTasks job was invisible to it.

services/sync.py is reached almost entirely through a BackgroundTask (the resync queued by PUT /providers/{id}/repos), which is why the gap concentrated there.

Verified rather than inferred: on a single interpreter (3.14) the core alone moves sync.py between 32% (ctrace), 32% (pytrace) and 46% (sysmon); and a probe wrapping SyncService.sync_connection shows it starting and completing identically on both interpreters. The code always ran — only the measurement differed.

Fixed by turning branch coverage off (so sysmon is usable on 3.12) and pinning COVERAGE_CORE=sysmon from mise.toml. Both legs now report an identical 89.90% and the same 338 uncovered statements. The floor is 89 — the earlier 80 was never a real measurement of this suite, just what the blinded core produced.

Tradeoff worth a look: this gives up branch coverage to get one trustworthy number on every leg. The alternative is keeping branch coverage and enforcing the floor only on the 3.14 leg. Happy to switch if you'd rather keep branch data.

Two claims in the standard don't match the repo. Starship is installed (modern-cli-tools with {} installs everything by default). And Hangar isn't in the hatch-vcs rollout list, though the rule table does cover it — I applied it because the drift was live.

Not done

• devcontainer-lock.json — needs the devcontainer CLI, which isn't available in the container; the file is resolved digests I won't fabricate. Run devcontainer upgrade --workspace-folder ..
• Prettier gate — reports 19 unformatted frontend files including the generated api-types.ts. Needs a .prettierignore first, and it's outside a Python standard.
• frontend/package.json still carries a hand-bumped 0.3.11, now inconsistent with the backend's derived version.

The devcontainer changes (base image → ubuntu-24.04, mise feature, Node 26, MISE_TRUSTED_CONFIG_PATHS) need a container rebuild to take effect.

🤖 Generated with Claude Code

https://claude.ai/code/session_01VLmETZdERJ6RFCdwZRdv4a