Modernize tooling: uv, ruff, ty, Python 3.13+ and full typing

[Korijn]

Brings the project setup in line with fork-tongue/observ, drops support for everything below Python 3.13, and fully annotates the package.

Packaging

• requires-python = ">=3.13", and tomli is gone in favour of stdlib tomllib.
• Unpinned the remaining dependencies: keyring~=24.3.0 → >=25.6, shellingham~=1.5.4 → >=1.5.4.
• flit → hatchling, and [project.optional-dependencies] dev → PEP 735 [dependency-groups] split into dev/ruff/ty so each CI job installs only what it needs.
• __version__ now comes from importlib.metadata, so the version is declared once in pyproject.toml instead of being kept in sync by hand.
• SPDX license = "MIT" + license-files.

Typing

Every function, parameter and module-level variable in keycmd is annotated, and the package ships a py.typed marker so consumers get the types.

Typing the config surface meant describing its shape, so [keys] and [aliases] are now TypedDicts (KeyConf, AliasConf, Conf) with NotRequired for the optional b64/format fields — the schema the README documents, expressed in code. load_conf casts at the boundary where user-authored TOML enters the program, which is where the promise is actually made; get_env still reports violations as user errors at runtime. find_file got @overloads, since its return type genuinely depends on first_only.

Enforcement, so this does not decay:

• ruff's ANN rules require annotations (the test suite is exempt).
• ty's off-by-default rules are on: missing-type-argument, possibly-missing-attribute, possibly-missing-import, possibly-unresolved-reference, division-by-zero. Suppressions must name a rule and must be needed (blanket-ignore-comment, unused-ignore-comment).
• CI and pre-commit run ty check --error-on-warning, so warn-level diagnostics fail rather than scroll by.

Two bugs fell out of making the types honest

• shell.exec passed env=None straight to os.execvpe, which requires a mapping and would have raised TypeError. Reachable via run_shell()/run_cmd() with no env on POSIX; the tests never hit it because they force the subprocess branch. It now falls back to os.environ, matching what the subprocess branch already did.
• creds.get_env bound both the loop variable and the looked-up key data to the name key, giving one name two types. Split into key/data and src/alias_src.

Linting

Ruff's selection now matches observ's — adds isort (I), T10, T20 and ANN, keeps B. The old ignore list (E501, E731, B019, RUF012) is gone; nothing in the codebase needed it.

Added .pre-commit-config.yaml running format, lint, typecheck and tests.

CI

Restructured from four ad-hoc jobs into lint / typecheck / test / build / publish, all uv-driven with caching:

• actions/checkout@v4 → @v7, upload-artifact@v4 → @v7, download-artifact@v4 → @v8; setup-python replaced by astral-sh/setup-uv. Third-party actions pinned by commit SHA.
• Build is now uv build + uvx twine check instead of the hand-rolled sdist-install-and-git reset --hard dance.
• The concurrency group no longer cancels tag runs mid-publish.
• Test matrix is Python 3.13 + 3.14. It stays on Windows because the suite exercises a real OS keyring, which is what the matrix was already doing and why.

Verification

• ruff check, ruff format --check and ty check --error-on-warning are all clean.
• sdist and wheel build and pass twine check; py.typed is present in both. The sdist installs into a clean 3.13 venv with a working keycmd --version.
• Tests: 16/17. test_shell.py::test_run_cmd fails only when run on Linux, because it asserts cmd.exe's exit code 1 for an unknown command while bash returns 127. Pre-existing and platform-specific, so it is green on the Windows runners.
• Checked the new enforcement actually bites rather than trusting a green run: an unannotated probe function draws 2 ANN errors, and a probe consumer confirms the types catch real misuse (assigning find_file(..., first_only=False) to a str, a keys entry missing credential, a non-str env value), while valid load_conf() → get_env() stays clean.

Notes

• PyPI publishing is unchanged — still secrets.PYPI_PASSWORD. observ uses trusted publishing (OIDC), which is better, but switching requires configuring a publisher on PyPI first, and doing it here would break the next release. Happy to switch once that exists.
• uv.lock is gitignored, matching observ — appropriate for a library.
• ty checks keycmd only and the tests are exempt from ANN, so "fully typed" means the package, not the test suite.

---

Generated by Claude Code