chore(localdev): development tooling

Author: kojiromike

.github/copilot-instructions.md

@@ -587,9 +587,88 @@ Before considering work complete:
 
 ---
 
+## Development Tooling: Taskfile vs Composer Scripts
+
+This module uses **both Taskfile and Composer scripts** with distinct responsibilities:
+
+**Taskfile:** Infrastructure operations (Docker, database, module management)
+**Composer scripts:** Code quality checks (phpcs, phpstan, rector)
+
+**Why Both?**
+- Composer scripts work in **any environment** (local, Docker, CI)
+- Taskfile provides **convenience wrappers** and **Docker orchestration**
+- Clear separation prevents bloated composer.json
+- Taskfile can call Composer scripts for code quality
+
+## Development Taskfile
+
+This module uses **Taskfile** (taskfile.dev) for development automation. When suggesting development commands, **prefer Taskfile for infrastructure operations** and **Composer scripts for code quality**.
+
+### When to Suggest Taskfile vs Composer
+
+**Always suggest Taskfile for:**
+- Docker operations: `task dev:start`, `task dev:logs`, `task dev:port`
+- Module cleanup: `task module:cleanup`, `task module:tables`
+- Database ops: `task db:shell`, `task db:export`
+
+**Suggest either Taskfile OR Composer for code quality:**
+- Code checks: `task check` OR `composer phpcs && composer phpstan`
+- Auto-fix: `task check:fix` OR `composer phpcbf`
+- In CI context: prefer `composer <script>` (no Docker dependency)
+- In local dev: prefer `task check` (convenience wrapper)
+
+**Examples:**
+- Start Docker → `task dev:start` (not `docker compose up`)
+- Clean tables → `task module:cleanup` (not raw SQL)
+- Run checks → `task check` OR `composer phpcs` (both valid)
+- View logs → `task dev:logs` (not `docker compose logs`)
+
+### Common Tasks
+
+```bash
+# Docker
+task dev:start          # Start environment
+task dev:logs           # View logs
+task dev:port           # Get URL
+task dev:shell          # Container shell
+
+# Module
+task module:cleanup     # Drop tables
+task module:tables      # List tables
+task module:data        # Show counts
+
+# Database
+task db:shell           # MariaDB CLI
+task db:query -- "SQL"  # Run query
+
+# Code Quality
+task check              # All checks
+task check:fix          # Auto-fix
+
+# Workflows
+task setup              # Complete setup
+task workflow:reinstall # Clean reinstall
+```
+
+### Why Taskfile + Composer (Not Just One)
+
+**Taskfile advantages:**
+- ✅ Self-documenting (`task --list`)
+- ✅ Safety prompts on destructive operations
+- ✅ Docker orchestration without raw commands
+- ✅ Complex bash logic and workflows
+- ✅ Variables and reusability
+
+**Composer scripts advantages:**
+- ✅ Work in any environment (no Docker needed)
+- ✅ Familiar to all PHP developers
+- ✅ CI/CD friendly (no additional tools)
+- ✅ Standard for PHP projects
+- ✅ No dependencies outside PHP ecosystem
+
 ## Docker Development Environment
 
-This module includes a Docker Compose setup for local development. When suggesting Docker-related commands:
+This module includes a Docker Compose setup for local development. Raw Docker commands are available but Taskfile is preferred:
 
 ### Common Docker Commands
 
@@ -670,8 +749,10 @@ When suggesting code completions:
 8. **Exception handling** - Use custom module exceptions, not die/exit
 9. **Template rendering** - Suggest Twig templates, not inline HTML
 10. **Type casting** - Cast request values: `(string)$request->request->get('field', '')`
-11. **Docker awareness** - When suggesting Docker commands, use `docker compose exec`
-12. **Database access** - Use QueryUtils for all database operations, never direct SQL functions
-13. **MariaDB from Docker** - Use `mariadb` command (not `mysql`)
-14. **Use git commands** - Use `git ls-files`, `git grep` instead of `find`, `grep` for file operations
-15. **Use pre-commit/composer** - Never suggest manual syntax checks; use `pre-commit run -a` or `composer check`
+11. **Prefer Taskfile** - Suggest `task <name>` over raw Docker/composer commands when appropriate
+12. **Docker awareness** - When suggesting Docker commands, use `docker compose exec`
+13. **Database access** - Use QueryUtils for all database operations, never direct SQL functions
+14. **MariaDB from Docker** - Use `mariadb` command (not `mysql`)
+15. **Use git commands** - Use `git ls-files`, `git grep` instead of `find`, `grep` for file operations
+16. **Use pre-commit/composer** - Never suggest manual syntax checks; use `pre-commit run -a` or `composer check`
+17. **Show task list** - When user asks what they can do, suggest `task --list`

CLAUDE.md

@@ -678,6 +678,132 @@ private function redirect(Request $request): RedirectResponse
 - This blocks the iframe with: "Firefox will not allow Firefox to display the page if another site has embedded it"
 - Solution: Always use `$request->server->get('SCRIPT_NAME')` for redirects
 
+## Development Tooling: Taskfile vs Composer Scripts
+
+### Separation of Concerns
+
+This module uses **both Taskfile and Composer scripts**, each with distinct responsibilities:
+
+**Taskfile is for:**
+- ✅ Docker orchestration (start, stop, logs, exec)
+- ✅ Database operations (import, export, queries via Docker)
+- ✅ Module management (cleanup, table inspection)
+- ✅ Complex workflows with prompts (destructive operations)
+- ✅ Infrastructure commands that don't run in all environments
+
+**Composer scripts are for:**
+- ✅ Code quality checks (phpcs, phpstan, rector)
+- ✅ PHP operations that work in any environment
+- ✅ CI/CD pipeline tasks
+- ✅ Commands that don't require Docker context
+
+**Why This Separation?**
+- Composer scripts work **everywhere** (local, Docker, CI, production)
+- Taskfile provides **convenience wrappers** and **orchestration**
+- Clear separation prevents tool bloat in composer.json
+- Taskfile can call Composer scripts (but not vice versa)
+
+### Development Taskfile
+
+#### Overview
+
+This module uses **Taskfile** for development automation. When users ask for common development tasks, suggest using the Taskfile instead of raw Docker commands.
+
+### When to Suggest Taskfile
+
+**Always suggest Taskfile for:**
+- Starting/stopping Docker environment
+- Database operations (cleanup, export, import)
+- Running code quality checks
+- Module installation/cleanup
+- Viewing logs
+
+**Example responses:**
+- User: "Start Docker" → Suggest: `task dev:start`
+- User: "Clean up tables" → Suggest: `task module:cleanup`
+- User: "Run checks" → Suggest: `task check`
+- User: "Show me the database tables" → Suggest: `task module:tables`
+
+### Common Tasks Reference
+
+**Docker Environment:**
+```bash
+task dev:start          # Start Docker with health check
+task dev:stop           # Stop (keeps data)
+task dev:restart        # Restart services
+task dev:reset          # Complete wipe (prompts)
+task dev:logs           # Follow logs
+task dev:logs:errors    # Error logs only
+task dev:port           # Get OpenEMR URL
+task dev:shell          # Container bash
+task dev:status         # Health check
+```
+
+**Module Management:**
+```bash
+task module:cleanup     # Drop all tables (prompts)
+task module:tables      # List module tables
+task module:data        # Show data counts
+task module:install     # Installation instructions
+```
+
+**Database:**
+```bash
+task db:shell           # MariaDB shell
+task db:export          # Export to backup.sql
+task db:import          # Import from backup.sql
+task db:query -- "SQL"  # Run ad-hoc query
+```
+
+**Code Quality (calls Composer scripts):**
+```bash
+task check              # All checks (calls: pre-commit run -a)
+task check:phpcs        # Code style (calls: composer phpcs)
+task check:phpstan      # Static analysis (calls: composer phpstan)
+task check:fix          # Auto-fix (calls: composer phpcbf)
+```
+
+**Note:** Code quality tasks delegate to Composer scripts. You can also run `composer phpcs`, `composer phpstan`, etc. directly.
+
+**Quick Workflows:**
+```bash
+task setup              # Complete setup
+task workflow:reinstall # Clean reinstall
+task workflow:reset     # Full reset
+```
+
+### Taskfile Best Practices for AI Agents
+
+1. **Prefer Taskfile over raw commands** - It's more user-friendly and self-documenting
+2. **Show available tasks** - Suggest `task --list` when user asks what they can do
+3. **Mention safety features** - Note that destructive tasks prompt for confirmation
+4. **Combine with explanations** - Explain what the task does, not just the command
+5. **Know when to use Composer instead** - For code quality checks that work in CI, suggest `composer phpcs` or `task check` interchangeably
+
+**Good Example:**
+```
+To clean up the database tables for a fresh reinstall:
+task module:cleanup
+
+This will drop all module tables and prompt for confirmation.
+After cleanup, reinstall via OpenEMR's module manager.
+```
+
+**Bad Example:**
+```
+Run: docker compose exec -T mysql mariadb -uroot -proot openemr < cleanup.sql
+```
+
+### Available Tasks Quick Reference
+
+Use `task --list` to show all 29 tasks organized by category:
+- Docker Environment (9 tasks)
+- Module Management (4 tasks)
+- Database Operations (4 tasks)
+- Code Quality (4 tasks)
+- Development Helpers (5 tasks)
+- Quick Workflows (3 tasks)
+
 ## Docker Development Environment
 
 ### Quick Start Commands

README.md

@@ -37,6 +37,20 @@ A HIPAA-compliant, omnichannel patient communication module for OpenEMR using th
 
 ## Installation
 
+### Important Note About Uninstall/Reinstall
+
+**OpenEMR does not automatically drop module tables on uninstall.** If you need to reinstall the module cleanly:
+
+```bash
+# Option 1: Via Docker (if using Docker environment)
+docker compose exec -T mysql mariadb -uroot -proot openemr < cleanup.sql
+
+# Option 2: Via phpMyAdmin or MySQL client
+# Connect to your OpenEMR database and run cleanup.sql
+```
+
+This will drop all module tables and allow a clean reinstallation.
+
 ### Via Composer (Recommended)
 
 1. Navigate to your OpenEMR installation directory
@@ -314,6 +328,38 @@ See [`POLLING-ARCHITECTURE.md`](./POLLING-ARCHITECTURE.md) for detailed implemen
 
 ## Development
 
+### Development Taskfile
+
+This module includes a **Taskfile** for common development tasks:
+
+```bash
+# Install Task (if not already installed)
+# macOS
+brew install go-task
+
+# Linux
+sh -c "$(curl --location https://taskfile.dev/install.sh)" -- -d -b ~/.local/bin
+
+# Show all available tasks
+task --list
+
+# Quick start
+task setup                    # Complete setup (install, prebuild, start)
+task dev:start                # Start Docker environment
+task dev:port                 # Get OpenEMR URL
+task module:cleanup           # Clean database for reinstall
+task check                    # Run all code quality checks
+```
+
+**Common tasks:**
+- `task dev:start` - Start Docker environment
+- `task dev:logs` - View live logs
+- `task dev:port` - Get OpenEMR access URL
+- `task module:cleanup` - Drop tables for clean reinstall
+- `task db:shell` - Access database
+- `task check` - Run pre-commit checks
+- `task --list` - See all available tasks
+
 ### Docker Development Environment
 
 Quick setup for local module development: