--- name: Worktree Manager slug: worktree-manager version: 1.3.0 description: "Manage Docker-based dev instances and git worktrees. Handles app container lifecycle, database seeding, and proxy route activation. Requires mysql-manager and proxy-manager to be running first." changelog: "v1.3.0: Fix dump_main_to to avoid sh -c/backtick shell injection (two docker exec), validate DB names before all SQL ops, validate instance name on all commands, align password var with MYSQL_ROOT_PASSWORD. v1.2.0: Validate instance names, add remove-worktree confirmation, warn on default password. v1.1.0: Split MySQL and proxy lifecycle into separate plugins." triggers: - "start instance" - "stop instance" - "create worktree" - "remove worktree" - "criar worktree" - "remover worktree" - "iniciar instância" - "parar instância" - "list instances" - "listar instâncias" - "worktree-manager" metadata: {"clawdbot":{"emoji":"🌿","requires":{"bins":["docker","git"]},"os":["linux","darwin"]}} --- # Worktree Manager Manages Docker app instances and git worktrees for local development. Each instance gets its own docker-compose stack (backend + frontend), isolated git branch, and `.env.worktree-` file. MySQL and nginx-proxy are managed separately by their own plugins. ## Prerequisites Start these first (order matters): 1. `proxy-manager start` — creates the shared Docker network (`nginx-proxy_net`) 2. `mysql-manager start` — starts the shared MySQL container ## Architecture ``` project/ ├── docker-compose.yml # app stack template (backend + frontend) ├── run.sh # this plugin's entry point (copy to project root) ├── .env.base # main instance env ├── .env.worktree- # per-worktree env (gitignored) └── .worktrees/ └── / # git worktree (gitignored) ``` - `main` → `.env.base`, project root - `worktree` → `.env.worktree-`, checked out at `.worktrees/` - URLs: `http://.frontend.localhost` / `http://.backend.localhost` ## Commands All commands run from the project root: ```bash ./run.sh list # show all instances + mysql/proxy status ./run.sh start [main|] # seed db, start containers, connect proxy ./run.sh stop [main|] # stop containers (db persists) ./run.sh restart [main|] # stop then start ./run.sh logs [main|] # follow container logs ./run.sh create-worktree # git worktree + branch + env file ./run.sh remove-worktree # stop containers + drop db + remove worktree ``` ## How to Execute Tasks ### Full environment setup (first time) ```bash proxy-manager/run.sh start # network + nginx-proxy mysql-manager/run.sh start # MySQL ./run.sh start main # main app instance ``` ### Create a new worktree and start it 1. `./run.sh create-worktree ` — creates branch `worktree/`, dir `.worktrees/`, env file 2. `./run.sh start ` — seeds db from main snapshot, starts containers, activates proxy route 3. URLs reported at the end ### Stop an instance ```bash ./run.sh stop ``` ### Remove a worktree (destructive — always confirm first) Confirm with user: "Remove worktree ''? Deletes containers, database, git worktree (branch `worktree/`), and `.env.worktree-`." ```bash ./run.sh remove-worktree ``` ### List all instances ```bash ./run.sh list ``` ## What `start` Does 1. Checks MySQL container is running (exits with error if not) 2. `CREATE DATABASE IF NOT EXISTS` for the instance 3. For non-main instances: dumps `codai_main` → instance db 4. `docker compose up --build -d` 5. `docker network connect` — proxy to instance network (activates routes) ## Rules - Always check `./run.sh list` before starting — it shows MySQL/proxy status. - Always confirm before `remove-worktree` — it is irreversible. - After `start`, print the frontend and backend URLs. - If `./run.sh` is not executable: `chmod +x run.sh` - `.env.worktree-*` files and `.worktrees/` dir must be gitignored. ## Configuration | Variable | Default | Purpose | |-------------------|---------------------|--------------------------------| | `MYSQL_CONTAINER` | `codai_db` | MySQL container name | | `MYSQL_ROOT_PASS` | `secret` | MySQL root password | | `MYSQL_MAIN_DB` | `codai_main` | Source DB for snapshots | | `PROXY_CONTAINER` | `codai_nginx_proxy` | nginx-proxy container name | | `PROJECT_PREFIX` | `codai-dev` | Docker Compose project prefix | ## Related Plugins - `proxy-manager` — nginx-proxy lifecycle and network management (start first) - `mysql-manager` — MySQL lifecycle and database admin (start second)

Worktree Manager

Description

Latest Changes

Install Worktree Manager with One Click