Packages del Monorepo Nidus

Este directorio contiene los paquetes compartidos que permiten construir aplicaciones consistentes, reutilizables y faciles de mantener dentro de Nidus.

Este archivo es el indice principal para humanos y agentes de IA cuando necesitan decidir donde buscar codigo reutilizable. Antes de crear una funcion, hook, schema, constante, servicio o componente compartido, leer este README y luego el README especifico del package candidato.

1. Objetivo de packages/

• Centralizar logica, configuracion y componentes compartidos.
• Reducir duplicacion entre apps.
• Definir contratos estables (exports) para escalar sin romper integraciones.

2. Estructura actual

3. Lineamientos de desarrollo

1. Cada package debe tener API publica clara via src/index.ts o exports en package.json.
2. No exponer internals sin necesidad. Exportar solo contratos estables.
3. Mantener cohesion: un package, un dominio tecnico.
4. Todo cambio debe incluir chequeo minimo:
   • pnpm lint --filter <package>
   • pnpm build --filter <package> o pnpm type-check --filter <package>
5. Documentar cualquier export nuevo en el README del package.

4. Como decidir donde guardar codigo

1. Si solo lo consume una app y contiene comportamiento, rutas, contenido o permisos propios de esa app, guardarlo en apps/<app>/.
2. Si lo consumen dos o mas apps, define un contrato transversal o es infraestructura compartida, guardarlo en el package correspondiente.
3. Si todavia no existe una necesidad real de compartirlo, no crear un package por anticipado.
4. Si una parte es generica y otra depende de una app, guardar la parte generica en packages/ y el adaptador/composition en la app.

Mapa rapido por responsabilidad

5. Como encontrar y consumir una API

1. Buscar el simbolo por nombre en todo el repositorio antes de implementarlo de nuevo.
2. Leer el README.md del package candidato.
3. Leer su package.json para confirmar el nombre, scripts y exports.
4. Leer src/index.ts y los barrels del dominio para confirmar la API publica.
5. Importar desde @repo/<package>, nunca desde packages/<package>/src/....
6. Si el export necesario no existe, agregarlo al barrel publico y documentarlo.

Ejemplo:

import { Button, cn } from '@repo/ui';
import { APP_ROUTES, FIRESTORE_PATHS } from '@repo/constants';
import { createUser } from '@repo/app-services';

6. Reglas de limites entre packages

• Un package nunca puede importar desde apps/.
• No duplicar schemas, tipos derivados, nombres de colecciones, rutas ni permisos.
• Los tipos de entidades persistidas y payloads deben derivarse de @repo/schemas.
• Los componentes no deben llamar Firebase directamente; usar adapters y services.
• @repo/app-services es para operaciones iniciadas desde apps cliente.
• @repo/app-errors define AppError sin dependencias de Firebase, React ni UI; los servicios lo lanzan con códigos estables y las apps convierten esos códigos en copy de producto.
• @repo/client-operations estandariza la ejecucion React Query desde hooks cliente; no implementa casos de uso, acceso Firebase ni presentacion UI. Reexporta AppError desde @repo/app-errors y su adopcion en una app es opt-in.
• @repo/app-function-services es para operaciones server-side ejecutadas por Cloud Functions.
• Evitar dependencias circulares y mantener cada package enfocado en un dominio tecnico.
• Mantener nombres de archivos, variables, funciones e interfaces en ingles.

7. Buenas practicas para codigo reutilizable

• Preferir funciones puras y sin side effects ocultos.
• Modelar contratos con tipos explicitos y/o esquemas Zod.
• Evitar acoplamiento circular entre packages.
• Mantener ejemplos de uso concretos en README.
• Versionar cambios de API en PR description.

8. Como contribuir a un package existente

1. Identificar el package correcto segun dominio.
2. Buscar y reutilizar una API existente antes de agregar otra.
3. Implementar solo el contrato generico; dejar la composicion especifica en la app.
4. Actualizar tests o agregar cobertura minima si el package tiene Vitest.
5. Actualizar el README del package con nuevos exports, ubicacion y reglas de uso.
6. Ejecutar los scripts definidos en el package.json del package antes del PR.

9. Como crear un package nuevo desde 01-base-package

1. Duplicar la carpeta base:

cp -r packages/01-base-package packages/nuevo-package

1. Actualizar package.json:

• name: @repo/nuevo-package
• exports y types segun tu API publica

1. Implementar API inicial en src/index.ts.
2. Completar README.md del package.
3. Verificar:

pnpm lint --filter @repo/nuevo-package
pnpm build --filter @repo/nuevo-package

10. Checklist rapido para nuevos packages

• package.json con nombre @repo/...
• src/index.ts con exports publicos
• tsconfig.json extendiendo @repo/tsconfig
• scripts de lint/build/type-check
• README documentado
• El package tiene al menos un consumidor real o una frontera tecnica justificada
• No importa desde apps/ ni expone rutas internas innecesarias
• Tests agregados o justificacion de por que no aplican
• README de packages/ y referencias de agentes actualizadas si cambia la arquitectura