@christianmaf80/agentic-workflow 1.14.0-beta.1 → 1.14.0-beta.2

package/dist/artifacts/12-adaptacion-core-cli-surfaces/analysis.md

@@ -1,301 +0,0 @@
----
-artifact: analysis
-phase: phase-2-analysis
-owner: architect-agent
-status: draft
-related_task: 12-adaptacion-core-cli-surfaces
----
-
-# Analysis — 12-adaptacion-core-cli-surfaces
-
-## 1. Resumen ejecutivo
-
-### Problema
-La implementación actual de `@extensio/core` y `extensio-cli` no está completamente alineada con las constituciones de Pages (v2.1.0) y Shards (v2.0.0). El gap más crítico es que `Shard` hereda de `Core` en lugar de `Surface`, violando la jerarquía arquitectónica definida.
-
-### Objetivo
-Adaptar Core y CLI para cumplir con las constituciones de Surfaces, garantizando:
-- Jerarquía correcta: `Core` → `Surface` → `Page` / `Shard`
-- Lifecycle hooks uniformes en `Surface`
-- CLI capaz de generar Pages y Shards correctamente
-- Demo funcional validada con E2E en 3 navegadores
-
-### Criterio de éxito
-Todos los acceptance criteria del task.md deben cumplirse:
-- [x] Informe de gaps documentado (completado en Phase 1)
-- [ ] Clase `Surface` con hooks uniformes
-- [ ] Clase `Page` conforme a constitución
-- [ ] Clase `Shard` heredando de `Surface`
-- [x] CLI puede generar Pages/Shards al crear módulo (`--withPage --withShard`)
-- [ ] CLI con comandos independientes `create page` / `create shard` (para añadir a módulo existente)
-- [ ] Demo reconstruida con CLI
-- [ ] Tests pasando en Chrome, Firefox, Safari
-
----
-
-## 2. Estado del proyecto (As-Is)
-
-### Estructura relevante
-
-```
-packages/core/
-├── src/
-│   ├── engine/
-│   │   └── core.mts           # Clase base Core (390 líneas)
-│   └── surface/
-│       ├── surface.mts        # Surface actual (57 líneas)
-│       ├── pages/
-│       │   └── index.mts      # Page actual (9 líneas)
-│       └── shards/
-│           ├── index.mts      # Shard actual (249 líneas)
-│           ├── lit.mts        # Adaptador Lit
-│           ├── react.mts      # Adaptador React
-│           └── angular.mts    # Adaptador Angular
-├── demo/
-│   └── src/
-│       └── manifest.json      # ⚠️ INCOMPLETA
-└── test/
-    └── ...                    # Tests existentes
-
-packages/cli/
-├── src/
-│   ├── generators/
-│   │   ├── driver/            # ✅ Funcional
-│   │   ├── module/            # ✅ Funcional (con withPage, withShard)
-│   │   └── project/           # ✅ Funcional
-│   └── commands/
-│       ├── plugins/
-│       │   └── surface-pages/ # ✅ Plugin funcional
-│       └── process-shards.mts # ✅ Funcional
-```
-
-### Estado actual de clases
-
-| Clase | Hereda de | Líneas | Conformidad |
-|-------|-----------|--------|-------------|
-| `Core` | — | 390 | ✅ Base correcta |
-| `Surface` | `Core` | 57 | ⚠️ Ciclo de vida incompleto |
-| `Page` | `Surface` | 9 | ⚠️ Implementación mínima |
-| `Shard` | `Core` | 249 | ❌ **DEBE heredar de Surface** |
-
-### Estado actual del CLI (VALIDADO)
-
-El generador de módulos **SÍ tiene soporte** para Pages y Shards:
-
-| Opción | Descripción | Estado |
-|--------|-------------|--------|
-| `--withPage` | Genera estructura de pages | ✅ Funcional |
-| `--withShard` | Genera estructura de shards | ✅ Funcional |
-| `--withSurface` | Legacy (activa ambos) | ✅ Funcional |
-
-**Templates existentes:**
-
-Pages (`templates/surface/pages/`):
-- `index.mts.ejs` - Usa Lit + decorador `@customElement`
-- `home.mts.ejs` - Página de ejemplo
-- `about.mts.ejs` - Página de ejemplo
-- `styles.css.ejs` - Estilos
-
-Shards (`templates/surface/shards/`):
-- `index.mts.ejs` - Registra shards con `Shard.register()`
-- `example.mts.ejs` - Shard de ejemplo con `_mount`, `render`, `update`, `_unmount`, `getTagName`
-- `styles.css.ejs` - Estilos
-
-**Generador module/index.mts** (líneas relevantes):
-- L322-356: Genera pages si `withPage=true`
-- L359-391: Genera shards si `withShard=true`
-- L190-195: Añade exports en package.json
-
-### Limitaciones detectadas (ACTUALIZADO)
-
-1. **Shard hereda de Core**: Viola arquitectura. Debe heredar de Surface.
-2. **Surface ciclo de vida**: `onMount()` llama a `run()`, pero según constitución debe ejecutarse DESPUÉS de `render()`.
-3. **Page mínima**: Solo hereda, no implementa nada específico.
-4. **CLI sin comandos independientes**: No existe `extensio create page` ni `extensio create shard` para añadir a módulos existentes. Solo se puede al crear módulo nuevo.
-5. **Demo incompleta**: Solo tiene `manifest.json`.
-6. **Templates de Page**: Usan Lit/decoradores pero Page en core no implementa render() compatible.
-
----
-
-## 3. Cobertura de Acceptance Criteria
-
-### AC-1: Surface con hooks uniformes
-- **Interpretación**: La clase `Surface` debe definir `onMount()` y `onUnmount()` como hooks que heredan Page y Shard. El ciclo de vida debe seguir la secuencia: `run()` → `_setup()` → `listen()` → `loadProps()` → `start()` → `render()` → `onMount()`.
-- **Verificación**: 
-  - Unit test que valide la secuencia de hooks
-  - Ambas subclases (Page, Shard) deben tener los hooks disponibles
-- **Riesgos**: Cambiar el momento de ejecución de `onMount()` podría romper código existente.
-
-### AC-2: Page hereda de Surface
-- **Interpretación**: Ya cumple, pero necesita más funcionalidad (método `render()`, gestión de ciclo completo).
-- **Verificación**: 
-  - Unit test de herencia
-  - E2E: navegar a una Page y verificar ciclo
-- **Riesgos**: Bajo. Page ya hereda de Surface.
-
-### AC-3: Shard hereda de Surface
-- **Interpretación**: **Cambio crítico**. Shard debe refactorizarse para heredar de Surface, moviendo lógica común a Surface.
-- **Verificación**: 
-  - Unit test de herencia
-  - E2E: cargar Shard en página web y verificar ciclo
-- **Riesgos**: 
-  - **Breaking change**: Adaptar importaciones de Shard
-  - Mover lógica de Storage/listener a Surface
-
-### AC-4: CLI genera Pages
-- **Interpretación**: Crear generador `page` independiente que produzca estructura conforme a constitución.
-- **Verificación**: 
-  - Ejecutar `extensio create page` y validar estructura generada
-  - Build de la Page sin errores
-- **Riesgos**: Templates deben seguir constitución exactamente.
-
-### AC-5: CLI genera Shards
-- **Interpretación**: Crear generador `shard` independiente que produzca estructura conforme a constitución.
-- **Verificación**: 
-  - Ejecutar `extensio create shard` y validar estructura generada
-  - Build del Shard sin errores
-- **Riesgos**: Registro como WebComponent debe funcionar.
-
-### AC-6: Demo reconstruida
-- **Interpretación**: Eliminar demo actual, crear nueva con CLI usando `extensio create module --withPages --withShards`, o crear module manualmente con Page y Shard de ejemplo.
-- **Verificación**: 
-  - Demo compila sin errores
-  - Funciona en Chrome, Firefox, Safari
-- **Riesgos**: Dependencia de cambios previos en Core y CLI.
-
-### AC-7: Tests pasan
-- **Interpretación**: Unit tests en Vitest, E2E en Playwright para los 3 navegadores.
-- **Verificación**: 
-  - `npm run test` pasa
-  - `npm run test:e2e -- --project=chromium,firefox,webkit` pasa
-- **Riesgos**: Safari (webkit) puede tener diferencias de comportamiento.
-
----
-
-## 4. Research técnico
-
-### Alternativa A: Migración incremental
-- **Descripción**: Refactorizar paso a paso, empezando por Surface, luego Page, luego Shard.
-- **Ventajas**: Menor riesgo de regresiones, permite testing gradual.
-- **Inconvenientes**: Puede dejar inconsistencias temporales.
-
-### Alternativa B: Migración completa (Big Bang)
-- **Descripción**: Refactorizar todo el stack (Surface, Page, Shard) de una vez.
-- **Ventajas**: Consistencia inmediata, no hay estados intermedios.
-- **Inconvenientes**: Mayor riesgo, más difícil de depurar si falla.
-
-### Decisión recomendada
-**Alternativa A: Migración incremental** 
-
-Orden propuesto:
-1. Refactorizar `Surface` (ciclo de vida correcto)
-2. Refactorizar `Shard` para heredar de `Surface`
-3. Verificar `Page` (ya hereda correctamente)
-4. Actualizar templates CLI si es necesario
-5. Reconstruir demo con `extensio create module --withPage --withShard`
-6. Tests E2E
-
----
-
-## 5. Agentes participantes
-
-### architect-agent
-- **Responsabilidades**: 
-  - Validar conformidad arquitectónica
-  - Aprobar cambios en Core
-  - Supervisar gates de cada fase
-- **Subáreas**: Core, CLI, constituciones
-
-### surface-agent (delegado)
-- **Responsabilidades**:
-  - Implementar cambios en Surface, Page, Shard
-  - Verificar lifecycle hooks
-- **Subáreas**: `packages/core/src/surface/`
-
-### qa-agent
-- **Responsabilidades**:
-  - Diseñar tests unitarios
-  - Diseñar tests E2E
-  - Validar cobertura en 3 navegadores
-- **Subáreas**: `packages/core/test/`, Playwright
-
-### Handoffs
-1. architect-agent → surface-agent: Plan de implementación aprobado
-2. surface-agent → qa-agent: Código implementado para testing
-3. qa-agent → architect-agent: Resultados de verificación
-
-### Componentes a modificar
-
-| Tipo | Acción | Componente |
-|------|--------|------------|
-| Core | MODIFICAR | `src/surface/surface.mts` |
-| Core | MODIFICAR | `src/surface/shards/index.mts` |
-| Core | VERIFICAR | `src/surface/pages/index.mts` |
-| Core | MODIFICAR | `package.json` (exports) |
-| CLI | CREAR | `src/generators/page/` (comando independiente) |
-| CLI | CREAR | `src/generators/shard/` (comando independiente) |
-| CLI | VERIFICAR | Templates existentes en `generators/module/` |
-| Demo | RECREAR | `packages/core/demo/` |
-
-### Demo (obligatoria)
-- **Necesidad**: Validar que Pages y Shards funcionan correctamente según constitución.
-- **Justificación**: Los acceptance criteria exigen demo con E2E en 3 navegadores.
-- **Impacto**: Eliminar demo actual, crear nueva con:
-  - Engine básico
-  - Al menos 1 Page
-  - Al menos 1 Shard
-  - Manifest configurado para popup y content scripts
-
----
-
-## 6. Impacto de la tarea
-
-### Arquitectura
-- **Alto impacto**: Cambio de herencia de Shard (Core → Surface)
-- **Medio impacto**: Refactorización de ciclo de vida de Surface
-
-### APIs / contratos
-- `Shard` cambiará de base class (potencial breaking change)
-- Nuevos exports en `package.json` de Core
-
-### Compatibilidad
-| Riesgo | Mitigación |
-|--------|------------|
-| Módulos existentes con Shard | Verificar demos de módulos existentes |
-| Imports de `@extensio/core/shard` | Mantener compatibilidad de exports |
-
-### Testing / verificación
-- **Unit tests**: Vitest para Core (lifecycle, herencia)
-- **Integration tests**: Carga de Shards desde Engine
-- **E2E tests**: Playwright en Chrome, Firefox, Safari
-
----
-
-## 7. Riesgos y mitigaciones
-
-| # | Riesgo | Severidad | Mitigación |
-|---|--------|-----------|------------|
-| 1 | Breaking change en Shard | 🔴 Alta | Mantener API pública, solo cambiar herencia interna |
-| 2 | Ciclo de vida de Surface rompe código existente | 🟡 Media | Tests exhaustivos antes y después |
-| 3 | Safari comportamiento diferente | 🟡 Media | Tests E2E específicos para webkit |
-| 4 | CLI templates desactualizados | 🟢 Baja | Crear templates nuevos siguiendo constitución |
-
----
-
-## 8. Preguntas abiertas
-
-No hay preguntas abiertas. Los acceptance criteria están claramente definidos desde Phase 0.
-
----
-
-## 9. Aprobación del desarrollador (OBLIGATORIA)
-
-```yaml
-approval:
-  developer:
-    decision: SI
-    date: 2026-01-14T08:03:49+01:00
-    comments: Aprobado con cambio arquitectónico (Page como controller sin render)
-```
-
-> Sin aprobación, esta fase **NO puede darse por completada** ni avanzar a Phase 3.

package/dist/artifacts/12-adaptacion-core-cli-surfaces/error-analysis.md

@@ -1,93 +0,0 @@
-# Error Analysis - Task 12
-
-## Error Encontrado Durante la Tarea
-
-### **Error**: Visibilidad incorrecta en override de `onUnmount()`
-
-**Descripción**:
-```
-Class 'Page' incorrectly extends base class 'Surface'.
-Property 'onUnmount' is protected in type 'Page' but public in type 'Surface'.
-```
-
-**Ubicación**: `packages/core/src/surface/pages/index.mts:127`
-
-**Causa Raíz**:
-El método `onUnmount()` en la clase base `Surface` es `public`:
-```typescript
-// Surface
-onUnmount(): void { }  // public por defecto
-```
-
-Pero el override en `Page` estaba marcado como `protected`:
-```typescript
-// Page (INCORRECTO)
-protected override onUnmount(): void { ... }
-```
-
-**Regla de TypeScript**:
-Cuando se hace override de un método, la visibilidad **no puede ser más restrictiva** que en la clase base.
-- Base: `public` → Override: debe ser `public` (o menos restrictivo, pero no aplica aquí)
-- Base: `protected` → Override: puede ser `protected` o `public`
-- Base: `private` → No se puede hacer override
-
-**Fix Aplicado**:
-```typescript
-// Page (CORREGIDO)
-public override onUnmount(): void {
-    // Unmount all Shards
-    for (const shard of this._shards.values()) {
-        try {
-            shard.unmount();
-        } catch (err) {
-            this.error(`Failed to unmount Shard ${shard.id}:`, err);
-        }
-    }
-    this._shards.clear();
-    this.log('All Shards unmounted');
-
-    super.onUnmount();
-}
-```
-
-**Archivo Modificado**: `packages/core/src/surface/pages/index.mts` (línea 125)
-
-**Commit**: Cambio de `protected` → `public` en `onUnmount()`
-
----
-
-## Lecciones Aprendidas
-
-### 1. **Consistencia de Visibilidad en Herencia**
-Al hacer override de métodos, siempre verificar la visibilidad en la clase base.
-
-### 2. **Compilación Incremental**
-Compilar con `tsc --noEmit` después de cada cambio crítico para detectar errores temprano.
-
-### 3. **Revisión de Constituciones**
-La constitución de Shards define `onUnmount()` sin especificar visibilidad, lo que implica `public` por defecto en TypeScript.
-
-### 4. **Pattern de Lifecycle Hooks**
-Los hooks de ciclo de vida (`onMount`, `onUnmount`) deben ser consistentes en visibilidad a través de toda la jerarquía:
-- `Surface.onMount()` → `public`
-- `Surface.onUnmount()` → `public`
-- `Page.onMount()` → `public` (heredado)
-- `Page.onUnmount()` → `public` (override correcto ahora)
-- `Shard.onMount()` → `public` (heredado via Surface)
-- `Shard.onUnmount()` → `public` (heredado via Surface)
-
----
-
-## Estado Actual
-
-✅ **Error Corregido**
-✅ **Compilación sin errores de lógica**
-⚠️ **Pendiente**: Tests para validar comportamiento
-
----
-
-## Próximos Pasos
-
-1. Ejecutar tests unitarios (Paso 8)
-2. Ejecutar tests E2E (Paso 9)
-3. Validar demo compilada

package/dist/artifacts/12-adaptacion-core-cli-surfaces/implementation-summary.md

@@ -1,111 +0,0 @@
-# Implementation Summary - Task 12
-
-## Changes Completed
-
-### ✅ Phase 4: Implementation (Steps 1-7)
-
-#### **Step 1: Refactor Surface** ✅
-- **File**: `packages/core/src/surface/surface.mts`
-- **Change**: Fixed `onMount()` lifecycle - removed `this.run()` call
-- **Impact**: `onMount()` is now a proper lifecycle hook, not the lifecycle initiator
-
-#### **Step 2: Migrate Shard to inherit from Surface** ✅
-- **File**: `packages/core/src/surface/shards/index.mts`
-- **Change**: `extends Core` → `extends Surface`
-- **Impact**: Shard now correctly inherits from Surface, following architecture hierarchy
-
-#### **Step 3: Implement Page as Controller** ✅
-- **Files**: 
-  - `packages/core/src/surface/pages/index.mts`
-  - `packages/core/src/surface/pages/types.d.mts` (new)
-- **Changes**:
-  - Added `loadShard()` method for loading Shards into Page's DOM
-  - Added `unloadShard()` for cleanup
-  - Added `getShards()` and `getShard()` for querying
-  - Page does NOT render - only orchestrates Shards
-  - Automatic cleanup in `onUnmount()`
-- **Impact**: Page is now a controller, not a renderer
-
-#### **Step 4: Update exports** ✅
-- **File**: `packages/core/package.json`
-- **Changes**:
-  - Added `./surface` export
-  - Added `./page` export
-  - Added `./page/types` export
-- **Impact**: Surface and Page types are now publicly accessible
-
-#### **Step 5-6: Create CLI Generators** ✅
-- **Files**:
-  - `packages/cli/src/generators/page/index.mts` (new)
-  - `packages/cli/src/generators/shard/index.mts` (new)
-  - `tools/mcp-server/src/tools/extensio-create.ts` (updated)
-- **Changes**:
-  - New `page` generator for adding Pages to modules
-  - New `shard` generator for adding Shards to modules
-  - MCP tool updated to support `type: 'page'` and `type: 'shard'`
-- **Impact**: Can now run `extensio create page` and `extensio create shard`
-
-#### **Step 7: Rebuild Demo** ✅
-- **Created**:
-  - `demo/src/manifest.json`
-  - `demo/src/engine/index.mts` - Simple Engine
-  - `demo/src/surface/pages/main/` - MainPage controller
-  - `demo/src/surface/shards/header.mts` - HeaderShard
-  - `demo/src/surface/shards/content.mts` - ContentShard
-  - `demo/src/surface/shards/index.mts` - Registration
-- **Demonstrates**:
-  - Page as controller loading Shards
-  - Shards rendering visual content
-  - No render in Page
-
----
-
-## Architecture Changes Summary
-
-| Component | Before | After |
-|-----------|--------|-------|
-| **Surface.onMount()** | Called `this.run()` | Empty hook for subclasses |
-| **Shard** | `extends Core` | `extends Surface` ✅ |
-| **Page** | Minimal (9 lines) | Controller with `loadShard()` |
-| **CLI** | Module only | + `page` + `shard` generators |
-| **Demo** | Incomplete | Full Page/Shards demo |
-
----
-
-## Next Steps (Not Yet Completed)
-
-### **Step 8: Unit Tests** ⏳
-- Test Surface lifecycle
-- Test Shard inheritance
-- Test Page.loadShard()
-
-### **Step 9: E2E Tests** ⏳
-- Demo in Chrome
-- Demo in Firefox
-- Demo in Safari
-
----
-
-## Known Issues to Analyze
-
-As requested by developer, need to analyze:
-- **Error inesperado durante la tarea** - Need to review terminal output and identify what went wrong
-
----
-
-## Files Modified
-
-### Core
-- `packages/core/src/surface/surface.mts`
-- `packages/core/src/surface/shards/index.mts`
-- `packages/core/src/surface/pages/index.mts`
-- `packages/core/src/surface/pages/types.d.mts` (new)
-- `packages/core/package.json`
-
-### CLI
-- `packages/cli/src/generators/page/index.mts` (new)
-- `packages/cli/src/generators/shard/index.mts` (new)
-- `tools/mcp-server/src/tools/extensio-create.ts`
-
-### Demo
-- `packages/core/demo/src/**` (recreated)