From b0644af0bf6f76dd1d3bc0c935a836dabf82df5f Mon Sep 17 00:00:00 2001 From: ThinkAI Readiness Date: Tue, 26 May 2026 17:35:06 +0000 Subject: [PATCH] chore(readiness): improve AI agent readiness --- .cursor/skills/backend-testing/SKILL.md | 29 ++++++++++++++++ .cursor/skills/deploy-compose/SKILL.md | 40 ++++++++++++++++++++++ .cursor/skills/openapi-client-gen/SKILL.md | 36 +++++++++++++++++++ 3 files changed, 105 insertions(+) create mode 100644 .cursor/skills/backend-testing/SKILL.md create mode 100644 .cursor/skills/deploy-compose/SKILL.md create mode 100644 .cursor/skills/openapi-client-gen/SKILL.md diff --git a/.cursor/skills/backend-testing/SKILL.md b/.cursor/skills/backend-testing/SKILL.md new file mode 100644 index 0000000000..00289b126c --- /dev/null +++ b/.cursor/skills/backend-testing/SKILL.md @@ -0,0 +1,29 @@ +--- +name: backend-testing +description: Runs and extends FastAPI backend pytest suites in Docker. Use when adding or fixing backend tests, debugging API regressions, or checking coverage under backend/tests/. +--- + +# Backend testing + +## Stack + +- Tests live in `backend/tests/` (pytest). +- Full CI-style run from repo root: `bash ./scripts/test.sh` (builds stack, runs tests, tears down). +- With stack already up: `docker compose exec backend bash scripts/tests-start.sh [pytest args]`. + +## Workflow + +1. Prefer existing helpers in `backend/tests/utils/` (`user.py`, `item.py`, `utils.py`) before duplicating setup. +2. Add tests next to the feature area under `backend/tests/`; follow existing naming (`test_*.py`). +3. Run a focused file: `docker compose exec backend bash scripts/tests-start.sh backend/tests/api/routes/test_items.py -x`. +4. After API schema or route changes, regenerate the OpenAPI client if the frontend depends on it (see `openapi-client-gen` skill). + +## Coverage + +- HTML report: `backend/htmlcov/index.html` after a test run. +- Do not commit coverage artifacts unless the project already tracks them. + +## Safety + +- Do not weaken assertions to make tests pass; fix behavior or fixtures. +- Avoid real external services; use test DB and fixtures provided by the stack. diff --git a/.cursor/skills/deploy-compose/SKILL.md b/.cursor/skills/deploy-compose/SKILL.md new file mode 100644 index 0000000000..34edaaf4fc --- /dev/null +++ b/.cursor/skills/deploy-compose/SKILL.md @@ -0,0 +1,40 @@ +--- +name: deploy-compose +description: Guides Docker Compose local dev and production deployment with Traefik. Use when changing compose files, .env, domains, staging/production deploy, or Traefik routing. +--- + +# Deploy and Docker Compose + +## Local development + +- Start stack: `docker compose watch` (uses `compose.yml` + `compose.override.yml` + `.env`). +- Logs: `docker compose logs [service]`. +- After `.env` changes: restart with `docker compose watch`. +- Docs: `development.md` (ports, Mailcatcher, mixed local/Docker workflows). + +Default URLs: frontend `http://localhost:5173`, API `http://localhost:8000`, Adminer `http://localhost:8080`. + +## Compose layout + +| File | Role | +|------|------| +| `compose.yml` | Base stack (db, backend, frontend, proxy labels) | +| `compose.override.yml` | Dev overrides (volumes, local Traefik) | +| `compose.traefik.yml` | Shared Traefik proxy for remote servers | +| `.env` | Secrets and `DOMAIN`, `STACK_NAME`, DB credentials | + +## Production / staging + +- Follow `deployment.md`: public Traefik on `traefik-public` network, wildcard DNS, `compose.traefik.yml` on the server. +- Set `DOMAIN` and stack name in `.env` before deploy; never commit real secrets to public repos. +- GitHub Actions workflows in `.github/workflows/` handle automated deploy when configured. + +## Subdomain local test + +Set `DOMAIN=localhost.tiangolo.com` in `.env`, then `docker compose watch` to exercise subdomain routing locally. + +## Safety + +- Do not force-push or change production secrets without explicit user request. +- Prefer `docker compose` over raw `docker run` so labels and networks stay consistent. +- Tear down test stacks cleanly (`docker compose down -v`) when scripts expect a fresh DB. diff --git a/.cursor/skills/openapi-client-gen/SKILL.md b/.cursor/skills/openapi-client-gen/SKILL.md new file mode 100644 index 0000000000..d436166d4f --- /dev/null +++ b/.cursor/skills/openapi-client-gen/SKILL.md @@ -0,0 +1,36 @@ +--- +name: openapi-client-gen +description: Regenerates the TypeScript OpenAPI client for the React frontend after backend API changes. Use when routes, models, or request/response schemas change, or when frontend client types are out of sync. +--- + +# OpenAPI client generation + +## When to run + +After changing FastAPI routes, Pydantic models, or anything reflected in the OpenAPI schema consumed by the frontend. + +## Regenerate (repo root) + +```bash +bash ./scripts/generate-client.sh +``` + +This script: + +1. Exports OpenAPI JSON from `app.main` via `backend` (`uv run python -c "import app.main; ..."`). +2. Writes `frontend/openapi.json`. +3. Runs `bun run --filter frontend generate-client` (`@hey-api/openapi-ts`). +4. Runs `bun run lint`. + +Generated output: `frontend/src/client/` (`sdk.gen.ts`, `schemas.gen.ts`, `types.gen.ts`, etc.). Config: `frontend/openapi-ts.config.ts`. + +## After generation + +- Fix any frontend call sites that broke due to renamed operations or types. +- Commit `openapi.json` and generated client files together with backend changes. +- Do not hand-edit `*.gen.ts` files; change the API or generator config instead. + +## Safety + +- Run backend tests after API changes (`backend-testing` skill). +- Keep operation IDs stable when possible to reduce frontend churn.