@opslane/claude-code-game 0.1.0

package/levels/07-skills/exercise/tests/test_reports.py

@@ -0,0 +1,190 @@
+"""Tests for report generation.
+
+Note: These tests will FAIL until students implement reports.py in Lesson 4.
+The tests serve as a specification for what needs to be implemented.
+"""
+
+import pytest
+from datetime import datetime
+from models import add_expense, Expense
+from reports import (
+    generate_monthly_report,
+    get_category_breakdown,
+    get_top_expenses,
+    save_report
+)
+
+
+class TestGenerateMonthlyReport:
+    """Tests for the generate_monthly_report function."""
+
+    @pytest.mark.skip(reason="Implement in Lesson 4")
+    def test_report_for_empty_month(self):
+        """Test report generation for month with no expenses."""
+        report = generate_monthly_report("2020-01")
+        assert "No expenses" in report or "no expenses" in report.lower()
+
+    @pytest.mark.skip(reason="Implement in Lesson 4")
+    def test_report_includes_total(self):
+        """Test that report includes total amount."""
+        add_expense(100.0, "Food", "Groceries", datetime(2026, 1, 15))
+        add_expense(50.0, "Transport", "Uber", datetime(2026, 1, 15))
+
+        report = generate_monthly_report("2026-01")
+
+        # Should contain total of $150
+        assert "150" in report
+
+    @pytest.mark.skip(reason="Implement in Lesson 4")
+    def test_report_includes_categories(self):
+        """Test that report includes category breakdown."""
+        add_expense(100.0, "Food", "Groceries", datetime(2026, 1, 15))
+        add_expense(50.0, "Transport", "Uber", datetime(2026, 1, 15))
+
+        report = generate_monthly_report("2026-01")
+
+        assert "Food" in report
+        assert "Transport" in report
+
+    @pytest.mark.skip(reason="Implement in Lesson 4")
+    def test_report_defaults_to_current_month(self):
+        """Test that no month argument uses current month."""
+        # This test is tricky since it depends on current date
+        # Just verify it doesn't error
+        report = generate_monthly_report()
+        assert report is not None
+        assert isinstance(report, str)
+
+    @pytest.mark.skip(reason="Implement in Lesson 4")
+    def test_report_format_is_markdown(self):
+        """Test that report is formatted as markdown."""
+        add_expense(100.0, "Food", "Test", datetime(2026, 1, 15))
+        report = generate_monthly_report("2026-01")
+
+        # Should have markdown headers
+        assert "#" in report
+
+
+class TestGetCategoryBreakdown:
+    """Tests for the get_category_breakdown function."""
+
+    @pytest.mark.skip(reason="Implement in Lesson 4")
+    def test_single_category(self):
+        """Test breakdown with single category."""
+        expenses = [
+            Expense("1", 50.0, "Food", "Lunch", datetime.now()),
+            Expense("2", 25.0, "Food", "Coffee", datetime.now()),
+        ]
+
+        breakdown = get_category_breakdown(expenses)
+
+        assert "Food" in breakdown
+        assert breakdown["Food"] == 75.0
+
+    @pytest.mark.skip(reason="Implement in Lesson 4")
+    def test_multiple_categories(self):
+        """Test breakdown with multiple categories."""
+        expenses = [
+            Expense("1", 50.0, "Food", "Lunch", datetime.now()),
+            Expense("2", 30.0, "Transport", "Bus", datetime.now()),
+            Expense("3", 20.0, "Food", "Snack", datetime.now()),
+        ]
+
+        breakdown = get_category_breakdown(expenses)
+
+        assert breakdown["Food"] == 70.0
+        assert breakdown["Transport"] == 30.0
+
+    @pytest.mark.skip(reason="Implement in Lesson 4")
+    def test_empty_list(self):
+        """Test breakdown with empty expense list."""
+        breakdown = get_category_breakdown([])
+        assert breakdown == {}
+
+
+class TestGetTopExpenses:
+    """Tests for the get_top_expenses function."""
+
+    @pytest.mark.skip(reason="Implement in Lesson 4")
+    def test_top_expenses_ordering(self):
+        """Test that expenses are sorted by amount descending."""
+        expenses = [
+            Expense("1", 25.0, "Food", "Small", datetime.now()),
+            Expense("2", 100.0, "Bills", "Big", datetime.now()),
+            Expense("3", 50.0, "Shopping", "Medium", datetime.now()),
+        ]
+
+        top = get_top_expenses(expenses, 3)
+
+        assert top[0].amount == 100.0
+        assert top[1].amount == 50.0
+        assert top[2].amount == 25.0
+
+    @pytest.mark.skip(reason="Implement in Lesson 4")
+    def test_top_n_limit(self):
+        """Test limiting to N expenses."""
+        expenses = [
+            Expense(str(i), float(i * 10), "Cat", "Desc", datetime.now())
+            for i in range(1, 11)
+        ]
+
+        top = get_top_expenses(expenses, 3)
+        assert len(top) == 3
+
+    @pytest.mark.skip(reason="Implement in Lesson 4")
+    def test_top_with_fewer_expenses(self):
+        """Test when requesting more than available."""
+        expenses = [
+            Expense("1", 50.0, "Food", "Only one", datetime.now()),
+        ]
+
+        top = get_top_expenses(expenses, 5)
+        assert len(top) == 1
+
+    @pytest.mark.skip(reason="Implement in Lesson 4")
+    def test_default_n_is_5(self):
+        """Test that default n value is 5."""
+        expenses = [
+            Expense(str(i), float(i), "Cat", "Desc", datetime.now())
+            for i in range(10)
+        ]
+
+        top = get_top_expenses(expenses)
+        assert len(top) == 5
+
+
+class TestSaveReport:
+    """Tests for the save_report function."""
+
+    @pytest.mark.skip(reason="Implement in Lesson 4")
+    def test_save_creates_file(self, tmp_path, monkeypatch):
+        """Test that save_report creates a file."""
+        import os
+        monkeypatch.chdir(tmp_path)
+
+        report_content = "# Test Report\n\nThis is a test."
+        path = save_report(report_content, "test-report.md")
+
+        assert path.exists()
+        assert path.read_text() == report_content
+
+    @pytest.mark.skip(reason="Implement in Lesson 4")
+    def test_save_creates_directory(self, tmp_path, monkeypatch):
+        """Test that save_report creates reports directory if needed."""
+        import os
+        monkeypatch.chdir(tmp_path)
+
+        save_report("# Test", "2026-01.md")
+
+        assert (tmp_path / "reports").is_dir()
+
+    @pytest.mark.skip(reason="Implement in Lesson 4")
+    def test_save_returns_path(self, tmp_path, monkeypatch):
+        """Test that save_report returns the file path."""
+        import os
+        monkeypatch.chdir(tmp_path)
+
+        path = save_report("# Test", "my-report.md")
+
+        assert path.name == "my-report.md"
+        assert "reports" in str(path)

package/levels/07-skills/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/07-skills/lesson.yaml

@@ -0,0 +1,49 @@
+id: "skills"
+number: 7
+module: "Building Blocks"
+title: "Skills (Auto-Activating Commands)"
+
+video:
+  url: "https://youtu.be/vBgMO4U7kZg"
+  duration_seconds: 300
+
+exercise:
+  intro: |
+    Create a skill that auto-activates when you ask about code.
+  objective: "Create a code explainer skill"
+
+intro: |
+  Skills live in .claude/skills/ and auto-activate based on context.
+
+  CLAUDE.md (Lesson 2) loads every session - it's always-on context.
+  Skills load on demand - only when Claude thinks they're relevant.
+
+  Use CLAUDE.md for things that always matter.
+  Use skills for workflow-specific instructions.
+
+  Create a code explainer skill:
+
+  Type: claude
+
+  Say: "Create a skill called 'code-explainer' that activates when I ask
+  to explain code. It should read the relevant files and explain what
+  they do in plain English."
+
+  After creating, test it by asking: "Explain the models.py file"
+
+verification:
+  - type: glob_exists
+    pattern: ".claude/skills/*/SKILL.md"
+    description: "Create a skill file"
+
+success: |
+  You created an auto-activating skill!
+
+  Test it: "Explain the database.py file"
+
+  Skills auto-trigger based on context.
+  Commands require explicit /invocation.
+
+limits:
+  max_duration_minutes: 15
+  max_claude_messages: 20

package/levels/08-mcp-servers/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