run-services

# Run Services

Start all local development services with pre-flight dependency checks and automatic error recovery.

## Overview

This command automates the full startup workflow:
0. Smart port selection — auto-detects free port group or reuses current worktree's ports
1. Pre-flight dependency checks (uv sync, venv, npm, worktree editable packages)
2. Stops any existing services (only if needed)
3. Starts all services via `run_services.sh`
4. Health-checks each service
5. Diagnoses and fixes failures, then retries (up to 2 retries)

## Port Configuration

Ports are allocated in groups of 3 with a +10 offset between groups:

| Group | Frontend | Backend | Docs |
|-------|----------|---------|------|
| Default | 8080 | 8081 | 8082 |
| +10 | 8090 | 8091 | 8092 |
| +20 | 8100 | 8101 | 8102 |
| +30 | 8110 | 8111 | 8112 |
| +40 | 8120 | 8121 | 8122 |

| Service | Env Var | Base Port |
|---------|---------|-----------|
| Frontend (Next.js) | `FRONTEND_PORT` | 8080 |
| Backend (FastAPI) | `BACKEND_PORT` | 8081 |
| Docs (Fumadocs) | `DOCS_PORT` | 8082 |
Step 0 (Smart Port Selection) determines which group to use automatically, unless ports are already set via environment variables.

## Execution Steps

### Step 0: Smart Port Selection

**Pre-check:** If `BACKEND_PORT`, `FRONTEND_PORT`, or `DOCS_PORT` are already set in the environment, skip auto-detection entirely and use those values directly. Report "Using pre-configured ports" and proceed to Step 1.

**0.1** Get current worktree root:
```bash
WORKTREE_ROOT=$(git rev-parse --show-toplevel)
```

**0.2** For each port group (offset 0, 10, 20, 30, 40 — max 5 attempts), check all 3 ports in the group. For each port, determine its status:

```bash
PID=$(lsof -t -i:$PORT 2>/dev/null | head -1)
```

If no PID → port is **free**.

If PID exists, get the process's working directory:
```bash
PROC_CWD=$(lsof -a -p $PID -d cwd -Fn 2>/dev/null | tail -1 | sed 's/^n//')
```

Then classify:
- **own** — `$PROC_CWD` starts with `$WORKTREE_ROOT` (use prefix match, since child processes like Next.js run from subdirectories like `$WORKTREE_ROOT/reflexio/website`)
- **other** — `$PROC_CWD` does NOT start with `$WORKTREE_ROOT`

**0.3** Decision per group:
- All 3 ports are **free** or **own** → **use this group**. Any "own" ports will be restarted in Step 3.
- Any port is **other** → **skip this group**, try the next offset (+10)
- All 5 groups exhausted → report error: "All port groups (8080-8122) are occupied by other worktrees. Free some ports or set BACKEND_PORT/FRONTEND_PORT/DOCS_PORT manually."

**0.4** Export the chosen ports:
```bash
export FRONTEND_PORT=<8080+N>
export BACKEND_PORT=<8081+N>
export DOCS_PORT=<8082+N>
export API_BACKEND_URL="http://localhost:${BACKEND_PORT}"
```

Report which group was selected and why, e.g.:
- "Using default ports (8080/8081/8082) — all free"
- "Using default ports (8080/8081/8082) — restarting own services"
- "Using offset +10 ports (8090/8091/8092) — default ports occupied by another worktree"

Also record whether any ports in the chosen group were "own" (needs stop) or all "free" (skip stop).

### Step 1: Pre-flight Dependency Checks

Run these checks before starting anything. They are idempotent and fast when deps are already installed.

**Python dependencies (run first — creates `.venv` if missing):**
```bash
uv sync
```

**Activate virtual environment (after `uv sync` so `.venv` exists):**
```bash
source .venv/bin/activate
```

**Worktree editable packages:**
In a git worktree, `uv sync` may resolve `reflexio_commons` and `reflexio_client` to a different worktree's path. Check and fix:
```bash
python -c "import reflexio_commons; import os; assert os.path.abspath(reflexio_commons.__file__).startswith(os.path.abspath('.'))" 2>/dev/null || uv pip install -e reflexio/reflexio_commons -e reflexio/reflexio_client
```

**Frontend dependencies (reflexio/website):**
Check if `node_modules` exists and has content. If missing or empty, install:
```bash
ls reflexio/website/node_modules/.package-lock.json 2>/dev/null || (cd reflexio/website && npm install)
```

**Docs dependencies (reflexio/public_docs):**
Check if `node_modules` exists and has content. If missing or empty, install:
```bash
ls reflexio/public_docs/node_modules/.package-lock.json 2>/dev/null || (cd reflexio/public_docs && npm install)
```

### Step 2: Stop Existing Services (Conditional)

**If any ports in the chosen group were classified as "own" in Step 0:** stop existing services first:
```bash
./stop_services.sh
```
Wait 2 seconds for ports to fully release.

**If all ports were "free":** skip this step entirely — nothing to stop.

### Step 3: Start Services

Run `run_services.sh` in the background with the exported port variables:
```bash
FRONTEND_PORT=$FRONTEND_PORT BACKEND_PORT=$BACKEND_PORT DOCS_PORT=$DOCS_PORT ./run_services.sh > /tmp/reflexio-services.log 2>&1 &
```

Wait ~15 seconds for services to boot. Next.js compilation takes time on first request.

### Step 4: Health Check Each Service

Check each service individually. Use `curl --max-time 10 -s -o /dev/null -w "%{http_code}"` to get HTTP status codes.

**Backend:**
```bash
curl --max-time 10 -s -o /dev/null -w "%{http_code}" http://localhost:${BACKEND_PORT}/health
```
Expected: 200

**Frontend:**
```bash
curl --max-time 10 -s -o /dev/null -w "%{http_code}" http://localhost:${FRONTEND_PORT}
```
Expected: 200 or 3xx (redirect is OK)

**Docs:**
```bash
curl --max-time 10 -s -o /dev/null -w "%{http_code}" http://localhost:${DOCS_PORT}
```
Expected: 200 or 3xx (redirect is OK)

A status of `000` means the service is not responding at all.

### Step 5: On Failure — Diagnose and Fix

If any health check fails, read the log for error details:
```bash
cat /tmp/reflexio-services.log
```

Also check if processes are even running:
```bash
lsof -i:${BACKEND_PORT} -i:${FRONTEND_PORT} -i:${DOCS_PORT}
```

#### Common Failure Patterns and Fixes

**a. "Cannot find package" / "Cannot find module" (npm)**
An npm dep