@damenor/agent-docs 0.1.0

package/templates/modules/reference/docs/reference/infrastructure.md

@@ -0,0 +1,191 @@
+---
+created: "2025-01-01"
+status: active
+type: reference
+tags: [referencia, infraestructura, entornos, CI/CD, URLs, acceso]
+---
+
+# Referencia de Infraestructura
+
+Información técnica sobre los entornos, acceso y pipelines del proyecto.
+
+---
+
+## Entornos
+
+| Entorno | Propósito | URL | Branch trigger | Region |
+|---------|-----------|-----|---------------|--------|
+| **Development** | Desarrollo local | `http://localhost:3000` | N/A | Local |
+| **Staging** | QA y validación | `https://staging.[dominio]` | Push a `[develop / main]` | [Región cloud] |
+| **Production** | Usuarios finales | `https://[dominio]` | Tag `v*` o manual | [Región cloud] |
+
+---
+
+## Arquitectura de infraestructura
+
+```
+                    ┌──────────────┐
+                    │  CDN / DNS   │
+                    │  [Proveedor] │
+                    └──────┬───────┘
+                           │
+                    ┌──────▼───────┐
+                    │  Load Balancer│
+                    │  [Proveedor] │
+                    └──────┬───────┘
+                           │
+              ┌────────────┼────────────┐
+              │            │            │
+       ┌──────▼──────┐ ┌──▼─────┐ ┌───▼──────┐
+       │  App Server │ │  App   │ │  App     │
+       │  (Primary)  │ │ Server │ │ Server   │
+       └──────┬──────┘ └──┬─────┘ └───┬──────┘
+              │           │           │
+              └───────────┼───────────┘
+                          │
+                  ┌───────▼───────┐
+                  │  Base de datos │
+                  │  [Tipo + Host] │
+                  └───────────────┘
+```
+
+### Servicios gestionados
+
+| Servicio | Proveedor | Propósito | Plan / Tamaño |
+|----------|-----------|-----------|---------------|
+| **[App Hosting]** | [Proveedor — ej. Vercel / AWS ECS / Railway] | Hosting de la aplicación | [Plan] |
+| **[Database]** | [Proveedor — ej. AWS RDS / Supabase / Neon] | Base de datos gestionada | [Plan y specs] |
+| **[Cache]** | [Proveedor — ej. Redis Cloud / ElastiCache] | Caché y sesiones (si aplica) | [Plan] |
+| **[Storage]** | [Proveedor — ej. S3 / Cloudflare R2] | Archivos estáticos y uploads | [Plan] |
+| **[CDN]** | [Proveedor — ej. CloudFront / Cloudflare] | Distribución de contenido | [Plan] |
+| **[Email]** | [Proveedor — ej. SendGrid / AWS SES] | Envío de emails transaccionales | [Plan] |
+
+---
+
+## Acceso
+
+### Hosting / Dashboard
+
+| Servicio | URL de acceso | Quién tiene acceso |
+|----------|--------------|-------------------|
+| [App Hosting Dashboard] | `https://[dashboard-url]` | [Lista de personas / roles] |
+| [Database Dashboard] | `https://[dashboard-url]` | [Lista de personas / roles] |
+| [CI/CD Dashboard] | `https://[dashboard-url]` | Todos los developers |
+
+### Base de datos
+
+| Entorno | Host | Puerto | Database | Usuario de acceso |
+|---------|------|--------|----------|-------------------|
+| Staging | `[host]` | `[puerto]` | `[nombre]` | `[usuario de solo lectura para debugging]` |
+| Production | `[host]` | `[puerto]` | `[nombre]` | Solo acceso vía aplicación. Acceso directo requiere aprobación. |
+
+**Conexión directa para debugging** (solo staging):
+
+```bash
+[comando de conexión — ej. psql "postgresql://user:pass@host:port/dbname"]
+```
+
+### SSH / Console *(si aplica)*
+
+```bash
+# Conectarse al servidor de staging
+[comando — ej. ssh user@staging-host]
+
+# Ver logs en tiempo real
+[comando — ej. kubectl logs -f deployment/app -n staging]
+```
+
+---
+
+## CI/CD Pipeline
+
+### Overview
+
+| Plataforma | Configuración | Ubicación |
+|-----------|--------------|-----------|
+| **[{{TECH_STACK}} / GitLab CI / etc.]** | YAML | `[.github/workflows/ o .gitlab-ci.yml]` |
+
+### Stages
+
+```
+[Push / PR] → Lint → Test → Build → Deploy (solo en merge/tag)
+```
+
+| Stage | Qué hace | Duración aprox. |
+|-------|---------|-----------------|
+| **Lint** | Ejecuta linter y formateador | ~30s |
+| **Test** | Tests unitarios y de integración | ~2min |
+| **Build** | Build de producción | ~1min |
+| **Deploy Staging** | Deploy automático a staging (solo en push a main) | ~3min |
+| **Deploy Production** | Deploy manual o via tag (solo desde main) | ~3min |
+
+### Secrets del CI/CD
+
+Los secrets se configuran en [Settings > Secrets / Variables] del repositorio:
+
+| Secret | Propósito | Rotación |
+|--------|-----------|----------|
+| `[DEPLOY_KEY]` | Autenticación con el hosting | Cada 90 días |
+| `[PRODUCTION_DATABASE_URL]` | Connection string de producción | Cuando se rota |
+| `[API_KEY_SERVICIO]` | API key para servicios externos | Según política del servicio |
+
+**Regla**: Nunca imprimir secrets en logs. Usar masked secrets en CI/CD.
+
+---
+
+## Monitoreo y alertas
+
+| Herramienta | URL | Qué monitorea |
+|------------|-----|---------------|
+| **[Uptime monitoring]** | `https://[dashboard]` | Disponibilidad de la aplicación |
+| **[Error tracking]** | `https://[dashboard]` | Errores en producción (Sentry, etc.) |
+| **[Logs]** | `https://[dashboard]` | Logs centralizados (DataDog, CloudWatch, etc.) |
+| **[Performance]** | `https://[dashboard]` | Core Web Vitals y performance |
+
+### Alertas activas
+
+| Alerta | Condición | Canal de notificación |
+|--------|-----------|----------------------|
+| App down | Health check falla 3 veces seguidas | [Slack #incidentes + PagerDuty] |
+| Error rate alto | > 5% de requests con error 5xx en 5 min | [Slack #incidentes] |
+| Latencia alta | P95 > 3s por 5 minutos | [Slack #incidentes] |
+| CPU alto | > 80% por 10 minutos | [Slack #infra] |
+
+---
+
+## Backup y recuperación
+
+| Qué | Frecuencia | Retención | Método |
+|-----|-----------|-----------|--------|
+| **Base de datos** | [Diaria / Continua] | [30 días] | [Automated backups del proveedor] |
+| **Uploads / Files** | [Continua] | [Indefinida] | [Replicación del storage] |
+| **Configuración** | En git | Indefinida | Versionado en el repositorio |
+
+### Restaurar un backup
+
+```bash
+# 1. Identificar el backup a restaurar
+[comando para listar backups]
+
+# 2. Restaurar (ejemplo con PostgreSQL)
+pg_restore --clean --dbname=[DATABASE_URL] [archivo_de_backup]
+
+# 3. Verificar integridad
+[comando de verificación]
+```
+
+---
+
+## Escalamiento
+
+| Recurso | Límite actual | Cuándo escalar | Cómo |
+|---------|--------------|---------------|------|
+| **App servers** | [N instancias] | CPU > 70% sostenido | [Auto-scaling / manual] |
+| **Database** | [Specs] | Conexiones agotadas o queries lentas | [Upgrade de plan] |
+| **Storage** | [GB] | Al 80% de capacidad | [Auto-expande / manual] |
+
+---
+
+## Cambios a esta referencia
+
+Cualquier cambio de infraestructura (nuevo servicio, cambio de plan, nueva URL) debe actualizarse en este archivo en el mismo PR o tarea que realiza el cambio.

package/templates/modules/tutorials/docs/tutorials/environment-setup.md

@@ -0,0 +1,212 @@
+---
+created: "2025-01-01"
+status: active
+type: tutorial
+tags: [tutorial, setup, entorno, configuración, onboarding]
+---
+
+# Configuración del Entorno de Desarrollo
+
+Este tutorial te guía paso a paso para configurar tu entorno de desarrollo completo. Al terminar, tendrás todas las herramientas necesarias para trabajar en el proyecto de forma eficiente.
+
+**Tiempo estimado**: 30 minutos.
+**Audiencia**: Developers que se incorporan al proyecto.
+**Prerrequisito**: Haber completado [`quick-start.md`](quick-start.md).
+
+---
+
+## Prerrequisitos
+
+Verificar que tienes las herramientas base instaladas (ver tabla en [`quick-start.md`](quick-start.md)).
+
+---
+
+## Paso 1: Configurar el editor
+
+### VS Code *(recomendado)*
+
+Instalar las siguientes extensiones:
+
+| Extensión | Para qué | ID |
+|-----------|----------|----|
+| **[ESLint / Linter]** | Mostrar errores de lint en el editor | `[dbaeumer.vscode-eslint]` |
+| **[Prettier / Formatter]** | Formatear código al guardar | `[esbenp.prettier-vscode]` |
+| **[Tailwind CSS IntelliSense]** | Autocompletado de clases | `[bradlc.vscode-tailwindcss]` |
+| **[GitLens]** | Ver historial de cambios inline | `[eamodio.gitlens]` |
+
+Configurar format-on-save. Añadir a `.vscode/settings.json`:
+
+```json
+{
+  "editor.formatOnSave": true,
+  "editor.defaultFormatter": "[esbenp.prettier-vscode]",
+  "editor.codeActionsOnSave": {
+    "source.fixAll.[eslint]": true
+  }
+}
+```
+
+### Otros editores
+
+Si usas otro editor, asegúrate de configurar:
+- Linter integrado
+- Formateo automático al guardar
+- Integración con git
+
+---
+
+## Paso 2: Configurar herramientas de línea de comandos
+
+### Git hooks
+
+Los hooks de git se instalan automáticamente al ejecutar `[npm install]`. Verificar:
+
+```bash
+ls .git/hooks/
+# Debería mostrar: pre-commit, commit-msg, etc.
+```
+
+### CLI tools recomendadas
+
+| Herramienta | Para qué | Instalación |
+|------------|----------|-------------|
+| **[gh]** | GitHub CLI (PRs, issues desde terminal) | `brew install gh` / `winget install GitHub.cli` |
+| **[ herramienta 2 ]** | [Descripción] | `[comando de instalación]` |
+
+---
+
+## Paso 3: Configurar variables de entorno completas
+
+Copiar y configurar el archivo de entorno:
+
+```bash
+cp .env.example .env
+```
+
+### Variables obligatorias
+
+| Variable | Descripción | Ejemplo | Cómo obtener el valor |
+|----------|-------------|---------|----------------------|
+| `APP_ENV` | Entorno de ejecución | `development` | Fijo |
+| `[DATABASE_URL]` | Conexión a la base de datos local | `postgresql://user:pass@localhost:5432/dbname` | Ver Paso 4 |
+| `[API_KEY_EXTERNA]` | API key para servicios externos | `[valor]` | Pedir al tech lead |
+
+### Variables opcionales
+
+| Variable | Default | Descripción |
+|----------|---------|-------------|
+| `LOG_LEVEL` | `info` | Nivel de logging (debug, info, warn, error) |
+| `PORT` | `[3000]` | Puerto del servidor de desarrollo |
+
+Ver la referencia completa en [`docs/reference/configuration.md`](../reference/configuration.md).
+
+---
+
+## Paso 4: Configurar la base de datos local
+
+### Instalación *(si no la tienes)*
+
+```bash
+# macOS
+brew install [postgresql]
+
+# Windows
+winget install PostgreSQL.PostgreSQL
+
+# Linux
+sudo apt install postgresql
+```
+
+### Crear la base de datos
+
+```bash
+# Conectarse a PostgreSQL
+psql -U postgres
+
+# Crear base de datos y usuario
+CREATE DATABASE [nombre_db];
+CREATE USER [usuario] WITH PASSWORD '[password]';
+GRANT ALL PRIVILEGES ON DATABASE [nombre_db] TO [usuario];
+\q
+```
+
+### Ejecutar migraciones
+
+```bash
+[comando de migración — ej. npm run db:migrate]
+```
+
+### Cargar datos de desarrollo
+
+```bash
+[comando de seed — ej. npm run db:seed]
+```
+
+Esto carga datos de ejemplo para poder trabajar localmente.
+
+---
+
+## Paso 5: Verificar la configuración
+
+Ejecuta esta lista de verificación:
+
+```bash
+# 1. Tests pasan
+[npm run test]
+
+# 2. Lint pasa
+[npm run lint]
+
+# 3. Build funciona
+[npm run build]
+
+# 4. Servidor arranca
+[npm run dev]
+```
+
+Si todo pasa sin errores, tu entorno está listo.
+
+---
+
+## Paso 6: Configuración adicional *(opcional)*
+
+### Docker *(si el proyecto lo usa)*
+
+```bash
+docker-compose up -d
+```
+
+Verifica que los contenedores estén corriendo:
+
+```bash
+docker-compose ps
+```
+
+### HTTPS local *(si es necesario)*
+
+```bash
+# Generar certificado local
+[comando para generar cert]
+
+# Arrancar con HTTPS
+[comando específico]
+```
+
+---
+
+## Problemas comunes
+
+| Problema | Solución |
+|----------|----------|
+| `EADDRINUSE` (puerto en uso) | Cambiar el puerto en `.env` o matar el proceso: `lsof -i :3000` |
+| Tests fallan por conexión a DB | Verificar que PostgreSQL esté corriendo: `pg_isready` |
+| `npm install` falla | Borrar `node_modules` y `package-lock.json`, verificar versión de Node |
+| Hook de git falla | Reinstalar hooks: `npm install` |
+
+Más soluciones en [`docs/guides/troubleshooting.md`](../guides/troubleshooting.md).
+
+---
+
+## Siguiente paso
+
+Ahora que tu entorno está listo, haz tu primera contribución: [`first-task.md`](first-task.md).

package/templates/modules/tutorials/docs/tutorials/first-task.md

@@ -0,0 +1,246 @@
+---
+created: "2025-01-01"
+status: active
+type: tutorial
+tags: [tutorial, primera-tarea, contribución, PR, git]
+---
+
+# Tu Primera Tarea — End to End
+
+Este tutorial te guía a través del ciclo completo de desarrollo: desde crear una branch hasta mergear tu PR. Lo harás con una tarea real (o un ejercicio de prueba).
+
+**Tiempo estimado**: 30-45 minutos.
+**Audiencia**: Developers que hacen su primera contribución al proyecto.
+**Prerrequisitos**: Haber completado [`quick-start.md`](quick-start.md) y [`environment-setup.md`](environment-setup.md).
+
+---
+
+## Qué vas a construir
+
+[Descripción de la tarea de ejemplo. Ejemplo: "Vas a añadir un componente de 'Alerta' al design system que muestre mensajes de éxito, warning y error con estilo consistente."]
+
+Al terminar, habrás practicado:
+- Crear una branch
+- Escribir código siguiendo las convenciones del proyecto
+- Escribir tests
+- Crear un Pull Request
+- Responder a code review
+
+---
+
+## Paso 1: Actualizar main y crear tu branch
+
+```bash
+# Asegúrate de estar en main
+git checkout main
+
+# Actualiza con los últimos cambios
+git pull origin main
+
+# Crea tu branch de trabajo
+git checkout -b feature/[nombre-de-tu-feature]
+```
+
+Nombrar la branch siguiendo las convenciones de [`dev-workflow.md`](../dev-workflow.md):
+- `feature/` para features nuevas
+- `fix/` para bug fixes
+- `refactor/` para refactors
+
+---
+
+## Paso 2: Leer la documentación relevante
+
+Antes de escribir código, leer:
+
+1. [`docs/CONTEXT.md`](../CONTEXT.md) — Vocabulario del dominio.
+2. [`docs/explanation/architecture.md`](../explanation/architecture.md) — Cómo está estructurado el proyecto.
+3. [`docs/DESIGN.md`](../DESIGN.md) — Si tu tarea involucra UI (colores, tipografía, componentes).
+4. [`docs/adr/`](../adr/) — Verificar si hay ADRs relacionados con tu tarea.
+
+Esto te dará el contexto necesario para escribir código que sigue las convenciones del proyecto.
+
+---
+
+## Paso 3: Implementar
+
+### 3.1 Identificar dónde va tu cambio
+
+Mirar la estructura del proyecto (ver `AGENTS.md`) y encontrar el lugar correcto:
+
+```
+src/
+├── components/     ← Si es un componente UI
+├── pages/          ← Si es una página nueva
+├── services/       ← Si es lógica de negocio
+├── utils/          ← Si es una utilidad reutilizable
+└── types/          ← Si necesitas definir tipos nuevos
+```
+
+### 3.2 Escribir el código
+
+Seguir las convenciones:
+
+- **Nombres en inglés** (variables, funciones, archivos).
+- **Comentarios en español** cuando sean necesarios.
+- **Tipado** (si el proyecto usa TypeScript): tipar todo lo que se pueda.
+- **Accesibilidad**: si es UI, incluir `aria-labels`, roles semánticos, contraste adecuado.
+
+### 3.3 Verificar mientras desarrollas
+
+```bash
+# En una terminal, mantener el servidor corriendo
+[npm run dev]
+
+# En otra terminal, ejecutar lint después de cambios significativos
+[npm run lint]
+```
+
+---
+
+## Paso 4: Escribir tests
+
+Todo código nuevo debe incluir tests. Ver las reglas en [`dev-workflow.md`](../dev-workflow.md).
+
+### Qué testear
+
+- **Happy path**: el caso principal donde todo funciona correctamente.
+- **Edge cases**: datos vacíos, valores límite, inputs inesperados.
+- **Error cases**: qué pasa cuando algo falla.
+
+### Ejemplo
+
+```typescript
+// [archivo de test — ej. src/components/Alert.test.tsx]
+describe('Alert', () => {
+  it('muestra el mensaje correctamente', () => {
+    // Test del happy path
+  });
+
+  it('aplica el estilo según la variante', () => {
+    // Test de cada variante (success, warning, error)
+  });
+
+  it('es accesible', () => {
+    // Test de accesibilidad (aria-label, role)
+  });
+});
+```
+
+### Ejecutar los tests
+
+```bash
+[npm run test]
+
+# Si quieres ejecutar solo los tests de tu cambio:
+[comando específico — ej. npm run test -- --grep "Alert"]
+```
+
+---
+
+## Paso 5: Commit y push
+
+### Hacer commit
+
+Seguir el formato de Conventional Commits (ver [`dev-workflow.md`](../dev-workflow.md)):
+
+```bash
+git add [archivos modificados]
+git commit -m "feat([alcance]): descripción breve del cambio"
+```
+
+Ejemplos:
+
+```bash
+git commit -m "feat(ui): se añadió componente Alert con variantes success, warning y error"
+git commit -m "test(ui): se añadieron tests unitarios para componente Alert"
+```
+
+### Hacer push
+
+```bash
+git push -u origin feature/[nombre-de-tu-feature]
+```
+
+---
+
+## Paso 6: Crear el Pull Request
+
+### En GitHub
+
+1. Ir al repositorio en GitHub.
+2. Click en "Compare & pull request".
+3. Llenar el template de PR (definido en [`dev-workflow.md`](../dev-workflow.md)):
+
+```markdown
+## Qué hace
+[Añadí el componente Alert con 3 variantes: success, warning y error.]
+
+## Por qué
+[El design system no tenía un componente estándar para alertas. Cada página implementaba su propio estilo.]
+
+## Cómo probar
+1. Arrancar el servidor con `npm run dev`
+2. Ir a la página de demo: `/demo/alerts`
+3. Verificar que las 3 variantes se renderizan correctamente
+4. Verificar que los tests pasan: `npm run test`
+
+## Checklist
+- [x] Tests añadidos
+- [x] Lint pasa sin errores
+- [ ] Documentación actualizada (verificar si DESIGN.md necesita update)
+```
+
+### Asignar reviewers
+
+Asignar al menos un reviewer según el área:
+- **UI/UX**: [Nombre del diseñador/a o frontend lead]
+- **Backend**: [Nombre del backend lead]
+- **General**: [Tech lead]
+
+---
+
+## Paso 7: Responder al code review
+
+Es normal recibir comentarios. No tomarlos personalmente.
+
+1. **Leer todos los comentarios** antes de empezar a responder.
+2. **Clasificar**: blocker (🔴), sugerencia (🟡), nit (🟢).
+3. **Corregir** los blockers primero, luego las sugerencias.
+4. **Hacer commit** con los cambios:
+   ```bash
+   git commit -m "refactor([alcance]): se aplicó feedback del code review"
+   git push
+   ```
+5. **Pedir re-review** cuando termines.
+
+---
+
+## Paso 8: Merge
+
+Una vez que el PR esté aprobado y CI pase:
+
+1. Hacer **squash merge** desde GitHub (o pedir a quien tenga permisos).
+2. Borrar la branch remota.
+3. Actualizar tu local:
+
+```bash
+git checkout main
+git pull origin main
+```
+
+---
+
+## Checklist final
+
+Después de mergear, verificar:
+
+- [ ] ¿Se actualizó la documentación afectada? (Ver [`AGENTS.md`](../../AGENTS.md) checklist post-tarea.)
+- [ ] ¿Se añadió un término nuevo al dominio? → Actualizar [`CONTEXT.md`](../CONTEXT.md).
+- [ ] ¿Se tomó una decisión técnica? → Crear ADR en [`docs/adr/`](../adr/TEMPLATE.md).
+- [ ] ¿Se cambió algo visual? → Actualizar [`DESIGN.md`](../DESIGN.md).
+
+---
+
+## Felicidades
+
+Acabas de completar tu primera contribución end-to-end. Ya conoces el flujo completo del proyecto. Para siguientes tareas, el proceso es el mismo: branch → código → tests → PR → review → merge.