From a1a215f24705fcd88e1b050931d4db8046664e9e Mon Sep 17 00:00:00 2001 From: grenkoff Date: Wed, 17 Jun 2026 02:38:34 +0500 Subject: [PATCH] Add /server-up and /server-down local-stack commands --- .claude/commands/server-down.md | 47 +++++++++++++++++++++ .claude/commands/server-up.md | 72 +++++++++++++++++++++++++++++++++ 2 files changed, 119 insertions(+) create mode 100644 .claude/commands/server-down.md create mode 100644 .claude/commands/server-up.md diff --git a/.claude/commands/server-down.md b/.claude/commands/server-down.md new file mode 100644 index 0000000..cd8d8e5 --- /dev/null +++ b/.claude/commands/server-down.md @@ -0,0 +1,47 @@ +--- +description: Stop the full local dev stack (frontend + API + docker infra) brought up by /server-up +allowed-tools: Bash(docker*), Bash(pkill*), Bash(curl*), Bash(cd*) +--- + +Tear down everything `/server-up` started, in reverse order: local processes first, then Docker. +This is the counterpart to `/server-up`. If `$ARGUMENTS` names a layer (`web`, `api`, `infra`), +stop only that one; otherwise stop all. + +Data is preserved: we `docker compose stop` (not `down`), so containers and named volumes survive +and `/server-up` restarts fast with the same DB contents. + +## 1. Frontend (Next.js, port 3000) +```bash +pkill -f "next dev" || true +``` +(`npm run dev` spawns `next dev` / `next-server`; the pattern catches the tree.) + +## 2. API (uvicorn, port 8000) +```bash +pkill -f "spin2note_api.main:app" || true +``` +Match on `spin2note_api.main:app` (NOT `uvicorn …`): the server runs as `uv run uvicorn …`, so +the `uvicorn` token only appears on the inner process — the `uv run` wrapper and the reloader's +child would survive and keep port 8000 open. The bare module pattern catches the whole tree. +If anything still answers on :8000 afterwards, fall back to killing by PID +(`pgrep -af "spin2note_api.main:app"` then `kill `). + +## 3. Backing infra (Docker) +```bash +docker compose stop +``` +Stops clickhouse, postgres, redis, minio, auth (and any others) without deleting them. +Use `docker compose down` instead ONLY if explicitly asked to remove containers; never add `-v` +unless the user explicitly wants to wipe data (that destroys the volumes). + +## 4. Verify everything is down +```bash +curl -s -o /dev/null -w 'api %{http_code}\n' http://localhost:8000/health 2>&1 || echo 'api down' +curl -s -o /dev/null -w 'web %{http_code}\n' http://localhost:3000 2>&1 || echo 'web down' +docker compose ps --format '{{.Service}}\t{{.Status}}' +``` +The two curls should fail to connect (port closed); `docker compose ps` should list nothing running. + +## Output +Report a compact table: layer -> stopped/still-up. Note that DB data is retained (volumes intact); +a later `/server-up` resumes from the same state. diff --git a/.claude/commands/server-up.md b/.claude/commands/server-up.md new file mode 100644 index 0000000..1f9cd14 --- /dev/null +++ b/.claude/commands/server-up.md @@ -0,0 +1,72 @@ +--- +description: Bring up the full local dev stack (docker infra + API + frontend) and verify it +allowed-tools: Bash(docker*), Bash(cd*), Bash(uv*), Bash(npm*), Bash(curl*), Bash(export*), Bash(pkill*), Read, Write +--- + +Bring up the complete local development stack and verify each layer is actually serving. +Run servers in the **background** (`run_in_background: true`); never block on them. + +## 0. Why this is not just `docker compose up` +The `api` and `worker` compose services **fail to build** (their Dockerfile copies only +`apps/api/pyproject.toml`, which requires a `README.md` that isn't in the build context → +`OSError: Readme file does not exist: README.md`). So we run the **backing stores in Docker** +but run **API + frontend locally** (uv / npm) instead. Do NOT `docker compose up` without a +service list — it will try to build `api` and abort the whole bring-up. + +## 1. Backing infra (Docker) +Start only the stores + auth, then wait for health: +```bash +docker compose up -d clickhouse postgres redis minio auth +docker compose ps --format '{{.Service}}\t{{.Status}}' +``` +All five should report `healthy`/`Up`. (`postgres` must be healthy before `auth` starts — compose +handles the ordering.) + +## 2. Ensure `apps/api/.env` exists +The local API (uvicorn) needs two overrides that differ from the in-code defaults. Create +`apps/api/.env` if missing (do not clobber an existing one without checking it): +``` +# GoTrue signs HS256 tokens with this secret (docker-compose default). The API must validate +# with the SAME secret, otherwise it falls back to the empty JWKS path and returns 401 "invalid token". +SUPABASE_JWT_SECRET=super-secret-jwt-token-change-me + +# ClickHouse native TCP is published on host port 9009 (host 9000 is taken by MinIO). +CLICKHOUSE_NATIVE_PORT=9009 +``` +If you change `.env`, the API must be (re)started to pick it up — settings are read once at boot. + +## 3. API (FastAPI, port 8000) — run in background +```bash +cd apps/api && uv run uvicorn spin2note_api.main:app --reload +``` +First run also needs the Rust parser built (only if `hh_parser` import fails): +```bash +cd apps/api && uv run maturin develop --manifest-path ../../crates/hh-parser/Cargo.toml +``` + +## 4. Frontend (Next.js, port 3000) — run in background +`npm`/`node` are **not on PATH**; node lives in `~/.local/node-v22.14.0-linux-x64/bin`. +Prepend it (or discover via `find ~/.local -maxdepth 2 -name node -type f` if that path moved): +```bash +export PATH="$HOME/.local/node-v22.14.0-linux-x64/bin:$PATH" +cd apps/web && npm run dev +``` + +## 5. Verify (don't declare success until these pass) +```bash +curl -s -o /dev/null -w 'auth %{http_code}\n' http://localhost:9999/health # -> 200 +curl -s -o /dev/null -w 'api %{http_code}\n' http://localhost:8000/health # -> 200 +curl -s -o /dev/null -w 'web %{http_code}\n' http://localhost:3000 # -> 200 +``` +Optionally confirm JWT validation works end-to-end (valid secret -> 200, wrong -> 401) by minting +an HS256 token (`sub`, `aud=authenticated`, `exp`) with `super-secret-jwt-token-change-me` and +calling `GET /stats/overview` with `Authorization: Bearer `. + +## Output +Report a compact table: layer -> URL -> status. Endpoints: +- Frontend (main UI): http://localhost:3000 +- API + Swagger: http://localhost:8000/docs +- GoTrue auth: http://localhost:9999 + +Note that databases are likely empty on a fresh bring-up (`/db-show` for a snapshot, `/db-migrate` +if tables are missing).