@arcadialdev/arcality 2.2.0

package/scripts/rebrand-report.mjs

@@ -0,0 +1,241 @@
+import fs from 'fs';
+import path from 'path';
+
+async function rebrandReport() {
+    // Definir directorios objetivo: El reporte personalizado, el nativo anidado y el reporte interno
+    const reportDir = process.env.REPORTS_DIR || 'tests-report';
+    const targetDirs = [
+        reportDir,
+        path.join(reportDir, 'native'),
+        'playwright-internal-report'
+    ];
+
+    const logoPngPath = path.join('public', 'logo.png');
+    let logoBase64 = '';
+
+    // Preparar Logo Arcality
+    if (fs.existsSync(logoPngPath)) {
+        try {
+            const logoBuffer = fs.readFileSync(logoPngPath);
+            logoBase64 = `data:image/png;base64,${logoBuffer.toString('base64')}`;
+            console.log("✅ Logo Arcality cargado desde public/logo.png");
+        } catch (e) {
+            console.error("⚠️ Error leyendo logo:", e.message);
+        }
+    } else {
+        console.warn("⚠️ No se encontró public/logo.png");
+    }
+
+    for (const dir of targetDirs) {
+        if (fs.existsSync(dir)) {
+            console.log(`Processing report directory: ${dir}`);
+            processDirectory(dir, logoBase64);
+        }
+    }
+
+    console.log("🏁 Branding process finished.");
+}
+
+function processDirectory(reportDir, logoBase64) {
+    const indexPath = path.join(reportDir, 'index.html');
+
+    // Procesar index.html principal
+    if (fs.existsSync(indexPath)) {
+        try {
+            let html = fs.readFileSync(indexPath, 'utf8');
+
+            // 1. Reemplazo de Títulos Estáticos
+            html = html.replace(/<title>.*?<\/title>/gi, '<title>Arcality Mission Report</title>');
+            html = html.replace(/Playwright Test Report/g, 'Arcality Mission Report');
+            html = html.replace(/Playwright Report/g, 'Arcality Report');
+
+            // 2. Limpieza de Stack Traces Sucios (Node Modules)
+            html = html.replace(/at\s+.*?node_modules.*?(\n|\r)/g, '');
+            html = html.replace(/at\s+.*?agentic-runner\.spec\.ts:\d+/g, '');
+
+            // 3. Inyección de Estilos y Scripts (MODO AGRESIVO)
+            const customStyles = `
+                <script id="arcality-branding-script">
+                    /* ARCALITY_BRANDING_SCRIPT */
+                    // 1. Limpieza de Caché y Service Worker
+                    if ('serviceWorker' in navigator) {
+                        navigator.serviceWorker.getRegistrations().then(r => r.forEach(reg => reg.unregister()));
+                    }
+
+                    // 2. Reemplazo Dinámico (Loop para vencer al JS de Playwright)
+                    function enforceBranding() {
+                        // Forzar Título
+                        if (!document.title.includes('Arcality')) {
+                            document.title = 'Arcality Mission Report';
+                        }
+                        
+                        // Forzar Favicon
+                        let icon = document.querySelector("link[rel*='icon']");
+                        if (!icon) {
+                            icon = document.createElement('link');
+                            icon.rel = 'shortcut icon';
+                            document.head.appendChild(icon);
+                        }
+                        if (icon && icon.href !== '${logoBase64}') icon.href = '${logoBase64}';
+
+                        // Insertar Logo Arcality en el Header
+                        if ('${logoBase64}' && !document.querySelector('.arcality-logo-injected')) {
+                            const logoImg = document.createElement('img');
+                            logoImg.src = '${logoBase64}';
+                            logoImg.className = 'arcality-logo-injected';
+                            logoImg.style.height = '32px';
+                            logoImg.style.marginRight = '12px';
+                            logoImg.style.verticalAlign = 'middle';
+                            
+                            // Intentar encontrar un lugar en el header
+                            const headerElements = ['header h1', '.Box-header h1', '.test-details-header h1', 'h1', 'header div'];
+                            for (const selector of headerElements) {
+                                const el = document.querySelector(selector);
+                                if (el && !el.querySelector('.arcality-logo-injected')) {
+                                    el.prepend(logoImg);
+                                    break;
+                                }
+                            }
+                        }
+
+                        // Reemplazar textos visibles
+                        const walker = document.createTreeWalker(document.body, NodeFilter.SHOW_TEXT, null, false);
+                        let node;
+                        while(node = walker.nextNode()) {
+                            if (node.nodeValue && node.nodeValue.includes('Playwright')) {
+                                node.nodeValue = node.nodeValue.replace(/Playwright/g, 'Arcality');
+                            }
+                        }
+                        
+                        // Ocultar elementos de Playwright/Github
+                        document.querySelectorAll('svg.octicon-mark-github, header svg, [aria-label*="Playwright"]').forEach(el => {
+                            el.style.display = 'none';
+                        });
+                    }
+
+                    setInterval(enforceBranding, 300);
+                    window.addEventListener('load', enforceBranding);
+                </script>
+                <style id="arcality-branding-style">
+                    /* ARCALITY_BRANDING_STYLE */
+                    @import url('https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600&display=swap');
+                    body, .Box-header, .Box-body, .test-details-header {
+                        font-family: 'Inter', -apple-system, system-ui, sans-serif !important;
+                    }
+                    /* Pequeños retoques visuales premium */
+                    div[role="tablist"] { border-radius: 8px; overflow: hidden; }
+                    .label, span[class*="Label"] { border-radius: 999px !important; }
+                    .arcality-logo-injected {
+                        filter: drop-shadow(0 2px 4px rgba(0,0,0,0.1));
+                        transition: transform 0.2s ease;
+                    }
+                    .arcality-logo-injected:hover {
+                        transform: scale(1.05);
+                    }
+                </style>
+            `;
+
+            // Eliminar inyecciones previas si existen (limpieza profunda)
+            html = html.replace(/<script id="arcality-branding-script">[\s\S]*?<\/script>/g, '');
+            html = html.replace(/<style id="arcality-branding-style">[\s\S]*?<\/style>/g, '');
+
+            // Compatibilidad con versiones sin ID (Modo agresivo)
+            html = html.replace(/<script>\s*\/\* ARCALITY_BRANDING \*\/[\s\S]*?<\/script>/g, '');
+            html = html.replace(/<style>\s*\/\* ARCALITY_BRANDING \*\/[\s\S]*?<\/style>/g, '');
+
+            // Eliminar cualquier script que contenga lógica de "Limpieza de Caché" o "document.createTreeWalker" inyectado previamente
+            html = html.replace(/<script>\s*\/\/ 1\. Limpieza de Caché[\s\S]*?<\/script>/g, '');
+            html = html.replace(/<script>\s*\/[\s\S]*?enforceBranding[\s\S]*?<\/script>/g, '');
+
+            // Inyectar justo antes del cierre de head
+            if (html.includes('</head>')) {
+                html = html.replace('</head>', `${customStyles}\n</head>`);
+            } else if (html.includes('<head>')) {
+                html = html.replace('<head>', `<head>\n${customStyles}`);
+            }
+
+            // 4. Cambiar icono estático si existe
+            if (logoBase64) {
+                html = html.replace(/data:image\/svg\+xml,%3csvg.*?%3c\/svg%3e/g, logoBase64);
+                html = html.replace(/rel="shortcut icon" href=".*?"/g, `rel="shortcut icon" href="${logoBase64}"`);
+                html = html.replace(/rel="icon" href=".*?"/g, `rel="icon" href="${logoBase64}"`);
+            }
+
+            fs.writeFileSync(indexPath, html, 'utf8');
+            console.log(`✨ [REBRAND] Report transformado en: ${indexPath}`);
+        } catch (err) {
+            console.error(`❌ Error al procesar ${indexPath}: ${err.message}`);
+        }
+    }
+
+    // Procesar Trace Viewer anidado si existe
+    processTraceViewer(reportDir, logoBase64);
+}
+
+function processTraceViewer(reportDir, logoBase64) {
+    const tracePath = path.join(reportDir, 'trace', 'index.html');
+
+    if (fs.existsSync(tracePath)) {
+        try {
+            let traceHtml = fs.readFileSync(tracePath, 'utf8');
+
+            // Reemplazos básicos
+            traceHtml = traceHtml.replace(/<title>.*?<\/title>/gi, '<title>Arcality Trace Viewer</title>');
+            traceHtml = traceHtml.replace(/Playwright Trace Viewer/g, 'Arcality Trace Viewer');
+            traceHtml = traceHtml.replace(/For more information, please see the <a href=".*?">docs<\/a>\./, 'Powered by Arcality Engine.');
+
+            const tvScript = `
+                <script id="arcality-trace-branding">
+                    /* ARCALITY_TRACE_BRANDING */
+                    function fixTraceBranding() {
+                        if (!document.title.includes('Arcality')) document.title = 'Arcality Trace Viewer';
+                        let icon = document.querySelector("link[rel*='icon']");
+                        if (!icon) {
+                            icon = document.createElement('link');
+                            icon.rel = 'icon';
+                            document.head.appendChild(icon);
+                        }
+                        if (icon && icon.href !== '${logoBase64}') icon.href = '${logoBase64}';
+
+                        if ('${logoBase64}' && !document.querySelector('.arcality-logo-injected')) {
+                            const logoImg = document.createElement('img');
+                            logoImg.src = '${logoBase64}';
+                            logoImg.className = 'arcality-logo-injected';
+                            logoImg.style.height = '24px';
+                            logoImg.style.margin = '0 10px';
+                            logoImg.style.verticalAlign = 'middle';
+
+                            const toolbar = document.querySelector('.split-view-vertical > div:first-child, header, .toolbar');
+                            if (toolbar) toolbar.prepend(logoImg);
+                        }
+                    }
+                    setInterval(fixTraceBranding, 500);
+                </script>
+            `;
+
+            // Limpieza e inyección
+            traceHtml = traceHtml.replace(/<script id="arcality-trace-branding">[\s\S]*?<\/script>/g, '');
+            traceHtml = traceHtml.replace(/<script>\s*\/\* ARCALITY_BRANDING \*\/[\s\S]*?<\/script>/g, '');
+
+            // Fix for potential spaces in HTML tags like '< head >', '< link >', etc.
+            traceHtml = traceHtml.replace(/<\s*(\w+)\s*>/g, '<$1>');
+            traceHtml = traceHtml.replace(/<\s*\/\s*(\w+)\s*>/g, '</$1>');
+
+            if (traceHtml.includes('</head>')) {
+                traceHtml = traceHtml.replace('</head>', `${tvScript}\n</head>`);
+            }
+
+            // Favicon
+            if (logoBase64) {
+                traceHtml = traceHtml.replace(/rel="icon" href=".*?"/g, `rel="icon" href="${logoBase64}"`);
+            }
+
+            fs.writeFileSync(tracePath, traceHtml, 'utf8');
+            console.log(`✨ [REBRAND] Trace Viewer transformado en: ${tracePath}`);
+        } catch (e) {
+            console.error(`⚠️ Error en Trace Viewer ${tracePath}: ${e.message}`);
+        }
+    }
+}
+
+rebrandReport().catch(console.error);

package/scripts/setup.mjs

@@ -0,0 +1,166 @@
+#!/usr/bin/env node
+// scripts/setup.mjs — Comando: arcality setup
+// Configura API Key + instala navegador Playwright (Chromium)
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { spawn } from 'node:child_process';
+import { createInterface } from 'node:readline';
+
+const CONFIG_DIR = path.join(os.homedir(), '.arcality');
+const CONFIG_FILE = path.join(CONFIG_DIR, 'config.json');
+const PACKAGE_ROOT = process.env.ARCALITY_ROOT || path.resolve(path.dirname(new URL(import.meta.url).pathname), '..');
+
+function question(prompt) {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    return new Promise(resolve => {
+        rl.question(prompt, answer => { rl.close(); resolve(answer.trim()); });
+    });
+}
+
+function loadConfig() {
+    try {
+        if (fs.existsSync(CONFIG_FILE)) {
+            let raw = fs.readFileSync(CONFIG_FILE, 'utf8');
+            if (raw.charCodeAt(0) === 0xFEFF) raw = raw.slice(1);
+            return JSON.parse(raw);
+        }
+    } catch { }
+    return {};
+}
+
+function saveConfig(config) {
+    if (!fs.existsSync(CONFIG_DIR)) {
+        fs.mkdirSync(CONFIG_DIR, { recursive: true });
+    }
+    fs.writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2), 'utf8');
+}
+
+async function main() {
+    // Leer versión
+    let version = 'unknown';
+    try {
+        const pkg = JSON.parse(fs.readFileSync(path.join(PACKAGE_ROOT, 'package.json'), 'utf8'));
+        version = pkg.version || 'unknown';
+    } catch { }
+
+    console.log('');
+    console.log('  ╔══════════════════════════════════════════╗');
+    console.log(`  ║   ARCALITY — Setup v${version.padEnd(24)}║`);
+    console.log('  ╚══════════════════════════════════════════╝');
+    console.log('');
+
+    const config = loadConfig();
+
+    // ──────────────── Paso 1: API Key de Arcality ────────────────
+    const currentKey = config.api_key || '';
+    const currentAnthropic = config.anthropic_api_key || '';
+
+    const maskedArc = currentKey
+        ? `✅ ${currentKey.slice(0, 6)}****${currentKey.slice(-4)}`
+        : '❌ (No configurada)';
+
+    const maskedAnt = currentAnthropic
+        ? `✅ ${currentAnthropic.slice(0, 6)}****${currentAnthropic.slice(-4)}`
+        : '❌ (No configurada)';
+
+    console.log(`  🔑 Arcality API Key (dummy/real):  ${maskedArc}`);
+    console.log(`  🧠 Anthropic API Key (corporativa): ${maskedAnt}`);
+    console.log('');
+
+    const newKey = await question('  👉 Ingresa Arcality API Key (Enter p. mantener): ');
+    if (newKey) {
+        if (!newKey.startsWith('arc_k_')) {
+            console.log('  ❌ La API Key debe iniciar con "arc_k_"');
+            process.exit(1);
+        }
+        config.api_key = newKey;
+    }
+
+    // API URL is internal-only (loaded via dotenv), always available
+    const hasSaaSBackend = !!process.env.ARCALITY_API_URL;
+
+    if (hasSaaSBackend) {
+        console.log('  🧠 Anthropic API Key (omitida — se usará el Cerebro SaaS)');
+        // Podemos limpiar la llave local por seguridad si queremos
+        if (config.anthropic_api_key) delete config.anthropic_api_key;
+    } else {
+        const newAnt = await question('  👉 Ingresa Anthropic API Key (Enter p. mantener): ');
+        if (newAnt) {
+            if (!newAnt.startsWith('sk-ant-')) {
+                console.log('  ⚠️  Formato de llave Anthropic inusual. Verifica que inicie con "sk-ant-"');
+            }
+            config.anthropic_api_key = newAnt;
+        }
+    }
+
+    // Configurar modelo por defecto
+    config.model = config.model || 'claude-sonnet-4-5';
+
+    // Guardar config
+    config.version = version;
+    config.setup_at = new Date().toISOString();
+    saveConfig(config);
+    console.log('');
+    console.log('  ✅ Configuración guardada correctamente.');
+
+    // ─── Paso 2: Instalar Chromium ───
+    console.log('');
+    console.log('  🌐 Instalando navegador (Chromium para Playwright)...');
+    console.log('');
+
+    try {
+        await new Promise((resolve, reject) => {
+            const child = spawn('npx', ['playwright', 'install', 'chromium'], {
+                stdio: 'inherit',
+                shell: true,
+                cwd: PACKAGE_ROOT
+            });
+            child.on('exit', code => code === 0 ? resolve() : reject(new Error(`Playwright install falló (exit code ${code})`)));
+            child.on('error', reject);
+        });
+        console.log('');
+        console.log('  ✅ Chromium instalado correctamente');
+    } catch (err) {
+        console.log('');
+        console.log(`  ⚠️  No se pudo instalar Chromium automáticamente: ${err.message}`);
+        console.log('     Puedes instalarlo manualmente ejecutando:');
+        console.log('     npx playwright install chromium');
+    }
+
+    // ─── Paso 3: Crear .env si no existe ───
+    const envFile = path.join(PACKAGE_ROOT, '.env');
+    const envExample = path.join(PACKAGE_ROOT, '.env.example');
+
+    if (!fs.existsSync(envFile) && fs.existsSync(envExample)) {
+        let content = fs.readFileSync(envExample, 'utf8');
+
+        // Inyectar la API Key
+        if (config.api_key) {
+            content = content.replace('ARCALITY_API_KEY=', `ARCALITY_API_KEY=${config.api_key}`);
+        }
+
+        fs.writeFileSync(envFile, content, 'utf8');
+        console.log('  ✅ .env creado desde .env.example');
+    } else if (fs.existsSync(envFile)) {
+        console.log('  ✅ .env existente (sin modificar)');
+    }
+
+    // ─── Resumen final ───
+    console.log('');
+    console.log('  ╔══════════════════════════════════════════╗');
+    console.log('  ║    ✅ SETUP COMPLETADO                    ║');
+    console.log('  ╚══════════════════════════════════════════╝');
+    console.log('');
+    console.log('  Para empezar, ejecuta:');
+    console.log('');
+    console.log('     arcality                         → Menú interactivo');
+    console.log('     arcality --agent "tu misión"     → Ejecución directa');
+    console.log('');
+}
+
+main().catch(err => {
+    console.error('  ❌ Error durante setup:', err.message);
+    process.exit(1);
+});

package/src/KnowledgeService.ts

@@ -0,0 +1,239 @@
+
+import * as crypto from 'crypto';
+import chalk from 'chalk';
+
+/**
+ * KnowledgeService (SaaS v2)
+ * Servicio centralizado para alimentar y consumir la base de conocimiento persistente de Arcality.
+ * Configurado para usar SNAKE_CASE según la especificación del servidor.
+ */
+
+export interface PortalIngestRequest {
+    project_id: string;
+    target_url: string;
+    page_title?: string;
+    dom_hash: string;
+    viewport?: { width: number; height: number };
+    components: Array<{
+        tag: string;
+        component_type: "ACTION" | "FIELD" | "INFO" | "NAVIGATION" | "DATA";
+        semantic_label: string;
+        text_content?: string;
+        is_interactive: boolean;
+        attributes?: any;
+        bounding_rect?: { x: number; y: number; width: number; height: number };
+    }>;
+}
+
+export interface PortalContextResponse {
+    rules: Array<{ title: string; description: string; severity: string }>;
+    fields: Array<{ field_identifier: string; field_type: string; is_required: boolean }>;
+}
+
+export interface ProjectDto {
+    id: string;
+    name: string;
+    base_url?: string;
+}
+
+export class KnowledgeService {
+    private static instance: KnowledgeService;
+    private apiBase: string;
+    private apiKey: string;
+    private projectId: string | null = null;
+
+    private constructor() {
+        // API URL is internal-only, loaded from the tool's .env via dotenv
+        this.apiBase = process.env.ARCALITY_API_URL || 'http://localhost:5164';
+        this.apiKey = process.env.ARCALITY_API_KEY || '';
+        this.projectId = process.env.ARCALITY_PROJECT_ID || null;
+    }
+
+    public static getInstance(): KnowledgeService {
+        if (!KnowledgeService.instance) {
+            KnowledgeService.instance = new KnowledgeService();
+        }
+        return KnowledgeService.instance;
+    }
+
+    public setProjectId(id: string) {
+        this.projectId = id;
+    }
+
+    public getProjectId(): string | null {
+        if (!this.projectId || this.projectId === 'undefined' || this.projectId === 'null') {
+            this.projectId = process.env.ARCALITY_PROJECT_ID || null;
+        }
+        return this.projectId;
+    }
+
+    /**
+     * 1. Gestión de Proyectos
+     */
+    public async getProjects(): Promise<ProjectDto[]> {
+        try {
+            const res = await fetch(`${this.apiBase}/api/v1/projects`, {
+                headers: { 'x-api-key': this.apiKey }
+            });
+            if (!res.ok) return [];
+            const data = await res.json();
+            return data.projects || [];
+        } catch (e: any) {
+            console.warn(chalk.yellow(`[KnowledgeService] Error al obtener proyectos: ${e.message}`));
+            return [];
+        }
+    }
+
+    public async createProject(name: string, baseUrl: string): Promise<ProjectDto | null> {
+        try {
+            const res = await fetch(`${this.apiBase}/api/v1/projects`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'x-api-key': this.apiKey
+                },
+                body: JSON.stringify({ name, base_url: baseUrl })
+            });
+            if (!res.ok) return null;
+            return await res.json();
+        } catch (e: any) {
+            console.error(chalk.red(`[KnowledgeService] Falló creación de proyecto: ${e.message}`));
+            return null;
+        }
+    }
+
+    /**
+     * 2. Ingesta (Post-Percept)
+     */
+    public async ingest(payload: PortalIngestRequest): Promise<void> {
+        if (!payload.project_id || payload.project_id === 'undefined') {
+            console.warn(chalk.yellow(`[Knowledge] Ingesta cancelada: project_id es inválido.`));
+            return;
+        }
+
+        try {
+            const res = await fetch(`${this.apiBase}/api/v1/portal/ingest`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'x-api-key': this.apiKey
+                },
+                body: JSON.stringify(payload)
+            });
+            if (res.status === 200) {
+                const data = await res.json();
+                if (data.status === 'skipped_duplicate_dom') {
+                   // console.log(chalk.gray(`[Knowledge] Ingesta omitida (Duplicado).`));
+                } else {
+                    console.log(chalk.cyan(`[Knowledge] Ingesta exitosa (Project: ${payload.project_id})`));
+                }
+            }
+        } catch (e: any) {
+            console.warn(chalk.yellow(`[Knowledge] Error en ingesta: ${e.message}`));
+        }
+    }
+
+    /**
+     * 3. Contexto (Pre-Reasoning)
+     */
+    public async getContext(url: string): Promise<PortalContextResponse | null> {
+        const pid = this.getProjectId();
+        if (!pid || pid === 'undefined') return null;
+        try {
+            const pathUrl = new URL(url).pathname;
+            // Para queries de GET solemos usar snake_case si el server es estricto
+            const res = await fetch(`${this.apiBase}/api/v1/portal/context?project_id=${pid}&path=${encodeURIComponent(pathUrl)}`, {
+                headers: { 'x-api-key': this.apiKey }
+            });
+            if (!res.ok) return null;
+            return await res.json();
+        } catch (e: any) {
+            console.warn(chalk.yellow(`[Knowledge] Error al obtener contexto: ${e.message}`));
+            return null;
+        }
+    }
+
+    /**
+     * 4. Aprendizaje (portal_domain_rules)
+     */
+    public async saveRule(title: string, description: string, severity: string = 'important', pageUrl?: string): Promise<void> {
+        const pid = this.getProjectId();
+        if (!pid || pid === 'undefined') return;
+        try {
+            const pathUrl = pageUrl ? new URL(pageUrl).pathname : null;
+            await fetch(`${this.apiBase}/api/v1/portal/rules`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'x-api-key': this.apiKey
+                },
+                body: JSON.stringify({
+                    project_id: pid,
+                    rule_type: "UI_UX", // Default según especificación
+                    title,
+                    description,
+                    severity
+                })
+            });
+            console.log(chalk.green(`[Knowledge] Nueva regla registrada: ${title}`));
+        } catch (e) { }
+    }
+
+    /**
+     * 5. Catálogo de Campos (portal_field_catalog)
+     */
+    public async saveField(identifier: string, type: string, isRequired: boolean): Promise<void> {
+        const pid = this.getProjectId();
+        if (!pid || pid === 'undefined') return;
+        try {
+            await fetch(`${this.apiBase}/api/v1/portal/fields`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'x-api-key': this.apiKey
+                },
+                body: JSON.stringify({
+                    project_id: pid,
+                    field_identifier: identifier,
+                    field_type: type,
+                    is_required: isRequired,
+                    source: "agent_auto"
+                })
+            });
+            console.log(chalk.green(`[Knowledge] Nuevo campo catalogado: ${identifier}`));
+        } catch (e) { }
+    }
+
+    /**
+     * 6. Conocimiento General (Documentación)
+     */
+    public async saveKnowledge(title: string, content: string, docType: string = 'PROCESS'): Promise<void> {
+        const pid = this.getProjectId();
+        if (!pid || pid === 'undefined') return;
+        try {
+            await fetch(`${this.apiBase}/api/v1/portal/knowledge`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'x-api-key': this.apiKey
+                },
+                body: JSON.stringify({
+                    project_id: pid,
+                    doc_type: docType,
+                    title,
+                    content,
+                    source: "agent_auto"
+                })
+            });
+            console.log(chalk.green(`[Knowledge] Nuevo conocimiento guardado: ${title}`));
+        } catch (e) { }
+    }
+
+    /**
+     * Utilidad: Calcular Hash para Ingesta
+     */
+    public calculateDomHash(components: any[]): string {
+        const fingerprint = components.map(c => `${c.tag}-${c.semanticLabel}`).join('|');
+        return crypto.createHash('sha256').update(fingerprint).digest('hex');
+    }
+}