emulator-env

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 + dashboard
• status: 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

• Dashboard: http://localhost:3333
• Emulator UI: http://localhost:4000
• Functions: http://localhost:5001

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.