@arcadialdev/arcality 2.6.7 → 3.0.1

package/scripts/init.mjs

@@ -7,18 +7,17 @@
 //   4. Create project via POST /api/v1/projects
 //   5. Write arcality.config
 
-import 'dotenv/config';
-import fs from 'node:fs';
-import path from 'node:path';
-import { fileURLToPath } from 'url';
-import { intro, outro, text, password as passwordPrompt, spinner, note, isCancel, cancel, confirm } from '@clack/prompts';
-import chalk from 'chalk';
-import figlet from 'figlet';
-import {
-    configExists,
-    loadProjectConfig,
-    saveProjectConfig,
-    createConfig,
+import 'dotenv/config';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'url';
+import { intro, outro, text, password as passwordPrompt, spinner, note, isCancel, cancel, confirm } from '@clack/prompts';
+import chalk from 'chalk';
+import {
+    configExists,
+    loadProjectConfig,
+    saveProjectConfig,
+    createConfig,
 } from '../src/configManager.mjs';
 import { getApiUrl } from '../src/configLoader.mjs';
 
@@ -26,14 +25,14 @@ const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const PACKAGE_ROOT = process.env.ARCALITY_ROOT || path.resolve(__dirname, '..');
 
-// ── Helpers ──
+// ── Helpers ──
 
-function getVersion() {
-    try {
-        const pkg = JSON.parse(fs.readFileSync(path.join(PACKAGE_ROOT, 'package.json'), 'utf8'));
-        return pkg.version || 'unknown';
-    } catch {
-        return 'unknown';
+function getVersion() {
+    try {
+        const pkg = JSON.parse(fs.readFileSync(path.join(PACKAGE_ROOT, 'package.json'), 'utf8'));
+        return pkg.version || 'unknown';
+    } catch {
+        return 'unknown';
     }
 }
 
@@ -56,75 +55,93 @@ function detectFramework(projectRoot) {
     }
 }
 
-function isValidUrl(url) {
-    try {
-        const u = new URL(url);
-        return u.protocol === 'http:' || u.protocol === 'https:';
-    } catch {
-        return false;
-    }
-}
+function isValidUrl(url) {
+    try {
+        const u = new URL(url);
+        return u.protocol === 'http:' || u.protocol === 'https:';
+    } catch {
+        return false;
+    }
+}
+
+function showInitBanner(version, projectRoot) {
+    const sentinelAscii = `
+ █████  ██████   ██████  █████  ██      ██ ████████ ██    ██
+██   ██ ██   ██ ██      ██   ██ ██      ██    ██     ██  ██
+███████ ██████  ██      ███████ ██      ██    ██      ████
+██   ██ ██   ██ ██      ██   ██ ██      ██    ██       ██
+██   ██ ██   ██  ██████ ██   ██ ███████ ██    ██       ██`;
+
+    intro(chalk.gray(sentinelAscii));
+
+    note(
+        chalk.gray('◉ Modo de Configuración: ') + chalk.bold.white('ACTIVO') + '\n' +
+        chalk.gray('◉ Enlace con Backend:    ') + chalk.bold.white('PREPARANDO') + '\n' +
+        chalk.gray('◉ Generador de Contexto: ') + chalk.bold.white('DISPONIBLE') + '\n' +
+        chalk.gray('─'.repeat(50)) + '\n' +
+        chalk.gray('Versión del Sistema: ') + chalk.white(`v${version}`),
+        'Estado Central de Arcality'
+    );
+
+    note(
+        chalk.gray('Nodo Objetivo: ') + chalk.white(process.env.NODE_ENV ?? 'development') + '\n' +
+        chalk.gray('Proyecto Local: ') + chalk.white(projectRoot) + '\n' +
+        chalk.gray('Comando:       ') + chalk.white('arcality init'),
+        'Inicialización del Proyecto'
+    );
+}
 
 // ── Main ──
 
-async function main() {
-    const version = getVersion();
-    const projectRoot = process.cwd();
-
-    console.clear();
-    const logo = figlet.textSync('Arcality', { font: 'Standard' });
-    intro(chalk.cyanBright(logo));
-
-    note(
-        chalk.magentaBright('Project Initialization') + '\n' +
-        chalk.gray('─'.repeat(50)) + '\n' +
-        chalk.bold.white('📦 Version: ') + chalk.yellow(version) + '\n' +
-        chalk.bold.white('📁 Project: ') + chalk.yellow(projectRoot),
-        'arcality init'
-    );
+async function main() {
+    const version = getVersion();
+    const projectRoot = process.cwd();
+
+    console.clear();
+    showInitBanner(version, projectRoot);
 
     // ── Check for existing config ──
-    if (configExists(projectRoot)) {
-        const existing = loadProjectConfig(projectRoot);
-        if (existing) {
-            note(
-                chalk.yellow('⚠️  An arcality.config already exists in this project.') + '\n\n' +
-                chalk.white('  Project: ') + chalk.cyan(existing.project?.name || 'unknown') + '\n' +
-                chalk.white('  Base URL: ') + chalk.cyan(existing.project?.baseUrl || 'unknown') + '\n' +
-                chalk.white('  Project ID: ') + chalk.gray(existing.projectId || 'unknown'),
-                'Existing Configuration'
-            );
-
-            const overwrite = await confirm({
-                message: 'Do you want to reconfigure? This will create a NEW project in backend.',
-            });
-
-            if (isCancel(overwrite) || !overwrite) {
-                outro(chalk.cyan('Configuration unchanged. Use `arcality run` to start.'));
-                return;
-            }
-        }
-    }
+    if (configExists(projectRoot)) {
+        const existing = loadProjectConfig(projectRoot);
+        if (existing) {
+            note(
+                chalk.yellow('⚠️  Ya existe un arcality.config en este proyecto.') + '\n\n' +
+                chalk.white('  Proyecto: ') + chalk.cyan(existing.project?.name || 'unknown') + '\n' +
+                chalk.white('  Base URL: ') + chalk.cyan(existing.project?.baseUrl || 'unknown') + '\n' +
+                chalk.white('  ID del Proyecto: ') + chalk.gray(existing.projectId || 'desconocido'),
+                'Configuración Existente'
+            );
+
+            const overwrite = await confirm({
+                message: '¿Deseas reconfigurar? Esto creará un NUEVO proyecto en backend.',
+            });
+
+            if (isCancel(overwrite) || !overwrite) {
+                outro(chalk.cyan('Configuración sin cambios. Usa `arcality run` para iniciar.'));
+                return;
+            }
+        }
+    }
 
     // ── Step 1: API Key ──
     const apiKey = await text({
-        message: chalk.cyan('🔑 Enter your Arcality API Key:'),
+        message: chalk.cyan('🔑 Ingresa tu API Key de Arcality:'),
         placeholder: 'arc_live_xxxxx',
         validate: (v) => {
-            if (!v || !v.trim()) return 'API Key is required.';
-            if (!v.startsWith('arc_')) return 'API Key must start with "arc_"';
+            if (!v || !v.trim()) return 'La API Key es obligatoria.';
+            if (!v.startsWith('arc_')) return 'La API Key debe iniciar con "arc_"';
         },
     });
 
     if (isCancel(apiKey)) {
-        cancel('Setup cancelled.');
+        cancel('Configuración cancelada.');
         process.exit(0);
     }
 
     // ── Step 2: Validate API Key (uses internal API URL) ──
     const apiUrl = getApiUrl();
     const s = spinner();
-    s.start('Validating API Key...');
+    s.start('Validando API Key...');
 
     let organizationId = null;
 
@@ -140,12 +157,12 @@ async function main() {
         if (!res.ok) {
             const errText = await res.text().catch(() => '');
             const errorMap = {
-                401: '❌ Invalid API Key. Please check your key and try again.',
-                403: `❌ Authentication Failed (HTTP 403). Server says: ${errText.slice(0, 150)}`,
-            };
-            const msg = errorMap[res.status] || `❌ Server error (HTTP ${res.status}): ${errText.slice(0, 150)}`;
-            s.stop(chalk.red(msg));
-            console.log(chalk.yellow('\n   Press Enter to return to menu...'));
+                401: '❌ API Key inválida. Revísala e inténtalo de nuevo.',
+                403: `❌ Autenticación fallida (HTTP 403). El servidor respondió: ${errText.slice(0, 150)}`,
+            };
+            const msg = errorMap[res.status] || `❌ Error del servidor (HTTP ${res.status}): ${errText.slice(0, 150)}`;
+            s.stop(chalk.red(msg));
+            console.log(chalk.yellow('\n   Presiona Enter para volver al menú...'));
             // Salida limpia (código 0) para que el menú padre no interprete esto como crash
             await new Promise(r => setTimeout(r, 3000));
             process.exit(0);
@@ -154,77 +171,77 @@ async function main() {
         const data = await res.json();
         organizationId = data.organizationId || data.organization_id || null;
 
-        s.stop(chalk.green('✅ API Key validated successfully'));
+        s.stop(chalk.green('✅ API Key validada correctamente'));
 
         if (data.plan) {
             note(
-                chalk.bold.white('📋 Plan: ') + chalk.cyan(data.plan) + '\n' +
-                chalk.bold.white('🏢 Org: ') + chalk.cyan(organizationId || 'N/A'),
-                'Account Info'
+                chalk.bold.white('📋 Plan: ') + chalk.cyan(data.plan) + '\n' +
+                chalk.bold.white('🏢 Organización: ') + chalk.cyan(organizationId || 'N/A'),
+                'Información de la Cuenta'
             );
         }
     } catch (err) {
-        s.stop(chalk.red(`❌ Could not connect to Arcality backend: ${err.message}`));
-        console.log(chalk.yellow('   Make sure the backend is running and accessible.'));
+        s.stop(chalk.red(`❌ No se pudo conectar al backend de Arcality: ${err.message}`));
+        console.log(chalk.yellow('   Asegúrate de que el backend esté activo y accesible.'));
         await new Promise(r => setTimeout(r, 3000));
         process.exit(0);
     }
 
     // ── Step 3: Project details ──
     const projectName = await text({
-        message: chalk.cyan('📋 Project name:'),
-        placeholder: 'My Portal QA',
-        validate: (v) => {
-            if (!v || v.trim().length < 2) return 'Project name is required (min 2 chars).';
-        },
-    });
-    if (isCancel(projectName)) { cancel('Setup cancelled.'); process.exit(0); }
-
-    const baseUrl = await text({
-        message: chalk.cyan('🌐 Base URL of the application to test:'),
-        placeholder: 'https://staging.example.com',
-        validate: (v) => {
-            if (!v || !v.trim()) return 'Base URL is required.';
-            if (!isValidUrl(v)) return 'Invalid URL. Use http:// or https://';
-        },
-    });
-    if (isCancel(baseUrl)) { cancel('Setup cancelled.'); process.exit(0); }
-
-    const hasLogin = await confirm({
-        message: chalk.cyan('🔐 Does your application require a Login/Authentication?'),
-    });
-    if (isCancel(hasLogin)) { cancel('Setup cancelled.'); process.exit(0); }
+        message: chalk.cyan('📋 Nombre del proyecto:'),
+        placeholder: 'Mi Portal QA',
+        validate: (v) => {
+            if (!v || v.trim().length < 2) return 'El nombre del proyecto es obligatorio (mínimo 2 caracteres).';
+        },
+    });
+    if (isCancel(projectName)) { cancel('Configuración cancelada.'); process.exit(0); }
+
+    const baseUrl = await text({
+        message: chalk.cyan('🌐 URL base de la aplicación a probar:'),
+        placeholder: 'https://staging.example.com',
+        validate: (v) => {
+            if (!v || !v.trim()) return 'La URL base es obligatoria.';
+            if (!isValidUrl(v)) return 'URL inválida. Usa http:// o https://';
+        },
+    });
+    if (isCancel(baseUrl)) { cancel('Configuración cancelada.'); process.exit(0); }
+
+    const hasLogin = await confirm({
+        message: chalk.cyan('🔐 ¿Tu aplicación requiere inicio de sesión/autenticación?'),
+    });
+    if (isCancel(hasLogin)) { cancel('Configuración cancelada.'); process.exit(0); }
 
     let username = '';
     let password = '';
 
     if (hasLogin) {
-        username = await text({
-            message: chalk.cyan('👤 Login username / email:'),
-            validate: (v) => {
-                if (!v || !v.trim()) return 'Username is required.';
-            },
-        });
-        if (isCancel(username)) { cancel('Setup cancelled.'); process.exit(0); }
-
-        password = await passwordPrompt({
-            message: chalk.cyan('🔒 Login password:'),
-            validate: (v) => {
-                if (!v || !v.length) return 'Password is required.';
-            },
-        });
-        if (isCancel(password)) { cancel('Setup cancelled.'); process.exit(0); }
+        username = await text({
+            message: chalk.cyan('👤 Usuario o correo de acceso:'),
+            validate: (v) => {
+                if (!v || !v.trim()) return 'El usuario es obligatorio.';
+            },
+        });
+        if (isCancel(username)) { cancel('Configuración cancelada.'); process.exit(0); }
+
+        password = await passwordPrompt({
+            message: chalk.cyan('🔒 Contraseña de acceso:'),
+            validate: (v) => {
+                if (!v || !v.length) return 'La contraseña es obligatoria.';
+            },
+        });
+        if (isCancel(password)) { cancel('Configuración cancelada.'); process.exit(0); }
     }
 
     // ── Step 4: Detect framework ──
     const frameworkDetected = detectFramework(projectRoot);
     if (frameworkDetected) {
-        console.log(chalk.gray(`   🛠️  Framework detected: ${chalk.magenta(frameworkDetected)}`));
+        console.log(chalk.gray(`   🛠️  Framework detectado: ${chalk.magenta(frameworkDetected)}`));
     }
 
     // ── Step 5: Create project in backend ──
     const sCreate = spinner();
-    sCreate.start('Creating project in Arcality backend...');
+    sCreate.start('Creando proyecto en el backend de Arcality...');
 
     let projectId = null;
     try {
@@ -254,8 +271,8 @@ async function main() {
             // If response is HTML (e.g. Cloudflare 521), show a clean message
             const isHtml = errText.trim().startsWith('<');
             const displayError = isHtml
-                ? `The Arcality backend server is temporarily unavailable (HTTP ${res.status}). The project will be saved locally only.`
-                : `HTTP ${res.status}: ${errText.slice(0, 200)}`;
+                ? `El servidor backend de Arcality no está disponible temporalmente (HTTP ${res.status}). El proyecto se guardará solo de forma local.`
+                : `HTTP ${res.status}: ${errText.slice(0, 200)}`;
 
             sCreate.stop(chalk.yellow(`⚠️  ${displayError}`));
             // Don't exit — write the config with a local-only project ID so user can still run
@@ -264,12 +281,12 @@ async function main() {
             const created = await res.json();
             projectId = created.id || created.Id;
             organizationId = organizationId || created.organizationId || created.organization_id || null;
-            sCreate.stop(chalk.green(`✅ Project created: "${projectName.trim()}" (${projectId})`));
-        }
-    } catch (err) {
-        sCreate.stop(chalk.yellow(`⚠️  Could not reach Arcality server: ${err.message}. Continuing in local mode.`));
-        projectId = projectId || `local_${Date.now()}`;
-    }
+            sCreate.stop(chalk.green(`✅ Proyecto creado: "${projectName.trim()}" (${projectId})`));
+        }
+    } catch (err) {
+        sCreate.stop(chalk.yellow(`⚠️  No se pudo conectar con el servidor de Arcality: ${err.message}. Se continuará en modo local.`));
+        projectId = projectId || `local_${Date.now()}`;
+    }
 
     // ── Step 6: Write arcality.config ──
     const config = createConfig({
@@ -286,60 +303,86 @@ async function main() {
 
     saveProjectConfig(config, projectRoot);
 
-    // ── Step 7: Custom QA Context ──
-    const wantsContext = await confirm({
-        message: chalk.cyan('📄 Do you want to generate a local QA Context file (.arcality/qa-context.md) to teach the AI specific business rules?'),
-    });
-    
-    if (!isCancel(wantsContext) && wantsContext) {
-        const arcalityDir = path.join(projectRoot, '.arcality');
-        if (!fs.existsSync(arcalityDir)) {
+    // ── Step 7: Custom QA Context ──
+    note(
+        chalk.white('El archivo ') + chalk.cyan('.arcality/qa-context.md') + chalk.white(' se inyecta al prompt del agente antes de cada misión.') + '\n' +
+        chalk.white('Úsalo para reglas del negocio, navegación especial y anti-patrones que Arcality deba respetar siempre.'),
+        'QA Context Local'
+    );
+
+    const wantsContext = await confirm({
+        message: chalk.cyan('📄 ¿Deseas generar un archivo local QA Context (.arcality/qa-context.md) para enseñarle al agente reglas del negocio?'),
+    });
+    
+    if (!isCancel(wantsContext) && wantsContext) {
+        const arcalityDir = path.join(projectRoot, '.arcality');
+        if (!fs.existsSync(arcalityDir)) {
             fs.mkdirSync(arcalityDir, { recursive: true });
         }
         
-        const qaContextPath = path.join(arcalityDir, 'qa-context.md');
-        const qaTemplate = `# 🧠 Arcality QA Context
-Este archivo es leído automáticamente por tu Agente Arcality antes de cada misión.
-Siéntete libre de borrar, modificar o agregar información para enseñarle a la IA las reglas exclusivas de tu sitio web.
-
-## 💼 Reglas Generales del Dominio
-> (Ejemplo: Formatos de documentos, restricciones, etc.)
-- 
-
-## 🧭 Navegación y UI Especial
-> (Ejemplo: Tiempos de espera, clics dobles necesarios, etc.)
-- 
-
-## 🛑 Casos Prohibidos y Anti-patrones
-> (Cosas que el agente NUNCA debe intentar)
-- 
-`;
-        if (!fs.existsSync(qaContextPath)) {
-            fs.writeFileSync(qaContextPath, qaTemplate);
-        }
-    }
+        const qaContextPath = path.join(arcalityDir, 'qa-context.md');
+        const qaTemplate = `# Arcality QA Context
+<!--
+Este archivo se inyecta antes de cada mision.
+Escribe reglas cortas, especificas y accionables.
+Usa un bullet por regla real.
+Los bullets que empiecen con "Ejemplo:" se ignoran hasta que los reemplaces.
+-->
+
+## Reglas del Dominio
+<!-- Restricciones de negocio, validaciones duras, formatos, limites -->
+- Ejemplo: Un usuario no puede registrar mas de 24 horas en un mismo dia.
+- Ejemplo: El campo "Numero de empleado" debe conservar ceros a la izquierda.
+
+## Navegacion y UI Especial
+<!-- Pasos raros de la interfaz, cargas lentas, modales, menus no obvios -->
+- Ejemplo: Despues de elegir un proyecto, espera a que cargue la tabla antes de registrar horas.
+- Ejemplo: El menu de acciones siempre se abre desde el icono ":" de la primera fila.
+
+## Casos Prohibidos y Anti-patrones
+<!-- Cosas que Arcality nunca debe intentar -->
+- Ejemplo: No uses "Continuar con Microsoft".
+- Ejemplo: No cierres el modal con Escape; usa el boton "Cancelar".
+
+## Datos y Credenciales de Prueba
+<!-- Usuarios de prueba, ambientes, datos obligatorios o datos que deben evitarse -->
+- Ejemplo: Usa el usuario QA_TIMESHEET_01 para pruebas de captura diaria.
+- Ejemplo: No reutilices folios ya aprobados.
+
+## Resultado Esperado y Validaciones Clave
+<!-- Como saber que la mision realmente termino bien -->
+- Ejemplo: La prueba termina cuando el registro aparece en la tabla "Timesheet - Hoy" de /welcome.
+- Ejemplo: Si aparece la leyenda "Expirado" en el proyecto, la prueba sigue siendo valida.
+`;
+        if (!fs.existsSync(qaContextPath)) {
+            fs.writeFileSync(qaContextPath, qaTemplate);
+            note(chalk.green(`✅ QA Context creado en: ${qaContextPath}`), 'Contexto Guardado');
+        } else {
+            note(chalk.cyan(`ℹ️ QA Context ya existente: ${qaContextPath}`), 'Contexto Detectado');
+        }
+    }
 
     // ── Summary ──
     note(
-        chalk.green('✅ arcality.config created successfully!') + '\n\n' +
-        chalk.bold.white('  Project: ') + chalk.cyan(config.project.name) + '\n' +
-        chalk.bold.white('  Base URL: ') + chalk.cyan(config.project.baseUrl) + '\n' +
-        chalk.bold.white('  Framework: ') + chalk.magenta(config.project.frameworkDetected || 'N/A') + '\n' +
-        chalk.bold.white('  Project ID: ') + chalk.gray(config.projectId) + '\n' +
-        chalk.bold.white('  YAML Dir: ') + chalk.yellow(config.runtime.yamlOutputDir),
-        'Configuration Saved'
-    );
-
-    outro(
-        chalk.cyanBright('🚀 Ready! Run ') +
-        chalk.bold.white('arcality run') +
-        chalk.cyanBright(' or ') +
-        chalk.bold.white('arcality') +
-        chalk.cyanBright(' to start testing.')
-    );
-}
-
-main().catch(err => {
-    console.error(chalk.red('  ❌ Error during init:'), err.message);
-    process.exit(1);
-});
+        chalk.green('✅ arcality.config creado correctamente') + '\n\n' +
+        chalk.bold.white('  Proyecto: ') + chalk.cyan(config.project.name) + '\n' +
+        chalk.bold.white('  URL Base: ') + chalk.cyan(config.project.baseUrl) + '\n' +
+        chalk.bold.white('  Framework: ') + chalk.magenta(config.project.frameworkDetected || 'N/A') + '\n' +
+        chalk.bold.white('  ID del Proyecto: ') + chalk.gray(config.projectId) + '\n' +
+        chalk.bold.white('  Carpeta de Misiones: ') + chalk.yellow(config.runtime.yamlOutputDir),
+        'Configuración Guardada'
+    );
+
+    outro(
+        chalk.cyanBright('🚀 Listo. Ejecuta ') +
+        chalk.bold.white('arcality run') +
+        chalk.cyanBright(' o ') +
+        chalk.bold.white('arcality') +
+        chalk.cyanBright(' para comenzar a probar.')
+    );
+}
+
+main().catch(err => {
+    console.error(chalk.red('  ❌ Error durante init:'), err.message);
+    process.exit(1);
+});

package/src/arcalityClient.mjs

@@ -93,6 +93,16 @@ function getEffectiveApiKey() {
     return key;
 }
 
+/**
+ * Gets the effective Project ID.
+ * Priority: arcality.config > ARCALITY_PROJECT_ID env var
+ */
+function loadProjectId() {
+    const localConfig = loadArcalityConfig();
+    if (localConfig?.projectId) return localConfig.projectId;
+    return process.env.ARCALITY_PROJECT_ID || null;
+}
+
 // ═══════════════════════════════════════════════════════
 // PUBLIC API
 // ═══════════════════════════════════════════════════════
@@ -244,6 +254,54 @@ export async function startMission(prompt, targetUrl) {
     };
 }
 
+/**
+ * Fetches missions from the backend API.
+ * @param {string} projectId 
+ * @param {string} tags - Comma separated tags (optional)
+ * @returns {Promise<Object>} Contains success flag and missions array
+ */
+export async function fetchMissions(projectId, tags) {
+    const key = getEffectiveApiKey();
+    if (!key) return { success: false, error: 'no_api_key', missions: [] };
+
+    const apiBase = getEffectiveApiBase();
+    if (!apiBase) {
+        // MOCK MODE: Return empty array for now since there's no backend
+        return { success: true, mode: 'mock', missions: [] };
+    }
+
+    try {
+        const url = new URL(`${apiBase}/api/v1/projects/${projectId}/missions`);
+        if (tags) {
+            url.searchParams.append('tags', tags);
+        }
+
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), 10000);
+        const res = await fetch(url.toString(), {
+            method: 'GET',
+            headers: {
+                'x-api-key': key
+            },
+            signal: controller.signal
+        });
+        clearTimeout(timeout);
+
+        if (!res.ok) {
+            const errText = await res.text();
+            console.warn(`[DEBUG] fetchMissions failed: ${res.status} - ${errText}`);
+            return { success: false, error: 'server_error', missions: [] };
+        }
+
+        const data = await res.json();
+        return { success: true, missions: data.missions || [] };
+    } catch (e) {
+        const reason = e?.name === 'AbortError' ? 'timeout (10s)' : (e?.message || 'unknown');
+        console.warn(`⚠️  fetchMissions failed (${apiBase}): ${reason}.`);
+        return { success: false, error: reason, missions: [] };
+    }
+}
+
 /**
  * Marks a mission as completed.
  * @param {string} missionId
@@ -281,6 +339,75 @@ function simpleHash(str) {
     return 'ph_' + Math.abs(hash).toString(36);
 }
 
+/**
+ * Crea una Task en Azure DevOps cuando se detecta un bug en el portal.
+ * Si la organización no tiene la integración configurada (HTTP 400) se registra
+ * sólo en modo DEBUG y NO interrumpe el flujo del test runner.
+ *
+ * @param {string} title       - Título de la tarea (generalmente la descripción corta del bug)
+ * @param {string} description - Descripción detallada del bug detectado
+ * @returns {Promise<{success: boolean, taskUrl?: string, error?: string}>}
+ */
+export async function createAdoTask(title, description) {
+    const apiBase = getEffectiveApiBase();
+    if (!apiBase) {
+        if (process.env.DEBUG) console.log(`[ADO] No hay ARCALITY_API_URL configurado. Omitiendo creación de Task en Azure DevOps.`);
+        return { success: false, error: 'no_api_url' };
+    }
+
+    const projectId = loadProjectId();
+    if (!projectId) {
+        if (process.env.DEBUG) console.log(`[ADO] No hay Project ID configurado. Omitiendo creación de Task en Azure DevOps.`);
+        return { success: false, error: 'no_project_id' };
+    }
+
+    const key = getEffectiveApiKey();
+    if (!key) {
+        if (process.env.DEBUG) console.log(`[ADO] No hay API key configurada. Omitiendo creación de Task en Azure DevOps.`);
+        return { success: false, error: 'no_api_key' };
+    }
+
+    try {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), 15000);
+
+        const res = await fetch(`${apiBase}/api/v1/integrations/azuredevops/task`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'x-api-key': key
+            },
+            body: JSON.stringify({ project_id: projectId, title, description }),
+            signal: controller.signal
+        });
+        clearTimeout(timeout);
+
+        if (res.status === 400) {
+            const data = await res.json().catch(() => ({}));
+            // La organización no tiene la integración de ADO configurada — no es un error crítico
+            if (data?.error === 'create_task_failed') {
+                if (process.env.DEBUG) console.log(`[ADO] Integración no configurada para esta organización: ${data.message}`);
+            } else {
+                console.warn(`⚠️ [ADO] Error al crear Task en Azure DevOps: ${data?.message || 'Bad Request'}`);
+            }
+            return { success: false, error: data?.message || 'create_task_failed' };
+        }
+
+        if (!res.ok) {
+            console.warn(`⚠️ [ADO] Error HTTP ${res.status} al crear Task en Azure DevOps.`);
+            return { success: false, error: `http_${res.status}` };
+        }
+
+        const data = await res.json();
+        console.log(`✅ [ADO] Task creada en Azure DevOps: ${data.task_url || '(sin URL)'}`);
+        return { success: true, taskUrl: data.task_url };
+    } catch (e) {
+        const reason = e?.name === 'AbortError' ? 'timeout (15s)' : (e?.message || 'unknown');
+        console.warn(`⚠️ [ADO] No se pudo crear la Task en Azure DevOps: ${reason}`);
+        return { success: false, error: reason };
+    }
+}
+
 /**
  * Obtiene el Token SAS y el path base para subir evidencias.
  * @param {string} missionId
@@ -309,7 +436,7 @@ export async function getEvidenceSasToken(missionId, projectId) {
             console.log(`[DEBUG] SAS Token API Failed: ${res.status} - ${txt}`);
             return null;
         }
-        
+
         const data = await res.json();
         return data;
     } catch (e) {