Cline rules

1---
2description: Overview of mtg-utils project architecture, directory structure, and technology stack
3author: Simone Gasbarroni
4version: 1.0
5tags: ["project-overview", "architecture", "python"]
6---
7 
8# mtg-utils Project Overview
9 
10## Objective
11 
12mtg-utils is a command-line utility designed for managing Magic: The Gathering card collections, decks, and performing various analyses. It helps users track their card collections from Moxfield, manage multiple decks, check missing cards, and monitor newly purchased cards.
13 
14---
15 
16## Technology Stack
17 
18| Component | Technology |
19|-----------|-----------|
20| Python Version | >=3.13 |
21| Package Manager | Poetry |
22| CLI Framework | Click |
23| HTTP Requests | Requests + Cloudscraper |
24| Data Validation | Pydantic |
25| Console Output | Rich |
26| Testing | pytest + pytest-cov |
27| Linting | Ruff + Pyright |
28 
29---
30 
31## Directory Structure
32 
33```
34mtg-utils/
35├── mtg_utils/               # Main package
36│   ├── __init__.py
37│   ├── main.py             # CLI entry point with Click
38│   ├── commands/           # CLI command modules
39│   │   ├── __init__.py
40│   │   ├── compare_decks.py
41│   │   ├── list_decks.py
42│   │   └── check_missing_cards/
43│   │   │   ├── __init__.py
44│   │   │   ├── command.py  # CLI command wrapper
45│   │   │   ├── logic.py    # Business logic
46│   │   │   └── render.py   # Console output
47│   │   └── update_card_library/
48│   │       ├── __init__.py
49│   │       ├── command.py
50│   │       ├── logic.py
51│   │       └── render.py
52│   └── utils/              # Shared utilities
53│       ├── __init__.py
54│       ├── cards.py        # Card data models and processing
55│       ├── config.py       # Configuration loading
56│       ├── console.py      # Rich console setup
57│       ├── moxfield_api.py # Moxfield API integration
58│       ├── panels.py       # Console panel rendering
59│       └── readers.py      # File reading utilities
60├── tests/                  # Test suite
61├── card_library/           # Data directory (generated at runtime)
62│   ├── owned_cards.txt
63│   ├── available_cards.txt
64│   ├── purchased.txt
65│   ├── purchased_formatted.txt
66│   └── decks/
67├── config.json             # User configuration
68├── pyproject.toml          # Poetry configuration
69├── .clinerules/            # AI assistant rules
70└── README.md
71```
72 
73---
74 
75## CLI Commands
76 
77| Command | Description |
78|---------|-------------|
79| `mtg-utils update-library` | Update card collection and decks from Moxfield |
80| `mtg-utils check-missing-cards` | Check missing cards for a deck |
81| `mtg-utils compare-decks` | Compare two decks for card differences |
82| `mtg-utils list-decks` | List configured decks |
83 
84---
85 
86## Core Concepts
87 
88### Card Library
89 
90The `card_library/` directory stores all card data:
91 
92- `owned_cards.txt` - Your complete Moxfield collection
93- `available_cards.txt` - Cards available (owned + purchased - used)
94- `purchased.txt` - Recently purchased cards
95- `decks/` - Individual decklist files
96 
97### Configuration
98 
99Users configure the tool via `config.json`:
100 
101```json
102{
103  "binder_id": "your-moxfield-binder-id",
104  "decks": {
105    "deck1": {
106      "file": "card_library/decks/deck1.txt",
107      "id": "moxfield-deck-id-1"
108    }
109  },
110  "purchased_file": "card_library/purchased.txt"
111}
112```
113 
114---
115 
116## Development Setup
117 
118### Prerequisites
119 
120- Python 3.13+
121- Poetry (recommended) or virtualenv
122 
123### Installation (Poetry)
124 
125```bash
126git clone https://github.com/yourusername/mtg-utils.git
127cd mtg-utils
128poetry install
129poetry shell
130```
131 
132### Running Tests
133 
134```bash
135poetry run pytest
136```
137 
138### Linting
139 
140```bash
141poetry run ruff check .
142poetry run pyright
143 
144```