@saulwade/swl-ses 1.0.0

package/plantillas/github-workflows/swl-security.yml

@@ -0,0 +1,51 @@
+name: Revisión de Seguridad — Claude Code
+
+# Plantilla distribuida por swl-ses.
+# Copiar este archivo a .github/workflows/ de tu proyecto.
+# Para setup automatizado: /swl:configurar-ci init
+#
+# PREREQUISITO — configurar el secret CLAUDE_API_KEY en tu repositorio:
+#   GitHub → Settings → Secrets and variables → Actions → New repository secret
+#   Nombre: CLAUDE_API_KEY
+#   Valor:  clave API de Anthropic (https://console.anthropic.com)
+#   La clave requiere permisos tanto para Claude API como para Claude Code.
+#
+# Referencia de la action oficial:
+#   https://github.com/anthropics/claude-code-security-review
+#
+# NOTA: los workflows de forks externos no reciben secrets por diseño de GitHub.
+# La revisión de seguridad solo corre en PRs de ramas del mismo repositorio.
+
+on:
+  pull_request:
+    branches: [main]
+
+# Permisos mínimos: escribir comentarios en PRs y leer contenido del repo.
+permissions:
+  pull-requests: write
+  contents: read
+
+jobs:
+  security:
+    name: Análisis de seguridad con Claude
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          # fetch-depth: 2 es requerido por la action para calcular el diff.
+          ref: ${{ github.event.pull_request.head.sha || github.sha }}
+          fetch-depth: 2
+
+      # Análisis semántico de seguridad sobre el diff del PR.
+      # Detecta: inyecciones SQL/OS, credenciales expuestas, auth débil,
+      # SSRF, XSS y las 10 categorías del OWASP Top 10.
+      # Comenta hallazgos directamente en el PR.
+      - uses: anthropics/claude-code-security-review@main
+        with:
+          claude-api-key: ${{ secrets.CLAUDE_API_KEY }}
+          comment-pr: true
+          upload-results: true
+          # Excluir directorios que no son código de producción.
+          # Ajustar según la estructura de tu proyecto.
+          # exclude-directories: "temp,docs,fixtures"

package/plantillas/mcp-mineru.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "https://json.schemastore.org/mcp-config.json",
+  "_comment": "Configuración MCP de MinerU para extracción de documentos. Se fusiona con .mcp.json del proyecto durante la instalación de SWL-SES.",
+  "mcpServers": {
+    "mineru": {
+      "command": "uvx",
+      "args": ["mineru-open-mcp"],
+      "env": {
+        "MINERU_API_TOKEN": ""
+      }
+    }
+  }
+}

package/plantillas/research/ARQUITECTURA.md

@@ -0,0 +1,220 @@
+# ARCHITECTURE: Arquitectura Propuesta — [Nombre del Proyecto]
+
+> Documento de diseño arquitectural. Define la estructura del sistema antes
+> de escribir código. Las decisiones aquí deben estar respaldadas por ADRs
+> para las más significativas.
+> Autor: [nombre] | Fecha: YYYY-MM-DD | Estado: Borrador / Revisado / Aprobado
+
+---
+
+## Visión general
+
+[2-3 párrafos describiendo la arquitectura en términos de alto nivel.
+Qué tipo de sistema es (monolito modular, microservicios, serverless, etc.).
+Por qué esta estructura es la correcta para este problema y equipo.]
+
+**Estilo arquitectural**: [ej. Monolito modular con frontend SPA]
+**Patrón principal**: [ej. Layered Architecture / Hexagonal / CQRS]
+**Justificación**: [Por qué este estilo y no otro para este proyecto]
+
+---
+
+## Diagrama de contexto (Nivel 1 — C4)
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                        Sistema: [Nombre]                        │
+│                                                                  │
+│  ┌──────────┐    HTTPS     ┌──────────────────┐                │
+│  │ Usuario  │ ──────────► │  Frontend SPA    │                │
+│  │          │ ◄────────── │  (Angular)       │                │
+│  └──────────┘              └────────┬─────────┘                │
+│                                     │ REST API                  │
+│                            ┌────────▼─────────┐                │
+│                            │   Backend API    │                │
+│                            │   (FastAPI)      │                │
+│                            └──┬────────────┬──┘                │
+│                               │            │                    │
+│                    ┌──────────▼──┐  ┌──────▼──────────┐       │
+│                    │ PostgreSQL  │  │ Redis (cache)   │       │
+│                    │    (BD)     │  │                 │       │
+│                    └─────────────┘  └─────────────────┘       │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+          ┌───────────────────┼───────────────────┐
+          │                   │                   │
+   ┌──────▼──────┐  ┌─────────▼──────┐  ┌────────▼────────┐
+   │ [Servicio   │  │ [API Externa   │  │ [Servicio de    │
+   │  Externo 1] │  │  ej. SAT CFDI] │  │  Email / SMS]   │
+   └─────────────┘  └────────────────┘  └─────────────────┘
+```
+
+[Actualizar el diagrama con los componentes reales del proyecto]
+
+---
+
+## Diagrama de contenedores (Nivel 2 — C4)
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                     Backend API                         │
+│                                                          │
+│  ┌─────────────┐   ┌─────────────┐   ┌──────────────┐  │
+│  │  Routers    │──►│  Services   │──►│ Repositories │  │
+│  │ (endpoints) │   │ (lógica de  │   │ (acceso a    │  │
+│  │             │◄──│  negocio)   │◄──│  datos)      │  │
+│  └─────────────┘   └──────┬──────┘   └──────┬───────┘  │
+│                            │                 │           │
+│                    ┌───────▼───────┐  ┌──────▼──────┐   │
+│                    │ Domain Models │  │    ORM      │   │
+│                    │ (Pydantic)    │  │ (SQLAlchemy)│   │
+│                    └───────────────┘  └─────────────┘   │
+└─────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Módulos del sistema
+
+### Módulo: [Nombre — ej. Autenticación]
+
+**Responsabilidad**: [Qué problema resuelve este módulo y nada más]
+**Interfaz pública**:
+- `POST /auth/login` — obtener token JWT
+- `POST /auth/refresh` — renovar token
+- `POST /auth/logout` — invalidar token
+- `AuthGuard` — guardia de Angular para rutas protegidas
+
+**Lo que NO hace este módulo**:
+- [Restricción explícita — qué responsabilidad NO tiene]
+
+**Archivos principales**:
+```
+backend/app/
+├── routers/auth.py
+├── services/auth_service.py
+├── models/usuario.py
+└── schemas/auth.py
+
+frontend/src/app/
+├── core/guards/auth.guard.ts
+└── features/auth/
+    ├── login/
+    └── services/auth.service.ts
+```
+
+---
+
+### Módulo: [Nombre — ej. Gestión de Facturas]
+
+**Responsabilidad**:
+**Interfaz pública**:
+- `GET /facturas` — listar facturas del usuario
+- `POST /facturas` — crear factura
+- `GET /facturas/{id}` — detalle
+- `PUT /facturas/{id}/timbrar` — enviar al PAC
+
+**Lo que NO hace este módulo**:
+-
+
+**Archivos principales**:
+```
+backend/app/
+├── routers/facturas.py
+├── services/factura_service.py
+├── models/factura.py
+└── schemas/factura.py
+
+frontend/src/app/features/facturas/
+├── list/
+├── form/
+└── services/facturas.service.ts
+```
+
+---
+
+### Módulo: [Nombre del tercer módulo]
+
+**Responsabilidad**:
+**Interfaz pública**:
+-
+
+---
+
+## Flujos de datos principales
+
+### Flujo 1: [ej. Creación de factura]
+
+```
+Usuario                Frontend              Backend API           BD
+  │                       │                      │                  │
+  │── Llena formulario ──►│                      │                  │
+  │                       │── POST /facturas ───►│                  │
+  │                       │                      │── Valida schema  │
+  │                       │                      │── Crea registro ►│
+  │                       │                      │◄─ Retorna ID ────│
+  │                       │◄── 201 { factura } ──│                  │
+  │◄── Redirige al detalle│                      │                  │
+```
+
+### Flujo 2: [ej. Autenticación con JWT]
+
+```
+Usuario                Frontend              Backend API           Redis
+  │                       │                      │                   │
+  │── Login (user/pass) ──►│                      │                   │
+  │                       │── POST /auth/login ──►│                   │
+  │                       │                      │── Verifica creds  │
+  │                       │                      │── Genera JWT      │
+  │                       │◄── 200 { token } ────│                   │
+  │                       │── Guarda en storage   │                   │
+  │◄─ Redirige al dashboard│                      │                   │
+```
+
+---
+
+## Decisiones arquitecturales clave
+
+| Decisión | Descripción | ADR |
+|----------|-------------|-----|
+| [Título de la decisión] | [Qué se decidió en una línea] | ADR-NNN |
+| [Título de la decisión] | | ADR-NNN |
+| [Título de la decisión] | | ADR-NNN |
+
+---
+
+## Estrategia de autenticación y autorización
+
+**Autenticación**: [ej. JWT con refresh tokens en httpOnly cookie]
+**Autorización**: [ej. RBAC con roles: ADMIN, OPERADOR, LECTOR]
+**Roles definidos**:
+
+| Rol | Descripción | Permisos |
+|-----|-------------|----------|
+| [ADMIN] | [descripción] | [CRUD completo] |
+| [OPERADOR] | [descripción] | [Crear y editar, no eliminar] |
+| [LECTOR] | [descripción] | [Solo lectura] |
+
+---
+
+## Estrategia de errores
+
+| Tipo de error | HTTP Status | Formato de respuesta |
+|---------------|-------------|---------------------|
+| Validación de input | 422 | `{ detail: [{ loc, msg, type }] }` (Pydantic default) |
+| No autenticado | 401 | `{ detail: "No autenticado" }` |
+| Sin permisos | 403 | `{ detail: "Sin permisos para esta operación" }` |
+| Recurso no encontrado | 404 | `{ detail: "Recurso no encontrado" }` |
+| Error de negocio | 400 | `{ detail: "descripción del error de negocio" }` |
+| Error interno | 500 | `{ detail: "Error interno del servidor" }` (sin exponer stack) |
+
+---
+
+## Checklist de arquitectura
+
+- [ ] Cada módulo tiene responsabilidad claramente definida
+- [ ] No hay dependencias circulares entre módulos
+- [ ] Los flujos de datos están documentados para los casos principales
+- [ ] La estrategia de auth cubre autenticación y autorización
+- [ ] Las decisiones significativas tienen ADRs pendientes de redactar
+- [ ] La arquitectura es verificable con los criterios definidos en HOJA-RUTA.md

package/plantillas/research/FUNCIONALIDADES.md

@@ -0,0 +1,175 @@
+# FEATURES: Investigación de Funcionalidades — [Nombre del Proyecto]
+
+> Análisis técnico de cada feature antes de comprometerse a implementarla.
+> El objetivo es estimar esfuerzo, identificar dependencias y anticipar riesgos
+> ANTES de comenzar el desarrollo.
+> Autor: [nombre] | Fecha: YYYY-MM-DD
+
+---
+
+## Cómo usar esta plantilla
+
+Para cada feature:
+1. Describir qué debe hacer (desde la perspectiva del usuario)
+2. Investigar cómo se implementa técnicamente
+3. Estimar la complejidad con base en la investigación, no en intuición
+4. Identificar dependencias bloqueantes
+5. Documentar riesgos técnicos específicos
+
+Escala de complejidad:
+- **S** (Small): <= 1 día de desarrollo
+- **M** (Medium): 2-4 días
+- **L** (Large): 1-2 semanas
+- **XL** (Extra Large): > 2 semanas — candidata a dividir en sub-features
+
+---
+
+## Feature 1: [Nombre de la feature]
+
+**Requisitos que implementa**: REQ-001, REQ-002
+**Módulo**: [Nombre del módulo del sistema]
+
+### Descripción funcional
+[Qué hace esta feature desde la perspectiva del usuario final.
+Flujo happy path en 3-5 pasos.]
+
+### Análisis técnico
+
+**Capa backend**:
+[Qué endpoints se necesitan. Qué modelos y tablas se crean o modifican.
+Qué lógica de negocio no trivial tiene. Operaciones async, jobs, etc.]
+
+**Capa frontend**:
+[Qué componentes. Qué formularios. Qué integración de API.
+State management necesario.]
+
+**Integraciones externas**:
+[APIs de terceros, servicios externos, webhooks, etc.]
+
+**Cambios a BD**:
+[Tablas nuevas, columnas nuevas, índices, constraints.]
+
+### Complejidad estimada
+
+| Componente | Estimación | Justificación |
+|-----------|------------|---------------|
+| Backend API | [S/M/L/XL] | [por qué] |
+| Frontend UI | [S/M/L/XL] | [por qué] |
+| Integración externa | [S/M/L/XL / N/A] | [por qué] |
+| Tests | [S/M/L/XL] | [por qué] |
+| **Total feature** | **[S/M/L/XL]** | |
+
+### Dependencias
+
+| Dependencia | Tipo | Estado | Bloqueante |
+|-------------|------|--------|------------|
+| [Feature o componente que debe estar listo primero] | Interna / Externa | Disponible / Pendiente | Sí / No |
+| [Librería o servicio externo necesario] | Externa | | |
+
+### Riesgos técnicos
+
+| Riesgo | Probabilidad | Impacto | Mitigación |
+|--------|-------------|---------|------------|
+| [Qué puede salir mal técnicamente] | Alta/Media/Baja | Alto/Medio/Bajo | [Cómo prevenirlo o manejarlo] |
+
+### Prototipo / PoC necesario
+
+[ ] No — suficientemente conocida para implementar directamente
+[ ] Sí — necesita spike de [N días] para validar: [qué se necesita validar]
+
+---
+
+## Feature 2: [Nombre de la feature]
+
+**Requisitos que implementa**: REQ-0XX
+**Módulo**:
+
+### Descripción funcional
+
+
+### Análisis técnico
+
+**Capa backend**:
+
+**Capa frontend**:
+
+**Integraciones externas**:
+
+**Cambios a BD**:
+
+### Complejidad estimada
+
+| Componente | Estimación | Justificación |
+|-----------|------------|---------------|
+| Backend API | | |
+| Frontend UI | | |
+| Tests | | |
+| **Total feature** | | |
+
+### Dependencias
+
+| Dependencia | Tipo | Estado | Bloqueante |
+|-------------|------|--------|------------|
+| | | | |
+
+### Riesgos técnicos
+
+| Riesgo | Probabilidad | Impacto | Mitigación |
+|--------|-------------|---------|------------|
+| | | | |
+
+---
+
+## Feature 3: [Nombre de la feature]
+
+**Requisitos que implementa**:
+**Módulo**:
+
+### Descripción funcional
+
+
+### Análisis técnico
+
+**Capa backend**:
+
+**Capa frontend**:
+
+**Cambios a BD**:
+
+### Complejidad estimada
+
+| Componente | Estimación | Justificación |
+|-----------|------------|---------------|
+| **Total feature** | | |
+
+### Dependencias
+
+### Riesgos técnicos
+
+---
+
+## Resumen de estimaciones
+
+| Feature | Complejidad | Dependencias bloqueantes | PoC necesario |
+|---------|-------------|--------------------------|---------------|
+| Feature 1: [nombre] | [S/M/L/XL] | [ninguna / sí: X] | No / Sí |
+| Feature 2: [nombre] | | | |
+| Feature 3: [nombre] | | | |
+
+**Esfuerzo total estimado**: [N semanas con [M] desarrolladores]
+**Features de alto riesgo que necesitan atención temprana**: [lista]
+
+---
+
+## Orden de implementación recomendado
+
+[Propuesta de orden de implementación considerando dependencias, riesgo y valor.
+Justificar por qué este orden y no otro.]
+
+1. [Feature] — base para las siguientes / mayor riesgo técnico / mayor valor
+2. [Feature] — depende de #1 / desbloquea features de frontend
+3. [Feature]
+4. [Feature]
+
+**Criterio de ordenamiento**: [qué principio guía el orden — ej. "riesgo primero",
+"valor al usuario antes posible", "dependencias técnicas"]

package/plantillas/research/RESUMEN.md

@@ -0,0 +1,165 @@
+# SUMMARY: Resumen Ejecutivo de Investigación — [Nombre del Proyecto]
+
+> Este documento consolida los hallazgos de toda la investigación técnica y
+> presenta las recomendaciones finales para tomar decisiones informadas.
+> Es el punto de entrada para el planificador y el equipo.
+> Autor: [nombre] | Fecha: YYYY-MM-DD | Estado: Borrador / Final
+
+---
+
+## TL;DR — Lo más importante
+
+[3-5 bullets con los hallazgos más críticos y las recomendaciones clave.
+Alguien que solo lea esto debe poder tomar decisiones informadas.]
+
+- **Stack recomendado**: [tecnologías principales] — madurez probada, equipo familiarizado.
+- **Mayor riesgo técnico**: [descripción en una línea] — mitigación disponible.
+- **Feature más compleja**: [nombre] — requiere spike de [N] días antes de comprometerse.
+- **Decisión más urgente**: [qué debe decidirse antes de empezar a codificar].
+- **Estimación total**: [N] semanas con [M] desarrolladores en [P] fases.
+
+---
+
+## Stack tecnológico — Decisión final
+
+| Capa | Tecnología elegida | Confianza | Alternativa descartada |
+|------|-------------------|-----------|------------------------|
+| Backend | [ej. FastAPI 0.111 + Python 3.12] | Alta | [Django — overhead para API-only] |
+| Base de datos | [ej. PostgreSQL 16] | Alta | [MySQL — menor soporte para JSONB] |
+| Frontend | [ej. Angular 18] | Alta | [React — consistencia con stack actual] |
+| Cache | [ej. Redis 7] | Alta | [Memcached — estructuras de datos limitadas] |
+| Infraestructura | [ej. Docker + GCP Cloud Run] | Media | [VMs — mayor mantenimiento operativo] |
+
+**Ver análisis detallado**: `research/STACK.md`
+
+---
+
+## Análisis de complejidad de features
+
+### Features de alta prioridad (P0-P1)
+
+| Feature | Complejidad | Esfuerzo estimado | Riesgo principal |
+|---------|-------------|-------------------|-----------------|
+| [Nombre] | [S/M/L/XL] | [N días] | [descripción del riesgo] |
+| [Nombre] | | | |
+| [Nombre] | | | |
+
+### Features de media-baja prioridad (P2-P3)
+
+| Feature | Complejidad | Esfuerzo estimado | Fase sugerida |
+|---------|-------------|-------------------|---------------|
+| [Nombre] | | | Fase [N] |
+| [Nombre] | | | Fase [N] |
+
+**Ver análisis detallado**: `research/FUNCIONALIDADES.md`
+
+---
+
+## Arquitectura — Resumen de decisiones
+
+**Estilo adoptado**: [ej. Monolito modular con separación de capas + SPA Angular]
+
+**Decisiones más importantes**:
+
+1. **[Decisión 1]**: [Qué se decide y por qué — 2 líneas máximo]
+2. **[Decisión 2]**: [Qué se decide y por qué]
+3. **[Decisión 3]**: [Qué se decide y por qué]
+
+**ADRs a redactar** (en orden de prioridad):
+- [ ] ADR-001: [Título de la decisión]
+- [ ] ADR-002: [Título]
+- [ ] ADR-003: [Título]
+
+**Ver arquitectura detallada**: `research/ARQUITECTURA.md`
+
+---
+
+## Riesgos identificados
+
+| # | Riesgo | Severidad | Mitigación recomendada |
+|---|--------|-----------|------------------------|
+| R1 | [Riesgo técnico específico] | Alta | [Acción concreta] |
+| R2 | [Riesgo de integración] | Alta | [Acción concreta] |
+| R3 | [Riesgo de estimación — feature puede ser más compleja] | Media | [Spike de N días primero] |
+| R4 | [Riesgo de dependencia externa] | Media | [Plan B] |
+| R5 | [Riesgo de equipo — conocimiento del stack] | Baja | [Capacitación / pair programming] |
+
+**Ver catálogo de trampas**: `research/TRAMPAS.md`
+
+---
+
+## Estimación de esfuerzo total
+
+**Metodología de estimación**: [T-shirt sizing / Story points / días ideales]
+
+| Fase | Contenido | Esfuerzo estimado | Supuestos |
+|------|-----------|-------------------|-----------|
+| Fase 1 | [Qué features incluye] | [N semanas] | [Supuesto de estimación] |
+| Fase 2 | | | |
+| Fase 3 | | | |
+| **Total** | | **[N] semanas** | |
+
+**Con [M] desarrolladores**: [N/M semanas en paralelo ideal]
+
+**Margen de contingencia recomendado**: +20% sobre el estimado base.
+
+**Incertidumbre**: [Alta/Media/Baja]
+- Alta: hay features con tecnología no conocida por el equipo o integraciones no exploradas
+- Media: stack conocido, pero hay 1-2 integraciones que necesitan spike
+- Baja: stack dominado, todas las integraciones son conocidas
+
+---
+
+## Preguntas que deben resolverse antes de iniciar
+
+[Preguntas cuya respuesta cambia significativamente el diseño o el alcance.
+Si no se resuelven antes de codificar, se acumula deuda de decisión.]
+
+| # | Pregunta | Impacto si no se responde | Quién decide | Urgencia |
+|---|----------|--------------------------|-------------|----------|
+| P1 | [Pregunta técnica o de negocio específica] | [Qué parte del diseño queda bloqueada] | [Nombre/Rol] | Alta |
+| P2 | | | | Alta |
+| P3 | | | | Media |
+
+---
+
+## Recomendaciones para el planificador
+
+[Recomendaciones específicas sobre cómo planificar la ejecución, basadas
+en los hallazgos de la investigación.]
+
+1. **Iniciar con spike técnico de [N] días** para validar [la integración X / la tecnología Y]
+   antes de comprometer el equipo a la estimación completa.
+
+2. **Feature [nombre] es el camino crítico** — cualquier retraso en esta feature
+   retrasa todo lo demás. Debe iniciar en la Fase 1 sin importar qué.
+
+3. **Contratar / capacitar en [tecnología]** antes de la Fase [N] — el equipo
+   actual no tiene experiencia suficiente con [tecnología específica].
+
+4. **No iniciar el frontend hasta que [condición]** — el API contract debe estar
+   estable antes de invertir en componentes UI.
+
+5. **Revisar este SUMMARY con el cliente** antes de iniciar — los supuestos de
+   [supuesto X] deben ser validados por el stakeholder.
+
+---
+
+## Documentos de investigación completos
+
+| Documento | Descripción | Estado |
+|-----------|-------------|--------|
+| `research/STACK.md` | Evaluación detallada de tecnologías | Completo / Pendiente |
+| `research/FUNCIONALIDADES.md` | Análisis de complejidad por feature | Completo / Pendiente |
+| `research/ARQUITECTURA.md` | Arquitectura propuesta con diagramas | Completo / Pendiente |
+| `research/TRAMPAS.md` | Trampas y anti-patrones del stack | Completo / Pendiente |
+
+---
+
+## Próximos pasos recomendados
+
+1. [ ] Aprobar (o ajustar) el stack tecnológico — responsable: [nombre], fecha límite: YYYY-MM-DD
+2. [ ] Responder preguntas abiertas P1 y P2 — responsable: [nombre], fecha límite: YYYY-MM-DD
+3. [ ] Ejecutar spike de [N] días para validar [integración X] — responsable: [nombre]
+4. [ ] Redactar ADR-001 a ADR-003 — responsable: [nombre]
+5. [ ] Crear HOJA-RUTA.md con fases basadas en estas estimaciones — responsable: planificador