worktree-wizard-integration

worktree-wizard Integration Knowledge

Purpose

Provide the domain knowledge needed to correctly integrate worktree-wizard into any project. This includes docker-compose conventions, env var patterns, volume mount strategies, hot-reload configurations, and justfile setup.

Core Conventions

Port Isolation via Labels

Add a wt.base-port label to every service needing port isolation. worktree-wizard adds the slot number (1-9) to compute the host port per worktree.

services:
  api:
    labels:
      wt.base-port: "8000"
    ports:
      - "${WT_API_PORT:-8000}:8000"   # host:container

Rules:

• Label value is the base port (slot 0 / main repo)
• Container-internal port never changes — only host port offsets
• Env var naming: WT_{SERVICE_NAME_UPPER}_PORT (hyphens/dots become underscores)
• Always provide :-default fallback so slot 0 works without env vars
• Services with multiple ports: use wt.base-port for the primary port only; additional ports use manual env var patterns

Data Isolation

To opt in to data isolation for a service, add a wt.data-dir label. This creates isolated data directories per slot.

  db:
    labels:
      wt.data-dir: "/var/lib/postgresql/data"
    volumes:
      - ${WT_DB_DATA:-./.docker-data/db}:/var/lib/postgresql/data

Internal Networking

Services communicate by service name over Docker's internal network. Port offsets are irrelevant for inter-service communication:

  backend:
    environment:
      - DATABASE_URL=postgresql://postgres:postgres@db:5432/app

Never use localhost or offset ports for service-to-service connections.

Volume Mounts for Hot-Reload

Mount source code into the container so host edits are visible immediately:

  backend:
    volumes:
      - ./backend:/app        # source code

For Node.js services, preserve container node_modules with an anonymous volume:

  frontend:
    volumes:
      - ./frontend:/app
      - /app/node_modules     # prevents host node_modules from shadowing

Hot-Reload per Framework

For per-framework Dockerfile patterns, dev commands, and configuration details, consult references/stack-patterns.md.

Quick reference:

Framework	Dev Command	Watches
FastAPI	uvicorn main:app --reload --host 0.0.0.0	*.py
Django	python manage.py runserver 0.0.0.0:8000	*.py
Flask	flask run --reload --host 0.0.0.0	*.py
Express	nodemon index.js or tsx watch	*.js/*.ts
Vite	vite --host 0.0.0.0 --port 3000	src/, index.html
Next.js	next dev --hostname 0.0.0.0 --port 3000	pages/, app/
Go (Air)	air	*.go
Rust (cargo-watch)	cargo watch -x run	*.rs
Rails	rails server -b 0.0.0.0	app/, config/
Spring Boot	./mvnw spring-boot:run	src/ (with devtools)

Justfile Setup

Import worktree.just from the project justfile:

import "worktree-wizard/worktree.just"

Override config vars before the import if needed:

wt-health-timeout := "90"
import "worktree-wizard/worktree.just"

.wt-required-tools

List CLI tools the project needs beyond git/just/docker:

# .wt-required-tools
node
psql

Post-Setup Hook

For custom logic after worktree creation (migrations, seed data):

#!/bin/bash
# scripts/wt-post-setup.sh
echo "Running migrations..."
docker compose exec -T db psql -U postgres -c "CREATE DATABASE app;" 2>/dev/null || true

Must be executable: chmod +x scripts/wt-post-setup.sh

.gitignore Additions

Always add:

.worktrees/
.docker-data/
.env*.local

Project Shapes

Single Service

One backend or microservice with optional database:

• 1 app service + 0-2 infrastructure services (db, cache)
• Volume mount at project root: ./:/app or ./src:/app/src

Monolith (Backend + Frontend)

Separate subdirectories for backend and frontend:

• Backend service: volume ./backend:/app
• Frontend service: volume ./frontend:/app + /app/node_modules
• Each gets its own wt.base-port
• Frontend references backend via service name internally, via WT_BACKEND_PORT for browser access

Additional Resources

Reference Files

• references/stack-patterns.md — Dockerfile templates, dev commands, and compose service blocks per framework (Python, Node, Go, Rust, Ruby, Java)