Add project files: decks, scripts, and collection data
This commit is contained in:
Tuan-Dat Tran
435
docs/plans/2026-02-19-auto-docs.md
Normal file
435
docs/plans/2026-02-19-auto-docs.md
Normal file
@@ -0,0 +1,435 @@
|
||||
# Auto-updating Documentation Implementation Plan
|
||||
|
||||
> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
|
||||
|
||||
**Goal:** Create README.md and AGENTS.md that auto-update via git pre-commit hook when files change.
|
||||
|
||||
**Architecture:** Template files with placeholders + Python generator script that reads deck/collection data + pre-commit hook that runs on every commit.
|
||||
|
||||
**Tech Stack:** Python 3 stdlib (json, pathlib, argparse)
|
||||
|
||||
---
|
||||
|
||||
### Task 1: Create Template Files
|
||||
|
||||
**Files:**
|
||||
- Create: `docs/templates/README.template.md`
|
||||
- Create: `docs/templates/AGENTS.template.md`
|
||||
|
||||
**Step 1: Create docs/templates directory**
|
||||
|
||||
```bash
|
||||
mkdir -p docs/templates
|
||||
```
|
||||
|
||||
**Step 2: Create README template**
|
||||
|
||||
Create `docs/templates/README.template.md`:
|
||||
|
||||
```markdown
|
||||
# MTG EDH Deck Manager
|
||||
|
||||
Command-line toolkit for managing Magic: The Gathering Commander (EDH) decks using the Scryfall API.
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
git clone <repo-url>
|
||||
cd Decks
|
||||
```
|
||||
|
||||
No dependencies required - pure Python 3 standard library.
|
||||
|
||||
## Usage
|
||||
|
||||
### Hydrate a Collection
|
||||
|
||||
Fetch card data from Scryfall for a decklist:
|
||||
|
||||
```bash
|
||||
python hydrate.py hydrate collection/decklist.txt -o collection_hydrated/ -c card_cache.json
|
||||
```
|
||||
|
||||
### Create a New Deck
|
||||
|
||||
```bash
|
||||
python hydrate.py new my_deck
|
||||
```
|
||||
|
||||
### Analyze Decks
|
||||
|
||||
Find upgrade options from your collection:
|
||||
|
||||
```bash
|
||||
python scripts/analyze_decks.py --collection collection_hydrated/deck.json --deck-dir decks/
|
||||
```
|
||||
|
||||
### Find Synergies
|
||||
|
||||
Search for cards by keywords, colors, and type:
|
||||
|
||||
```bash
|
||||
# Find landfall cards in Simic colors
|
||||
python scripts/find_synergies.py --collection collection_hydrated/deck.json --colors U G --keywords landfall
|
||||
|
||||
# Find Bird creatures in Bant colors
|
||||
python scripts/find_synergies.py --collection collection_hydrated/deck.json --colors U G W --creature-type Bird
|
||||
|
||||
# Find instants with CMC 2 or less
|
||||
python scripts/find_synergies.py --collection collection_hydrated/deck.json --type instant --cmc-max 2
|
||||
```
|
||||
|
||||
### Generate Reports
|
||||
|
||||
```bash
|
||||
python scripts/deck_report.py --collection collection_hydrated/deck.json --decks-dir decks/ --output report.md
|
||||
```
|
||||
|
||||
## Decks
|
||||
|
||||
{{DECK_TABLE}}
|
||||
|
||||
## Workflow
|
||||
|
||||
1. **Import** - Place text decklists in `collection/`
|
||||
2. **Hydrate** - Run `hydrate.py` to fetch Scryfall data → `collection_hydrated/`
|
||||
3. **Define** - Create deck JSON files in `decks/`
|
||||
4. **Analyze** - Run `analyze_decks.py` to find upgrade options
|
||||
5. **Report** - Use `deck_report.py` for markdown summaries
|
||||
|
||||
## Collection Stats
|
||||
|
||||
{{COLLECTION_STATS}}
|
||||
|
||||
---
|
||||
|
||||
*This file is auto-generated. Edit `docs/templates/README.template.md` instead.*
|
||||
```
|
||||
|
||||
**Step 3: Create AGENTS template**
|
||||
|
||||
Create `docs/templates/AGENTS.template.md`:
|
||||
|
||||
```markdown
|
||||
# AGENTS.md
|
||||
|
||||
Guide for AI assistants working on this codebase.
|
||||
|
||||
## Build/Verify Commands
|
||||
|
||||
This project has no external dependencies or test framework.
|
||||
|
||||
```bash
|
||||
# No lint/typecheck commands currently
|
||||
# Verify scripts work by running them:
|
||||
python hydrate.py --help
|
||||
python scripts/analyze_decks.py --help
|
||||
```
|
||||
|
||||
## Code Style
|
||||
|
||||
- **Language:** Python 3 (stdlib only, no external packages)
|
||||
- **Formatting:** 4-space indent, max line length ~100
|
||||
- **Imports:** Standard library only (argparse, json, pathlib, urllib, re, sys, os, time)
|
||||
- **CLI:** Use `argparse` with subparsers for multi-command tools
|
||||
- **Error handling:** Print to stderr, use sys.exit(1) for failures
|
||||
- **Docstrings:** Triple-quoted at module and function level with usage examples
|
||||
- **Type hints:** Optional but encouraged for complex functions
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
├── hydrate.py # Main CLI - fetches card data from Scryfall
|
||||
├── card_cache.json # Local cache of Scryfall card data
|
||||
├── deck_analysis.json # Analysis output
|
||||
├── collection/ # Raw decklist text files
|
||||
├── collection_hydrated/ # Enriched card data by type
|
||||
│ ├── deck.json # All cards combined
|
||||
│ ├── commander.json
|
||||
│ ├── creatures.json
|
||||
│ ├── instants.json
|
||||
│ ├── sorceries.json
|
||||
│ ├── artifacts.json
|
||||
│ ├── enchantments.json
|
||||
│ ├── lands.json
|
||||
│ └── planeswalkers.json
|
||||
├── decks/ # Deck definitions (JSON)
|
||||
│ └── <deck_name>.json # name, commander, colors, archetype, cards
|
||||
├── scripts/
|
||||
│ ├── analyze_decks.py # Find upgrade options for decks
|
||||
│ ├── find_synergies.py # Search for synergistic cards
|
||||
│ ├── parse_deck.py # Parse text decklists to JSON
|
||||
│ └── deck_report.py # Generate markdown reports
|
||||
└── docs/
|
||||
└── templates/ # Documentation templates
|
||||
```
|
||||
|
||||
## Data Formats
|
||||
|
||||
### Deck JSON (`decks/*.json`)
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "Deck Name",
|
||||
"commander": "Commander Name",
|
||||
"colors": ["U", "G", "W"],
|
||||
"archetype": "Theme Description",
|
||||
"cards": {
|
||||
"Card Name": count,
|
||||
...
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Card Data (`collection_hydrated/*.json`)
|
||||
|
||||
Array of card objects with Scryfall fields:
|
||||
- `name`, `mana_cost`, `cmc`, `colors`, `color_identity`
|
||||
- `type_line`, `oracle_text`, `power`, `toughness`, `loyalty`
|
||||
- `scryfall_uri`, `count`
|
||||
|
||||
## Extension Guide
|
||||
|
||||
### Adding a New Deck
|
||||
|
||||
1. Create `decks/<name>.json` with required fields
|
||||
2. Run `python scripts/update_docs.py` to regenerate documentation
|
||||
|
||||
### Adding a New Script
|
||||
|
||||
1. Create `scripts/<name>.py` with argparse CLI
|
||||
2. Follow existing patterns: `load_collection()`, argparse with --help
|
||||
3. Update README template with usage example
|
||||
4. Run `python scripts/update_docs.py`
|
||||
|
||||
### Modifying Deck Analysis
|
||||
|
||||
- `scripts/analyze_decks.py`: Core logic for finding upgrades
|
||||
- Color identity matching uses `color_identity` field from Scryfall
|
||||
- Cards are categorized by `type_line`
|
||||
|
||||
## Current Decks
|
||||
|
||||
{{DECK_TABLE}}
|
||||
```
|
||||
|
||||
**Step 4: Commit templates**
|
||||
|
||||
```bash
|
||||
git add docs/templates/
|
||||
git commit -m "Add documentation templates"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 2: Create update_docs.py Script
|
||||
|
||||
**Files:**
|
||||
- Create: `scripts/update_docs.py`
|
||||
|
||||
**Step 1: Create the generator script**
|
||||
|
||||
Create `scripts/update_docs.py`:
|
||||
|
||||
```python
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
Generate README.md and AGENTS.md from templates.
|
||||
Usage:
|
||||
python scripts/update_docs.py
|
||||
"""
|
||||
|
||||
import json
|
||||
import os
|
||||
from pathlib import Path
|
||||
|
||||
|
||||
SCRIPT_DIR = Path(__file__).parent
|
||||
PROJECT_ROOT = SCRIPT_DIR.parent
|
||||
TEMPLATES_DIR = PROJECT_ROOT / "docs" / "templates"
|
||||
DECKS_DIR = PROJECT_ROOT / "decks"
|
||||
COLLECTION_DIR = PROJECT_ROOT / "collection_hydrated"
|
||||
|
||||
|
||||
def load_decks() -> list[dict]:
|
||||
"""Load all deck JSON files."""
|
||||
decks = []
|
||||
if DECKS_DIR.exists():
|
||||
for path in sorted(DECKS_DIR.glob("*.json")):
|
||||
with open(path, "r", encoding="utf-8") as f:
|
||||
data = json.load(f)
|
||||
data["filename"] = path.stem
|
||||
decks.append(data)
|
||||
return decks
|
||||
|
||||
|
||||
def load_collection_stats() -> dict:
|
||||
"""Get collection statistics."""
|
||||
stats = {
|
||||
"total_cards": 0,
|
||||
"unique_cards": 0,
|
||||
"by_type": {}
|
||||
}
|
||||
deck_file = COLLECTION_DIR / "deck.json"
|
||||
if deck_file.exists():
|
||||
with open(deck_file, "r", encoding="utf-8") as f:
|
||||
cards = json.load(f)
|
||||
stats["unique_cards"] = len(cards)
|
||||
stats["total_cards"] = sum(c.get("count", 1) for c in cards)
|
||||
for category in ["creatures", "instants", "sorceries", "artifacts", "enchantments", "lands", "planeswalkers"]:
|
||||
cat_file = COLLECTION_DIR / f"{category}.json"
|
||||
if cat_file.exists():
|
||||
with open(cat_file, "r", encoding="utf-8") as f:
|
||||
cards = json.load(f)
|
||||
stats["by_type"][category] = len(cards)
|
||||
return stats
|
||||
|
||||
|
||||
def generate_deck_table(decks: list[dict]) -> str:
|
||||
"""Generate markdown table of decks."""
|
||||
if not decks:
|
||||
return "*No decks defined yet.*"
|
||||
lines = ["| Deck | Colors | Commander | Archetype |", "|------|--------|-----------|-----------|"]
|
||||
color_map = {"W": "White", "U": "Blue", "B": "Black", "R": "Red", "G": "Green"}
|
||||
for deck in decks:
|
||||
name = deck.get("name", deck.get("filename", "Unknown"))
|
||||
colors = deck.get("colors", [])
|
||||
color_str = "".join(colors) if colors else "Colorless"
|
||||
commander = deck.get("commander", "Unknown")
|
||||
archetype = deck.get("archetype", "-")
|
||||
lines.append(f"| {name} | {color_str} | {commander} | {archetype} |")
|
||||
return "\n".join(lines)
|
||||
|
||||
|
||||
def generate_collection_stats(stats: dict) -> str:
|
||||
"""Generate collection statistics section."""
|
||||
lines = [f"- **Total cards:** {stats['total_cards']}", f"- **Unique cards:** {stats['unique_cards']}"]
|
||||
if stats["by_type"]:
|
||||
lines.append("- **By type:**")
|
||||
for category, count in sorted(stats["by_type"].items()):
|
||||
lines.append(f" - {category.title()}: {count}")
|
||||
return "\n".join(lines)
|
||||
|
||||
|
||||
def generate_docs() -> None:
|
||||
"""Generate README.md and AGENTS.md from templates."""
|
||||
decks = load_decks()
|
||||
stats = load_collection_stats()
|
||||
deck_table = generate_deck_table(decks)
|
||||
collection_stats = generate_collection_stats(stats)
|
||||
|
||||
for template_name in ["README.template.md", "AGENTS.template.md"]:
|
||||
template_path = TEMPLATES_DIR / template_name
|
||||
if not template_path.exists():
|
||||
print(f"Template not found: {template_path}")
|
||||
continue
|
||||
with open(template_path, "r", encoding="utf-8") as f:
|
||||
content = f.read()
|
||||
content = content.replace("{{DECK_TABLE}}", deck_table)
|
||||
content = content.replace("{{COLLECTION_STATS}}", collection_stats)
|
||||
output_name = template_name.replace(".template", "")
|
||||
output_path = PROJECT_ROOT / output_name
|
||||
with open(output_path, "w", encoding="utf-8") as f:
|
||||
f.write(content)
|
||||
print(f"Generated: {output_path}")
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
generate_docs()
|
||||
```
|
||||
|
||||
**Step 2: Test the script**
|
||||
|
||||
```bash
|
||||
python scripts/update_docs.py
|
||||
```
|
||||
|
||||
Expected: Creates README.md and AGENTS.md in project root
|
||||
|
||||
**Step 3: Verify generated files**
|
||||
|
||||
```bash
|
||||
ls -la README.md AGENTS.md
|
||||
head -20 README.md
|
||||
```
|
||||
|
||||
**Step 4: Commit the script**
|
||||
|
||||
```bash
|
||||
git add scripts/update_docs.py README.md AGENTS.md
|
||||
git commit -m "Add update_docs.py and generate initial documentation"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 3: Create Pre-commit Hook
|
||||
|
||||
**Files:**
|
||||
- Create: `.git/hooks/pre-commit`
|
||||
|
||||
**Step 1: Create the hook**
|
||||
|
||||
```bash
|
||||
cat > .git/hooks/pre-commit << 'EOF'
|
||||
#!/bin/bash
|
||||
# Auto-update documentation on commit
|
||||
|
||||
python scripts/update_docs.py
|
||||
|
||||
if [ -f README.md ]; then
|
||||
git add README.md
|
||||
fi
|
||||
|
||||
if [ -f AGENTS.md ]; then
|
||||
git add AGENTS.md
|
||||
fi
|
||||
EOF
|
||||
chmod +x .git/hooks/pre-commit
|
||||
```
|
||||
|
||||
**Step 2: Test the hook**
|
||||
|
||||
```bash
|
||||
# Make a small change to trigger the hook
|
||||
echo "# test" >> hydrate.py
|
||||
git add hydrate.py
|
||||
git commit -m "Test pre-commit hook"
|
||||
```
|
||||
|
||||
Expected: Hook runs, updates docs if needed, includes them in commit
|
||||
|
||||
**Step 3: Verify hook worked**
|
||||
|
||||
```bash
|
||||
git log -1 --stat
|
||||
```
|
||||
|
||||
Expected: README.md and AGENTS.md may appear in commit if changed
|
||||
|
||||
---
|
||||
|
||||
### Task 4: Cleanup and Final Commit
|
||||
|
||||
**Step 1: Remove test change if added**
|
||||
|
||||
```bash
|
||||
# If you added the test line, revert it:
|
||||
git checkout hydrate.py
|
||||
```
|
||||
|
||||
**Step 2: Make a clean commit documenting the hook**
|
||||
|
||||
```bash
|
||||
git add .git/hooks/pre-commit
|
||||
git commit -m "Add pre-commit hook for auto-updating documentation"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- [ ] `README.md` exists with deck table and usage docs
|
||||
- [ ] `AGENTS.md` exists with build commands and project structure
|
||||
- [ ] `scripts/update_docs.py` generates both files from templates
|
||||
- [ ] Pre-commit hook runs and stages updated docs
|
||||
- [ ] Templates are editable without touching generated files
|
||||
Reference in New Issue
Block a user