# 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#