gruperly/AGENTS.md

AGENTS.md — Gruperly

Monorepo web + API para gestión de cobros grupales. Reglas optimizadas para agentes.

Stack & ejecutables de verdad

• Package manager / runtime: Bun (v1.4+, package.json viene con workspaces y packageManager: bun). Usa bun para instalar (bun install), scripts y filtros. No uses npm/yarn/pnpm.
• Monorepo: Bun Workspaces orquestado con Turborepo (turbo.json). Dependencias entre paquetes usan workspace:*.
• Los paquetes son Node "type": "module".

Comandos

• bun run typecheck — corre tsc --noEmit en todos los paquetes vía turborepo. Es la verificación principal; correlo tras tocar código.
• bun run --filter @gruperly/api typecheck / ... @gruperly/web typecheck — verificación de un solo paquete.
• bun run dev — levanta API (4000) y web (6173) con turborepo.
• No hay script lint en ningún paquete; bun run lint no hace nada útil. No dependas de él.
• Base de datos (API): bun run db:generate / db:migrate / db:push / db:studio, o bien bun --filter @gruperly/api db:*.

Estructura y fronteras

• apps/api — Backend Bun + Hono. Entry point src/index.ts (monta Bun.serve, puerto por defecto 4000 vía PORT). Rutas modulares en src/routes/. Prisma en prisma/schema.prisma.
• apps/web — Frontend React 19 + Vite + Tailwind v4. Entry src/main.tsx → src/router.tsx. Puerto 6173 (vite.config.ts).
• packages/shared — Esquemas Zod + tipos. Se consume como TS fuente directo (exports apunta a src/index.ts, sin build previo). @gruperly/shared se resuelve vía paths en cada tsconfig de app.
• packages/config — tsconfig.base.json; todos los tsconfig lo extienden.

Gotchas operativos

• Prisma 7: requiere apps/api/.env (con DATABASE_URL). El CLI lee apps/api/prisma.config.ts (datasource url vía env('DATABASE_URL')); el schema usa provider = "prisma-client" con output en prisma/generated/prisma (gitignoreado; regenera con bun run db:generate). El PrismaClient se importa desde ../../prisma/generated/prisma/client y se instancia con @prisma/adapter-pg. Sin .env el CLI falla; copia desde apps/api/.env.example.
• Turborepo solo lee lockfile textual bun.lock (no el binario bun.lockb). Si se regenera, usa bun install --save-text-lockfile. No versiones bun.lockb.
• .env, dist/, .turbo/ están gitignoreados (que no te extrañe su ausencia).

Convenciones repo-específicas

• Frontend en español: copy de UI, comentarios y textos en español.
• Tailwind v4 con tokens en @theme dentro de apps/web/src/index.css (p. ej. --color-accent: #1e90ff). Se usan como clases auto-generadas: text-accent, bg-success-soft, etc. Radius por defecto 0.75rem (rounded-xl).
• Router NO es file-based (aunque stack.md lo diga): las rutas se declaran manualmente en apps/web/src/router.tsx con createRoute + addChildren y se registran vía module augmentation. Cada vista nueva debe añadirse ahí.
• Nav (Inicio/Grupos/Cobros/Ajustes) vive en apps/web/src/components/layout/nav-items.ts; es la fuente única para BottomNav (móvil) y Sidebar (desktop) — no dupliques la lista.
• UI: primitivos propios en apps/web/src/components/ui/ (avatar, button, badge) más helper cn() en src/lib/utils.ts (clsx + tailwind-merge). Aunque stack.md mencione Shadcn, todavía no está instalado (sin Radix); úsalos directos.
• Layout mobile-first: RootLayout usa columna max-w-md en móvil y dos columnas (Sidebar + contenido max-w-6xl) en lg+.

Fuentes de contexto

• stack.md — arquitectura y spec técnica de referencia (UI tokens exactos, stack por app).
• README.md — setup de la base de datos y comandos generales.