forgecad 0.6.3 → 0.8.0

package/dist-skill/docs/runbook.md

@@ -1,345 +0,0 @@
-# ForgeCAD Hosted Service — Runbook
-
-Operational reference for running, testing, and troubleshooting the forgecad.io hosted service.
-
-For the full documentation index see [INDEX.md](../INDEX.md).
-For environment variables, Docker setup, and deployment details see [deployment.md](deployment.md).
-For releasing new versions see [RELEASING.md](../RELEASING.md).
-For platform feature docs (auth, projects, sharing, admin, email) see [platform/](../platform/).
-
----
-
-## Quick Reference
-
-| What | Command |
-|------|---------|
-| Start local DB | `npm run dev:db` |
-| Stop local DB | `npm run dev:db:stop` |
-| Start API server | `npm run dev:server` |
-| Start frontend (with API proxy) | `npm run dev:studio` |
-| Run API tests | `bash scripts/test-shares-api.sh` |
-| Run unit tests | `npm run test:unit` |
-| Run full test suite | `npm test` |
-| Health check | `curl http://localhost:5174/api/health` |
-| SSH to production | `ssh hetzner` |
-
----
-
-## Local Development Stack
-
-### Minimal (editor only, no auth)
-
-```bash
-npm run dev
-```
-
-No database, no login. For geometry, sketches, viewer work.
-
-### Full stack (auth, projects, sharing)
-
-Three terminals:
-
-```bash
-# 1. Database
-npm run dev:db
-
-# 2. API server (port 5174)
-npm run dev:server
-
-# 3. Frontend (port 5173, proxies /api → 5174)
-npm run dev:studio
-```
-
-Open http://localhost:5173. Dev credentials are hardcoded in `dev:server` — see [deployment.md](deployment.md#local-development).
-
-### Verify the stack is healthy
-
-```bash
-# API health
-curl -s http://localhost:5174/api/health | python3 -m json.tool
-
-# Database
-docker exec forgecad-postgresql-1 psql -U forgecad -d forgecad -c "SELECT count(*) FROM users;"
-
-# Migration state
-docker exec forgecad-postgresql-1 psql -U forgecad -d forgecad -c "SELECT * FROM _migrations ORDER BY id;"
-```
-
----
-
-## Testing
-
-### API tests (end-to-end, from terminal)
-
-These scripts exercise the real server — no mocks, real HTTP, real database.
-
-| Script | What it tests | Prerequisites |
-|--------|--------------|---------------|
-| `scripts/test-shares-api.sh` | Publish, fetch, update, unpublish, auth enforcement | `dev:db` + `dev:server` |
-
-Run:
-
-```bash
-bash scripts/test-shares-api.sh
-```
-
-The script registers a fresh test user, runs through the full lifecycle, and cleans up. Each run uses a unique email so it's safe to re-run.
-
-### Adding new API test scripts
-
-Follow the pattern in `test-shares-api.sh`:
-
-1. Name: `scripts/test-<feature>-api.sh`
-2. Check server health first (`/api/health`)
-3. Register a unique test user per run
-4. Use `acurl()` helper for authenticated requests
-5. Assert HTTP status codes and response fields
-6. Clean up (delete created resources)
-7. Print colored pass/fail per step
-
-### Unit tests
-
-```bash
-npm run test:unit           # vitest
-npm test                    # unit + CLI invariant checks
-```
-
-### Invariant checks (CLI)
-
-```bash
-node dist-cli/forgecad.js check suite
-```
-
-Runs compiler snapshots, example validation, parameter scanning, transform/dimension invariants.
-
----
-
-## Database
-
-### Migrations
-
-Migrations run automatically on server startup (`server/db/migrate.ts`). The system:
-
-1. Maintains a `_migrations` table tracking applied migrations by sequential ID
-2. Runs unapplied migrations in order on boot
-3. Each migration is idempotent SQL (`CREATE TABLE IF NOT EXISTS`, `ALTER ... ADD COLUMN IF NOT EXISTS`)
-
-**To add a new migration:** append to the `MIGRATIONS` array in `server/db/migrate.ts`.
-
-### Inspect the database locally
-
-```bash
-docker exec -it forgecad-postgresql-1 psql -U forgecad -d forgecad
-```
-
-Common queries:
-
-```sql
--- List tables
-\dt
-
--- Users
-SELECT id, email, name, role, created_at FROM users;
-
--- Projects
-SELECT id, slug, name, visibility, owner_id FROM projects;
-
--- Shared/published models
-SELECT share_id, filename, title, owner_id, updated_at FROM shared_files;
-
--- Audit log (recent)
-SELECT action, details, created_at FROM audit_log ORDER BY created_at DESC LIMIT 20;
-
--- Migration state
-SELECT * FROM _migrations ORDER BY id;
-```
-
-### Reset local database
-
-```bash
-npm run dev:db:stop
-docker volume rm forgecad_postgresql-dev-data   # or the worktree-specific volume name
-npm run dev:db
-# Server will re-run all migrations on next start
-```
-
----
-
-## Production (Hetzner / Coolify)
-
-### Access
-
-```bash
-ssh hetzner    # see ~/.ssh/config for host alias
-```
-
-### Find containers
-
-```bash
-docker ps --format "{{.Names}}" | grep forge
-```
-
-### Logs
-
-```bash
-# App logs (recent)
-docker logs --tail 200 <forgecad-container>
-
-# Follow live
-docker logs -f <forgecad-container>
-
-# Filter for errors
-docker logs <forgecad-container> 2>&1 | grep -i error | tail -20
-```
-
-### Database access in production
-
-```bash
-# Get credentials from the app container's environment
-docker exec <forgecad-container> env | grep POSTGRES
-
-# Connect
-docker exec -it <postgres-container> psql -U <USER> -d forgecad
-```
-
-### Health check
-
-```bash
-curl -s https://forgecad.io/api/health | python3 -m json.tool
-```
-
-### Verify a deployment landed
-
-Coolify auto-builds and deploys on push to `mainline`. This usually takes 2–5 minutes. The deploy is triggered by Coolify polling the repo (not a webhook), so the delay varies.
-
-To confirm:
-
-```bash
-# 1. Check container was recently recreated (look at the "Up X minutes" status and CreatedAt)
-ssh hetzner 'docker ps --format "{{.Names}}\t{{.CreatedAt}}\t{{.Status}}" | grep -E "^forgecad-" | grep -v postgres'
-
-# 2. Check for healthy status
-ssh hetzner 'docker ps --format "{{.Names}}\t{{.Status}}" | grep -E "^forgecad-" | grep -v postgres | grep healthy'
-
-# 3. Check startup logs for errors
-ssh hetzner 'docker logs --tail 30 $(docker ps --format "{{.Names}}" | grep -E "^forgecad-" | grep -v postgres) 2>&1'
-
-# 4. Hit the health endpoint
-curl -s https://forgecad.io/api/health | python3 -m json.tool
-
-# 5. Verify specific code landed (check compiled output, not source)
-ssh hetzner 'docker exec $(docker ps --format "{{.Names}}" | grep -E "^forgecad-" | grep -v postgres) grep -c "YOUR_KEYWORD" /app/dist-server/routes/files.js'
-```
-
-Container names change on each deploy — always discover dynamically with `docker ps | grep forgecad`. The app dir is `/app/` with compiled output in `dist/`, `dist-server/`, `dist-cli/`.
-
-### Restart
-
-Coolify auto-deploys on push to `mainline`. For manual restart:
-
-```bash
-docker restart $(docker ps --format "{{.Names}}" | grep -E "^forgecad-" | grep -v postgres)
-```
-
-### System resources
-
-```bash
-df -h       # disk
-free -h     # memory
-docker stats --no-stream   # per-container CPU/memory
-```
-
----
-
-## API Endpoints Reference
-
-### Public (no auth)
-
-| Method | Route | Purpose |
-|--------|-------|---------|
-| GET | `/api/health` | Server health + uptime |
-| GET | `/api/shares/:shareId` | Fetch a published model |
-
-### Auth
-
-| Method | Route | Purpose |
-|--------|-------|---------|
-| POST | `/api/auth/register` | Create account |
-| POST | `/api/auth/login` | Login (returns cookies) |
-| POST | `/api/auth/refresh` | Refresh access token |
-| POST | `/api/auth/logout` | Clear session |
-| GET | `/api/auth/session` | Current user info |
-| GET | `/api/auth/providers` | OAuth provider URLs |
-| POST | `/api/auth/callback/:provider` | OAuth callback |
-| POST | `/api/auth/forgot-password` | Request password reset |
-| POST | `/api/auth/reset-password` | Apply password reset |
-| GET | `/api/auth/verify-email` | Confirm email |
-| POST | `/api/auth/resend-verification` | Resend verification email |
-
-### Projects (all require auth)
-
-| Method | Route | Role | Purpose |
-|--------|-------|------|---------|
-| GET | `/api/projects` | — | List user's projects |
-| POST | `/api/projects` | — | Create project |
-| GET | `/api/projects/:id` | viewer | Project details |
-| PATCH | `/api/projects/:id` | owner | Update project |
-| DELETE | `/api/projects/:id` | owner | Delete project |
-| GET | `/api/projects/:id/members` | viewer | List members |
-| POST | `/api/projects/:id/members` | owner | Add member |
-| PATCH | `/api/projects/:id/members/:userId` | owner | Update member role |
-| DELETE | `/api/projects/:id/members/:userId` | owner | Remove member |
-
-### Files (all require auth + project role)
-
-| Method | Route | Role | Purpose |
-|--------|-------|------|---------|
-| GET | `/api/projects/:id/watch` | viewer | SSE file watcher |
-| POST | `/api/projects/:id/save` | editor | Save file |
-| POST | `/api/projects/:id/delete` | editor | Delete file |
-| POST | `/api/projects/:id/mkdir` | editor | Create directory |
-| GET | `/api/projects/:id/read-binary` | viewer | Download mesh file |
-
-### Shares (published models)
-
-| Method | Route | Auth | Purpose |
-|--------|-------|------|---------|
-| GET | `/api/shares/:shareId` | none | Fetch published model (public) |
-| GET | `/api/shares` | required | List user's published models |
-| POST | `/api/shares` | required | Publish or update a model |
-| DELETE | `/api/shares/:shareId` | required (owner) | Unpublish |
-
----
-
-## Troubleshooting
-
-### Server won't start
-
-| Symptom | Cause | Fix |
-|---------|-------|-----|
-| `pino-pretty` transport error | Missing dev dependency in worktree | Use `NODE_ENV=production` or install pino-pretty |
-| Port 5174 already in use | Another server instance running | `lsof -i :5174` then kill the PID |
-| `FORGE_DB_URL` missing | Env var not set | Use `npm run dev:server` which sets it automatically |
-| Connection refused on :5432 | Postgres not running | `npm run dev:db` |
-
-### Auth issues
-
-| Symptom | Cause | Fix |
-|---------|-------|-----|
-| 500 on login/register | Missing `FORGE_JWT_SECRET` | Set it (any string for dev, `openssl rand -base64 32` for prod) |
-| 401 on authenticated endpoints | Expired access token (15 min) | Client should auto-refresh; check refresh token cookie |
-| CORS errors in browser | `FORGE_ALLOWED_ORIGINS` mismatch | Must match the frontend's origin exactly |
-
-### Email issues
-
-| Symptom | Cause | Fix |
-|---------|-------|-----|
-| No verification/reset email received; logs show `[email] To: user@...` | `RESEND_API_KEY` is empty — falling back to console log | Set `RESEND_API_KEY` in Coolify → redeploy. See [guides/email-setup.md](guides/email-setup.md) |
-
-### Database issues
-
-| Symptom | Cause | Fix |
-|---------|-------|-----|
-| Migration fails | Schema conflict from manual changes | Reset local DB (see above) |
-| `relation does not exist` | Migrations didn't run | Check `_migrations` table; restart server |
-| Quota errors on file save | User's `storage_used_bytes` exceeded 50MB | Check with `SELECT storage_used_bytes FROM users WHERE ...` |