diff --git a/CLAUDE.md b/CLAUDE.md index 91bed19..633158a 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -63,8 +63,8 @@ make api # uvicorn on 127.0.0.1:8000 (docs at /docs) make dashboard # Observable preview on :3000 make check # curl /state/health -# Shortcut: db + migrate + api -make start +# Shortcut: db + migrate + api (restarts if already running) +make backend ``` The MCP server is registered in `.mcp.json` at the repo root. After `make install` creates `.venv`, restart Claude Code for `/mcp` to show `state-hub`. diff --git a/README.md b/README.md index 7a79d95..c966b90 100644 --- a/README.md +++ b/README.md @@ -88,7 +88,7 @@ Health check: `make check` ### Shortcut ```bash -make start # db + migrate + api (all in one) +make backend # db + migrate + api (restarts if already running) ``` ### Dashboard diff --git a/SCOPE.md b/SCOPE.md index d810551..6e1ff77 100644 --- a/SCOPE.md +++ b/SCOPE.md @@ -93,7 +93,7 @@ The Custodian is both an **operational system** (State Hub: PostgreSQL + FastAPI - Start with: `CLAUDE.md` (session protocol) + `README.md` (architecture overview) - Key files / directories: `state-hub/` (live API + MCP), `canon/` (governance), `workplans/` (active work), `state-hub/mcp_server/TOOLS.md` (tool reference) -- Entry points: `cd state-hub && make start` (API); Claude Code with state-hub MCP registered +- Entry points: `cd state-hub && make backend` (API); Claude Code with state-hub MCP registered --- diff --git a/state-hub/Makefile b/state-hub/Makefile index da878eb..d621d7c 100644 --- a/state-hub/Makefile +++ b/state-hub/Makefile @@ -1,4 +1,4 @@ -.PHONY: install install-cli db db-tools migrate seed api dashboard check test start clean register-project validate-adr add-domain rename-domain add-repo list-repos register-path cleanup-stale tunnel tunnel-daemon tunnel-loop tunnel-status tunnel-stop install-hooks install-hooks-all gitea-inventory +.PHONY: install install-cli db db-tools migrate seed api dashboard check test backend clean register-project validate-adr add-domain rename-domain add-repo list-repos register-path cleanup-stale tunnel tunnel-daemon tunnel-loop tunnel-status tunnel-stop install-hooks install-hooks-all gitea-inventory COMPOSE = docker compose -f infra/docker-compose.yml --env-file .env @@ -36,6 +36,7 @@ mcp-http: MCP_TRANSPORT=sse MCP_PORT=8001 uv run python mcp_server/server.py dashboard: + @pkill -f "observable preview" 2>/dev/null && echo "Stopped running dashboard" || true cd dashboard && npm run dev check: @@ -105,9 +106,16 @@ tunnel-stop: @pkill -f "autossh.*$(TUNNEL_PORT)" 2>/dev/null && echo "autossh stopped" || true @pkill -f "ssh.*-R $(TUNNEL_PORT)" 2>/dev/null && echo "ssh loop stopped" || true -start: db - sleep 3 +## Shortcut: start (or restart) the full backend — db + migrate + api. +## If the API is already running it is stopped first; postgres wait is skipped if already up. +backend: db + @echo "Waiting for postgres..."; \ + for i in 1 2 3 4 5 6 7 8 9 10; do \ + nc -z 127.0.0.1 5432 2>/dev/null && break; \ + sleep 1; \ + done $(MAKE) migrate + @pkill -f "uvicorn api.main:app" 2>/dev/null && echo "Stopped running API" || true $(MAKE) api ## Register a project: make register-project DOMAIN=railiance PROJECT_PATH=/home/worsch/railiance diff --git a/state-hub/README.md b/state-hub/README.md index 1e225de..f7a0338 100644 --- a/state-hub/README.md +++ b/state-hub/README.md @@ -42,7 +42,7 @@ make api # uvicorn :8000 --reload ### Shortcut ```bash -make start # db + sleep + migrate + api +make backend # db + migrate + api (restarts if already running) ``` ### Dashboard @@ -74,7 +74,7 @@ custodian register-project # register cwd as a Custodian project | `make api` | `uvicorn api.main:app --reload` | | `make dashboard` | Observable dev server | | `make check` | `curl /state/health` | -| `make start` | `db` + wait + `migrate` + `api` | +| `make backend` | `db` + wait + `migrate` + `api` (restarts if running) | | `make register-project DOMAIN=x PROJECT_PATH=y` | Register a project | | `make clean` | `docker compose down -v` (destroys DB volume) | diff --git a/state-hub/dashboard/src/docs/live-data.md b/state-hub/dashboard/src/docs/live-data.md index 53edf69..c1eb54c 100644 --- a/state-hub/dashboard/src/docs/live-data.md +++ b/state-hub/dashboard/src/docs/live-data.md @@ -41,7 +41,7 @@ To restart the API: cd ~/the-custodian/state-hub make api # starts uvicorn on 127.0.0.1:8000 # or, if postgres is not running: -make start # db + migrate + api +make backend # db + migrate + api (restarts if already running) ``` ---