ops-run-local

name	ops-run-local
description	Manage the local development environment for Expo + serverless backend projects. Supports start, stop, restart, and status for the full stack or individual services.
allowed-tools	["Bash","Read"]

Ops: Run Local

Manage the local development environment.

Argument: $ARGUMENTS — start, stop, restart, status, start-frontend, start-backend (default: start)

Path Convention

• Frontend: Current project directory (.)
• Backend: ${BACKEND_DIR:-../backend-v2} — set BACKEND_DIR in .claude/settings.local.json if your backend is elsewhere

Prerequisites (run before any operation)

1. Verify backend directory exists:

   BACKEND_DIR="${BACKEND_DIR:-../backend-v2}"
   test -d "$BACKEND_DIR" && echo "Backend dir OK: $BACKEND_DIR" || echo "ERROR: Backend dir not found at $BACKEND_DIR — set BACKEND_DIR"
   

2. Check port availability:

   lsof -i :8081 2>/dev/null | grep LISTEN
   lsof -i :3000 2>/dev/null | grep LISTEN
   

3. Verify bun is installed:

   which bun && bun --version
   

Discovery

Read the frontend package.json to find available start scripts (e.g., start:local, start:dev, start:staging). Read the backend package.json to find backend start scripts (e.g., start:local, start:dev).

Operations

start (full stack)

Start both backend and frontend for local development.

1. Start backend (background):

   cd "${BACKEND_DIR:-../backend-v2}" && IS_OFFLINE=true bun run start:local
   

   Run this in the background using the Bash tool with run_in_background: true.

2. Wait for backend (up to 30 seconds):

   for i in $(seq 1 30); do
     curl -sf http://localhost:3000/graphql -X POST \
       -H "Content-Type: application/json" \
       -d '{"query":"{ __typename }"}' > /dev/null 2>&1 && echo "Backend ready" && break
     sleep 1
   done
   

3. Start frontend (background):

   bun run start:local
   

   Run this in the background using the Bash tool with run_in_background: true.

4. Verify frontend (up to 60 seconds — Metro bundler can be slow):

   for i in $(seq 1 60); do
     curl -sf http://localhost:8081 > /dev/null 2>&1 && echo "Frontend ready" && break
     sleep 1
   done
   

5. Report status table.

start-frontend (frontend only, pointing at remote backend)

Use when the backend is already deployed and you only need the frontend.

1. bun run start:dev
   

   Run in background.

2. Verify:

   for i in $(seq 1 60); do
     curl -sf http://localhost:8081 > /dev/null 2>&1 && echo "Frontend ready" && break
     sleep 1
   done
   

start-backend (backend only)

1. Check AWS credentials (discover profile from backend package.json scripts or remote-routine ~/.aws/config):

   aws sts get-caller-identity --profile {aws-profile} 2>/dev/null
   

   If this is an interactive local session and credentials are expired, refresh the backend's local AWS signin flow. In headless sessions, rely on the configured environment-backed AWS profile and do not start an SSO browser/device flow.

2. Start:

   cd "${BACKEND_DIR:-../backend-v2}" && IS_OFFLINE=true bun run start:local
   

   Run in background.

3. Verify:

   for i in $(seq 1 30); do
     curl -sf http://localhost:3000/graphql -X POST \
       -H "Content-Type: application/json" \
       -d '{"query":"{ __typename }"}' > /dev/null 2>&1 && echo "Backend ready" && break
     sleep 1
   done
   

stop

Kill all local services.

# Kill frontend (Metro bundler)
lsof -ti :8081 | xargs kill -9 2>/dev/null || echo "No frontend process on :8081"

# Kill backend (Serverless Offline)
lsof -ti :3000 | xargs kill -9 2>/dev/null || echo "No backend process on :3000"

# Stop Docker if running
cd "${BACKEND_DIR:-../backend-v2}" && docker compose down 2>/dev/null || true

restart

1. Run stop (above).
2. Wait 2 seconds: sleep 2
3. Run start (above).
4. Verify both services respond.

status

Check what is currently running and responsive.

echo "=== Port Check ==="
echo -n "Frontend :8081 — "; lsof -i :8081 2>/dev/null | grep LISTEN > /dev/null && echo "LISTENING" || echo "NOT LISTENING"
echo -n "Backend  :3000 — "; lsof -i :3000 2>/dev/null | grep LISTEN > /dev/null && echo "LISTENING" || echo "NOT LISTENING"

echo ""
echo "=== Health Check ==="
echo -n "Frontend :8081 — "; curl -sf -o /dev/null -w "%{http_code}" http://localhost:8081 2>/dev/null || echo "UNREACHABLE"
echo -n "Backend  :3000 — "; curl -sf -o /dev/null -w "%{http_code}" http://localhost:3000/graphql -X POST -H "Content-Type: application/json" -d '{"query":"{ __typename }"}' 2>/dev/null || echo "UNREACHABLE"

echo ""
echo "=== Docker ==="
docker compose -f "${BACKEND_DIR:-../backend-v2}/compose.yaml" ps 2>/dev/null || echo "No Docker services running"

Report results as a table:

Service	Port	Listening	Responsive
Frontend (Metro)	8081	YES/NO	YES/NO
Backend (Serverless Offline)	3000	YES/NO	YES/NO