---
name: dev-serve
description: |
  Boots the TTRPG Initiative Tracker dev stack (Node backend + CRA frontend) for
  hands-on human testing, then opens a headed browser window the user can see and
  click. Use when user says "let me test", "open it for me", "give me a browser",
  "run it locally", "boot the app", or wants to manually use the app. Handles
  STORAGE mode selection (ws vs firebase), port collision cleanup, background
  process management, and headed agent_browser launch in one shot.
---

# dev-serve

Run the full app stack for human testing, then open a headed browser window the
user can see and drive.

## Prerequisites

- Repo root has `server/`, `shared/`, `src/` (npm workspaces).
- Node 18+.
- Ports 4001 (backend) and 3999 (frontend) free, or let this skill kill stale procs.

## Defaults

- Backend: `DB_PATH=/tmp/tracker-dev.sqlite PORT=4001`
- Frontend: `REACT_APP_STORAGE=ws` (self-hosted backend) unless user asks for firebase.
  Override: user says "firebase mode" → `REACT_APP_STORAGE=firebase` + requires
  `.env.local` with `REACT_APP_FIREBASE_*`.
- Frontend port: `3999`. Backend: `4001`.

## Steps

### 1. Kill stale procs (idempotent)

```bash
pkill -f "node server/index.js" 2>/dev/null
pkill -f "react-scripts start" 2>/dev/null
sleep 2
```

Do not error if pkill finds nothing.

### 2. Boot backend (background, log to /tmp)

```bash
rm -f /tmp/tracker-dev.sqlite*
DB_PATH=/tmp/tracker-dev.sqlite PORT=4001 nohup node server/index.js > /tmp/tracker-backend.log 2>&1 &
sleep 2
curl -s http://127.0.0.1:4001/health   # must return {"ok":true}
```

If health fails, tail `/tmp/tracker-backend.log`, diagnose, fix. Do not proceed.

### 3. Boot frontend (background, log to /tmp)

```bash
REACT_APP_STORAGE=ws \
REACT_APP_BACKEND_URL=http://127.0.0.1:4001 \
REACT_APP_BACKEND_WS=ws://127.0.0.1:4001/ws \
BROWSER=none PORT=3999 nohup npm start > /tmp/tracker-frontend.log 2>&1 &
```

Wait ~10s, then confirm compile:

```bash
grep -E "Compiled successfully|Failed to compile" /tmp/tracker-frontend.log | tail -1
```

`BROWSER=none` stops CRA from stealing focus; we open our own headed window.

### 4. Open headed browser window for user

Use `agent_browser` tool, fresh session (headed flag is launch-scoped):

```json
{
  "agent_browser": {
    "args": ["open", "http://127.0.0.1:3999", "--headed"],
    "sessionMode": "fresh",
    "timeoutMs": 20000
  }
}
```

Then snapshot to confirm UI rendered (look for "TTRPG Initiative Tracker" heading +
"Create Campaign" button, NOT "Loading campaigns..." after 2-3s).

### 5. Tell user the URL

```
App:     http://127.0.0.1:3999   (browser window open)
Backend: http://127.0.0.1:4001
Logs:    /tmp/tracker-frontend.log, /tmp/tracker-backend.log
```

User can also navigate to that URL in their own browser if they closed the
agent_browser window.

## Troubleshooting

| Symptom | Cause | Fix |
|---------|-------|-----|
| "Loading campaigns..." stuck | WS subscribe silent fail | Check `/tmp/tracker-backend.log` for WS connection; check ws.js `ensureWs` uses `.onopen/.onmessage` not `.on('open')` |
| "Configuration Error" screen | firebase mode without `.env.local`, OR init not gated on STORAGE_MODE | Confirm `STORAGE=ws`; confirm `initializeStorage()` gates firebase |
| Port 4001/3999 EADDRINUSE | stale proc | Rerun step 1 |
| Campaign created but not visible | WS broadcast not wired, or path prefix not normalized | Check ws.js `norm()` strips `artifacts/.../public/data/` |
| Headed window not on screen | remote/VM/headless env | `--headed` only guarantees browser context, not OS visibility; tell user env limitation |

## Teardown

When user done testing, kill both:

```bash
pkill -f "node server/index.js"
pkill -f "react-scripts start"
```

Or leave running if user continuing dev. Ask which.

## Storage mode notes

- `ws` (default here): self-hosted backend. Cross-device via backend WS. No Firebase creds needed.
- `firebase`: original upstream. Needs `.env.local`. Behavior identical per characterization tests.
- `memory`: in-process, tests only. Resets on reload.

Switching modes mid-session: kill procs, re-export `REACT_APP_STORAGE`, reboot.