Tested build workflow locally with success

Author: mekarpeles

.github/agents/open-library-instructions.md

@@ -2,15 +2,19 @@
 
 This document provides step-by-step instructions for GitHub Copilot agents working on Open Library tasks. Follow these instructions to set up, build, test, and verify changes.
 
+> **Note**: If `docker compose` (with space) fails with "unknown command", use `docker-compose` (with hyphen) instead. This is required when using colima or Docker without the buildx plugin.
+
 ## Repository Structure
 
 Open Library is a Python/JavaScript web application built with:
+
 - **Backend**: Python 3.12, web.py framework, Infogami wiki system
 - **Frontend**: JavaScript/Vue.js, LESS/CSS, Lit web components
 - **Infrastructure**: Docker Compose for local development
 - **Database**: PostgreSQL, Solr for search
 
 ### Key Directories
+
 - `openlibrary/core/` - Core Open Library functionality
 - `openlibrary/plugins/` - Models, controllers, and view helpers
 - `openlibrary/views/` - Views for rendering web pages
@@ -24,34 +28,40 @@ Open Library is a Python/JavaScript web application built with:
 ## Initial Setup
 
 ### 1. Check Docker Installation
+
 ```bash
 docker --version
-docker compose version
+docker-compose version  # or "docker compose version" if using Docker Desktop with buildx plugin
 docker run hello-world
 ```
 
 ### 2. Build the Docker Environment
+
 ```bash
 # From the repository root
-docker compose build
+docker-compose build  # or "docker compose build" if using Docker Desktop with buildx plugin
 ```
+
 This takes 15-30 minutes on first run. If it times out, re-run the command.
 
 ### 3. Start the Application
+
 ```bash
 # Start all services
-docker compose up -d
+docker-compose up -d  # or "docker compose up -d" if using Docker Desktop with buildx plugin
 
 # View logs to confirm startup
-docker compose logs -f --tail=50 web
+docker-compose logs -f --tail=50 web  # or "docker compose logs -f --tail=50 web"
 ```
 
 The application is ready when you see repeating log entries like:
+
 ```
 infobase_1 | 172.19.0.5:45716 - - [16/Feb/2023 16:54:10] "HTTP/1.1 GET /openlibrary.org/log/2023-02-16:0" - 200 OK
 ```
 
 ### 4. Verify the Application is Running
+
 - Visit http://localhost:8080 in your browser
 - You should see the Open Library homepage with "development version" banner
 - Services are available at:
@@ -76,51 +86,60 @@ docker compose run --rm home make lit-components  # Lit web components
 ```
 
 ### Install Node Dependencies (if package.json changes)
+
 ```bash
 docker compose run --rm home npm install --no-audit
 ```
 
 ### Install Python Dependencies (if requirements.txt changes)
+
 ```bash
 # Rebuild the home container
 docker compose build home
 ```
 
 ### Update Git Submodules (e.g., infogami)
+
 ```bash
 docker compose run --rm home sh -c "git submodule init && git submodule sync && git submodule update"
 ```
 
 ## Running Tests
 
 ### Run All Tests
+
 ```bash
 docker compose run --rm home make test
 ```
 
 This runs:
+
 1. Python tests (pytest)
 2. JavaScript tests (jest)
 3. i18n validation tests
 
 ### Run Python Tests Only
+
 ```bash
 docker compose run --rm home make test-py
 # Or with pytest directly:
 docker compose run --rm home pytest . --ignore=infogami --ignore=vendor --ignore=node_modules
 ```
 
 ### Run JavaScript Tests Only
+
 ```bash
 docker compose run --rm home npm run test:js
 ```
 
 ### Run i18n Tests
+
 ```bash
 docker compose run --rm home make test-i18n
 ```
 
 ### Run Specific Test File
+
 ```bash
 docker compose run --rm home pytest tests/unit/test_something.py
 docker compose run --rm home pytest tests/unit/test_something.py::test_specific_function
@@ -129,6 +148,7 @@ docker compose run --rm home pytest tests/unit/test_something.py::test_specific_
 ## Linting and Code Quality
 
 ### Pre-commit Hooks (Recommended)
+
 The repository uses pre-commit hooks for automated linting. These run automatically in CI but should be run locally:
 
 ```bash
@@ -144,6 +164,7 @@ docker compose run --rm home pre-commit run --all-files
 ```
 
 ### Python Linting
+
 ```bash
 # Run ruff linter (primary Python linter)
 docker compose run --rm home make lint
@@ -161,6 +182,7 @@ docker compose run --rm home python -m mypy openlibrary/
 ```
 
 ### JavaScript Linting
+
 ```bash
 # Lint JavaScript and Vue files
 docker compose run --rm home npm run lint:js
@@ -170,6 +192,7 @@ docker compose run --rm home npm run lint-fix:js
 ```
 
 ### CSS Linting
+
 ```bash
 # Lint CSS/LESS files
 docker compose run --rm home npm run lint:css
@@ -179,6 +202,7 @@ docker compose run --rm home npm run lint-fix:css
 ```
 
 ### All Linting Together
+
 ```bash
 # Run all linters (check only, no fixes)
 docker compose run --rm home npm run lint  # JS + CSS
@@ -193,29 +217,35 @@ docker compose run --rm home python -m black .             # Python formatting
 ## Internationalization (i18n)
 
 ### Extract Messages (Create/Update .pot file)
+
 ```bash
 docker compose run --rm home python ./scripts/i18n-messages extract
 ```
 
 ### Compile Messages
+
 ```bash
 docker compose run --rm home make i18n
 # Or:
 docker compose run --rm home python ./scripts/i18n-messages compile
 ```
 
 ### Validate i18n for Specific Locales
+
 ```bash
 docker compose run --rm home python ./scripts/i18n-messages validate de es fr hr it ja zh
 ```
 
 ## Development Workflow
 
 ### 1. Make Code Changes
+
 Edit files in your local repository. Changes are automatically synced to the Docker container via volume mounts.
 
 ### 2. Restart Services (if needed)
+
 Most Python changes require a restart:
+
 ```bash
 docker compose restart web
 # Or for all services:
@@ -225,6 +255,7 @@ docker compose restart
 Frontend asset changes require rebuilding (see "Building Assets" section).
 
 ### 3. View Logs
+
 ```bash
 # View logs for a specific service
 docker compose logs -f web
@@ -236,6 +267,7 @@ docker compose logs -f
 ```
 
 ### 4. Access Container Shell
+
 ```bash
 # Open bash in the web container
 docker compose exec web bash
@@ -245,6 +277,7 @@ docker compose run --rm home bash
 ```
 
 ### 5. Run Commands in Container
+
 ```bash
 # Format: docker compose run --rm home <command>
 docker compose run --rm home python scripts/some_script.py
@@ -254,12 +287,15 @@ docker compose run --rm home psql -h db -U openlibrary openlibrary
 ## Common Development Tasks
 
 ### Clear Browser Cache
+
 If changes aren't appearing:
+
 1. Hard refresh: Ctrl+Shift+R (Linux/Windows) or Cmd+Shift+R (Mac)
 2. Clear browser cache completely
 3. Check that assets were rebuilt (check timestamps in `static/build/`)
 
 ### Database Operations
+
 ```bash
 # Connect to PostgreSQL
 docker compose exec db psql -U openlibrary openlibrary
@@ -269,6 +305,7 @@ docker compose run --rm home python scripts/run_migrations.py
 ```
 
 ### Solr Reindexing (if needed)
+
 ```bash
 # Note: This is a long-running operation
 docker compose run --rm home make reindex-solr
@@ -277,18 +314,22 @@ docker compose run --rm home make reindex-solr
 ## Cleanup and Reset
 
 ### Stop Services
+
 ```bash
 docker compose down
 ```
 
 ### Remove Volumes (Reset Database)
+
 ```bash
 docker compose down
 docker compose rm -v
 ```
 
 ### Full Environment Reset
+
 If you encounter persistent issues:
+
 ```bash
 # Stop everything
 docker compose down
@@ -312,11 +353,13 @@ docker compose up -d
 When working on an Open Library issue, follow this workflow:
 
 ### 1. Understand the Task
+
 - Read the issue description carefully
 - Review related files and code
 - Check existing tests
 
 ### 2. Set Up Environment
+
 ```bash
 # Ensure services are running
 docker compose up -d
@@ -326,22 +369,26 @@ curl http://localhost:8080
 ```
 
 ### 3. Make Changes
+
 - Edit the necessary files
 - Follow existing code style and patterns
 - Add or update tests as needed
 
 ### 4. Build Assets (if frontend changes)
+
 ```bash
 # Build affected assets
 docker compose run --rm home npm run build-assets
 ```
 
 ### 5. Compile i18n (if template changes)
+
 ```bash
 docker compose run --rm home make i18n
 ```
 
 ### 6. Run Linters
+
 ```bash
 # Python
 docker compose run --rm home make lint
@@ -358,6 +405,7 @@ docker compose run --rm home npm run lint-fix
 ```
 
 ### 7. Run Tests
+
 ```bash
 # Run relevant tests
 docker compose run --rm home pytest tests/unit/test_your_feature.py
@@ -367,12 +415,14 @@ docker compose run --rm home make test
 ```
 
 ### 8. Manual Verification
+
 - Restart services if needed: `docker compose restart web`
 - Test in browser at http://localhost:8080
 - Verify the changes work as expected
 - Check for console errors in browser dev tools
 
 ### 9. Final Checks
+
 - Run pre-commit hooks: `docker compose run --rm home pre-commit run --all-files`
 - Ensure all tests pass
 - Verify linting passes
@@ -381,14 +431,17 @@ docker compose run --rm home make test
 ## Troubleshooting
 
 ### "No module named 'infogami'"
+
 ```bash
 docker compose run --rm home sh -c "git submodule init && git submodule sync && git submodule update"
 ```
 
 ### "Cannot allocate memory" Errors
+
 Increase Docker's RAM allocation to at least 4GB and swap to 2GB in Docker Desktop settings.
 
 ### Port Already in Use
+
 ```bash
 # Check what's using the port
 lsof -i :8080  # or netstat -an | grep 8080
@@ -397,6 +450,7 @@ lsof -i :8080  # or netstat -an | grep 8080
 ```
 
 ### Container Keeps Restarting
+
 ```bash
 # Check logs for errors
 docker compose logs web
@@ -408,6 +462,7 @@ docker compose logs web
 ```
 
 ### Changes Not Appearing
+
 1. Rebuild assets: `docker compose run --rm home npm run build-assets`
 2. Restart service: `docker compose restart web`
 3. Hard refresh browser: Ctrl+Shift+R