npm - sinapse-ai - Versions diffs - 5.0.8 → 6.0.1 - Mend

sinapse-ai 5.0.8 → 6.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (660) hide show

package/docs/es/git-workflow-guide.md DELETED Viewed

@@ -1,995 +0,0 @@
-<!--
-  Traducción: ES
-  Original: /docs/en/git-workflow-guide.md
-  Última sincronización: 2026-01-26
--->
-# Guía de Flujo de Trabajo Git de SINAPSE
-> 🌐 [EN](../git-workflow-guide.md) | [PT](../pt/git-workflow-guide.md) | **ES**
----
-_Story: 2.2-git-workflow-implementation.yaml_
-## Tabla de Contenidos
-- [Descripción General](#descripción-general)
-- [Arquitectura de Defensa en Profundidad](#arquitectura-de-defensa-en-profundidad)
-- [Capa 1: Validación Pre-commit](#capa-1-validación-pre-commit)
-- [Capa 2: Validación Pre-push](#capa-2-validación-pre-push)
-- [Capa 3: Pipeline CI/CD](#capa-3-pipeline-cicd)
-- [Protección de Ramas](#protección-de-ramas)
-- [Flujo de Trabajo Diario](#flujo-de-trabajo-diario)
-- [Resolución de Problemas](#resolución-de-problemas)
-- [Consejos de Rendimiento](#consejos-de-rendimiento)
-## Descripción General
-SINAPSE implementa una estrategia de validación de **Defensa en Profundidad** con tres capas progresivas que detectan problemas tempranamente y aseguran la calidad del código antes del merge.
-### ¿Por Qué Tres Capas?
-1. **Retroalimentación rápida** - Detectar problemas inmediatamente durante el desarrollo
-2. **Validación local** - Sin dependencia de la nube para verificaciones básicas
-3. **Validación autoritativa** - Puerta final antes del merge
-4. **Consistencia de stories** - Asegurar que el desarrollo se alinee con las stories
-### Diagrama de Arquitectura
-```
-┌─────────────────────────────────────────────────────────────┐
-│                     Developer Workflow                       │
-└─────────────────────────────────────────────────────────────┘
-                              │
-                              ▼
-┌─────────────────────────────────────────────────────────────┐
-│ Layer 1: Pre-commit Hook (Local - <5s)                     │
-│ ✓ ESLint (code quality)                                     │
-│ ✓ TypeScript (type checking)                                │
-│ ✓ Cache enabled                                              │
-└─────────────────────────────────────────────────────────────┘
-                              │
-                              ▼
-┌─────────────────────────────────────────────────────────────┐
-│ Layer 2: Pre-push Hook (Local - <2s)                       │
-│ ✓ Story checkbox validation                                 │
-│ ✓ Status consistency                                         │
-│ ✓ Required sections                                          │
-└─────────────────────────────────────────────────────────────┘
-                              │
-                              ▼
-┌─────────────────────────────────────────────────────────────┐
-│ Layer 3: GitHub Actions CI (Cloud - 2-5min)                │
-│ ✓ All lint/type checks                                      │
-│ ✓ Full test suite                                           │
-│ ✓ Code coverage (≥80%)                                      │
-│ ✓ Story validation                                          │
-│ ✓ Branch protection                                         │
-└─────────────────────────────────────────────────────────────┘
-                              │
-                              ▼
-                      ┌──────────────┐
-                      │ Merge Ready  │
-                      └──────────────┘
-```
-## Arquitectura de Defensa en Profundidad
-### Capa 1: Pre-commit (Local - Rápido)
-**Objetivo de Rendimiento:** <5 segundos
-**Disparador:** `git commit`
-**Ubicación:** `.husky/pre-commit`
-**Qué valida:**
-- Calidad de código ESLint
-- Verificación de tipos TypeScript
-- Errores de sintaxis
-- Problemas de importación
-**Cómo funciona:**
-```bash
-# Se dispara automáticamente al hacer commit
-git add .
-git commit -m "feat: add feature"
-# Ejecuta:
-# 1. ESLint con caché (.eslintcache)
-# 2. Compilación incremental de TypeScript (.tsbuildinfo)
-```
-**Beneficios:**
-- ⚡ Retroalimentación rápida (<5s)
-- 💾 Con caché para velocidad
-- 🔒 Previene commits de código roto
-- 🚫 Sin sintaxis inválida en el historial
-### Capa 2: Pre-push (Local - Validación de Stories)
-**Objetivo de Rendimiento:** <2 segundos
-**Disparador:** `git push`
-**Ubicación:** `.husky/pre-push`
-**Qué valida:**
-- Completitud de checkboxes de story vs estado
-- Secciones requeridas de story presentes
-- Consistencia de estado
-- Registros del agente Dev
-**Cómo funciona:**
-```bash
-# Se dispara automáticamente al hacer push
-git push origin feature/my-feature
-# Valida todos los archivos de story en docs/stories/
-```
-**Reglas de Validación:**
-1. **Consistencia de Estado:**
-```yaml
-# ❌ Inválido: completado pero tareas incompletas
-status: "completed"
-tasks:
-  - "[x] Task 1"
-  - "[ ] Task 2"  # ¡Error!
-# ✅ Válido: todas las tareas completadas
-status: "completed"
-tasks:
-  - "[x] Task 1"
-  - "[x] Task 2"
-```
-2. **Secciones Requeridas:**
-- `id`
-- `title`
-- `description`
-- `acceptance_criteria`
-- `status`
-3. **Flujo de Estados:**
-```
-ready → in progress → Ready for Review → completed
-```
-### Capa 3: CI/CD (Nube - Autoritativo)
-**Rendimiento:** 2-5 minutos
-**Disparador:** Push a cualquier rama, creación de PR
-**Plataforma:** GitHub Actions
-**Ubicación:** `.github/workflows/ci.yml`
-**Jobs:**
-1. **ESLint** (job `lint`)
-   - Se ejecuta en entorno limpio
-   - Sin dependencia de caché
-2. **TypeScript** (job `typecheck`)
-   - Verificación completa de tipos
-   - Sin compilación incremental
-3. **Tests** (job `test`)
-   - Suite completa de tests
-   - Reporte de cobertura
-   - Umbral del 80% obligatorio
-4. **Validación de Stories** (job `story-validation`)
-   - Todas las stories validadas
-   - Consistencia de estado verificada
-5. **Resumen de Validación** (job `validation-summary`)
-   - Agrega todos los resultados
-   - Bloquea el merge si alguno falla
-**Monitoreo de Rendimiento:**
-- Job de rendimiento opcional
-- Mide tiempos de validación
-- Solo informativo
-## Capa 1: Validación Pre-commit
-### Referencia Rápida
-```bash
-# Validación manual
-npm run lint
-npm run typecheck
-# Auto-corrección de problemas de lint
-npm run lint -- --fix
-# Saltar hook (NO recomendado)
-git commit --no-verify
-```
-### Configuración de ESLint
-**Archivo:** `.eslintrc.json`
-```json
-{
-  "extends": ["eslint:recommended", "plugin:@typescript-eslint/recommended"],
-  "parser": "@typescript-eslint/parser",
-  "plugins": ["@typescript-eslint"],
-  "cache": true,
-  "cacheLocation": ".eslintcache"
-}
-```
-**Características clave:**
-- Soporte para TypeScript
-- Caché habilitado
-- Advierte sobre console.log
-- Ignora variables no usadas con prefijo `_`
-### Configuración de TypeScript
-**Archivo:** `tsconfig.json`
-```json
-{
-  "compilerOptions": {
-    "target": "ES2022",
-    "strict": true,
-    "incremental": true,
-    "tsBuildInfoFile": ".tsbuildinfo"
-  }
-}
-```
-**Características clave:**
-- Target ES2022
-- Modo estricto
-- Compilación incremental
-- Módulos CommonJS
-### Optimización de Rendimiento
-**Archivos de Caché:**
-- `.eslintcache` - Resultados de ESLint
-- `.tsbuildinfo` - Datos incrementales de TypeScript
-**Primera ejecución:** ~10-15s (sin caché)
-**Ejecuciones subsiguientes:** <5s (con caché)
-**Invalidación de caché:**
-- Cambios de configuración
-- Actualizaciones de dependencias
-- Eliminación de archivos
-## Capa 2: Validación Pre-push
-### Referencia Rápida
-```bash
-# Validación manual
-node .sinapse-ai/utils/sinapse-validator.js pre-push
-node .sinapse-ai/utils/sinapse-validator.js stories
-# Validar una sola story
-node .sinapse-ai/utils/sinapse-validator.js story docs/stories/1.1-story.yaml
-# Saltar hook (NO recomendado)
-git push --no-verify
-```
-### Validador de Stories
-**Ubicación:** `.sinapse-ai/utils/sinapse-validator.js`
-**Características:**
-- Salida de terminal coloreada
-- Indicadores de progreso
-- Mensajes de error claros
-- Advertencias para problemas potenciales
-**Ejemplo de Salida:**
-```
-══════════════════════════════════════════════════════════
-  Story Validation: 2.2-git-workflow-implementation.yaml
-══════════════════════════════════════════════════════════
-Story: 2.2 - Git Workflow with Multi-Layer Validation
-Status: in progress
-Progress: 12/15 tasks (80.0%)
-✓ Story validation passed with warnings
-Warning:
-  • Consider updating status to 'Ready for Review'
-```
-### Reglas de Validación
-#### 1. Formato de Checkbox
-Formatos soportados:
-- `[x]` - Completado (minúscula)
-- `[X]` - Completado (mayúscula)
-- `[ ]` - Incompleto
-No reconocidos:
-- `[o]`, `[*]`, `[-]` - No cuentan como completos
-#### 2. Consistencia de Estado
-| Estado             | Regla                               |
-| ------------------ | ----------------------------------- |
-| `ready`            | Ninguna tarea debería estar marcada |
-| `in progress`      | Algunas tareas marcadas             |
-| `Ready for Review` | Todas las tareas marcadas           |
-| `completed`        | Todas las tareas marcadas           |
-#### 3. Secciones Requeridas
-Todas las stories deben tener:
-```yaml
-id: "X.X"
-title: "Story Title"
-description: "Story description"
-status: "ready" | "in progress" | "Ready for Review" | "completed"
-acceptance_criteria:
-  - name: "Criterion"
-    tasks:
-      - "[ ] Task"
-```
-#### 4. Registro del Agente Dev
-Recomendado pero no requerido:
-```yaml
-dev_agent_record:
-  agent_model: 'claude-sonnet-4-5'
-  implementation_date: '2025-01-23'
-```
-Advertencia si falta.
-### Mensajes de Error
-**Secciones Requeridas Faltantes:**
-```
-✗ Missing required sections: description, acceptance_criteria
-```
-**Inconsistencia de Estado:**
-```
-✗ Story marked as completed but only 12/15 tasks are checked
-```
-**Archivo No Existente:**
-```
-✗ Story file not found: docs/stories/missing.yaml
-```
-## Capa 3: Pipeline CI/CD
-### Estructura del Workflow
-**Archivo:** `.github/workflows/ci.yml`
-**Jobs:**
-1. **lint** - Validación ESLint
-2. **typecheck** - Verificación TypeScript
-3. **test** - Tests Jest con cobertura
-4. **story-validation** - Consistencia de stories
-5. **validation-summary** - Agregar resultados
-6. **performance** (opcional) - Métricas de rendimiento
-### Detalles de Jobs
-#### Job ESLint
-```yaml
-- name: Run ESLint
-  run: npm run lint
-```
-- Se ejecuta en Ubuntu latest
-- Timeout: 5 minutos
-- Usa caché de npm
-- Falla con cualquier error de lint
-#### Job TypeScript
-```yaml
-- name: Run TypeScript type checking
-  run: npm run typecheck
-```
-- Se ejecuta en Ubuntu latest
-- Timeout: 5 minutos
-- Falla con errores de tipos
-#### Job Test
-```yaml
-- name: Run tests with coverage
-  run: npm run test:coverage
-```
-- Se ejecuta en Ubuntu latest
-- Timeout: 10 minutos
-- Cobertura subida a Codecov
-- Umbral de cobertura del 80% obligatorio
-#### Job Validación de Stories
-```yaml
-- name: Validate story checkboxes
-  run: node .sinapse-ai/utils/sinapse-validator.js stories
-```
-- Se ejecuta en Ubuntu latest
-- Timeout: 5 minutos
-- Valida todas las stories
-#### Job Resumen de Validación
-```yaml
-needs: [lint, typecheck, test, story-validation]
-if: always()
-```
-- Se ejecuta después de todas las validaciones
-- Verifica estados de todos los jobs
-- Falla si cualquier validación falló
-- Proporciona resumen
-### Disparadores de CI
-**Eventos de Push:**
-- Rama `master`
-- Rama `develop`
-- Ramas `feature/**`
-- Ramas `bugfix/**`
-**Eventos de Pull Request:**
-- Contra `master`
-- Contra `develop`
-### Ver Resultados de CI
-```bash
-# Ver checks del PR
-gh pr checks
-# Ver ejecuciones del workflow
-gh run list
-# Ver ejecución específica
-gh run view <run-id>
-# Re-ejecutar jobs fallidos
-gh run rerun <run-id>
-```
-## Protección de Ramas
-### Configuración
-```bash
-# Ejecutar script de configuración
-node scripts/setup-branch-protection.js
-# Ver protección actual
-node scripts/setup-branch-protection.js --status
-```
-### Requisitos
-- GitHub CLI (`gh`) instalado
-- Autenticado con GitHub
-- Acceso de administrador al repositorio
-### Reglas de Protección
-**Protección de Rama Master:**
-1. **Verificaciones de Estado Requeridas:**
-   - ESLint
-   - TypeScript Type Checking
-   - Jest Tests
-   - Story Checkbox Validation
-2. **Revisiones de Pull Request:**
-   - 1 aprobación requerida
-   - Descartar revisiones obsoletas en nuevos commits
-3. **Reglas Adicionales:**
-   - Historial lineal obligatorio (solo rebase)
-   - Force pushes bloqueados
-   - Eliminación de rama bloqueada
-   - Reglas aplican a administradores
-### Configuración Manual
-Via GitHub CLI:
-```bash
-# Establecer verificaciones de estado requeridas
-gh api repos/OWNER/REPO/branches/master/protection/required_status_checks \
-  -X PUT \
-  -f strict=true \
-  -f contexts[]="ESLint" \
-  -f contexts[]="TypeScript Type Checking"
-# Requerir revisiones de PR
-gh api repos/OWNER/REPO/branches/master/protection/required_pull_request_reviews \
-  -X PUT \
-  -f required_approving_review_count=1
-# Bloquear force pushes
-gh api repos/OWNER/REPO/branches/master/protection/allow_force_pushes \
-  -X DELETE
-```
-## Flujo de Trabajo Diario
-### Iniciando una Nueva Funcionalidad
-```bash
-# 1. Actualizar master
-git checkout master
-git pull origin master
-# 2. Crear rama de funcionalidad
-git checkout -b feature/my-feature
-# 3. Hacer cambios
-# ... editar archivos ...
-# 4. Commit (dispara pre-commit)
-git add .
-git commit -m "feat: add my feature [Story X.X]"
-# 5. Push (dispara pre-push)
-git push origin feature/my-feature
-# 6. Crear PR
-gh pr create --title "feat: Add my feature" --body "Description"
-```
-### Actualizando una Story
-```bash
-# 1. Abrir archivo de story
-code docs/stories/X.X-story.yaml
-# 2. Marcar tareas completadas
-# Cambiar: - "[ ] Task"
-# A:       - "[x] Task"
-# 3. Actualizar estado si es necesario
-# Cambiar: status: "in progress"
-# A:       status: "Ready for Review"
-# 4. Commit de actualizaciones de story
-git add docs/stories/X.X-story.yaml
-git commit -m "docs: update story X.X progress"
-# 5. Push (valida story)
-git push
-```
-### Corrigiendo Fallos de Validación
-**Errores de ESLint:**
-```bash
-# Auto-corregir problemas
-npm run lint -- --fix
-# Verificar problemas restantes
-npm run lint
-# Commit de correcciones
-git add .
-git commit -m "style: fix lint issues"
-```
-**Errores de TypeScript:**
-```bash
-# Ver todos los errores
-npm run typecheck
-# Corregir errores en código
-# ... editar archivos ...
-# Verificar corrección
-npm run typecheck
-# Commit de correcciones
-git add .
-git commit -m "fix: resolve type errors"
-```
-**Errores de Validación de Stories:**
-```bash
-# Verificar stories
-node .sinapse-ai/utils/sinapse-validator.js stories
-# Corregir archivo de story
-code docs/stories/X.X-story.yaml
-# Verificar corrección
-node .sinapse-ai/utils/sinapse-validator.js story docs/stories/X.X-story.yaml
-# Commit de corrección
-git add docs/stories/
-git commit -m "docs: fix story validation"
-```
-**Fallos de Tests:**
-```bash
-# Ejecutar tests
-npm test
-# Ejecutar test específico
-npm test -- path/to/test.js
-# Corregir tests fallidos
-# ... editar archivos de test ...
-# Ejecutar con cobertura
-npm run test:coverage
-# Commit de correcciones
-git add .
-git commit -m "test: fix failing tests"
-```
-### Haciendo Merge de un Pull Request
-```bash
-# 1. Asegurar que CI pasa
-gh pr checks
-# 2. Obtener aprobación
-# (Esperar revisión de miembro del equipo)
-# 3. Merge (squash)
-gh pr merge --squash --delete-branch
-# 4. Actualizar master local
-git checkout master
-git pull origin master
-```
-## Resolución de Problemas
-### Hook No Se Ejecuta
-**Síntomas:** Commit tiene éxito sin validación
-**Soluciones:**
-1. Verificar instalación de Husky:
-```bash
-npm run prepare
-```
-2. Verificar que existen archivos de hook:
-```bash
-ls -la .husky/pre-commit
-ls -la .husky/pre-push
-```
-3. Verificar permisos de archivos (Unix):
-```bash
-chmod +x .husky/pre-commit
-chmod +x .husky/pre-push
-```
-### Hook Pre-commit Lento
-**Síntomas:** Pre-commit toma >10 segundos
-**Soluciones:**
-1. Limpiar cachés:
-```bash
-rm .eslintcache .tsbuildinfo
-git commit  # Reconstruye caché
-```
-2. Verificar cambios de archivos:
-```bash
-git status
-# Commit de menos archivos a la vez
-```
-3. Actualizar dependencias:
-```bash
-npm update
-```
-### Validación de Story Falla
-**Síntoma:** Pre-push falla con errores de story
-**Problemas Comunes:**
-1. **Desajuste de checkbox:**
-```yaml
-# Error: Estado completado pero tareas incompletas
-status: 'completed'
-tasks:
-  - '[x] Task 1'
-  - '[ ] Task 2' # ← Corregir esto
-# Solución: Completar todas las tareas o cambiar estado
-```
-2. **Secciones faltantes:**
-```yaml
-# Error: Secciones requeridas faltantes
-id: '1.1'
-title: 'Story'
-# Faltan: description, acceptance_criteria, status
-# Solución: Agregar secciones faltantes
-```
-3. **YAML inválido:**
-```yaml
-# Error: Sintaxis YAML inválida
-tasks:
-  - "[ ] Task 1
-  - "[ ] Task 2"  # ← Falta comilla de cierre arriba
-# Solución: Corregir sintaxis YAML
-```
-### CI Falla pero Local Pasa
-**Síntomas:** CI falla pero todas las validaciones locales pasan
-**Causas Comunes:**
-1. **Diferencias de caché:**
-```bash
-# Limpiar cachés locales
-rm -rf node_modules .eslintcache .tsbuildinfo coverage/
-npm ci
-npm test
-```
-2. **Diferencias de entorno:**
-```bash
-# Usar misma versión de Node que CI (18)
-nvm use 18
-npm test
-```
-3. **Archivos sin commit:**
-```bash
-# Verificar cambios sin commit
-git status
-# Stash si es necesario
-git stash
-```
-### Protección de Rama Bloquea Merge
-**Síntomas:** No puede hacer merge del PR incluso con aprobaciones
-**Verificar:**
-1. **Checks requeridos pasan:**
-```bash
-gh pr checks
-# Todos deben mostrar ✓
-```
-2. **Aprobaciones requeridas:**
-```bash
-gh pr view
-# Verificar sección "Reviewers"
-```
-3. **Rama está actualizada:**
-```bash
-# Actualizar rama
-git checkout feature-branch
-git rebase master
-git push --force-with-lease
-```
-## Consejos de Rendimiento
-### Gestión de Caché
-**Mantener cachés:**
-- `.eslintcache` - Resultados de ESLint
-- `.tsbuildinfo` - Info de build de TypeScript
-- `coverage/` - Datos de cobertura de tests
-**Agregar a .gitignore:**
-```gitignore
-.eslintcache
-.tsbuildinfo
-coverage/
-```
-### Desarrollo Incremental
-**Mejores Prácticas:**
-1. **Commits pequeños:**
-   - Menos archivos = validación más rápida
-   - Más fácil de debuggear fallos
-2. **Probar durante el desarrollo:**
-```bash
-# Ejecutar validación manualmente antes del commit
-npm run lint
-npm run typecheck
-npm test
-```
-3. **Corregir problemas inmediatamente:**
-   - No dejar que los problemas se acumulen
-   - Más fácil de corregir en contexto
-### Optimización de CI
-**Optimizaciones del workflow:**
-1. **Jobs paralelos** - Todas las validaciones se ejecutan en paralelo
-2. **Timeouts de jobs** - Fallan rápido en cuelgues
-3. **Caché** - Dependencias npm cacheadas
-4. **Jobs condicionales** - Job de rendimiento solo en PRs
-### Rendimiento de Validación de Stories
-**Rendimiento Actual:**
-- Una sola story: <100ms
-- Todas las stories: <2s (típico)
-**Consejos de optimización:**
-1. **Mantener stories enfocadas** - Una funcionalidad por story
-2. **Limitar conteo de tareas** - Dividir stories grandes en más pequeñas
-3. **YAML válido** - Errores de parsing ralentizan validación
-## Temas Avanzados
-### Saltando Validaciones
-**Cuándo es apropiado:**
-- Hotfixes de emergencia
-- Cambios solo de documentación
-- Cambios de configuración de CI
-**Cómo saltar:**
-```bash
-# Saltar pre-commit
-git commit --no-verify
-# Saltar pre-push
-git push --no-verify
-# Saltar CI (no recomendado)
-# Agregar [skip ci] al mensaje de commit
-git commit -m "docs: update [skip ci]"
-```
-**Advertencia:** Solo saltar cuando sea absolutamente necesario. Las validaciones saltadas no detectarán problemas.
-### Validación Personalizada
-**Agregar validadores personalizados:**
-1. **Crear función validadora:**
-```javascript
-// .sinapse-ai/utils/custom-validator.js
-module.exports = async function validateCustom() {
-  // Tu lógica de validación
-  return { success: true, errors: [] };
-};
-```
-2. **Agregar al hook:**
-```bash
-# .husky/pre-commit
-node .sinapse-ai/utils/sinapse-validator.js pre-commit
-node .sinapse-ai/utils/custom-validator.js
-```
-3. **Agregar a CI:**
-```yaml
-# .github/workflows/ci.yml
-- name: Custom validation
-  run: node .sinapse-ai/utils/custom-validator.js
-```
-### Soporte para Monorepo
-**Para monorepos:**
-1. **Validaciones con alcance:**
-```javascript
-// Solo validar paquetes cambiados
-const changedFiles = execSync('git diff --name-only HEAD~1').toString();
-const packages = getAffectedPackages(changedFiles);
-```
-2. **Validación paralela de paquetes:**
-```yaml
-strategy:
-  matrix:
-    package: [package-a, package-b, package-c]
-```
-## Referencias
-- **SINAPSE Validator:** [.sinapse-ai/utils/sinapse-validator.js](../../.sinapse-ai/utils/sinapse-validator.js)
-- **CI Workflow:** [.github/workflows/ci.yml](../../.github/workflows/ci.yml)
----
-**¿Preguntas? ¿Problemas?**
-- [Abrir un Issue](https://github.com/SinapseAI/sinapse-ai/issues)
-- [Unirse a Discord](https://discord.gg/gk8jAdXWmj)