| name | emulator-env |
| description | Start/stop/status the local test environment — Firebase Emulator Suite + dev-status dashboard (port 3333). Triggers include "에뮬레이터 띄워/내려/상태". |
| user_invocable | true |
Emulator Environment Manager
Manage the local test environment: Firebase Emulator Suite and the dev-status.js monitoring dashboard. Start background processes from the main session (background Bash) so their handles stay owned by this session — logs and shutdown remain manageable later.
Arguments
- No args or
up: start environment (reuse if already running)
down: stop emulator + dashboardstatus: report port status only, change nothing
Ports
| Service | Port |
|---|
| Firebase Auth emulator | 9099 |
| Functions emulator | 5001 |
| Firestore emulator | 8080 |
| Emulator UI | 4000 |
| Emulator Hub | 4400 |
| dev-status dashboard | 3333 |
up
1. Ensure .env.test exists
[ -f functions/secrets/.env.test ] || cp functions/secrets/.env.test.example functions/secrets/.env.test
2. Check emulator state
lsof -i :5001 -i :8080 -i :9099 -sTCP:LISTEN
- All three ports listening → emulator already running. Do NOT restart; report reuse and skip to step 4.
- Some but not all listening (zombie) → report which ports are stale, kill them (
lsof -ti :<port> | xargs kill), then continue to step 3.
- None listening → continue to step 3.
3. Start emulator (background)
Run as a background Bash process (the script internally moves to repo root where firebase.json lives):
cd functions && npm run emulator
4. Start dev-status dashboard
If port 3333 is not listening (lsof -i :3333 -sTCP:LISTEN), run as a background Bash process from the repo root:
node dev-status.js
5. Wait for ready
Poll until 5001 / 8080 / 9099 / 3333 all listen (single bash retry loop, ~60s budget):
for i in $(seq 1 30); do
up=$(for p in 5001 8080 9099 3333; do lsof -ti :$p -sTCP:LISTEN >/dev/null && echo $p; done | wc -l)
[ "$up" -ge 4 ] && echo ready && break
sleep 2
done
On timeout: read the emulator background process output and report the cause (common: port already in use, firebase CLI missing, .env.test malformed).
6. Report
down
Collect PIDs across all managed ports and SIGTERM:
for p in 9099 5001 8080 4000 4400 3333; do lsof -ti :$p -sTCP:LISTEN; done | sort -u | xargs kill 2>/dev/null
Wait a moment, then verify all ports are freed (rerun the lsof check; if something survives, report the PID instead of force-killing). Report the result.
status
Report each port's state as a table, change nothing:
for p in 9099 5001 8080 4000 4400 3333; do
pid=$(lsof -ti :$p -sTCP:LISTEN | head -1)
echo "$p ${pid:-free}"
done
Notes
npm run emulator = cd .. && firebase emulators:start — full suite (auth + functions + firestore), defined in functions/package.json.- The dashboard (
dev-status.js, repo root) monitors all service ports and can kill processes from the browser.
- To run E2E tests against this environment, see the
emulator-test skill.
