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	8061	8062
+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	8061
Docs (Fumadocs)	DOCS_PORT	8062
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:

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:

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:

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