Adding lots of skills

2026-05-09 22:44:17 +02:00
parent b57fc43fc0
commit bb444759f6
58 changed files with 3585 additions and 86 deletions
@@ -0,0 +1,120 @@
+# Skill: Local Dev Testing
+
+How to spin up a project locally, verify it is healthy, and authenticate
+against it for API testing.
+
+---
+
+## 1. Start a project with devtest
+
+`gutask devtest` starts the project via `./dev.sh`, waits for the frontend
+and backend to respond, then stops the service.
+
+```bash
+# Basic: start gnommoweb on default ports, stop after health check
+gutask devtest --dir /path/to/gnommoweb --port 5173 --api-port 3001
+
+# Keep it running after the check (for manual inspection or further tests)
+gutask devtest --dir /path/to/gnommoweb --port 5173 --api-port 3001 --keep
+
+# Custom timeout (default 90s — increase if npm install is needed)
+gutask devtest --dir /path/to/gnommoweb --port 5174 --api-port 3002 --timeout 180 --keep
+```
+
+On failure, devtest dumps the last 20 lines of `./dev.log` automatically.
+
+**Standard project paths (Agent0 environment):**
+
+| Project         | Path                                                                              |
+|-----------------|-----------------------------------------------------------------------------------|
+| gnommoweb       | agent-zero-data/projects/glitch_university/gnommoweb                              |
+| dobby-inference | agent-zero-data/projects/glitch_university/gnommoweb/dobby-inference              |
+
+
+---
+
+## 2. Run dev.sh directly
+
+`./dev.sh` accepts `--port` (frontend) and `--api-port` (backend).
+All output is written to `./dev.log` in the project root.
+
+```bash
+cd /path/to/gnommoweb
+./dev.sh --port 5173 --api-port 3001
+```
+
+The script:
+- Runs `git pull --ff-only` (picks up changes from other agents)
+- Installs npm deps if `node_modules` is missing
+- Starts Docker service containers (db, minio, dobby) if not already running
+- Runs database migrations (`npm run migrate:up`)
+- Starts backend and frontend, logging both to `./dev.log`
+
+To inspect logs while running:
+```bash
+tail -f /path/to/gnommoweb/dev.log
+```
+
+---
+
+## 3. Obtain a JWT session token (dev-only)
+
+Most user-facing endpoints require a session cookie (`auth_token`).
+In development, use the dev-only session endpoint instead of Google OAuth:
+
+```bash
+# Mint a session for user_id=698 (adjust to the local user's ID)
+curl -c /tmp/dev-cookies.txt -X POST http://localhost:3001/api/dev/session \
+  -H "Content-Type: application/json" \
+  -d '{"user_id": 698}'
+# → {"ok":true,"user":{"id":698,"email":"...","name":"...","isAdmin":true}}
+
+# Use the cookie on any user-protected endpoint
+curl -b /tmp/dev-cookies.txt http://localhost:3001/api/letters
+curl -b /tmp/dev-cookies.txt http://localhost:3001/api/user/profile
+```
+
+**This endpoint returns 404 in production.** It only works when
+`NODE_ENV=development`.
+
+To find the local user ID:
+```bash
+KEY=<CONTENT_API_KEY>
+curl -s http://localhost:3001/api/admin/users?limit=10 \
+  -H "Authorization: Bearer $KEY" | python3 -m json.tool
+```
+
+---
+
+## 4. Agent and admin API access
+
+Many endpoints accept the `CONTENT_API_KEY` bearer token (admin-level)
+or agent credentials (X-Agent-Id + X-Agent-Password headers):
+
+```bash
+# Admin bearer token (from .env CONTENT_API_KEY)
+curl http://localhost:3001/api/agents \
+  -H "Authorization: Bearer $CONTENT_API_KEY"
+
+# Agent credentials (from .env AGENT_ID + AGENT_PASSWORD)
+curl http://localhost:3001/api/agent-chat/inbox/3 \
+  -H "Authorization: Bearer $CONTENT_API_KEY" \
+  -H "X-Agent-Id: $AGENT_ID" \
+  -H "X-Agent-Password: $AGENT_PASSWORD"
+```
+
+These are set in `gutasktool/.env` and loaded automatically by `gutask`.
+
+---
+
+## 5. Quick reference
+
+| What                        | Command                                                        |
+|-----------------------------|----------------------------------------------------------------|
+| Run devtest                 | `gutask devtest --dir <path> --port 5173 --api-port 3001`      |
+| Keep service running        | add `--keep`                                                   |
+| Watch logs                  | `tail -f <project>/dev.log`                                    |
+| Get dev session cookie      | `POST /api/dev/session {"user_id": N}`                         |
+| List local users            | `GET /api/admin/users` with CONTENT_API_KEY                    |
+| Send agent letter           | `gutask chat send <agent_name_or_id> "<message>"`              |
+(venv) root@18e4f1044611:/a0/usr/workdir/gutasktool#