@christianmaf80/agentic-workflow 1.10.0-beta.1 → 1.12.0-beta.1

package/dist/rules/constitution/clean-code.md

@@ -1,4 +1,4 @@
-# Clean Code Rules (Agentic System)
+# Clean Code Rules (Extensio)
 
 type: rules
 version: 2
@@ -10,11 +10,12 @@ scope: global
 ## Purpose
 
 This document defines the **mandatory Clean Code rules** for all source code,
-agents, and workflows in the Agentic ecosystem.
+agents, workflows, drivers, and modules in the Extensio ecosystem.
 
 These rules are inspired by **Robert C. Martin – Clean Code** and adapted to:
 - TypeScript + ES Modules
-- Modular systems
+- Browser extension architecture
+- Reactive, modular systems
 - Multi-agent workflows
 
 Any code that violates these rules MUST be considered incomplete.
@@ -32,14 +33,23 @@ Any code that violates these rules MUST be considered incomplete.
 - Use **nouns** for variables.
 - Avoid generic names: `data`, `info`, `tmp`, `value`.
 
+❌ `let data;`  
+✅ `let activeTabId;`
+
 ### 1.3 Functions / Methods
 - Use **verbs** or verb phrases.
 - Names MUST describe exactly **one responsibility**.
 
+❌ `handleStuff()`  
+✅ `persistSessionState()`
+
 ### 1.4 Classes
 - Use **nouns**.
 - One clear domain responsibility per class.
 
+❌ `Manager`, `Processor`, `Helper`  
+✅ `StorageDriver`, `TabsEngine`
+
 ---
 
 ## 2. Functions & Methods (Small and Focused)
@@ -56,6 +66,9 @@ If it exceeds this, it MUST be split.
 - Prefer **objects** over multiple parameters.
 - Avoid boolean flags (they hide responsibility branches).
 
+❌ `loadTab(id, true)`  
+✅ `loadTab({ id, forceReload })`
+
 ---
 
 ## 3. Single Responsibility Principle (Strict)
@@ -63,6 +76,11 @@ If it exceeds this, it MUST be split.
 - Every function, class, and file MUST have **one reason to change**.
 - Mixing concerns is forbidden.
 
+Examples of forbidden mixes:
+- UI logic + storage logic
+- Browser API calls + business rules
+- Validation + mutation
+
 ---
 
 ## 4. Comments (Last Resort)
@@ -85,6 +103,19 @@ If a comment is needed to explain *what*, the code is wrong.
 - Do NOT silently ignore errors.
 - Do NOT use generic `catch (e) {}` blocks.
 
+❌
+```ts
+try { doSomething(); } catch {}
+```
+
+✅
+```ts
+try { doSomething(); }
+catch (error) {
+  throw new StorageInitializationError(error);
+}
+```
+
 ---
 
 ## 6. Formatting & Structure
@@ -95,13 +126,13 @@ If a comment is needed to explain *what*, the code is wrong.
 
 ### 6.2 Class Member Order (MANDATORY)
 
-1. Static properties
-2. Static methods
-3. Instance properties
-4. Constructor
-5. Event handlers / listeners
-6. Private methods
-7. Public methods
+1. Static properties  
+2. Static methods  
+3. Instance properties  
+4. constructor  
+5. Event handlers / listeners  
+6. Private methods  
+7. Public methods  
 
 Any deviation is a violation.
 
@@ -113,9 +144,28 @@ Any deviation is a violation.
 - File name MUST match the main exported concept.
 - Avoid “utils” files unless the domain is explicit.
 
+❌ `utils.ts`  
+✅ `tab-url-normalizer.ts`
+
 ---
 
-## 8. Duplication & Abstraction
+## 8. Drivers (Extensio-Specific)
+
+- Drivers MUST be thin facades.
+- NO business logic inside drivers.
+- Browser-specific adaptations ONLY.
+
+---
+
+## 9. Modules (Extensio-Specific)
+
+- Modules MUST be domain-focused.
+- Modules MUST communicate ONLY through reactive storage or defined APIs.
+- No direct cross-module imports unless explicitly allowed.
+
+---
+
+## 10. Duplication & Abstraction
 
 - Duplication is preferred over **wrong abstraction**.
 - Abstract ONLY when at least **two concrete implementations exist**.
@@ -124,7 +174,7 @@ Any deviation is a violation.
 
 ---
 
-## 9. Tests & Verifiability (Conceptual)
+## 11. Tests & Verifiability (Conceptual)
 
 - Code MUST be verifiable in isolation.
 - Hidden side effects are forbidden.
@@ -132,7 +182,7 @@ Any deviation is a violation.
 
 ---
 
-## 10. Clean Code Gate
+## 12. Clean Code Gate
 
 Any agent, workflow, or human contributor MUST ensure:
 
@@ -150,4 +200,6 @@ Inspired by:
 - Robert C. Martin – *Clean Code*
 - Robert C. Martin – *Clean Architecture*
 
+Adapted for Extensio.
+
 This rule set is **binding** when referenced as `INJECTED`.

package/dist/rules/constitution/drivers.md

@@ -0,0 +1,294 @@
+---
+trigger: model_decision
+description: Se aplica cuando se crean, modifican o auditan drivers, o cuando un agente toma decisiones sobre ellos, garantizando estructura contractual, aislamiento, compatibilidad multi-browser y ausencia de lógica de negocio
+---
+
+---
+id: constitution.drivers
+type: rule
+owner: architect-agent
+version: 1.0.0
+severity: PERMANENT
+scope: global
+---
+
+# CONSTITUTION: Drivers (Extensio)
+
+## Objetivo
+Este documento define **reglas obligatorias** y contractuales para los drivers de Extensio.
+Todo driver **DEBE** cumplir estas reglas.  
+El `role.driver-agent` **DEBE** auditar y hacer cumplir este contrato.
+
+---
+
+## 1. Definición (qué es un driver)
+Un driver es una **fachada** (facade) que abstrae APIs del navegador (WebExtensions) o Web APIs
+para que el resto del framework sea **browser-agnóstico**.
+
+Un driver:
+- adapta APIs (shape, compat, eventos, tipos)
+- expone una API estable y documentada
+- encapsula diferencias entre navegadores
+
+Un driver:
+- NO contiene lógica de negocio
+- NO conoce módulos de negocio
+- NO decide flujos o workflows
+- NO persiste estado de negocio (solo adapta storage si es driver de storage)
+
+---
+
+## 2. Estructura obligatoria por driver
+Cada driver **DEBE** seguir esta estructura mínima:
+
+- `src/index.mts` → **wrapper público** (API estable + JSDoc)
+- `src/__BROWSER__/index.mts` → implementación por navegador (chrome/firefox/safari)
+- `src/types.d.mts` → tipos locales del driver
+- `src/constants.mts` → constantes tipadas (`Record<string, string>`)
+- `src/common/index.mts` → implementación compartida (si aplica)
+- Integración de tipos en `globals.d.mts` (root) y de constantes en `constants.mts` (root)
+  como parte obligatoria de la estructura del driver.
+
+### 2.1 Wrapper (src/index.mts)
+Reglas:
+- `src/index.mts` **NO puede** ser un simple re-export.
+- Debe exponer una clase o funciones wrapper que:
+  - deleguen en la implementación específica (`__BROWSER__`)
+  - añadan JSDoc
+  - mantengan API estable
+- Debe importar `__BROWSER__/index.mts` usando el patrón del build (ej. `__BROWSER__`).
+
+### 2.2 Implementación por navegador (src/__BROWSER__/index.mts)
+Reglas:
+- Debe mapear a las APIs reales del navegador.
+- Debe mantener el contrato de tipos definido por `types.d.mts`.
+- Debe aislar diferencias específicas del navegador sin filtrar detalles al wrapper.
+
+### 2.3 Types (src/types.d.mts)
+Reglas:
+- El driver **DEBE** definir sus tipos localmente.
+- Import interno de tipos del mismo driver:
+  - `import type { X } from '../types.d.mts'`
+- Los drivers **NO** consumen tipos de otros drivers:
+  - cada driver define sus propios tipos para mantener independencia y portabilidad
+- Interfaces genéricas comunes (p.ej. `BrowserEvent`) **se duplican** localmente
+  para evitar dependencias cruzadas indeseadas.
+- La integracion de tipos **DEBE** reflejarse correctamente en `globals.d.mts`
+  (imports/exports sin duplicados ni nombres corruptos).
+- Todo driver **DEBE** registrar sus tipos en `globals.d.mts` dentro del
+  namespace global `Extensio.<NamespaceDelDriver>`.
+
+Ejemplo (globals.d.mts):
+```ts
+declare global {
+  namespace Extensio {
+    namespace Tabs {
+      type TabStatusType = typeof TabStatus[keyof typeof TabStatus];
+    }
+  }
+}
+```
+
+### 2.4 Constants (src/constants.mts)
+Reglas:
+- Todo string repetido o enumeración string-based debe centralizarse aquí.
+- Toda enumeración **DEBE** definirse en `constants.mts` y usarse para crear tipos.
+  - Objetivo: reutilizar los valores como objetos en runtime y como tipos en compile-time.
+- Debe tiparse como `Record<string, string>`.
+- Los drivers **NO** consumen constantes de otros drivers:
+  - cada driver define sus propias constantes para mantener independencia y portabilidad
+- Las constantes del driver **DEBEN** extender las constantes globales del proyecto
+  para que puedan ser usadas por los módulos.
+- La integracion de constantes **DEBE** reflejarse correctamente en el `constants.mts`
+  del root (exports sin duplicados ni nombres corruptos).
+- Todo driver **DEBE** exportar sus constantes en el `constants.mts` del root.
+
+Ejemplo (constants.mts root):
+```ts
+export { TabStatus, WindowType } from '@extensio/driver-tabs/src/constants.mts';
+```
+- Prohibido hardcodear “magic strings” repetidos en el código del driver.
+
+### 2.5 Common (src/common/index.mts)
+Reglas:
+- Solo si existe lógica compartible entre navegadores.
+- No debe incluir lógica de negocio.
+- Debe ser consumida por los `__BROWSER__/index.mts`, no por módulos.
+
+### 2.6 Demo (demo/)
+Reglas:
+- Si un driver tiene carpeta `demo`, cualquier import hacia `src` **DEBE** usar
+  el alias `__PARENT_SRC__` (nunca rutas relativas al `src`).
+  - Ejemplo: `import { Tabs } from '__PARENT_SRC__/index.mts';`
+- La demo **DEBE** mantener la estructura de Extensio y cumplir `constitution.extensio_architecture`.
+- La demo **DEBE** generarse con `mcp_extensio-cli tools` cuando exista soporte aplicable.
+
+---
+
+## 3. Events (contrato obligatorio)
+Los eventos **DEBEN** exponerse como wrappers que implementen una interfaz local `BrowserEvent`.
+
+Ejemplo de forma:
+- En `types.d.mts`:
+  - `export interface BrowserEvent<T extends (...args: any) => void> { addListener(cb: T): void; removeListener(cb: T): void; hasListener(cb: T): boolean; }`
+- En `src/__BROWSER__/index.mts`:
+  - `static onCreated: BrowserEvent<(arg: X) => void> = { addListener: ..., removeListener: ..., hasListener: ... }`
+
+Regla:
+- Prohibido exponer directamente eventos crudos del navegador (ej. `chrome.tabs.onUpdated`).
+
+---
+
+## 4. Scoping y dependencias (aislamiento)
+- Un driver no debe depender de otro driver por imports directos.
+- Si necesita tipos externos, usar `Extension.*`.
+- Un driver **NUNCA** debe usar otro driver; deben ser agnósticos e independientes.
+- Los drivers **DEBEN** definir sus propios tipos; **NO** deben usar `@types` de otras librerías.
+- Si necesita interactuar con otros drivers, hacerlo a través del dominio superior (módulo/core),
+  nunca creando dependencia de paquete circular.
+
+---
+
+## 5. Clean Code (en drivers)
+- Se aplica `clean-code.md` como contrato obligatorio para drivers.
+
+---
+
+## 6. Compatibilidad multi-browser
+- La API del wrapper debe ser **estable** entre navegadores.
+- Las divergencias deben resolverse en `__BROWSER__`.
+- Si una API no existe en un navegador:
+  - se define comportamiento fallback (documentado)
+  - o se lanza error controlado (documentado)
+- Debe evitarse divergencia silenciosa.
+
+---
+
+## 7. Tooling recomendado (scaffolding)
+Cuando exista comando disponible, los drivers **DEBEN** generarse con `mcp_extensio-cli tools`.
+
+Principio:
+- Preferir generación por CLI para consistencia.
+- Si el CLI no soporta una operación, la modificación manual es válida solo si:
+  - cumple este contrato
+  - queda registrada como “lección aprendida” por el `driver-agent`.
+
+---
+
+## 8. Auditoría de cumplimiento
+Criterios mínimos de auditoría:
+- estructura de carpetas correcta (Sección 2)
+- wrapper no es re-export (2.1)
+- types aislados (2.3)
+- events como wrappers (3)
+- constants centralizadas (2.4)
+- no lógica de negocio (1)
+- compatibilidad documentada (6)
+
+---
+
+## 9. Severidad
+Cualquier violación de:
+- estructura (Sección 2)
+- types isolation (2.3)
+- events wrappers (3)
+- lógica de negocio en drivers (1)
+
+se considera **SEVERITY: HIGH** y debe corregirse antes de integrar cambios.
+
+---
+
+## 10. Ejemplos (drivers reales)
+Los ejemplos respetan la independencia entre drivers: no hay consumo de tipos ni
+constantes de otros drivers dentro de un driver.
+
+### 10.1 Enumeraciones en `constants.mts` (Tabs driver)
+Fuente: `packages/drivers/tabs/src/constants.mts`
+```ts
+export const TabStatus: Record<string, string> = {
+  Loading: 'loading',
+  Complete: 'complete',
+};
+
+export const WindowType: Record<string, string> = {
+  Normal: 'normal',
+  Popup: 'popup',
+  Panel: 'panel',
+  App: 'app',
+  Devtools: 'devtools',
+};
+```
+
+### 10.2 Tipos derivados de constantes (Tabs driver)
+Fuente: `packages/drivers/tabs/src/types.d.mts`
+```ts
+import { TabStatus, WindowType } from './constants.mts';
+
+export type TabStatusType = typeof TabStatus[keyof typeof TabStatus];
+export type WindowTypeType = typeof WindowType[keyof typeof WindowType];
+```
+
+### 10.3 Re-export de constantes (Tabs driver)
+Fuente: `packages/drivers/tabs/src/types.d.mts`
+```ts
+export { TabStatus, WindowType };
+```
+
+---
+
+### 10.4 Clase wrapper en `src/index.mts` (Tabs driver)
+Fuente: `packages/drivers/tabs/src/index.mts`
+```ts
+import { Tabs as CommonTabs } from '__BROWSER__/index.mts';
+import type { Tab, BrowserEvent } from './types.d.mts';
+
+export class Tabs extends CommonTabs {
+  static override get(tabId: number): Promise<Tab> {
+    return CommonTabs.get(tabId);
+  }
+
+  static override onCreated: BrowserEvent<(tab: Tab) => void> = {
+    addListener: (cb) => CommonTabs.onCreated.addListener(cb),
+    removeListener: (cb) => CommonTabs.onCreated.removeListener(cb),
+    hasListener: (cb) => CommonTabs.onCreated.hasListener(cb),
+  };
+}
+```
+
+---
+
+### 10.5 Consumo desde Core/Modules (Navigation)
+Fuente: `packages/core/src/engine/navigation/index.mts`
+```ts
+import { Tabs } from '@extensio/driver-tabs';
+import { Windows } from '@extensio/driver-windows';
+
+await Tabs.create({ url, active: true });
+await Windows.create({ url, type: 'popup', focused: true });
+```
+
+---
+
+### 10.6 Demo usando `__PARENT_SRC__`
+Ejemplo (alias definido en `tsconfig.json` de drivers):
+```ts
+import { Tabs } from '__PARENT_SRC__/index.mts';
+```
+
+---
+
+### 10.7 Extensión de globals (Prompt AI driver)
+Fuente: `packages/drivers/prompt-ai/src/types.d.mts`
+```ts
+declare global {
+  interface WindowOrWorkerGlobalScope {
+    ai?: {
+      languageModel: AILanguageModelFactory;
+    };
+  }
+}
+```
+
+---
+
+Fin de la constitución de drivers.

package/dist/rules/constitution/extensio-architecture.md

@@ -0,0 +1,131 @@
+---
+trigger: always_on
+---
+
+# EXTENSIO ARCHITECTURE - FRAMEWORK RULES
+
+Este documento define los **principios arquitectónicos fundamentales** del framework Extensio.
+Para reglas contractuales detalladas de cada componente, consultar su constitución específica.
+
+---
+
+## 1. PRINCIPIOS ARQUITECTÓNICOS (PERMANENT)
+
+### 1.1 Filosofía Base
+Extensio es un framework para construir extensiones de navegador complejas
+de forma modular, reactiva y predecible.
+
+Su filosofía se basa en los siguientes principios:
+
+- Separar estrictamente la lógica de negocio de las APIs del navegador (Drivers) y de la UI (Surfaces).
+- Aislar cada dominio funcional en paquetes independientes del monorepo, sin dependencias cruzadas.
+- Utilizar un modelo reactivo como único mecanismo de comunicación entre los módulos.
+- Priorizar la predecibilidad del comportamiento frente a la flexibilidad implícita.
+- Diseñar el sistema para escalar en complejidad sin degradar mantenibilidad.
+- Mantener el código agnóstico del navegador y del entorno de ejecución.
+
+### 1.2 Independencia y Dirección de Dependencias
+- Todos los paquetes DEBEN ser independientes y versionables.
+- El acoplamiento directo entre paquetes del mismo tipo está PROHIBIDO.
+- El uso de capacidades externas DEBE realizarse exclusivamente mediante Drivers.
+- Core NO DEBE conocer ni depender de ningún paquete del proyecto.
+
+### 1.3 Prohibición de Dependencias Cruzadas
+- Un módulo NO DEBE depender de otro módulo.
+- Un driver NO DEBE depender de otro driver.
+- El uso de drivers por parte de los módulos NO constituye una dependencia conceptual.
+- Ningún paquete DEBE introducir ciclos de dependencias, directos o indirectos.
+
+### 1.4 Separación de Responsabilidades
+- El principio SRP (Single Responsibility Principle) DEBE aplicarse estrictamente.
+- Está PROHIBIDO mezclar UI con lógica de negocio dentro de módulos.
+- Los drivers NO DEBEN contener lógica de negocio.
+- Los bucles reactivos están PROHIBIDOS.
+
+---
+
+## 2. SCOPES DEL FRAMEWORK (PERMANENT)
+
+El framework define tres scopes principales. Cada uno tiene su propia constitución con reglas detalladas.
+
+### 2.1 Engine
+- El Engine es el componente central y obligatorio de todo módulo.
+- Se ejecuta en el entorno de Service Worker.
+- Es responsable del estado reactivo y persistente del módulo.
+- **NO DEBE** renderizar UI ni acceder al DOM.
+- **Constitución detallada**: `constitution.modules`
+
+### 2.2 Context
+- Un Context es una extensión opcional del Engine.
+- Encapsula lógica que requiere acceso al DOM o APIs no disponibles en el Service Worker.
+- El Engine controla completamente el ciclo de vida del Context.
+- **NO DEBE** contener lógica de negocio ni renderizar UI.
+- **Constitución detallada**: `constitution.modules`
+
+### 2.3 Surfaces
+Las Surfaces representan la capa visual del framework. Se dividen en:
+
+#### Pages
+- Documentos completos que se renderizan en un tab del navegador.
+- Representan vistas de alto nivel (opciones, dashboards).
+- **Constitución detallada**: `constitution.pages`
+
+#### Shards
+- Componentes visuales reutilizables (WebComponents).
+- Componentes de UI puros, sin estado persistente propio.
+- **Constitución detallada**: `constitution.shards`
+
+---
+
+## 3. DRIVERS (PERMANENT)
+
+Los Drivers son adaptadores que envuelven APIs del navegador.
+Representan la frontera de efectos laterales del sistema.
+
+**Constitución detallada**: `constitution.drivers`
+
+---
+
+## 4. CORE PACKAGE (PERMANENT)
+
+- Core DEBE exponer Engine, Context y Surfaces.
+- Core DEBE proveer el sistema reactivo (@property, @onChanged).
+- Core NO DEBE depender de ningún paquete del proyecto.
+- Core NO DEBE contener lógica de negocio de ningún módulo.
+
+---
+
+## 5. EXTENSIO CLI (PERMANENT)
+
+El tool `mcp_extensio-cli` es el ÚNICO punto de entrada para build y test.
+- Unit e Integration **DEBEN** ejecutarse con **Vitest**.
+- E2E **DEBE** ejecutarse con **Playwright**.
+- Scaffolding de módulos, drivers y surfaces **DEBE** usar `mcp_extensio-cli`.
+
+---
+
+## 6. ORDEN DE COMPOSICIÓN DE CLASES (PERMANENT)
+
+1. Propiedades estáticas
+2. Métodos estáticos
+3. Propiedades de instancia
+4. Constructor
+5. Event handlers
+6. Métodos privados
+7. Métodos públicos
+
+---
+
+## 7. CONSTITUCIONES ESPECÍFICAS
+
+Para reglas contractuales detalladas, consultar:
+
+| Componente | Constitución |
+|------------|--------------|
+| Módulos | `constitution.modules` |
+| Drivers | `constitution.drivers` |
+| Pages | `constitution.pages` |
+| Shards | `constitution.shards` |
+| Clean Code | `constitution.clean_code` |
+
+---

package/dist/rules/constitution/index.md

@@ -1,29 +1,31 @@
 ---
 id: rules.constitution.index
 owner: architect-agent
-version: 1.0.0
+version: 2.0.0
 severity: PERMANENT
-scope: global
+trigger: always_on
 ---
 
-# INDEX — Constitution
+# INDEX — Rules / Constitution
 
-## Agent identification (MANDATORY)
-First line of the document:
-`<icon> **<agent-name>**: <message>`
-
-## Objective
-List constitution rules and their paths.
+## Objetivo
+Este fichero enumera todas las rules del dominio `constitution`.
+Los workflows y agentes **DEBEN** referenciar estas reglas
+por alias en lugar de rutas directas.
 
 ## Aliases (YAML)
 ```yaml
 constitution:
-  agent_system: .agent/rules/constitution/agent-system.md
   GEMINI_location: .agent/rules/constitution/GEMINI.location.md
-  project_architecture: .agent/rules/constitution/project-architecture.md
+  extensio_architecture: .agent/rules/constitution/extensio-architecture.md
   clean_code: .agent/rules/constitution/clean-code.md
+  drivers: .agent/rules/constitution/drivers.md
+  modules: .agent/rules/constitution/modules.md
+  shards: .agent/rules/constitution/shards.md
+  pages: .agent/rules/constitution/pages.md
   agents_behavior: .agent/rules/constitution/agents-behavior.md
 ```
 
-## Rules
-- Any new constitution MUST be added here.
+## Reglas
+- Este índice **solo** declara reglas del dominio `constitution`.
+- Cualquier nueva regla del dominio **DEBE** añadirse aquí.