@opslane/claude-code-game 0.1.0

package/levels/08-mcp-servers/exercise/utils.py

@@ -0,0 +1,163 @@
+"""Utility functions for the expense tracker."""
+
+from datetime import datetime, timedelta
+from typing import Optional
+import locale
+
+
+def format_currency(amount: float) -> str:
+    """Format amount as currency.
+
+    Args:
+        amount: The numeric amount
+
+    Returns:
+        Formatted string like '$1,234.56'
+
+    Example:
+        >>> format_currency(1234.5)
+        '$1,234.50'
+    """
+    try:
+        locale.setlocale(locale.LC_ALL, '')
+        return locale.currency(amount, grouping=True)
+    except (locale.Error, ValueError):
+        # Fallback if locale not available
+        return f"${amount:,.2f}"
+
+
+def parse_date(date_str: Optional[str]) -> Optional[datetime]:
+    """Parse a date string in various formats.
+
+    Supports:
+    - YYYY-MM-DD (2026-01-15)
+    - MM/DD/YYYY (01/15/2026)
+    - 'today'
+    - 'yesterday'
+
+    Args:
+        date_str: The date string to parse
+
+    Returns:
+        datetime object or None if input is None
+
+    Raises:
+        ValueError: If date format is not recognized
+
+    Example:
+        >>> parse_date('2026-01-15')
+        datetime(2026, 1, 15, 0, 0, 0)
+        >>> parse_date('today')
+        datetime(...)  # Today at midnight
+    """
+    if not date_str:
+        return None
+
+    date_str = date_str.lower().strip()
+
+    # Handle relative dates
+    if date_str == 'today':
+        return datetime.now().replace(hour=0, minute=0, second=0, microsecond=0)
+
+    if date_str == 'yesterday':
+        return (datetime.now() - timedelta(days=1)).replace(
+            hour=0, minute=0, second=0, microsecond=0
+        )
+
+    # Try YYYY-MM-DD (ISO format)
+    try:
+        return datetime.strptime(date_str, '%Y-%m-%d')
+    except ValueError:
+        pass
+
+    # Try MM/DD/YYYY (US format)
+    try:
+        return datetime.strptime(date_str, '%m/%d/%Y')
+    except ValueError:
+        pass
+
+    # Try DD/MM/YYYY (European format)
+    try:
+        return datetime.strptime(date_str, '%d/%m/%Y')
+    except ValueError:
+        pass
+
+    raise ValueError(f"Could not parse date: {date_str}. Use YYYY-MM-DD format.")
+
+
+def validate_category(category: str) -> str:
+    """Normalize category name.
+
+    Capitalizes first letter, strips whitespace.
+
+    Args:
+        category: Raw category input
+
+    Returns:
+        Normalized category name
+
+    Example:
+        >>> validate_category('  food  ')
+        'Food'
+    """
+    return category.strip().capitalize()
+
+
+def format_date(dt: datetime) -> str:
+    """Format a datetime for display.
+
+    Args:
+        dt: The datetime to format
+
+    Returns:
+        Formatted string like 'Jan 15, 2026'
+    """
+    return dt.strftime('%b %d, %Y')
+
+
+def format_month(month_str: str) -> str:
+    """Format a YYYY-MM string for display.
+
+    Args:
+        month_str: Month in YYYY-MM format
+
+    Returns:
+        Formatted string like 'January 2026'
+
+    Example:
+        >>> format_month('2026-01')
+        'January 2026'
+    """
+    dt = datetime.strptime(month_str, '%Y-%m')
+    return dt.strftime('%B %Y')
+
+
+# Valid categories for validation/suggestions
+VALID_CATEGORIES = [
+    "Food",
+    "Transport",
+    "Entertainment",
+    "Shopping",
+    "Bills",
+    "Health",
+    "Education",
+    "Travel",
+    "Other"
+]
+
+
+def suggest_category(partial: str) -> list[str]:
+    """Suggest categories matching a partial input.
+
+    Args:
+        partial: Partial category name
+
+    Returns:
+        List of matching categories
+
+    Example:
+        >>> suggest_category('fo')
+        ['Food']
+    """
+    partial_lower = partial.lower()
+    return [cat for cat in VALID_CATEGORIES if cat.lower().startswith(partial_lower)]

package/levels/08-mcp-servers/lesson.yaml

@@ -0,0 +1,59 @@
+id: "mcp-servers"
+number: 8
+module: "Extensions"
+title: "MCP Servers (External Sources)"
+
+video:
+  url: "https://youtu.be/r3CuQHbMLPw"
+  duration_seconds: 300
+
+exercise:
+  intro: |
+    Connect Claude to external data sources using MCP (Model Context Protocol).
+  objective: "Install an MCP server and use it to fetch external data"
+
+intro: |
+  MCP servers connect Claude to external tools and data sources.
+
+  Remember Lesson 1? Claude trusted outdated Firecrawl docs and wrote
+  broken v1 code. MCP servers solve this — they let Claude fetch live
+  data from external sources.
+
+  Let's fix Lesson 1's problem with context7 (a documentation MCP):
+
+  1. Start Claude: `claude`
+  2. Install context7:
+     "Add the context7 MCP server using:
+     claude mcp add context7 -- npx -y @upstash/context7-mcp@latest"
+  3. IMPORTANT: Exit Claude (Ctrl+C) and restart it.
+     MCP tools only load on startup — you must restart to use them.
+  4. Now ask the SAME question from Lesson 1:
+     "Write a function that scrapes a URL using the Firecrawl Python SDK"
+  5. Watch Claude fetch the current Firecrawl docs via context7
+     → It should use the correct v2 API (Firecrawl, scrape, etc.)
+     → Not the outdated v1 API from the docs/ folder
+
+  The MCP gives Claude access to current documentation automatically.
+
+verification:
+  - type: message_exists
+
+success: |
+  You connected Claude to live documentation!
+
+  Compare to Lesson 1:
+  - Without MCP: Claude used outdated docs → broken v1 code
+  - With context7: Claude fetched current docs → correct v2 code
+
+  MCP servers extend Claude's reach beyond its training data:
+  - context7: Live library documentation
+  - postgres: Database queries
+  - github: Repository management
+  - slack: Team communication
+
+  Any API can become an MCP server. Check your servers:
+  claude mcp list
+
+limits:
+  max_duration_minutes: 15
+  max_claude_messages: 20

package/levels/09-plugins/exercise/README.md

@@ -0,0 +1,152 @@
+# Expense Tracker
+
+A simple CLI expense tracker built with Python and SQLite.
+
+This is the project used throughout the Claude Code course. You'll learn to use
+Claude Code to understand, debug, and extend this codebase.
+
+## Quick Start
+
+```bash
+# 1. Seed the database with sample data
+python seed_data.py
+
+# 2. Try some commands
+python main.py list
+python main.py summary
+python main.py list --category Food
+```
+
+## Commands
+
+### Add an expense
+```bash
+python main.py add <amount> <category> <description> [--date YYYY-MM-DD]
+
+# Examples:
+python main.py add 45.50 Food "Grocery shopping"
+python main.py add 25.00 Transport "Uber" --date 2026-01-15
+```
+
+### List expenses
+```bash
+python main.py list [--category CATEGORY] [--month YYYY-MM] [--limit N]
+
+# Examples:
+python main.py list
+python main.py list --category Food
+python main.py list --month 2026-01
+python main.py list --limit 5
+```
+
+### Show expense details
+```bash
+python main.py show <expense_id>
+
+# Example:
+python main.py show abc123
+```
+
+### Delete an expense
+```bash
+python main.py delete <expense_id>
+
+# Example:
+python main.py delete abc123
+```
+
+### View spending summary
+```bash
+python main.py summary
+```
+
+## Running Tests
+
+```bash
+# Run all tests
+pytest
+
+# Run with verbose output
+pytest -v
+
+# Run specific test file
+pytest tests/test_models.py
+
+# Run tests matching a pattern
+pytest -k "category"
+```
+
+## Project Structure
+
+```
+expense_tracker/
+├── main.py           # CLI entry point
+├── models.py         # Expense data model and core functions
+├── database.py       # SQLite database operations
+├── utils.py          # Helper functions (formatting, parsing)
+├── reports.py        # Report generation (Lesson 4)
+├── seed_data.py      # Script to populate sample data
+├── tests/
+│   ├── conftest.py       # Pytest fixtures
+│   ├── test_models.py    # Model tests
+│   ├── test_database.py  # Database tests
+│   └── test_reports.py   # Report tests (Lesson 4)
+├── data/
+│   └── expenses.db   # SQLite database (created on first run)
+└── README.md
+```
+
+## Course Lessons
+
+This codebase is used in the following lessons:
+
+| Lesson | Focus | What You'll Do |
+|--------|-------|----------------|
+| 1 | Context | Explore the codebase, see context limits |
+| 2 | CLAUDE.md | Create project memory |
+| 3 | Bug Fix | Fix the negative amount validation bug |
+| 4 | Debugging | Fix the case-sensitive category bug |
+| 5 | Specs | Add recurring expenses feature |
+| 6 | Planning | Implement the reports module |
+| 7+ | Building Blocks | Create commands, skills, workflows |
+
+## Known Issues (For Learning)
+
+This codebase has intentional bugs for learning purposes:
+
+1. **Negative amounts accepted** (Lesson 3)
+   - `add_expense()` doesn't validate that amount > 0
+   - Tests `test_add_negative_amount_should_fail` and `test_add_zero_amount_should_fail` fail
+
+2. **Case-sensitive category filtering** (a later lesson)
+   - `list_expenses(category="Food")` won't find expenses with category "food" or "FOOD"
+   - Test `test_list_by_category_case_insensitive` fails
+
+3. **Reports not implemented** (Lesson 4)
+   - `reports.py` has stub functions that raise `NotImplementedError`
+   - All tests in `test_reports.py` are skipped until implementation
+
+## Development
+
+### Requirements
+- Python 3.10+
+- pytest (for running tests)
+
+### Setup
+```bash
+# Create virtual environment (optional but recommended)
+python -m venv venv
+source venv/bin/activate  # On Windows: venv\Scripts\activate
+
+# Install dev dependencies
+pip install pytest ruff
+
+# Initialize database
+python seed_data.py
+```
+
+### Code Style
+- Type hints on all function signatures
+- Docstrings on public functions
+- Black-compatible formatting
+- No unused imports

package/levels/09-plugins/exercise/database.py

@@ -0,0 +1,171 @@
+"""SQLite database operations for expense storage."""
+
+import sqlite3
+import os
+from pathlib import Path
+from datetime import datetime
+from typing import Optional, TYPE_CHECKING
+from contextlib import contextmanager
+
+if TYPE_CHECKING:
+    from models import Expense
+
+# Database path - use environment variable for testing, otherwise default location
+DB_PATH = Path(os.environ.get(
+    "EXPENSE_DB_PATH",
+    Path(__file__).parent / "data" / "expenses.db"
+))
+
+
+@contextmanager
+def get_connection():
+    """Get a database connection with proper cleanup.
+
+    Yields:
+        sqlite3.Connection with Row factory enabled
+
+    Example:
+        with get_connection() as conn:
+            conn.execute("SELECT * FROM expenses")
+    """
+    conn = sqlite3.connect(DB_PATH)
+    conn.row_factory = sqlite3.Row
+    try:
+        yield conn
+        conn.commit()
+    finally:
+        conn.close()
+
+
+def init_db() -> None:
+    """Initialize the database schema.
+
+    Creates the expenses table if it doesn't exist.
+    Also creates the data directory if needed.
+    """
+    DB_PATH.parent.mkdir(parents=True, exist_ok=True)
+
+    with get_connection() as conn:
+        conn.execute('''
+            CREATE TABLE IF NOT EXISTS expenses (
+                id TEXT PRIMARY KEY,
+                amount REAL NOT NULL,
+                category TEXT NOT NULL,
+                description TEXT,
+                date TEXT NOT NULL,
+                recurring INTEGER DEFAULT 0,
+                recurring_frequency TEXT
+            )
+        ''')
+
+
+def save_expense(expense: "Expense") -> None:
+    """Save an expense to the database.
+
+    Args:
+        expense: The Expense object to save
+    """
+    with get_connection() as conn:
+        conn.execute('''
+            INSERT INTO expenses (id, amount, category, description, date, recurring, recurring_frequency)
+            VALUES (?, ?, ?, ?, ?, ?, ?)
+        ''', (
+            expense.id,
+            expense.amount,
+            expense.category,
+            expense.description,
+            expense.date.isoformat(),
+            1 if expense.recurring else 0,
+            expense.recurring_frequency
+        ))
+
+
+def load_expenses() -> list["Expense"]:
+    """Load all expenses from the database.
+
+    Returns:
+        List of all Expense objects, ordered by date descending
+    """
+    from models import Expense  # Import here to avoid circular import
+
+    with get_connection() as conn:
+        rows = conn.execute('SELECT * FROM expenses ORDER BY date DESC').fetchall()
+
+    expenses = []
+    for row in rows:
+        expenses.append(Expense(
+            id=row['id'],
+            amount=row['amount'],
+            category=row['category'],
+            description=row['description'],
+            date=datetime.fromisoformat(row['date']),
+            recurring=bool(row['recurring']),
+            recurring_frequency=row['recurring_frequency']
+        ))
+
+    return expenses
+
+
+def get_expense_by_id(expense_id: str) -> Optional["Expense"]:
+    """Get a single expense by ID.
+
+    Args:
+        expense_id: The unique expense ID
+
+    Returns:
+        The Expense if found, None otherwise
+    """
+    from models import Expense  # Import here to avoid circular import
+
+    with get_connection() as conn:
+        row = conn.execute(
+            'SELECT * FROM expenses WHERE id = ?',
+            (expense_id,)
+        ).fetchone()
+
+    if not row:
+        return None
+
+    return Expense(
+        id=row['id'],
+        amount=row['amount'],
+        category=row['category'],
+        description=row['description'],
+        date=datetime.fromisoformat(row['date']),
+        recurring=bool(row['recurring']),
+        recurring_frequency=row['recurring_frequency']
+    )
+
+
+def remove_expense(expense_id: str) -> bool:
+    """Remove an expense from the database.
+
+    Args:
+        expense_id: The unique expense ID
+
+    Returns:
+        True if an expense was deleted, False if not found
+    """
+    with get_connection() as conn:
+        cursor = conn.execute('DELETE FROM expenses WHERE id = ?', (expense_id,))
+        return cursor.rowcount > 0
+
+
+def clear_all_expenses() -> None:
+    """Clear all expenses from the database.
+
+    WARNING: This deletes all data! Use only for testing.
+    """
+    with get_connection() as conn:
+        conn.execute('DELETE FROM expenses')
+
+
+def get_expense_count() -> int:
+    """Get the total number of expenses.
+
+    Returns:
+        Count of expenses in database
+    """
+    with get_connection() as conn:
+        row = conn.execute('SELECT COUNT(*) as count FROM expenses').fetchone()
+        return row['count']

package/levels/09-plugins/exercise/main.py

@@ -0,0 +1,97 @@
+#!/usr/bin/env python3
+"""Expense Tracker CLI - Track your daily expenses."""
+
+import argparse
+from datetime import datetime
+from models import add_expense, list_expenses, delete_expense, get_expense
+from utils import format_currency, parse_date
+from database import init_db
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Track your expenses")
+    subparsers = parser.add_subparsers(dest="command", help="Commands")
+
+    # Add expense
+    add_parser = subparsers.add_parser("add", help="Add a new expense")
+    add_parser.add_argument("amount", type=float, help="Amount spent")
+    add_parser.add_argument("category", help="Category (Food, Transport, etc.)")
+    add_parser.add_argument("description", help="What was the expense for?")
+    add_parser.add_argument("--date", help="Date (YYYY-MM-DD), defaults to today")
+
+    # List expenses
+    list_parser = subparsers.add_parser("list", help="List expenses")
+    list_parser.add_argument("--category", help="Filter by category")
+    list_parser.add_argument("--month", help="Filter by month (YYYY-MM)")
+    list_parser.add_argument("--limit", type=int, default=10, help="Max results")
+
+    # Delete expense
+    delete_parser = subparsers.add_parser("delete", help="Delete an expense")
+    delete_parser.add_argument("id", help="Expense ID to delete")
+
+    # Show single expense
+    show_parser = subparsers.add_parser("show", help="Show expense details")
+    show_parser.add_argument("id", help="Expense ID")
+
+    # Summary
+    subparsers.add_parser("summary", help="Show spending summary")
+
+    args = parser.parse_args()
+
+    # Initialize database
+    init_db()
+
+    if args.command == "add":
+        date = parse_date(args.date) if args.date else datetime.now()
+        expense = add_expense(args.amount, args.category, args.description, date)
+        print(f"Added expense: {expense.id} - {format_currency(expense.amount)}")
+
+    elif args.command == "list":
+        expenses = list_expenses(
+            category=args.category,
+            month=args.month,
+            limit=args.limit
+        )
+        if not expenses:
+            print("No expenses found.")
+        for exp in expenses:
+            print(f"{exp.id} | {exp.date.strftime('%Y-%m-%d')} | "
+                  f"{exp.category:12} | {format_currency(exp.amount):>10} | {exp.description}")
+
+    elif args.command == "delete":
+        if delete_expense(args.id):
+            print(f"Deleted expense {args.id}")
+        else:
+            print(f"Expense {args.id} not found")
+
+    elif args.command == "show":
+        expense = get_expense(args.id)
+        if expense:
+            print(f"ID:          {expense.id}")
+            print(f"Amount:      {format_currency(expense.amount)}")
+            print(f"Category:    {expense.category}")
+            print(f"Description: {expense.description}")
+            print(f"Date:        {expense.date.strftime('%Y-%m-%d %H:%M')}")
+        else:
+            print(f"Expense {args.id} not found")
+
+    elif args.command == "summary":
+        expenses = list_expenses()
+        total = sum(e.amount for e in expenses)
+        print(f"Total expenses: {format_currency(total)}")
+
+        # Group by category
+        categories: dict[str, float] = {}
+        for exp in expenses:
+            categories[exp.category] = categories.get(exp.category, 0) + exp.amount
+
+        print("\nBy category:")
+        for cat, amount in sorted(categories.items(), key=lambda x: x[1], reverse=True):
+            print(f"  {cat:15} {format_currency(amount):>10}")
+
+    else:
+        parser.print_help()
+
+
+if __name__ == "__main__":
+    main()