Add build system foundation: utils.py and tests

Implements Phase 1 of issue #4 (automated content generation):

- Created directory structure: data/, templates/, tests/, scripts/
- Added requirements-build.txt with dependencies
- Implemented scripts/utils.py with core utilities:
  - load_spreadsheet(): Load Excel files, handle empty cells
  - inject_content(): Template marker replacement
  - validate_required_fields(): Required field validation
  - validate_url_format(): URL format checking
  - check_file_exists(): File existence validation
- Added comprehensive test suite (31 tests, all passing)
- All tests use REAL files - no mocks or simulations

Refs #4

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: jeremymanning

requirements-build.txt

@@ -0,0 +1,25 @@
+# Build system dependencies for Context Lab website
+# Install with: pip install -r requirements-build.txt
+
+# Excel file parsing
+openpyxl>=3.1.0
+
+# HTML templating (for content block generation)
+Jinja2>=3.1.0
+
+# HTML validation
+html5lib>=1.1
+beautifulsoup4>=4.12.0
+
+# Test framework
+pytest>=7.4.0
+pytest-timeout>=2.2.0
+
+# HTTP requests for URL validation tests
+requests>=2.31.0
+
+# Screenshot comparison for visual regression tests
+Pillow>=10.0.0
+
+# Browser automation for visual tests
+selenium>=4.15.0

scripts/__init__.py

@@ -0,0 +1 @@
+"""Build scripts for Context Lab website."""

scripts/utils.py

@@ -0,0 +1,133 @@
+"""Shared utilities for build scripts.
+
+This module provides common functions for loading spreadsheets,
+validating data, and injecting content into HTML templates.
+"""
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+import openpyxl
+
+
+def load_spreadsheet(filepath: Path) -> List[Dict[str, Any]]:
+    """Load Excel spreadsheet and return list of row dictionaries.
+
+    Args:
+        filepath: Path to the .xlsx file
+
+    Returns:
+        List of dictionaries, one per row, with column headers as keys.
+        Empty cells are converted to empty strings.
+
+    Raises:
+        FileNotFoundError: If the spreadsheet doesn't exist
+        openpyxl.utils.exceptions.InvalidFileException: If file is not valid xlsx
+    """
+    wb = openpyxl.load_workbook(filepath, read_only=True, data_only=True)
+    sheet = wb.active
+
+    # Get headers from first row
+    headers = [cell.value for cell in sheet[1]]
+
+    # Validate headers - no None values allowed
+    if None in headers:
+        raise ValueError(f"Spreadsheet has empty header cells: {headers}")
+
+    rows = []
+    for row in sheet.iter_rows(min_row=2, values_only=True):
+        # Skip completely empty rows
+        if not any(cell is not None for cell in row):
+            continue
+
+        # Create dict, converting None to empty string for consistency
+        row_dict = {}
+        for header, value in zip(headers, row):
+            if value is None:
+                row_dict[header] = ''
+            else:
+                row_dict[header] = value
+        rows.append(row_dict)
+
+    wb.close()
+    return rows
+
+
+def inject_content(template_path: Path, output_path: Path,
+                   replacements: Dict[str, str]) -> None:
+    """Inject generated content into template at marker locations.
+
+    Markers in the template should be HTML comments like: <!-- MARKER_NAME -->
+
+    Args:
+        template_path: Path to the template HTML file
+        output_path: Path where the generated HTML will be written
+        replacements: Dictionary mapping marker names to HTML content
+
+    Raises:
+        FileNotFoundError: If template doesn't exist
+        ValueError: If a marker is not found in the template
+    """
+    content = template_path.read_text(encoding='utf-8')
+
+    for marker, html in replacements.items():
+        pattern = f'<!-- {marker} -->'
+        if pattern not in content:
+            raise ValueError(
+                f"Marker '{pattern}' not found in template {template_path}"
+            )
+        content = content.replace(pattern, html)
+
+    output_path.write_text(content, encoding='utf-8')
+
+
+def validate_required_fields(row: Dict[str, Any], required: List[str],
+                             row_num: int) -> List[str]:
+    """Validate that required fields are present and non-empty.
+
+    Args:
+        row: Dictionary of field values from a spreadsheet row
+        required: List of required field names
+        row_num: Row number (for error messages), 1-indexed from data rows
+
+    Returns:
+        List of error messages (empty if all fields valid)
+    """
+    errors = []
+    for field in required:
+        value = row.get(field)
+        if value is None or (isinstance(value, str) and value.strip() == ''):
+            errors.append(f"Row {row_num}: Missing required field '{field}'")
+    return errors
+
+
+def validate_url_format(url: str) -> bool:
+    """Check if a string looks like a valid URL.
+
+    Args:
+        url: String to validate
+
+    Returns:
+        True if URL starts with http:// or https://, False otherwise
+    """
+    if not url or not isinstance(url, str):
+        return False
+    url = url.strip()
+    return url.startswith('http://') or url.startswith('https://')
+
+
+def check_file_exists(filepath: Path, base_dir: Path) -> Optional[str]:
+    """Check if a referenced file exists.
+
+    Args:
+        filepath: Filename (not full path) referenced in spreadsheet
+        base_dir: Directory where the file should exist
+
+    Returns:
+        Error message if file doesn't exist, None if it exists
+    """
+    if not filepath or not str(filepath).strip():
+        return None  # Empty is OK for optional fields
+
+    full_path = base_dir / str(filepath).strip()
+    if not full_path.exists():
+        return f"File not found: {full_path}"
+    return None

tests/__init__.py

@@ -0,0 +1 @@
+"""Tests for Context Lab website build system."""

tests/conftest.py

@@ -0,0 +1,6 @@
+"""Pytest configuration and shared fixtures."""
+import sys
+from pathlib import Path
+
+# Add scripts directory to path for imports
+sys.path.insert(0, str(Path(__file__).parent.parent / 'scripts'))