From 778f3fdcad8f5a556b51f162cb0e3fe665db228d Mon Sep 17 00:00:00 2001 From: Jose Selesan Date: Fri, 28 Aug 2026 17:05:58 -0300 Subject: [PATCH] feat: add AGENTS.md for project documentation and guidelines --- AGENTS.md | 44 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 44 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..136b248 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,44 @@ +# 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 requiere `apps/api/.env`** (con `DATABASE_URL`) para `generate`/`validate`/`migrate`; sin él falla con `P1012`. Está gitignoreado; 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.