@christianmaf80/agentic-workflow 1.8.0-beta.1 → 1.11.0-beta.1

package/dist/artifacts/10-shard-build-plugin/analysis.md

@@ -0,0 +1,290 @@
+---
+artifact: analysis
+phase: phase-2-analysis
+owner: architect-agent
+status: approved
+related_task: 10-shard-build-plugin
+---
+
+# Analysis — 10-shard-build-plugin
+
+## 1. Resumen ejecutivo
+**Problema**
+- Los shards actualmente no se detectan ni compilan automáticamente durante el build. Requieren declaración manual en `package.json:exports` y el desarrollador debe calcular URLs manualmente con `Runtime.getURL()`.
+
+**Objetivo**
+- Automatizar la detección y compilación de shards referenciados mediante `loadShard(ShardClass)` en engines, manteniendo las rutas relativas dentro del módulo y soportando dependencias de npm.
+
+**Criterio de éxito**
+- Plugin `surface-shards` detecta `loadShard(X)` y compila entry points automáticamente
+- Engine puede usar `loadShard(ShardClass)` sin calcular URLs manualmente
+- Demo existente actualizado y funcional
+- Tests unitarios pasan
+
+---
+
+## 2. Estado del proyecto (As-Is)
+
+**Estructura relevante**
+- `packages/cli/src/commands/plugins/` - Plugins de build existentes
+  - `surface-pages/` - Plugin que detecta scripts en HTML
+  - `replacers/` - Plugins de resolución de paths
+- `packages/core/src/engine/engine.mts` - Clase Engine con método `loadShard()`
+- `packages/core/src/surface/shards/` - Clase base Shard y adaptadores (React, Lit, Angular)
+- `packages/core/demo/` - Demo actual con ActionButtonShard
+
+**Drivers existentes**
+- `@extensio/driver-scripting` - Usado por `loadShard()` para inyectar CSS/JS
+- `@extensio/driver-runtime` - Provee `Runtime.getURL()`
+
+**Core / Engine / Surfaces**
+- **Engine:** Método `loadShard(cssUrl, jsUrl, options)` recibe URLs como strings
+- **Shard:** Clase base abstracta sin propiedad `static url`
+- **ReactShard:** Adaptador que extiende Shard, usado en demo
+
+**Limitaciones detectadas**
+- No existe plugin específico para shards
+- Los shards solo se compilan si están en `package.json:exports`
+- API de `loadShard` requiere URLs manuales (verbose, propenso a errores)
+
+---
+
+## 3. Cobertura de Acceptance Criteria
+
+### AC-1: Alcance
+**Texto:** Crear plugin `surface-shards` para Vite/Rollup, modificar API de `loadShard` en clase `Engine`, añadir propiedad estática `url` en clase base `Shard`
+
+**Interpretación:**
+- Crear nuevo plugin siguiendo patrón de `surface-pages`
+- Refactorizar `Engine.loadShard()` para aceptar clase en vez de URLs
+- Extender clase `Shard` con propiedad estática
+
+**Verificación:**
+- Existe archivo `packages/cli/src/commands/plugins/surface-shards/index.mts`
+- `Engine.loadShard()` acepta `ShardClass` como primer parámetro
+- Clase `Shard` tiene declaración `static url: string`
+
+**Riesgos / ambigüedades:**
+- Ninguna detectada - requisitos claros
+
+---
+
+### AC-2: Entradas / Datos
+**Texto:** Código fuente de engines (*.mts), imports de clases Shard, propiedad estática `url` de cada Shard
+
+**Interpretación:**
+- Plugin debe analizar archivos en `**/engine/**/*.mts`
+- Buscar patrones: `import { X } from './shards/...'` + `loadShard(X)`
+- Leer `static url` de cada clase Shard
+
+**Verificación:**
+- Plugin detecta imports de shards
+- Plugin resuelve propiedad `static url` en tiempo de build
+
+**Riesgos / ambigüedades:**
+- Análisis estático con regex puede fallar en casos edge (imports dinámicos, destructuring complejo)
+- Mitigación: Documentar patrones soportados
+
+---
+
+### AC-3: Salidas / Resultado esperado
+**Texto:** Shards compilados en `dist/surface/shards/[ShardName].mjs`, para npm reutilizar plugin existente de node_modules, API: `loadShard(ShardClass, options?)`
+
+**Interpretación:**
+- Shards mantienen ruta relativa: `src/surface/shards/X.mts` → `dist/surface/shards/X.mjs`
+- Dependencias npm usan carpeta `node-modules/` (ya implementado)
+- Nueva firma de API
+
+**Verificación:**
+- Build genera shards en rutas esperadas
+- `loadShard(ShardClass)` funciona en runtime
+- Shards de npm se resuelven correctamente
+
+**Riesgos / ambigüedades:**
+- Ninguna - usa infraestructura existente
+
+---
+
+### AC-4: Restricciones
+**Texto:** No incluir CSS por convención, mantener compatibilidad con arquitectura Extensio, no romper demos/tests existentes
+
+**Interpretación:**
+- No generar CSS automáticamente - el shard importa su propio CSS
+- Seguir principios de `extensio-architecture.md`
+- Mantener backward compatibility o migrar demo
+
+**Verificación:**
+- Plugin no procesa CSS por convención
+- Tests existentes pasan o se actualizan
+- Demo funcional tras cambios
+
+**Riesgos / ambigüedades:**
+- Demo actual usa API antigua - requiere actualización
+
+---
+
+### AC-5: Criterio de aceptación (Done)
+**Texto:** Plugin `surface-shards` detecta `loadShard(X)` y compila entry points, `Engine.loadShard(ShardClass)` funciona, demo actualizada y funcional, tests unitarios pasan
+
+**Interpretación:**
+- Todas las piezas anteriores funcionando en conjunto
+
+**Verificación:**
+- Build exitoso con shards detectados
+- Demo E2E pasa
+- Unit tests pasan
+
+**Riesgos / ambigüedades:**
+- Ninguna
+
+---
+
+## 4. Research técnico
+
+### Alternativa A: Plugin de análisis estático con regex (RECOMENDADA)
+**Descripción:** Plugin de Rollup/Vite que analiza código de engines con regex buscando `import {X} from './shards/...'` + `loadShard(X)`
+
+**Patrón de implementación:**
+- Exportar función que retorna objeto con hooks de Rollup
+- Hook `transform`: analizar archivos `**/engine/**/*.mts`
+- Detectar imports + llamadas a `loadShard()`
+- Compilar entry points detectados
+
+**Ventajas:**
+- Automatización completa
+- Sin configuración adicional
+- Sigue patrón establecido de `surface-pages` plugin
+- Compatible con pipeline de build existente
+
+**Inconvenientes:**
+- Regex limitada para casos edge
+- Requiere documentar patrones soportados
+
+**Decisión recomendada:** Implementar Alternativa A
+- Es la propuesta aprobada en research
+- Patrones de código son predecibles
+- Se puede mejorar con AST en futuras iteraciones
+
+---
+
+## 5. Agentes participantes
+
+### architect-agent
+**Responsabilidades:**
+- Validar coherencia arquitectónica global
+- Revisar cambios en Core (Engine, Shard)
+- Aprobar plan de implementación
+
+**Subáreas asignadas:**
+- Revisión de arquitectura
+
+---
+
+### researcher-agent
+**Responsabilidades:**
+- Completado en Phase 1 ✅
+
+---
+
+### driver-agent (NO requerido)
+- No se crean ni modifican drivers
+
+---
+
+### module-agent (NO requerido)
+- No se crean módulos
+
+---
+
+### qa-agent
+**Responsabilidades:**
+- Diseñar tests unitarios para plugin `surface-shards`
+- Actualizar tests E2E del demo
+- Validar que no hay regresiones
+
+**Subáreas asignadas:**
+- Testing
+
+---
+
+**Handoffs:**
+1. Research (researcher) → Analysis (architect) ✅
+2. Analysis → Plan (architect)
+3. Plan → Implementation (architect + qa)
+4. Implementation → Verification (qa)
+
+---
+
+**Componentes necesarios:**
+
+| Componente | Acción | Impacto |
+|------------|--------|---------|
+| `surface-shards` plugin | CREAR | Nuevo plugin en `packages/cli/src/commands/plugins/surface-shards/` |
+| `Engine.loadShard()` | MODIFICAR | Breaking change en API (mantener backward compat deprecada) |
+| `Shard` clase base | MODIFICAR | Añadir `static url: string` |
+| Demo `ActionButtonShard` | MODIFICAR | Actualizar a nueva API |
+| Tests E2E demo | MODIFICAR | Actualizar aserciones |
+
+**Demo (si aplica):**
+- Se requiere **actualizar** demo existente (`packages/core/demo`)
+- Justificación: Validar nueva API y plugin en funcionamiento real
+- Alineación con arquitectura: El demo ya existe y seguirá el mismo patrón Engine → loadShard → Context
+
+---
+
+## 6. Impacto de la tarea
+
+**Arquitectura:**
+- Nuevo plugin en la pipeline de build
+- Cambio en API pública de `Engine.loadShard()`
+- Extensión de clase base `Shard`
+
+**APIs / contratos:**
+- **Breaking change:** `loadShard(cssUrl, jsUrl, options)` → `loadShard(ShardClass, options)`
+- **Mitigación:** Mantener firma anterior como deprecada durante 1 release
+
+**Compatibilidad:**
+- Código existente usando `loadShard()` con URLs directas dejará de funcionar
+- Demo debe actualizarse
+- Documentación debe actualizarse
+
+**Testing / verificación:**
+- **Unit tests:** Plugin `surface-shards` (detección de patrones)
+- **Integration tests:** Build completo con shards
+- **E2E tests:** Demo navegador (Chrome)
+
+---
+
+## 7. Riesgos y mitigaciones
+
+**Riesgo 1: Regex no detecta patrones complejos**
+- **Impacto:** Shards no compilados si usan imports no estándar
+- **Mitigación:** Documentar patrones soportados, validar en tests
+
+**Riesgo 2: Breaking change en loadShard**
+- **Impacto:** Demo y código existente rompe
+- **Mitigación:** Mantener API anterior deprecada, actualizar demo
+
+**Riesgo 3: Shards de npm no se resuelven**
+- **Impacto:** Módulos externos no funcionales
+- **Mitigación:** Reutilizar lógica de `generateVendorModules()`
+
+---
+
+## 8. Preguntas abiertas
+(Ninguna - todas resueltas en Phase 0 y Phase 1)
+
+---
+
+## 9. Aprobación
+Este análisis **requiere aprobación explícita del desarrollador**.
+
+```yaml
+approval:
+  developer:
+    decision: SI
+    date: 2026-01-12T07:56:17+01:00
+    comments: Aprobado. El plugin de shards debe seguir el patrón de los otros plugins de Rollup
+```
+
+> Sin aprobación, esta fase **NO puede darse por completada** ni avanzar a Fase 3.

package/dist/artifacts/10-shard-build-plugin/architect/subtask-implementation.md

@@ -0,0 +1,105 @@
+# Subtask Implementation Report — architect-agent
+
+## Subtask: Plugin surface-shards + Engine.loadShard() refactor + Demo update
+
+### Cambios realizados
+
+#### 1. Plugin `surface-shards` creado
+**Archivo:** `packages/cli/src/commands/plugins/surface-shards/index.mts`
+
+**Funcionalidad:**
+- Hook `resolveId`: Marca imports de shards como `external` para evitar bundlearlos con el engine
+- Hook `transform`: 
+  - Detecta pattern `import { ClassName } from './path/to/shard'` + `loadShard(ClassName)`
+  - Compila cada shard detectado como entry point independiente
+  - Inyecta mapping `ClassName.__EXTENSIO_COMPILED_PATH__ = 'surface/shards/ClassName.mjs'` al final del código del engine
+- Función `compileShardScript()`: Usa `vite.build()` con todos los replacers necesarios
+
+**Decisiones técnicas:**
+- Usamos regex simple para detección (suficiente para patrones estándar)
+- Shards se compilan con misma configuración que `surface-pages` (esbuild, replacers, etc.)
+- Path del shard se normaliza a forward slashes para compatibilidad cross-platform
+
+---
+
+#### 2. Plugin integrado en build pipeline
+**Archivo:** `packages/cli/src/commands/build.mts`
+
+**Cambios:**
+- Línea 19: Import de `surfaceShardsPlugin`
+- Líneas 344-348: Añadido plugin a la lista de plugins de Vite
+
+---
+
+#### 3. Engine.loadShard() refactorizado
+**Archivo:** `packages/core/src/engine/engine.mts`
+
+**Nueva API:**
+```typescript
+public async loadShard<T extends typeof Shard>(
+  ShardClass: T,
+  options?: ShardOptions
+): Promise<void>;
+```
+
+**Backward compatibility:**
+```typescript
+/** @deprecated */
+public async loadShard(
+  cssUrl: string,
+  jsUrl: string,
+  options?: ShardOptions
+): Promise<void>;
+```
+
+**Lógica:**
+- Detecta firma mediante `typeof ShardClassOrCssUrl`
+- Nueva firma: Lee `ShardClass.__EXTENSIO_COMPILED_PATH__` y usa `Runtime.getURL()`
+- Legacy firma: Usa URLs directamente (deprecada)
+- CSS es opcional en nueva API (shard importa su propio CSS)
+
+**Decisiones técnicas:**
+- Usamos function overloading para mantener backward compatibility
+- Error claro si `__EXTENSIO_COMPILED_PATH__` no existe (indica que plugin no detectó el shard)
+
+---
+
+#### 4. Demo actualizado
+**Archivo:** `packages/core/demo/src/engine/index.mts`
+
+**Cambios:**
+- Línea 16: Import de `ActionButtonShard`
+- Línea 97: Cambio de `loadShard(cssUrl, jsUrl, options)` a `loadShard(ActionButtonShard, options)`
+
+**Nota:** NO se modificó `ActionButtonShard.mts` - el plugin inyecta `__EXTENSIO_COMPILED_PATH__` automáticamente
+
+---
+
+### Tests ejecutados
+
+**Pendiente:** Build manual del demo para verificar que:
+1. Plugin detecta el shard
+2. Shard se compila en `dist/surface/shards/ActionButtonShard.mjs`
+3. Engine tiene `ActionButtonShard.__EXTENSIO_COMPILED_PATH__` inyectado
+4. No hay errores de compilación
+
+---
+
+### Desviaciones del plan
+
+**Ninguna** - Implementación sigue exactamente el plan aprobado.
+
+---
+
+### Herramientas utilizadas
+
+- Edición manual de código (no requiere scaffolding)
+- Siguiendo patrón de `surface-pages` plugin existente
+
+---
+
+### Próximos pasos
+
+1. Build manual del demo para verificación
+2. Tests E2E si build es exitoso
+3. Revisión arquitectónica del architect-agent