wt

What this skill does

# Worktree Management

Worktrees allow parallel development on multiple branches, each with its own HTTPS domain. The `wt` CLI tool in `~/dev/infrastructure/bin/wt` handles everything automatically.

There are two creation modes: **fast** (default) and **full**.

## How It Works

### Fast Mode (default)

```
wt create calendar-fix
  1. git worktree add .worktrees/calendar-fix -b feature/calendar-fix
  2. Symlinks vendor/, node_modules/, .env to main project
  3. Symlinks gitignored SSL certs needed by Vite
  4. Generates nginx server config (new port)
  5. Generates Traefik routing config
  6. Regenerates TLS certificate with new SAN
  7. Writes .wt-meta (mode=fast, db=shared)
```

Result: `https://demo.kibi--calendar-fix.test` is immediately accessible. Shares database with main project. No install step needed.

Best for: frontend fixes, small bugfixes, CSS changes.

### Full Mode

```
wt create:full new-migration
  1. git worktree add .worktrees/new-migration -b feature/new-migration
  2. Runs composer install + npm install (own copies)
  3. Runs npm run build (Vite assets)
  4. Copies .env, adjusts APP_URL, DB_DATABASE, CENTRAL_DOMAIN, and SERVER_NAME
  5. Symlinks gitignored SSL certs needed by Vite
  6. Creates separate PostgreSQL database (pattern: {project}_wt_{name_underscored})
  7. Runs php artisan migrate --seed
  8. For multi-tenant projects (kibi): auto-creates demo tenant
  9. Generates nginx server config (new port)
  10. Generates Traefik routing config
  11. Regenerates TLS certificate with new SAN
  12. Writes .wt-meta (mode=full, db={project}_wt_{name_underscored})
```

Result: `https://demo.kibi--new-migration.test` with its own database, vendor/, and node_modules/.

Best for: new packages, migrations, breaking changes.

## Metadata

Each worktree contains a `.wt-meta` file that stores its configuration:

```
mode=fast|full
db=<database-name-or-shared>
```

This file is used by `wt remove` to determine cleanup steps and by `wt list` to display mode info.

## Domain Pattern

| Project Type | Main Domain | Worktree Domain |
|-------------|-------------|-----------------|
| With tenant subdomains (kibi) | `*.kibi.test` | `*.kibi--<name>.test` |
| Simple (bessler, contradoo, scada) | `project.test` | `project--<name>.test` |

The `--` separator is used because it cannot be a valid tenant name.

## Commands

All commands auto-detect the project based on the current working directory.

```bash
cd ~/dev/projects/kibi-connect/kibi

# Create worktree (fast mode - symlinks vendor/node_modules/.env, shares DB)
wt create <name> [branch] [base]

# Create worktree (full mode - own vendor/node_modules/.env, separate DB)
wt create:full <name> [branch] [base]

# Default branch: feature/<name>
# Default base: origin/develop

# List worktrees (shows mode, vendor status, database)
wt list

# Run command in worktree
wt run <name> artisan migrate
wt run <name> artisan test --filter=MyTest

# Remove worktree (cleans up routing + cert, drops DB for full mode)
wt remove <name>
```

## What the Script Does

### On `wt create` (fast mode):
1. `git fetch origin`
2. `git worktree add .worktrees/<name> -b feature/<name> origin/develop`
3. Symlinks `vendor/` and `node_modules/` to main project (relative symlinks)
4. Symlinks `.env` to main project
5. Symlinks gitignored SSL certificates needed by Vite (e.g. `certs/` directory) to main project
6. Generates deterministic port from hash of `project-name` (range 8100-8999)
7. Creates nginx config at `/opt/homebrew/etc/nginx/servers/<project>-wt-<name>.conf`
8. Creates Traefik config at `~/dev/infrastructure/traefik/dynamic/<project>-wt-<name>.yml`
9. Regenerates mkcert certificate with new SAN for the worktree domain
10. Writes `.wt-meta` with `mode=fast`
11. Reloads nginx

### On `wt create:full` (full mode):
1. `git fetch origin`
2. `git worktree add .worktrees/<name> -b feature/<name> origin/develop`
3. Runs `composer install` (own vendor/)
4. Runs `npm install` (own node_modules/)
5. Runs `npm run build` to compile Vite assets (ensures the worktree serves properly without a running Vite dev server)
6. Copies `.env` from main project
7. Adjusts `APP_URL`, `DB_DATABASE`, `CENTRAL_DOMAIN`, and `SERVER_NAME` in the copied `.env` (sets correct worktree domain)
8. Symlinks gitignored SSL certificates needed by Vite (e.g. `certs/` directory) to main project
9. Creates a separate PostgreSQL database (`{project}_wt_{name_underscored}`)
10. Runs `php artisan migrate --seed`
11. For multi-tenant projects (kibi): auto-creates the demo tenant (`php artisan kibi:create-demo-tenant`)
12. Generates deterministic port from hash of `project-name` (range 8100-8999)
13. Creates nginx config at `/opt/homebrew/etc/nginx/servers/<project>-wt-<name>.conf`
14. Creates Traefik config at `~/dev/infrastructure/traefik/dynamic/<project>-wt-<name>.yml`
15. Regenerates mkcert certificate with new SAN for the worktree domain
16. Writes `.wt-meta` with `mode=full` and `db={project}_wt_{name_underscored}`
17. Reloads nginx

### On `wt remove`:
1. Reads `.wt-meta` to determine mode
2. Removes nginx config
3. Removes Traefik config
4. Regenerates certificate without the removed SAN
5. For full mode: asks to drop the worktree database
6. `git worktree remove --force`
7. Optionally deletes the branch

### On `wt list`:
Shows all worktrees with mode (fast/full), vendor status (symlinked/independent), and database (shared/own name).

## Known Projects

Read `../setup-infra/references/projects.json` for the full project list with paths, ports, and domain patterns.

## Important Notes

- **Fast mode**: Worktrees share database, vendor/, node_modules/, and .env with the main project (via symlinks)
- **Full mode**: Worktrees have their own database, vendor/, node_modules/, and .env (independent copies)
- Each worktree gets its own nginx server block and Traefik route (both modes)
- PHP-FPM is shared across all worktrees (different document roots, same process pool)
- No extra containers or processes needed per worktree
- The `.worktrees/` directory is gitignored
- The `.wt-meta` file in each worktree tracks its mode and database name

## Troubleshooting

**"Not in a known project directory"**: `cd` into one of the known project directories first.

**502 Bad Gateway on worktree domain**: nginx config may not have reloaded. Run `nginx -s reload`.

**SSL error on worktree domain**: Certificate needs to be regenerated. Run `infra cert-regen "*.kibi--<name>.test"` or re-create the worktree.

**Port conflict**: The port is deterministic based on the project+name hash. If there's a collision, remove and recreate with a different name.