diff --git a/CLAUDE.md b/CLAUDE.md index 633158a..14a67ff 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -58,13 +58,10 @@ make db # start postgres on 127.0.0.1:5432 make migrate # alembic upgrade head make seed # insert 6 canonical topics -# Run services -make api # uvicorn on 127.0.0.1:8000 (docs at /docs) +# Run services (each restarts the service if already running) +make api # db + migrate + uvicorn on 127.0.0.1:8000 make dashboard # Observable preview on :3000 make check # curl /state/health - -# 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 c966b90..aec085e 100644 --- a/README.md +++ b/README.md @@ -88,7 +88,7 @@ Health check: `make check` ### Shortcut ```bash -make backend # db + migrate + api (restarts if already running) +make api # db + migrate + api (restarts if already running) ``` ### Dashboard diff --git a/SCOPE.md b/SCOPE.md index 6e1ff77..0f4b1c2 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 backend` (API); Claude Code with state-hub MCP registered +- Entry points: `cd state-hub && make api` (API); Claude Code with state-hub MCP registered --- diff --git a/state-hub/Makefile b/state-hub/Makefile index 44c6492..4567d68 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 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 +.PHONY: install install-cli db db-tools migrate seed api dashboard check test 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 @@ -25,9 +25,6 @@ migrate: seed: uv run python scripts/seed.py -api: - uv run uvicorn api.main:app --reload --host 127.0.0.1 --port 8000 - ## MCP server in SSE/HTTP mode for remote Claude Code sessions (e.g. COULOMBCORE). ## Exposes the same tools as the stdio server over HTTP at http://127.0.0.1:8001/sse ## Remote clients connect via the ops-bridge tunnel (port 18001 on the remote host). @@ -106,9 +103,9 @@ 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 -## 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 +## Start (or restart) the full backend — db + migrate + uvicorn. +## Stops uvicorn on :8000 if already running, then starts fresh. +api: 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; \ @@ -116,7 +113,7 @@ backend: db done $(MAKE) migrate @fuser -k 8000/tcp 2>/dev/null && echo "Stopped running API" || true - $(MAKE) api + uv run uvicorn api.main:app --reload --host 127.0.0.1 --port 8000 ## Register a project: make register-project DOMAIN=railiance PROJECT_PATH=/home/worsch/railiance register-project: diff --git a/state-hub/README.md b/state-hub/README.md index f7a0338..eb35140 100644 --- a/state-hub/README.md +++ b/state-hub/README.md @@ -36,13 +36,7 @@ make install # uv sync make db # docker compose up postgres make migrate # alembic upgrade head (creates 5 tables) make seed # insert 6 canonical topics -make api # uvicorn :8000 --reload -``` - -### Shortcut - -```bash -make backend # db + migrate + api (restarts if already running) +make api # db + migrate + uvicorn :8000 (restarts if running) ``` ### Dashboard @@ -71,10 +65,9 @@ custodian register-project # register cwd as a Custodian project | `make db-tools` | Start postgres + pgadmin (http://127.0.0.1:5050) | | `make migrate` | `alembic upgrade head` | | `make seed` | Insert 6 canonical topics | -| `make api` | `uvicorn api.main:app --reload` | -| `make dashboard` | Observable dev server | +| `make api` | `db` + wait + `migrate` + `uvicorn` (restarts if running) | +| `make dashboard` | Observable dev server (restarts if running) | | `make check` | `curl /state/health` | -| `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 c1eb54c..274b702 100644 --- a/state-hub/dashboard/src/docs/live-data.md +++ b/state-hub/dashboard/src/docs/live-data.md @@ -39,9 +39,7 @@ To restart the API: ```bash cd ~/the-custodian/state-hub -make api # starts uvicorn on 127.0.0.1:8000 -# or, if postgres is not running: -make backend # db + migrate + api (restarts if already running) +make api # db + migrate + uvicorn (restarts if already running) ``` ---