@damenor/agent-docs 0.1.1 → 0.4.0

package/templates/modules/reference/docs/reference/code-style.md

@@ -1,275 +0,0 @@
----
-created: "2026-05-07"
-updated: "2026-05-07"
-status: active
-type: reference
-tags: [code-style, conventions, reference, standards]
----
-
-# Code Style
-
-Convenciones de código del proyecto. Todo código nuevo DEBE seguir estas reglas.
-
-> [!important] Regla general
-> Lo que se puede automatizar (linter, formatter), se automatiza. Lo que no, se documenta aquí.
-
-## Automatización
-
-El proyecto usa estas herramientas para enforcear estilo automáticamente:
-
-| Herramienta | Qué enforcea | Archivo config |
-|-------------|-------------|----------------|
-| [ESLint / Pylint / etc.] | Reglas de código | [config file] |
-| [Prettier / Black / etc.] | Formateo | [config file] |
-| [TypeScript / mypy / etc.] | Tipos | [config file] |
-| EditorConfig | Configuración del editor | `.editorconfig` |
-
-**Si el linter pasa, el estilo es correcto.** No discutir estilo que el linter ya resuelve.
-
-## Nombramiento
-
-### Archivos y Carpetas
-
-| Tipo | Convención | Ejemplo |
-|------|-----------|---------|
-| Componentes UI | `PascalCase` | `Button.tsx`, `NavBar.vue` |
-| Utilidades | `camelCase` | `formatDate.ts`, `parseConfig.js` |
-| Tests | `[nombre].test/spec.[ext]` | `auth.test.ts`, `api.spec.ts` |
-| Tipos/Interfaces | `PascalCase` | `User.ts`, `ApiResponse.ts` |
-| Constantes | `UPPER_SNAKE_CASE` | `API_URLS.ts`, `MAX_RETRIES.ts` |
-| Páginas/Rutas | `kebab-case` | `user-profile.tsx`, `about.vue` |
-
-### Variables y Funciones
-
-| Tipo | Convención | Ejemplo |
-|------|-----------|---------|
-| Variables | `camelCase` | `userName`, `isActive` |
-| Constantes | `UPPER_SNAKE_CASE` | `MAX_RETRIES`, `API_BASE_URL` |
-| Funciones | `camelCase` | `getUser()`, `calculateTotal()` |
-| Booleanos | `is`/`has`/`should` prefix | `isLoading`, `hasPermission` |
-| Clases | `PascalCase` | `UserService`, `HttpClient` |
-| Interfaces/Types | `PascalCase` | `User`, `ApiResponse` |
-| Enums | `PascalCase` | `UserRole`, `OrderStatus` |
-| Eventos | `on` prefix | `onClick`, `onSubmit` |
-
-## Imports
-
-### Orden de imports
-
-```typescript
-// 1. Librerías externas
-import { useState, useEffect } from 'react'
-import axios from 'axios'
-
-// 2. Imports internos (alias si están configurados)
-import { Button } from '@/components/ui/Button'
-import { useAuth } from '@/hooks/useAuth'
-
-// 3. Tipos
-import type { User, ApiResponse } from '@/types'
-
-// 4. Estilos (si aplica)
-import './styles.css'
-```
-
-### Reglas
-
-- Imports agrupados con línea en blanco entre grupos
-- Sin imports wildcard (`import *`) a menos que sea necesario
-- Usar alias de path configurados (`@/`, `~`, etc.)
-- Imports de tipos con `import type` cuando sea solo tipo
-
-## Estructura de Código
-
-### Componentes UI
-
-```typescript
-// Orden dentro de un componente:
-// 1. Types/Interfaces
-// 2. Constantes
-// 3. Componente principal
-// 4. Subcomponentes (si son pequeños)
-// 5. Export
-
-interface ButtonProps {
-  variant?: 'primary' | 'secondary'
-  children: React.ReactNode
-  onClick?: () => void
-}
-
-const VARIANT_STYLES = {
-  primary: 'bg-blue-600 text-white',
-  secondary: 'bg-gray-200 text-gray-800',
-}
-
-export function Button({ variant = 'primary', children, onClick }: ButtonProps) {
-  return (
-    <button className={VARIANT_STYLES[variant]} onClick={onClick}>
-      {children}
-    </button>
-  )
-}
-```
-
-### Funciones de API / Servicios
-
-```typescript
-// Orden:
-// 1. Validación de inputs
-// 2. Lógica de negocio
-// 3. Side effects (logs, métricas)
-// 4. Return
-
-export async function createUser(input: CreateUserInput): Promise<User> {
-  // Validación
-  validateCreateUserInput(input)
-
-  // Lógica
-  const hashedPassword = await hashPassword(input.password)
-  const user = await db.user.create({ ...input, password: hashedPassword })
-
-  // Side effects
-  logger.info('User created', { userId: user.id })
-
-  return user
-}
-```
-
-## Comentarios
-
-### Cuándo comentar
-
-Comentar el **por qué**, no el **qué**:
-
-```typescript
-// ❌ Mal: Restate lo que el código ya dice
-counter += 1
-
-// ✅ Bien: Explica por qué
-if (now - windowStart > WINDOW_SIZE_MS) {
-  counter = 0
-  windowStart = now
-}
-```
-
-### Cuándo NO comentar
-
-- Código auto-explicativo
-- TODOs que deberías hacer ahora
-- Código comentado (elimínalo, git tiene historia)
-- **No usar comentarios inline** para explicar decisiones — usar JSDoc/docstring
-
-### JSDoc / Docstrings
-
-**OBLIGATORIO** para funciones públicas del módulo y componentes complejos. Explicar el POR QUÉ, no el qué:
-
-```typescript
-/**
- * Creates a new user with hashed password.
- * Uses bcrypt with 12 rounds — chose this over argon2 because
- * we don't need GPU-resistant hashing for internal users.
- *
- * @param input - User creation data
- * @returns Created user without password
- * @throws {ValidationError} If email is invalid or already exists
- */
-```
-
-```typescript
-/**
- * Debounced search that cancels previous requests.
- * Needed because the API has a rate limit of 10 req/min
- * and users type fast in the search bar.
- */
-export function useSearch(query: string, delay = 300) { ... }
-```
-
-**Cuando escribir JSDoc**:
-- Funciones exportadas / públicas del módulo
-- Componentes UI complejos (props no obvias, comportamiento especial)
-- Hooks custom con lógica no trivial
-- Funciones que resuelven un problema específico (documentar el problema)
-- Funciones donde se tomó una decisión de implementación no obvia
-
-## Manejo de Errores
-
-- Nunca usar `any` como tipo de error
-- Siempre manejar errores en el nivel apropiado
-- Logear errores con contexto suficiente
-- No swallow errors silenciosamente
-
-```typescript
-// ❌ Mal
-try {
-  await doSomething()
-} catch (e) {}
-
-// ✅ Bien
-try {
-  await doSomething()
-} catch (error) {
-  logger.error('Failed to do something', { error, context })
-  throw new AppError('Something went wrong', { cause: error })
-}
-```
-
-## Testing
-
-### Convenciones de Tests
-
-- Archivos de test junto al archivo que testean o en carpeta `__tests__/`
-- Nombre descriptivo: `should [expected behavior] when [condition]`
-- Patrón AAA: Arrange → Act → Assert
-- Un assertion conceptual por test
-
-```typescript
-describe('createUser', () => {
-  it('should create user with hashed password when input is valid', async () => {
-    // Arrange
-    const input = { email: 'test@test.com', password: 'password123' }
-
-    // Act
-    const user = await createUser(input)
-
-    // Assert
-    expect(user.email).toBe(input.email)
-    expect(user.password).not.toBe(input.password)
-  })
-})
-```
-
-## Git
-
-### Mensajes de Commit
-
-Seguir [Conventional Commits](https://www.conventionalcommits.org/):
-
-```
-tipo(alcance): descripción breve
-
-tipo: feat | fix | docs | style | refactor | perf | test | chore
-alcance: módulo o componente afectado (opcional)
-```
-
-Ejemplos:
-```
-feat(auth): add JWT refresh token rotation
-fix(api): handle null user in response
-docs(readme): update setup instructions
-refactor(utils): extract date formatting to shared util
-```
-
-### Nombres de Branches
-
-```
-tipo/descripción-corta
-
-tipos: feat | fix | refactor | docs | chore
-```
-
-Ejemplos:
-```
-feat/user-profile
-fix/login-redirect
-refactor/api-error-handling
-```

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

@@ -1,117 +0,0 @@
----
-created: "2025-01-01"
-status: active
-type: reference
-tags: [referencia, configuración, variables, entorno, env]
----
-
-# Referencia de Configuración
-
-Listado completo de variables de entorno y opciones de configuración del proyecto.
-
----
-
-## Variables de entorno
-
-### Aplicación
-
-| Variable | Requerida | Default | Descripción | Ejemplo |
-|----------|-----------|---------|-------------|---------|
-| `APP_ENV` | Sí | `development` | Entorno de ejecución. Valores: `development`, `staging`, `production` | `production` |
-| `APP_PORT` | No | `[3000]` | Puerto donde escucha el servidor | `8080` |
-| `APP_URL` | Sí (prod) | `http://localhost:3000` | URL pública de la aplicación | `https://[dominio]` |
-| `APP_NAME` | No | `{{PROJECT_NAME}}` | Nombre de la aplicación para logs y metadata | `Mi Proyecto` |
-| `LOG_LEVEL` | No | `info` | Nivel de logging. Valores: `debug`, `info`, `warn`, `error` | `debug` |
-
-### Base de datos
-
-| Variable | Requerida | Default | Descripción | Ejemplo |
-|----------|-----------|---------|-------------|---------|
-| `DATABASE_URL` | Sí | — | Connection string completo de la base de datos | `postgresql://user:pass@host:5432/dbname?ssl=true` |
-| `DATABASE_POOL_SIZE` | No | `10` | Tamaño del pool de conexiones | `20` |
-| `DATABASE_SSL` | No | `false` | Habilitar SSL para la conexión | `true` |
-
-### Autenticación
-
-| Variable | Requerida | Default | Descripción | Ejemplo |
-|----------|-----------|---------|-------------|---------|
-| `JWT_SECRET` | Sí | — | Secret para firmar JWTs. **Debe ser único por entorno y nunca commiteado.** | `[string aleatorio de 32+ caracteres]` |
-| `JWT_EXPIRES_IN` | No | `1h` | Tiempo de expiración del token de acceso | `30m` |
-| `JWT_REFRESH_EXPIRES_IN` | No | `7d` | Tiempo de expiración del refresh token | `30d` |
-
-### Servicios externos
-
-| Variable | Requerida | Default | Descripción | Ejemplo |
-|----------|-----------|---------|-------------|---------|
-| `[SERVICIO]_API_KEY` | Sí (prod) | — | API key para [servicio externo] | `[key]` |
-| `[SERVICIO]_API_URL` | No | `[URL default]` | URL base de la API del servicio | `https://api.servicio.com/v1` |
-| `[SERVICIO]_TIMEOUT` | No | `5000` | Timeout en ms para requests al servicio | `10000` |
-
-### Email *(si aplica)*
-
-| Variable | Requerida | Default | Descripción | Ejemplo |
-|----------|-----------|---------|-------------|---------|
-| `SMTP_HOST` | No | — | Host del servidor SMTP | `smtp.gmail.com` |
-| `SMTP_PORT` | No | `587` | Puerto SMTP | `465` |
-| `SMTP_USER` | No | — | Usuario SMTP | `noreply@[dominio]` |
-| `SMTP_PASSWORD` | No | — | Contraseña SMTP | `[password]` |
-| `EMAIL_FROM` | No | `noreply@[dominio]` | Email remitente por defecto | `contacto@[dominio]` |
-
-### Storage / CDN *(si aplica)*
-
-| Variable | Requerida | Default | Descripción | Ejemplo |
-|----------|-----------|---------|-------------|---------|
-| `STORAGE_BUCKET` | No | — | Nombre del bucket de storage | `mi-proyecto-assets` |
-| `STORAGE_REGION` | No | — | Región del bucket | `us-east-1` |
-| `CDN_URL` | No | — | URL del CDN para assets | `https://cdn.[dominio]` |
-
----
-
-## Valores por entorno
-
-| Variable | Development | Staging | Production |
-|----------|-------------|---------|------------|
-| `APP_ENV` | `development` | `staging` | `production` |
-| `LOG_LEVEL` | `debug` | `info` | `warn` |
-| `DATABASE_URL` | Local DB | Staging DB | Production DB |
-| `JWT_SECRET` | Cualquier valor para dev | Secret de staging | Secret de producción (rotado regularmente) |
-| `[API_KEY]` | Key de testing | Key de staging | Key de producción |
-
----
-
-## Archivos de configuración
-
-### `.env.example`
-
-El archivo `.env.example` en la raíz del proyecto contiene **todas las variables posibles** con valores de ejemplo o placeholders. Se commitea al repo y sirve como referencia.
-
-**Regla**: Si se añade una variable nueva, actualizar `.env.example` primero.
-
-### Archivos de config del framework
-
-| Archivo | Propósito | Formato |
-|---------|-----------|---------|
-| `[tsconfig.json / pyproject.toml / etc.]` | Configuración del lenguaje/framework | [JSON / TOML / YAML] |
-| `[tailwind.config.js / etc.]` | Configuración de estilos | [JS / CSS] |
-| `[docker-compose.yml]` | Servicios de desarrollo local | YAML |
-| `[Dockerfile]` | Imagen Docker para producción | Dockerfile |
-
----
-
-## Reglas de configuración
-
-1. **Nunca commitear secrets**: Todo valor sensible (passwords, API keys, secrets) va en `.env` que está en `.gitignore`.
-2. **Defaults seguros**: Las variables que tienen default deben funcionar "out of the box" para desarrollo local.
-3. **Fail fast**: Si una variable requerida no está configurada, la aplicación debe fallar al arrancar con un mensaje claro que diga cuál falta.
-4. **Validación al inicio**: Las variables se validan al arrancar la aplicación, no en cada request.
-5. **Documentar cambios**: Si se añade una variable nueva, actualizar este archivo y `.env.example` en el mismo commit.
-
----
-
-## Cómo añadir una variable nueva
-
-1. Añadir la variable a `.env.example` con un valor de ejemplo o placeholder.
-2. Añadir la variable a este archivo (`configuration.md`) en la sección correspondiente.
-3. Implementar la lectura de la variable en código (con valor default si aplica).
-4. Configurar la variable en los entornos de staging y production (CI/CD secrets, dashboard del hosting, etc.).
-5. Commit todo junto (código + docs + `.env.example`).

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

@@ -1,191 +0,0 @@
----
-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.