name: book-lamp-development description: Guidelines and workflows for developing the Book Lamp application, focusing on the Google Sheets adapter pattern and project philosophy.

Book Lamp Development Skill

This skill provides comprehensive guidelines for developing, maintaining, and extending the Book Lamp application.

Core Philosophy

Following the Python Architecture Tutor principles, we prioritise clarity, readability, and explicit structure:

1. Layered Architecture (Separation of Concerns)

The project is structured into distinct layers to separate business logic from external side effects:

• Models/Entities: Pure data structures (e.g., book dictionaries with defined keys).
• Adapters (Persistence): Isolated in book_lamp/services/. GoogleSheetsStorage is our primary adapter for Google Sheets.
• Service Layer: Pure logic that sits between entry points and adapters (e.g., book_lookup.py).
• Entry Points: Flask routes in app.py and CLI commands.

2. Pure vs. Effectful Separation

• Pure Code: Logic should be deterministic. It should not perform I/O or rely on system time directly.
• Effectful Code: All I/O (Google Sheets API, network, filesystem, time) must be isolated at the edges in adapter classes or functions.
• Dependency Injection: Inject adapters into logic or entry points to keep them decoupled.

3. Mentorship & Readability

• Explicit over Implicit: Avoid "magic". Prefer clear connections between components.
• British English: All comments, documentation, and naming (where possible) MUST use British English (e.g., serialise, colour, optimise).
• Standard Library: Prefer modern Python standards (e.g., datetime.now(timezone.utc), pathlib).

4. Frontend Architecture

• Separation of Concerns: CSS and JavaScript must be kept in dedicated files in book_lamp/static/.
• CSS: Avoid inline styles or <style> blocks in HTML templates. Use descriptive filenames (e.g., base.css, books.css).
• HTML: Keep templates focused on structure and Jinja2 logic.

Documentation Standard

• Docstrings: Use Google Style docstrings for all public functions and classes.
• Template:

  def function_name(param1: str) -> bool:
      """Short summary of the function.
  
      Detailed description if necessary.
  
      Args:
          param1: Description of param1.
  
      Returns:
          Description of the return value.
      """
  

Working with Google Sheets Storage

The GoogleSheetsStorage class in book_lamp/services/sheets_storage.py is the primary adapter for data.

Sheet Structure

• Books: id, isbn13, title, author, publication_year, thumbnail_url, created_at
• ReadingRecords: id, book_id, status, start_date, end_date, rating, created_at

Dynamic Management

• On first run or if a token is present, the app creates a folder hierarchy AppData/BookLamp in the user's Google Drive.
• It creates/uses a spreadsheet based on the environment:
  • Production: BookLampData
  • Development: DevBookLampData

Extending the Schema

1. Update the initialize_sheets method to include new headers.
2. Update the range in get_all_books or get_reading_records.
3. Update the mapping logic in the getter and adder methods.
4. Always use 1-based indexing for row deletions and updates as required by the Google Sheets API.

Handling IDs

• IDs are managed manually by finding the maximum value in the first column of a tab and incrementing it.
• Always check for empty sheets or sheets with only headers.

Testing Strategy

Unit Tests

• Test pure logic with table-driven tests.
• Mock the GoogleSheetsStorage or use the MOCK_STORAGE pattern if available.
• Place unit tests in the tests/ directory.

E2E Tests (Playwright)

• E2E tests are located in tests-e2e/.
• Use npm test to run the suite.
• The app should automatically handle TEST_MODE to avoid hitting real Google APIs during testing.

Security and Configuration

OAuth and Authentication

• The application uses Google OAuth2 for authentication.
• Users must authorize the application to access their Google Drive and Sheets.
• The token.json file stores the OAuth2 tokens.

Secrets and Sanitization

• Never commit credentials.json, token.json, or .env files.
• Required Environment Variables:
  • SECRET_KEY: For Flask session management.
  • GOOGLE_CLIENT_ID: Google Cloud Client ID.
  • GOOGLE_CLIENT_SECRET: Google Cloud Client Secret.
• Input Sanitization: Always strip and normalize user input (ISBNs, titles) before processing or storing.

Debugging and Diagnostics

Common Google Sheets Errors

• 403 Forbidden: Check if the OAuth user has given the app permission to access Google Drive and Sheets.
• 401 Unauthorized: Ensure the user has authorized the app via the /login route.
• Initialization Error: If the app cannot create the folder hierarchy, check Drive permissions.
• Invalid Credentials: Delete token.json and re-run the login flow via the web interface.

Logs

• Application logs are configured with standard formatting. Check terminal output for OAuth flow logs and API interactions.

Environment Setup

1. Dependencies: Run mise install followed by poetry install.
2. Configuration: Copy .env.example to .env and fill in GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET.
3. Authentication: Start the app and visit /login to authorize Google access.
4. Initialization: The app automatically creates the necessary folders and spreadsheets on first use. You can also run poetry run flask --app book_lamp.app init-sheets to prepare it manually.
5. Local Run: poetry run flask --app book_lamp.app run --debug.

Commits and Change Discipline

• Use Semantic Commits (e.g., feat:, fix:, refactor:, docs:).
• Subject line: Max 50 characters.
• Body lines: Max 72 characters.
• Make small, cohesive edits. Verify each step with tests.

Tooling

• Tool Manager: mise (manages Python, Node, and Poetry versions)
• Python: 3.13.x
• Dependency Manager: Poetry (poetry install, poetry run)
• Formatters: black, isort
• Linters: ruff, mypy (strict mode)