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

package/dist/artifacts/11-revision-sistema-agentic/modules-v2.md

@@ -0,0 +1,250 @@
+---
+trigger: model_decision
+description: Se aplica cuando se crean, modifican o auditan módulos, o cuando un agente toma decisiones sobre ellos, garantizando estructura contractual, reactividad y cumplimiento arquitectónico.
+---
+
+---
+id: constitution.modules
+type: rule
+owner: architect-agent
+version: 2.0.0
+severity: PERMANENT
+scope: global
+---
+
+# CONSTITUTION: Módulos (Extensio)
+
+## Objetivo
+Este documento define **reglas obligatorias** y contractuales para los módulos de Extensio.
+Todo módulo **DEBE** cumplir estas reglas.
+El `role.module-agent` **DEBE** auditar y hacer cumplir este contrato.
+
+---
+
+## 1. Definición (qué es un módulo)
+
+Un módulo es una **unidad de negocio** que organiza lógica reactiva y persistente.
+
+Un módulo:
+- Gobierna un dominio funcional concreto
+- Expone un estado reactivo propio
+- Interactúa con drivers mediante APIs
+
+Un módulo **NO**:
+- Es UI (las Surfaces son sus vistas)
+- Contiene drivers (los consume como puertos)
+- Depende de otros módulos
+
+---
+
+## 2. Scopes del Módulo
+
+| Scope | Obligatorio | Descripción |
+|-------|-------------|-------------|
+| **Engine** | ✅ Sí | Componente central. Se ejecuta en Service Worker. Gestiona estado reactivo. |
+| **Context** | ❌ Opcional | Extensión del Engine para lógica que requiere DOM o APIs no disponibles en SW. |
+| **Surfaces** | ❌ Opcional | Capa visual: Pages (documentos) y Shards (componentes). |
+
+**Regla**: Si existe Context o Surfaces, **DEBE** documentarse el motivo y relación con Engine.
+
+---
+
+## 3. Estructura Obligatoria
+
+Cada módulo **DEBE** seguir esta estructura mínima:
+
+```
+packages/modules/<module-name>/
+├── src/
+│   ├── index.mts              # Entry point público
+│   ├── types.d.mts            # Tipos locales del módulo
+│   ├── constants.mts          # Constantes tipadas
+│   ├── engine/
+│   │   └── index.mts          # Engine del módulo (OBLIGATORIO)
+│   ├── context/               # (si aplica)
+│   │   └── index.mts
+│   └── surface/
+│       ├── pages/
+│       │   └── index.mts      # Índice de Pages (si usa Pages)
+│       └── shards/
+│           └── index.mts      # Registro de Shards (si usa Shards)
+├── package.json
+└── tsconfig.json
+```
+
+### 3.1 Types (`src/types.d.mts`)
+
+- El módulo **DEBE** definir sus tipos localmente.
+- Import interno: `import type { X } from '../types.d.mts'`
+- Los módulos **NO** consumen tipos de otros módulos directamente.
+- Tipos consumidos externamente **DEBEN** registrarse en `global.d.mts`:
+
+```ts
+// global.d.mts
+declare global {
+  namespace Extensio {
+    namespace SessionManager {
+      export type SessionState = SessionState;
+      export type SessionConfig = SessionConfig;
+    }
+  }
+}
+```
+
+### 3.2 Constants (`src/constants.mts`)
+
+- Todo string repetido o enumeración string-based debe centralizarse aquí.
+- Toda enumeración **DEBE** definirse como `Record<string, string>`.
+- Prohibido hardcodear "magic strings" en el código.
+
+```ts
+// constants.mts
+export const SessionStatus = {
+  Active: 'active',
+  Idle: 'idle',
+  Expired: 'expired',
+} as const;
+
+export type SessionStatusType = typeof SessionStatus[keyof typeof SessionStatus];
+```
+
+### 3.3 Naming Conventions
+
+| Elemento | Convención | Ejemplo |
+|----------|------------|---------|
+| Archivos/carpetas | kebab-case | `session-manager/`, `user-profile.mts` |
+| Clases | PascalCase | `SessionManagerEngine`, `UserProfileContext` |
+| Registro de Shards | kebab-case con guión | `session-manager-widget` |
+| Namespace global | PascalCase | `Extensio.SessionManager` |
+
+---
+
+## 4. Ciclo de Vida del Módulo (PERMANENT)
+
+Todo módulo **DEBE** respetar estrictamente la siguiente secuencia:
+
+### Secuencia de Ejecución
+
+| # | Método | Tipo | Descripción |
+|---|--------|------|-------------|
+| 1 | `run()` | Público | Único punto de entrada. Inicia el ciclo completo. |
+| 2 | `_setup()` | Privado (Core) | Inicializa infraestructura reactiva. **NO sobrescribir.** |
+| 3 | `_listen()` | Privado (Core) | Registra listeners internos del framework. **NO sobrescribir.** |
+| 4 | `setup()` | Público | Configuración del dominio. **NO acceder a props persistentes.** |
+| 5 | `listen()` | Público | Registro de listeners con `@onChanged`. **NO lógica de negocio.** |
+| 6 | `loadProps()` | Interno | Carga propiedades persistentes desde storage. |
+| 7 | `start()` | Público | Ejecución inicial. **PUEDE** leer props y ejecutar lógica. |
+
+### Reglas del Ciclo de Vida
+
+- `run()` es el **único** punto de arranque.
+- `_setup()` y `_listen()` son privados y gestionados por Core.
+- `setup()` y `listen()` **NO DEBEN** acceder a estado persistente.
+- `start()` es el primer punto donde se puede leer estado y ejecutar lógica inicial.
+
+---
+
+## 5. Reactividad (PERMANENT)
+
+### Decoradores Obligatorios
+
+| Decorador | Uso | Regla |
+|-----------|-----|-------|
+| `@property` | Declarar propiedades persistentes | **OBLIGATORIO** para todo estado reactivo |
+| `@onChanged` | Reaccionar a cambios de propiedades | **OBLIGATORIO** para listeners |
+
+### Sincronización
+
+En clases que extienden de Core (Engine, Context):
+- **OBLIGATORIO** usar `await this.waitingLoadProps()` si un listener accede a props reactivas.
+
+```ts
+@onChanged('session')
+async onSessionChanged(value: SessionState) {
+  await this.waitingLoadProps();
+  // Ahora es seguro acceder a otras props
+}
+```
+
+---
+
+## 6. Aislamiento (PERMANENT)
+
+- Un módulo **NO PUEDE** depender de otro módulo.
+- No se permiten dependencias cruzadas (ni directas ni indirectas).
+- Los drivers se consumen como **puertos de acceso**, sin acoplamiento conceptual.
+- El módulo **NO CONOCE** la implementación interna del driver.
+
+---
+
+## 7. Integración con Surfaces
+
+### 7.1 Pages (`src/surface/pages/index.mts`)
+
+Si el módulo define Pages:
+- Este archivo es **OBLIGATORIO**.
+- **Responsabilidad**: Importar archivos `.html` y exportar URLs resueltas.
+
+```ts
+// src/surface/pages/index.mts
+import dashboard from "./dashboard/dashboard.html";
+export const Pages = { dashboard };
+```
+
+- El Engine debe importar este índice para que el CLI detecte las páginas.
+
+### 7.2 Shards (`src/surface/shards/index.mts`)
+
+Si el módulo implementa Shards:
+- Este archivo es **OBLIGATORIO**.
+- **Único lugar** donde se registran los WebComponents.
+- Usar `Shard.register(tagName, ComponentClass)`.
+
+```ts
+// src/surface/shards/index.mts
+import { Shard } from '@extensio/core/shard';
+import { MyShard } from './my-shard.mts';
+
+Shard.register('my-module-shard', MyShard);
+export { MyShard };
+```
+
+- El Engine debe importar los Shards para que el CLI los compile independientemente.
+
+---
+
+## 8. Tooling
+
+- Los módulos **DEBEN** generarse con `mcp_extensio-cli` cuando esté disponible.
+- Si no existe soporte CLI, la creación manual es válida solo si:
+  - Cumple este contrato
+  - Queda registrada como lección aprendida
+
+---
+
+## 9. Auditoría
+
+Criterios mínimos de auditoría para un módulo:
+
+| Criterio | Verificación |
+|----------|--------------|
+| Estructura de carpetas | Conforme a §3 |
+| Ciclo de vida | Conforme a §4 |
+| Reactividad | `@property` y `@onChanged` correctos |
+| Types/Constants | Aislados en sus archivos |
+| Aislamiento | Sin dependencias cruzadas |
+| Surfaces indexadas | Si aplica, conforme a §7 |
+
+---
+
+## 10. Severidad
+
+Cualquier violación de:
+- Estructura (§3)
+- Ciclo de vida (§4)
+- Reactividad (§5)
+- Aislamiento (§6)
+
+se considera **SEVERITY: HIGH** y bloquea la validación del módulo.
+
+---

package/dist/artifacts/11-revision-sistema-agentic/pages-v2.md

@@ -0,0 +1,366 @@
+---
+trigger: model_decision
+description: Se aplica cuando se crean, modifican o auditan Pages, o cuando un agente toma decisiones sobre ellas, garantizando estructura contractual, ciclo de vida y cumplimiento arquitectónico.
+---
+
+---
+id: constitution.pages
+type: rule
+owner: architect-agent
+version: 2.1.0
+severity: PERMANENT
+scope: global
+---
+
+# CONSTITUTION: Pages (Extensio)
+
+## Objetivo
+Este documento define **reglas obligatorias** y contractuales para las Pages de Extensio.
+Toda Page **DEBE** cumplir estas reglas.
+Los agentes **DEBEN** auditar y hacer cumplir este contrato.
+
+---
+
+## 1. Definición (qué es una Page)
+
+Una Page es una **Surface de nivel superior** que representa un documento HTML completo dentro de la extensión.
+
+Una Page:
+- Es un documento HTML que vive dentro de la extensión
+- Se renderiza en su propio contexto (popup, tab, panel)
+- Hereda de la clase `Page` que extiende `Surface` → `Core`
+- Carga JavaScript mediante `<script type="module" src="...">`
+- Puede tener de 1 a N scripts asociados
+- Sigue el ciclo de vida estándar de Extensio: `run()` → `listen()` → `start()`
+
+Una Page **NO**:
+- Contiene lógica de negocio (eso es responsabilidad del Engine)
+- Accede directamente al estado del módulo sin usar el sistema reactivo
+- Se instancia directamente; se navega mediante `Engine.navigate()`
+
+---
+
+## 2. Jerarquía de Clases
+
+```
+Core
+  └── Surface (clase abstracta)
+        └── Page (clase concreta)
+```
+
+### Clase Base: `Surface`
+
+La clase `Surface` extiende `Core` y añade:
+- Hooks DOM: `onMount()` (inicia ciclo con `run()`), `onUnmount()` (cleanup)
+- Listener de Storage: `onStorageChanged()`, `checkListeners()`
+- El sistema reactivo (`@property`, `@onChanged`) viene de `Core`
+
+### Clase: `Page`
+
+```ts
+import { Surface } from '../surface.mts';
+import { Scope } from '../../constants.mts';
+
+export class Page extends Surface {
+    constructor(name: string, scope: string = Scope.Page) {
+        super(name, scope);
+    }
+}
+```
+
+---
+
+## 3. Estructura Obligatoria
+
+Cada Page **DEBE** seguir esta estructura dentro del módulo:
+
+```
+packages/modules/<module-name>/
+└── src/
+    └── surface/
+        └── pages/
+            ├── index.mts              # Índice de Pages (OBLIGATORIO)
+            └── <page-name>/
+                ├── index.html         # Documento HTML
+                ├── index.mts          # Script principal (lógica de la Page)
+                └── styles.css         # Estilos (opcional)
+```
+
+### 3.1 Índice de Pages (`src/surface/pages/index.mts`)
+
+Este archivo es **OBLIGATORIO** si el módulo define Pages.
+
+**Responsabilidad**:
+- Importar todos los archivos `.html` del módulo
+- Exportar las URLs resueltas para uso con `navigate()`
+- Permitir al CLI detectar y procesar las páginas
+
+```ts
+// src/surface/pages/index.mts
+import dashboard from "./dashboard/index.html";
+import settings from "./settings/index.html";
+
+export const Pages = {
+  dashboard,
+  settings,
+};
+```
+
+> **IMPORTANTE**: El import de un `.html` es transformado por el CLI en una URL runtime.
+> El valor exportado es un `string` (la URL), **NO** un objeto JavaScript.
+
+### 3.2 Documento HTML (`index.html`)
+
+El archivo HTML **DEBE**:
+- Ser un documento HTML5 válido
+- Incluir al menos un `<script type="module" src="...">` que cargue el entry point
+- No contener lógica inline (todo en archivos externos)
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Dashboard</title>
+  <link rel="stylesheet" href="./styles.css">
+</head>
+<body>
+  <div id="app"></div>
+  <script type="module" src="./index.mts"></script>
+</body>
+</html>
+```
+
+### 3.3 Script Principal (`index.mts`)
+
+El script de entrada **DEBE**:
+- Extender la clase `Page`
+- Implementar el ciclo de vida de Extensio
+- Llamar a `run()` para iniciar
+
+```ts
+// index.mts
+import { Page } from '@extensio/core/surface/pages';
+
+class DashboardPage extends Page {
+  constructor() {
+    super('dashboard-page');
+  }
+
+  // Opcional: configurar listeners de eventos/drivers
+  override listen() {
+    super.listen();
+    // Registrar listeners aquí
+  }
+
+  // Punto de entrada principal - se ejecuta después de cargar props
+  override start() {
+    this.render();
+  }
+
+  private render() {
+    const app = document.getElementById('app');
+    if (app) {
+      app.innerHTML = '<h1>Dashboard</h1>';
+    }
+  }
+}
+
+// Iniciar la Page
+const page = new DashboardPage();
+page.run();
+```
+
+---
+
+## 4. Ciclo de Vida de una Page
+
+El ciclo de vida de una Page sigue el patrón estándar de Extensio:
+
+### 4.1 Secuencia de Ejecución
+
+| # | Método | Tipo | Descripción |
+|---|--------|------|-------------|
+| 1 | `constructor()` | Público | Inicializa la Page con nombre |
+| 2 | `run()` | Público | **Punto de entrada**. Inicia el ciclo de vida completo. |
+| 3 | `_setup()` | Privado (Core) | Inicializa infraestructura reactiva. Llama a `_listen()`, `listen()`, `loadProps()`. |
+| 4 | `_listen()` | Privado (Surface) | Registra listener de Storage |
+| 5 | `listen()` | Público | Punto para registrar listeners de eventos y drivers |
+| 6 | `loadProps()` | Interno | Carga propiedades persistentes |
+| 7 | `start()` | Público | **Método principal**. Aquí se ejecuta la lógica de la Page. |
+
+### 4.2 Reglas del Ciclo de Vida
+
+- `run()` es el **único** punto de arranque de la Page
+- `listen()` es para registrar listeners, **NO** para lógica de negocio
+- `start()` es el primer punto donde se puede leer estado y renderizar
+
+---
+
+## 5. Navegación
+
+### 5.1 Cargar una Page desde el Engine
+
+Las Pages se cargan mediante el método `navigate()` del Engine:
+
+```ts
+// En el Engine
+import { Pages } from './surface/pages/index.mts';
+
+// Navegar a una Page de la extensión
+// Pages.dashboard es un STRING (la URL del HTML)
+await this.navigate(Pages.dashboard);
+
+// Navegar con opciones
+await this.navigate(Pages.settings, {
+  type: 'popup',
+  rect: { width: 400, height: 600 },
+  active: true,
+});
+```
+
+> **NOTA**: `navigate()` recibe el **path del HTML** (string), nunca un objeto JavaScript.
+
+### 5.2 Cómo funciona `navigate()`
+
+```ts
+public async navigate(url: string | { default: string }, options?: NavigationOptions) {
+  const resolvedUrl = typeof url === 'object' && 'default' in url
+    ? url.default
+    : this.getUrl(url as string);
+
+  return Navigation.open(resolvedUrl, options);
+}
+```
+
+El método acepta:
+- Un `string` directo (URL o path)
+- Un objeto con `{ default: string }` (para compatibilidad con imports)
+
+### 5.3 NavigationOptions
+
+| Opción | Tipo | Default | Descripción |
+|--------|------|---------|-------------|
+| `type` | `'regular' \| 'popup'` | `'regular'` | Tipo de ventana |
+| `rect.width` | `number` | - | Ancho de la ventana (solo popup) |
+| `rect.height` | `number` | - | Alto de la ventana (solo popup) |
+| `rect.top` | `number` | - | Posición Y (solo popup) |
+| `rect.left` | `number` | - | Posición X (solo popup) |
+| `active` | `boolean` | `true` | Si la ventana debe tener foco |
+
+### 5.4 Escuchar Navegación (onNavigate)
+
+Cada Engine tiene un listener `onNavigate` que captura eventos de navegación:
+
+```ts
+// En el Engine
+override onNavigate(event: NavigationEvent) {
+  console.log('Navegación detectada:', event);
+  
+  if (event.isExtensionPage) {
+    // Es una Page de la extensión
+  } else {
+    // Es una URL externa
+  }
+}
+```
+
+### 5.5 NavigationEvent
+
+| Campo | Tipo | Descripción |
+|-------|------|-------------|
+| `event` | `string` | Tipo de evento: `'load'`, `'focus'`, `'window'` |
+| `url` | `string` | URL de la página |
+| `title` | `string?` | Título de la página |
+| `tabId` | `number` | ID del tab |
+| `windowId` | `number` | ID de la ventana |
+| `isExtensionPage` | `boolean` | `true` si es una Page de la extensión |
+
+---
+
+## 6. Integración con Shards (PENDIENTE)
+
+> **NOTA**: Esta funcionalidad está pendiente de implementar en Core.
+
+Una Page **PODRÁ**:
+- Registrar Shards locales
+- Cargar Shards dinámicamente en su DOM
+- Comunicarse con Shards mediante el sistema reactivo
+
+---
+
+## 7. Build y Compilación
+
+### 7.1 Plugin `surface-pages`
+
+El CLI usa el plugin `surface-pages` para procesar Pages:
+
+1. **Detección**: Intercepta imports de archivos `.html`
+2. **Parsing**: Lee el HTML y busca `<script src="...">` 
+3. **Compilación**: Compila cada script como módulo ES (`.mjs`)
+4. **Transformación**: Actualiza las referencias en el HTML de `.mts/.ts` a `.mjs`
+5. **Copia**: Escribe el HTML transformado en `dist/`
+6. **Export**: Retorna la URL runtime del HTML
+
+### 7.2 Transformación del Import
+
+```ts
+// Código fuente
+import dashboard from "./dashboard/index.html";
+
+// Código transformado por el CLI
+const runtimeUrl = globalThis.Extension?.Runtime?.getURL("surface/pages/dashboard/index.html") || "surface/pages/dashboard/index.html";
+export default runtimeUrl;
+```
+
+### 7.3 Output
+
+```
+dist/
+└── surface/
+    └── pages/
+        └── dashboard/
+            ├── index.html    # HTML con referencias actualizadas
+            ├── index.mjs     # Script compilado
+            └── styles.css    # Estilos copiados
+```
+
+---
+
+## 8. Naming Conventions
+
+| Elemento | Convención | Ejemplo |
+|----------|------------|---------|
+| Carpeta de Page | kebab-case | `user-settings/` |
+| Archivo HTML | `index.html` | `index.html` |
+| Archivo Script | `index.mts` | `index.mts` |
+| Clase Page | PascalCase + `Page` | `UserSettingsPage` |
+
+---
+
+## 9. Auditoría
+
+Criterios mínimos de auditoría para una Page:
+
+| Criterio | Verificación |
+|----------|--------------|
+| Estructura | Conforme a §3 |
+| Índice de Pages | Existe y exporta la Page |
+| HTML válido | Documento HTML5 con `<script type="module">` |
+| Ciclo de vida | Extiende `Page`, usa `run()` y `start()` |
+| Navegación | Se carga mediante `Engine.navigate()` |
+| No lógica de negocio | Solo UI y comunicación reactiva |
+
+---
+
+## 10. Severidad
+
+Cualquier violación de:
+- Estructura (§3)
+- Ciclo de vida (§4)
+- Navegación (§5)
+
+se considera **SEVERITY: HIGH** y bloquea la validación de la Page.
+
+---