Skip to content

AGENTS.md

Latest commit

 

History

History
67 lines (57 loc) · 3.99 KB

AGENTS.md

File metadata and controls

67 lines (57 loc) · 3.99 KB
Raw

AGENTS.md — guia do repositório p/ agentes de código

Template fullstack opinativo (NÃO é framework: sem packages publicados, sem CLI de scaffold — clona e usa). Stack: Hono + oRPC + Drizzle/Postgres + Zod no back; React + TanStack + Tailwind/shadcn no web; Expo no mobile; Tauri no desktop.

Mapa (dono de cada pasta)

api/          back: modules/<recurso>/*.controller.ts (oRPC fino) + *.service.ts (regra)
web/          front web: file-based TanStack Router (routes/arquivo = rota) + shadcn
mobile/       Expo Router (file-based) + mesmo client oRPC
desktop/      Tauri 2: serve web/dist (zero UI própria)
lib/          compartilhado: env.ts db.ts openapi.ts server.ts (único lugar c/ lógica reusável)
contracts/    oRPC contract-first (oc.route) — FONTE da API, swagger e clients
routes/api.ts contrato-RAIZ + Hono shell (health/spec/docs) + mount OpenAPIHandler
database/     schema/tables (Model: tabela+Zod+tipos) + migrations + seeders + factories
config/       env.ts (Zod, falha no boot) + database.ts (conexão ÚNICA db)
docs/         architecture.md (regras) · api.md (ponteiro p/ Scalar) · openapi.json (gerado)

Detalhe das regras em docs/architecture.md — leia antes de codar.

Comandos

pnpm install
docker compose -f docker/compose.yml up -d db   # Postgres local (obrigatório p/ dev)
pnpm seed && pnpm dev                            # API :3333 · /docs (Scalar) · /openapi.json
pnpm check          # tsc api+web+mobile
pnpm test           # bun test, PGlite em memória (NODE_ENV=test)
pnpm build          # build do web
pnpm --filter @mystack/api openapi:export        # regenera docs/openapi.json (commit!)
pnpm --filter @mystack/desktop dev|build         # precisa Rust + webkit (Linux)

Fluxo: novo recurso (ex. tickets)

  1. database/schema/tables/tickets.ts — tabela Drizzle (pgTable, uuid client-side, timestamp mode:'string') + Zod (Create/Update/Params/Query) + tipos. Um arquivo só.
  2. contracts/tickets.contract.ts — oc.route({method, path}) + input/output do schema. summary/tags viram swagger. Registre em contracts/index.ts (appContract).
  3. api/src/modules/tickets/tickets.service.ts — regra com db de @app/config/database. Nunca Context aqui. null p/ ausente (router converte em ORPCError).
  4. api/src/modules/tickets/tickets.controller.ts — implement(contrato) + handlers de 1 linha. Registre em routes/api.ts (orpcRouter).
  5. database/migrate.ts — DDL da tabela + database/migrations/NNNN_nome.sql.
  6. api/tests/ — cubra CRUD + 400 + 404.
  7. Telas: web/src/routes/tickets/index.tsx (createFileRoute) e/ou mobile/app/tickets/index.tsx. Front usa orpc.tickets.list.queryOptions({ input }) — nunca monte URL.
  8. pnpm openapi:export (via filter api), pnpm check, pnpm test.

Armadilhas (leia, dói menos)

  • Paths canônicos SEM trailing slash (/products, não /products/). oRPC não casa igual Hono.
  • Sem z.coerce em query: SmartCoercion converte ?limit=20 sozinho.
  • exactOptionalPropertyTypes: true — código gerado (shadcn) às vezes precisa de patch mínimo.
  • Alias @app/* → raiz do repo. Bun, Vite e Metro resolvem (metro via metro.config.js); se criar pasta nova fora do padrão, confira os 3 resolvers + includes dos tsconfigs.
  • TS 7: sem baseUrl nos tsconfigs; routeTree.gen.ts do web é COMMITADO (tsc precisa dele).
  • Banco fora do repo: DATABASE_URL obrigatório; dev = compose, teste = PGlite, prod = gerenciado. timestamp sempre mode:'string' (senão o output Zod quebra com Date).
  • Versões no catalog: do pnpm-workspace.yaml. Front trava no Expo SDK 57 (react 19.2.3, react-native 0.86.3). pnpm dlx shadcn add ok, mas passe as deps p/ o catalog e confira o diff (patches em calendar.tsx/spinner.tsx, CSS em shadcn-tailwind.css).
  • docs/openapi.json é artefato: regenerar e commitar após mudar contracts.
  • Desktop build exige Rust + webkit2gtk; AppImage exige FUSE (use --bundles deb sem FUSE).