Subwave Worktree Dev

SUB/WAVE worktree dev setup

Get the SUB/WAVE dev stack running from inside a git worktree so branch changes can be tested without touching the main checkout.

Why a worktree needs prep

A worktree checks out every tracked file, so all source is already there. But the dev stack also depends on gitignored files that do not travel with a worktree checkout:

state/ is mirrored from main so the worktree boots into the same configured station — same LLM provider, same personas, same library moods, same jingles — ready to test branch changes against real data. Runtime state (queue.json, session.json, archive/, logs/, listeners.jsonl, now-playing.json) is not copied, since those would clash with what the worktree's own containers produce fresh on first boot. The broadcast container generates its own state/icecast-secrets.env on first boot, so worktrees never need to copy icecast config either.

Two load-bearing facts

1. One stack at a time. Both compose files use fixed container names (sub-wave-broadcast, …) and host ports (Web 7700, Controller 7701, Icecast 7702). A worktree stack and the main-checkout stack collide — stop whatever is running before starting another.
2. Controller changes need --build, web changes do not. The controller image COPYs its source at build time, so testing worktree controller code requires docker compose up -d --build. The web dev server (npm run dev) hot-reloads from the worktree filesystem, so UI changes appear with no build.

Workflow

Step 0 — Identify the worktree

The target worktree is usually the session's current directory. Confirm it is a linked worktree and not the main checkout:

bashCopy code
git rev-parse --absolute-git-dir          # a worktree's is <main>/.git/worktrees/<name>
git worktree list                         # shows the main tree + every linked worktree

If the user named a specific worktree path, use that.

Step 1 — Stop any running stack

Only one stack can run. Stop whatever is up (it may be the main checkout's):

bashCopy code
# Kill the web dev server if it holds :7700 — but only if it is `node`,
# never macOS ControlCenter/AirPlay.
WEB_PID=$(lsof -nP -iTCP:7700 -sTCP:LISTEN -t 2>/dev/null | head -1)
[ -n "$WEB_PID" ] && ps -p "$WEB_PID" -o comm= | grep -qi node && kill "$WEB_PID"

# Bring down whichever dev stack is up. The compose file lives at the
# checkout root (not under docker/); container names are global, so any
# checkout's docker-compose.dev.yml targets the running containers.
docker compose -f <some-checkout>/docker-compose.dev.yml down

Step 2 — Prep the worktree

Run the bundled script. It copies the env files, mirrors the operator's declarative state/ from main (settings, moods, sfx, jingles, sessions, voice), and runs npm install for the web app. <skill base directory> is the absolute path shown as "Base directory for this skill" when the skill loads.

bashCopy code
bash "<skill base directory>/scripts/prep-worktree.sh" <worktree-path>

Flags: --reset-state wipes and re-scaffolds state/ (use when the user wants a clean slate); --skip-npm skips the dependency install (use when node_modules is already good). The script is idempotent — re-running it only fills in what is missing, never overwrites a file the worktree already has.

If the user opens the player from another device (e.g. over Tailscale), pass that host as SUBWAVE_DEV_HOST=<ip> so a scaffolded web/.env.local points there, and start the web server with SUBWAVE_DEV_ORIGINS=<ip> npm run dev — Next dev blocks /_next/* for non-localhost origins otherwise.

If /state still reports needsSetup: true after boot, the root .env has no NAVIDROME_* and main had no state/setup-config.json — that is a fresh station headed for /onboarding, not a fault. Add the creds to the worktree's root .env and docker compose -f docker-compose.dev.yml up -d controller (env_file changes need a recreate, not a restart).

Step 3 — Start the stack from the worktree

Compose files now live at the worktree root (not under docker/):

bashCopy code
cd <worktree-path> && docker compose -f docker-compose.dev.yml up -d --build

--build is required so the worktree's controller source is baked into the image. The first build is slow (all services); later builds only rebuild changed layers. Then start the web dev server in the background (it is a long-running foreground process):

bashCopy code
cd <worktree-path>/web && npm run dev

Step 4 — Verify on-air

Give Liquidsoap ~5s to connect to Icecast, then probe the controller:

bashCopy code
sleep 5
curl -sf http://localhost:7701/health                               # expect {"status":"on-air"}
curl -sf -o /dev/null -w '%{http_code}\n' http://localhost:7700      # expect 200

If /health fails, peek at docker compose logs --tail=30 controller broadcast and surface the error. A fresh state/ is normal — an empty queue and default settings on first boot are expected, not faults.

Iterating

• Web/UI change — nothing to do; npm run dev hot-reloads it.
• Controller source change — rebuild just that service: cd <worktree-path> && docker compose -f docker-compose.dev.yml up -d --build controller.
• liquidsoap/radio.liq change — it is bind-mounted in dev; just docker compose restart broadcast.

Allowed without confirmation

• Running scripts/prep-worktree.sh (copies env files, scaffolds state/, npm install)
• docker compose up -d --build / down against a worktree's dev compose file
• npm run dev / killing a node process on :7700
• Reading logs, curl health probes

Confirm before running

• --reset-state when state/ already has real data the user may want
• docker compose down -v (wipes volumes)
• Killing a non-node process on :7700
• Touching the main checkout's controller/.env, state/, or config

When NOT to use this skill / hand off

• Main checkout, not a worktree → use subwave-control to start/stop.
• Production (docker-compose.yml or docker-compose.byo.yml) → use subwave-control.
• First-time repo setup, git pull + rebuild, jingle generation, config changes → use subwave-deploy.