passkey-mcp AGENTS.md

passkey-mcp — Agent Notes

Read this before touching anything. It documents verified reality, not aspirations. The roadmap is PLAN.md; current version is 0.3.0 (pre-1.0 — the old 1.x labels were re-baselined, see CHANGELOG.md).

Environment

• Python: 3.10+ floor; dev machine runs 3.14 (uv manages it)
• Package manager: uv — never pip. uv sync creates .venv/
• CLI install: pipx install --force -e . — required after any change you want to exercise through the real passkey command
• One-off validation without reinstall: uv run passkey <args> or uv run python -c "from passkey.cli import main; ..."

Testing — the truth (verified 2026-07-28)

The suite does NOT pass as-committed. Do not trust any doc that says it does. There is no CI. Three independent problems:

1. tests/test_cli.py hangs forever. Tests call real main() → _require_auth() → real sudo -v. Without a cached sudo timestamp it blocks on an interactive prompt. Nothing mocks the auth layer. (It "passes" on the maintainer's Mac only because pam_tid.so was hand-added to /etc/pam.d/sudo and Touch ID silently approves.)
2. tests/test_bundle.py takes ~2 minutes. Production scrypt is N=2^20 ≈ 5s/derivation on this machine, and the file does 20+ derivations.
3. Tests pollute real user state. Keyring is mocked but audit.py and the metadata lock are not — test runs write fake rows into the real ~/Library/Application Support/passkey/audit.log (entries named test, found, existing are test fixtures, not your activity).

Also: pytest-timeout is NOT installed — uv run pytest --timeout=120 errors out, despite what old docs say. ruff is NOT in the synced venv (declared under [project.optional-dependencies] dev, which uv sync ignores in favor of [dependency-groups] dev). Use uvx ruff check instead.

How to actually validate changes today

# Fast subset — everything EXCEPT cli/bundle hangs-and-slowdowns (~0.5s, 250 tests)
uv run pytest --ignore=tests/test_cli.py --ignore=tests/test_bundle.py -q

# CLI tests: only with auth mocked or sudo cached; run per-file with care
uv run pytest tests/test_cli.py -q        # HANGS without Touch ID/sudo cache

# Bundle tests: green but ~2 min
uv run pytest tests/test_bundle.py -q

# Lint (ruff is not in the venv)
uvx ruff check passkey/ tests/