inv-runner

Python Invoke task automation for the DTX website project.

Documentation References (Single Source of Truth)

For complete command reference, consult these mkdocs files:

| Document | Content | |----------|---------| | docs/development/invoke-tasks.md | Complete invoke command reference | | docs/development/backend-quickstart.md | Backend development quickstart | | docs/development/testing.md | Testing procedures including worktree verification |

Running Invoke Commands

Method 1: PATH Prefix (Recommended for Claude)

When bash hooks block source commands, prepend the venv bin to PATH:

PATH=".venv/bin:$PATH" inv <command>

For worktrees, use the full path:

PATH="/path/to/worktree/.venv/bin:$PATH" /path/to/worktree/.venv/bin/inv <command>

Method 2: Poetry Run

poetry run inv <command>

Method 3: Activate venv

source .venv/bin/activate
inv <command>

Why PATH Matters

Invoke tasks call python manage.py or other Python commands. Without venv bin in PATH:

/bin/bash: line 1: python: command not found

PATH prefix ensures subprocess calls find the correct Python interpreter.

Key Patterns

Run vs Exec

run - One-off command in NEW container (with --rm):

inv test.run --cmd 'python manage.py test app.tests -v 2'

exec - Command in RUNNING container:

inv dev.exec backend 'python manage.py shell'

Environment-Specific Commands

All environments (dev, test, prod) support:

inv <env>.up       # Start
inv <env>.down     # Stop and remove
inv <env>.logs     # Follow logs
inv <env>.run --cmd '<cmd>'  # One-off command

Database Operations

inv db.migrate.all       # Migrations for all environments
inv db.migrate.test      # Test environment only
inv db.populate.all      # Reset and populate test DB

Adding a new Django app: inv db.migrate.* runs python manage.py makemigrations <apps> with an explicit app list defined at backend/tasks.py::apps (it does NOT auto-discover from INSTALLED_APPS). When you scaffold a new app, append it there too — otherwise makemigrations silently skips it. Reference impl: the user app entry in backend/tasks.py:27. Registering in settings.INSTALLED_APPS covers migrate but not makemigrations in this project.

Testing (Docker - Recommended)

Avoid Redis hanging issues by running tests in Docker:

inv test.run --cmd 'python manage.py test app.tests -v 2'

Cypress E2E

inv test.setup           # Full setup
inv test.spec --spec navigation  # Specific spec
inv test.headless        # All tests headless

Worktree Workflow

From worktree root:

cd /path/to/worktree
PATH=".venv/bin:$PATH" inv test.down
PATH=".venv/bin:$PATH" inv test.setup
PATH=".venv/bin:$PATH" inv db.migrate.test
PATH=".venv/bin:$PATH" inv db.populate.all
PATH=".venv/bin:$PATH" inv test.up

Common Issues

| Issue | Solution | |-------|----------| | python: command not found | Use PATH prefix method | | Redis connection errors | Use Docker: inv test.run --cmd '...' | | Tests hang on cleanup | Use Docker: inv test.run --cmd '...' | | Module not found | Ensure correct venv is activated |

When Modifying Tasks

Update these files when changing invoke tasks:

• docs/development/invoke-tasks.md (primary reference)
• docs/development/backend-quickstart.md (if backend-related)