Copilot instructions

1# mtg-utils – Copilot Instructions
2 
3Python CLI tool (Click + Poetry, Python ≥ 3.13) for managing Magic: The Gathering card collections and decks, backed by the Moxfield API.
4 
5## Build & Test
6 
7```sh
8poetry install          # install dependencies
9poetry run mtg-utils    # run the CLI
10make test               # fast test run (no coverage) — for inner-loop dev
11make coverage           # full test run with coverage enforcement + HTML report
12make ci                 # lint + coverage — mirrors what GitHub Actions runs
13make lint               # ruff check only
14```
15 
16Tests pass on a clean checkout. Always run `make coverage` (or `poetry run pytest`) after changes to confirm 100% coverage is maintained. CI runs on every push/PR via `.github/workflows/ci.yml`.
17 
18## Architecture
19 
20```
21mtg_utils/
22  main.py                        # Click group; registers all commands
23  commands/
24    check_missing_cards.py       # check-missing-cards command
25    compare_decks.py             # compare-decks command
26    update_card_library.py       # update-library command
27  utils/
28    config.py                    # load_config(), DEFAULT_CONFIG_FILE
29    readers.py                   # read_list() – strips blank lines
30    moxfield_api.py              # get_deck_list(), get_library() via cloudscraper
31```
32 
33All external HTTP goes through `moxfield_api.py`. Mock it in tests with `unittest.mock.patch`.
34 
35## Key Conventions
36 
37- **Card format** (everywhere): `{quantity} {card name}` per line, e.g. `2 Lightning Bolt`.
38- **Config** (`config.json`): defines `binder_id`, `purchased_file`, and `decks` map with `id` and `file` per deck. Optional `shared_decks` list per deck re-uses cards from sibling decks without double-counting from the library pool.
39- **Data files** live under `card_library/` and `decklists/`; sorting order is preserved by `library_sort_key` (snow lands last, then alphabetical).
40- **CWD matters**: commands resolve paths relative to the process CWD. Tests use `monkeypatch.chdir(tmp_path)` to isolate file I/O.
41 
42## Testing Patterns
43 
44- Use `click.testing.CliRunner` for end-to-end CLI tests.
45- Use `tmp_path` for all file I/O; never write to real `card_library/` in tests.
46- Use the `repo` fixture from `tests/conftest.py` (chdir + `make_config` helper) for new CLI/filesystem tests.
47- Test files follow `tests/test_<module>.py` naming.
48- Mock network calls: `patch("mtg_utils.commands.<cmd>.get_deck_list", ...)`.
49- Mark tests: `@pytest.mark.unit` (pure logic) or `@pytest.mark.integration` (CLI + filesystem). Run a subset with `pytest -m unit` or `pytest -m integration`.
50 
51## Agents & Skills
52 
53| Name | Purpose |
54|---|---|
55| [Product Designer](.github/agents/product-designer.agent.md) | Feature design, user stories, acceptance criteria, CLI UX specs |
56| [Software Engineer](.github/agents/software-engineer.agent.md) | Collection data, deck files, config, command implementation |
57| [QA Engineer](.github/agents/qa-engineer.agent.md) | Write and run pytest tests only |
58| [Facilitator](.github/agents/facilitator.agent.md) | End-to-end tasks spanning both implementation and tests |
59| [CI Engineer](.github/agents/ci-engineer.agent.md) | GitHub Actions workflows, Makefile CI targets |
60 
61For feature work or bug fixes that need tests, prefer the **Facilitator** agent.
62