@arcadialdev/arcality 2.4.28 → 2.4.29

package/README.md

@@ -1,9 +1,9 @@
 <div align="center">
-  <img src="https://unpkg.com/@arcadialdev/arcality/public/logo-arcadial-blanco.png" width="120" alt="Arcality Logo" />
+  <img src="./public/logo-arcadial-blanco.png" width="120" alt="Arcality Logo" />
   <br>
   <h1>Arcality Engine</h1>
   <p><b>Autonomous AI-Powered E2E Web Testing Agent</b></p>
-
+  
   [![NPM Version](https://img.shields.io/npm/v/@arcadialdev/arcality?color=c084fc&label=NPM&style=for-the-badge)](https://www.npmjs.com/package/@arcadialdev/arcality)
 </div>
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arcadialdev/arcality",
-  "version": "2.4.28",
+  "version": "2.4.29",
   "description": "AI-powered QA testing tool — Autonomous web testing agent by Arcadial",
   "main": "index.js",
   "scripts": {
@@ -8,7 +8,7 @@
     "arcality": "node scripts/gen-and-run.mjs",
     "postinstall": "node scripts/postinstall.mjs",
     "setup": "node scripts/setup.mjs",
-    "build:runner": "npx esbuild tests/_helpers/agentic-runner.spec.ts --bundle --minify --platform=node --target=node18 --format=cjs --external:@playwright/test --external:chalk --external:dotenv --external:node-fetch --external:js-yaml --external:axios --external:crypto --external:fs --external:path --outfile=tests/_helpers/agentic-runner.bundle.spec.js",
+    "build:runner": "npx esbuild tests/_helpers/agentic-runner.spec.ts --bundle --platform=node --target=node18 --format=cjs --external:@playwright/test --external:chalk --external:dotenv --external:node-fetch --external:js-yaml --external:axios --external:crypto --external:fs --external:path --outfile=tests/_helpers/agentic-runner.bundle.spec.js",
     "prepublishOnly": "npm run build:runner"
   },
   "bin": {
@@ -17,11 +17,8 @@
   "files": [
     "bin/",
     "scripts/",
-    "src/configLoader.mjs",
-    "src/configManager.mjs",
-    "src/arcalityClient.mjs",
-    "tests/_helpers/agentic-runner.bundle.spec.js",
-    "tests/_helpers/ArcalityReporter.js",
+    "src/",
+    "tests/_helpers/",
     ".agents/",
     "public/",
     "playwright.config.js",

package/scripts/gen-and-run.mjs

@@ -428,10 +428,6 @@ async function main() {
     let firstRun = true;
     let globalReportProcess = null;
 
-    // Immutable flag: true when started from `arcality run` (--agent flag on CLI).
-    // Used to exit cleanly instead of showing the interactive menu on completion or errors.
-    const CLI_AGENT_MODE = initialAgentMode;
-
     setupEnvironment();
 
     while (true) {
@@ -632,10 +628,6 @@ async function main() {
                     'plan_expired': '💳 Your plan has expired'
                 };
                 note(chalk.red(errorMessages[validation.error] || `Error: ${validation.error}`), '❌ Authentication');
-                if (CLI_AGENT_MODE) {
-                    outro(chalk.red('❌ Authentication failed. Exiting.'));
-                    process.exit(1);
-                }
                 agentMode = false;
                 prompt = "";
                 skipMenu = false;
@@ -728,10 +720,6 @@ async function main() {
                     chalk.gray(`🔄 Resets: ${mission.resets_at ? new Date(mission.resets_at).toLocaleString() : 'tomorrow'}`),
                     '⚠️ Limit Reached'
                 );
-                if (CLI_AGENT_MODE) {
-                    outro(chalk.red('❌ Mission limit reached. Exiting.'));
-                    process.exit(1);
-                }
                 agentMode = false;
                 prompt = "";
                 skipMenu = false;
@@ -919,17 +907,16 @@ async function main() {
                     process.env.ARCALITY_API_KEY
                 );
 
-                // In CLI agent mode (arcality run), exit immediately — no interactive menu.
-                if (CLI_AGENT_MODE) {
-                    outro(chalk.cyan('✅ Mission finished! See you later.'));
-                    return;
-                }
-
                 await text({
                     message: 'Press Enter to return to menu...',
                     placeholder: 'Enter'
                 });
 
+                if (skipMenu) {
+                    outro(chalk.cyan('Mission finished! See you later.'));
+                    return;
+                }
+
                 agentMode = false;
                 prompt = "";
                 firstRun = false;

package/src/KnowledgeService.ts

@@ -0,0 +1,256 @@
+
+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 || 'https://arcalityqadev.arcadial.lat';
+        this.apiKey = process.env.ARCALITY_API_KEY || '';
+        this.projectId = process.env.ARCALITY_PROJECT_ID || null;
+    }
+
+    /**
+     * Fetch wrapper with a 10-second timeout to prevent hanging.
+     * All KnowledgeService calls are telemetry/secondary — they must NEVER block the agent.
+     */
+    private async fetchWithTimeout(url: string, options: RequestInit = {}, timeoutMs = 10000): Promise<Response> {
+        const controller = new AbortController();
+        const id = setTimeout(() => controller.abort(), timeoutMs);
+        try {
+            const res = await fetch(url, { ...options, signal: controller.signal });
+            clearTimeout(id);
+            return res;
+        } catch (err: any) {
+            clearTimeout(id);
+            throw err;
+        }
+    }
+
+    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 this.fetchWithTimeout(`${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 this.fetchWithTimeout(`${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 this.fetchWithTimeout(`${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;
+            const res = await this.fetchWithTimeout(
+                `${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');
+    }
+}

package/src/consoleBanner.ts

@@ -0,0 +1,32 @@
+import figlet from 'figlet';
+import chalk from 'chalk';
+import fs from 'fs';
+import path from 'path';
+import { intro, note } from '@clack/prompts';
+
+export function showBanner(): void {
+  const projectName = 'Arcality';
+  const subtitle = 'Powered by Arcadial';
+
+  let version = 'unknown';
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(process.cwd(), 'package.json'), 'utf8'));
+    version = pkg.version || 'unknown';
+  } catch { }
+
+  const logo = figlet.textSync(projectName, {
+    font: 'Standard',
+    horizontalLayout: 'default',
+    verticalLayout: 'default',
+  });
+
+  intro(chalk.cyanBright(logo));
+
+  note(
+    chalk.magentaBright(subtitle) + '\n' +
+    chalk.gray('─'.repeat(50)) + '\n' +
+    chalk.bold.white('📦 Version: ') + chalk.yellow(version) + '\n' +
+    chalk.bold.white('⚙️  Environment: ') + chalk.yellow(process.env.NODE_ENV ?? 'development'),
+    'System Information'
+  );
+}

package/src/envSetup.ts

@@ -0,0 +1,205 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import prompts from 'prompts';
+
+export class UserCancelledError extends Error {
+  constructor(message = 'Usuario canceló la operación') {
+    super(message);
+    this.name = 'UserCancelledError';
+  }
+}
+
+type EnvValues = {
+  BASE_URL?: string;
+  LOGIN_USER?: string;
+  LOGIN_PASSWORD?: string;
+  ARCALITY_PROJECT_ID?: string;
+};
+
+interface ArcalityConfigFile {
+  apiKey?: string;
+  projectId?: string;
+  project?: {
+    name?: string;
+    baseUrl?: string;
+    frameworkDetected?: string;
+  };
+  auth?: {
+    username?: string;
+    password?: string;
+  };
+  runtime?: {
+    yamlOutputDir?: string;
+    reuseSuccessfulYamls?: boolean;
+    singleConfigurationMode?: boolean;
+  };
+}
+
+function envPath(): string {
+  return path.join(process.cwd(), '.env');
+}
+
+function arcalityConfigPath(): string {
+  return path.join(process.cwd(), 'arcality.config');
+}
+
+function escapeEnvValue(v: string): string {
+  const needsQuotes = /[\s"'`\\]/.test(v);
+  const cleaned = v.replace(/"/g, '\\"');
+  return needsQuotes ? `"${cleaned}"` : cleaned;
+}
+
+function parseDotEnv(content: string): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const line of content.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+
+    const idx = trimmed.indexOf('=');
+    if (idx === -1) continue;
+
+    const k = trimmed.slice(0, idx).trim();
+    let v = trimmed.slice(idx + 1).trim();
+
+    if (
+      (v.startsWith('"') && v.endsWith('"')) ||
+      (v.startsWith("'") && v.endsWith("'"))
+    ) {
+      v = v.slice(1, -1);
+    }
+    out[k] = v;
+  }
+  return out;
+}
+
+export function readExistingEnv(): Record<string, string> {
+  const p = envPath();
+  if (!fs.existsSync(p)) return {};
+  return parseDotEnv(fs.readFileSync(p, 'utf8'));
+}
+
+/**
+ * Loads arcality.config if it exists.
+ */
+function loadArcalityConfig(): ArcalityConfigFile | null {
+  const p = arcalityConfigPath();
+  try {
+    if (!fs.existsSync(p)) return null;
+    let raw = fs.readFileSync(p, 'utf8');
+    if (raw.charCodeAt(0) === 0xFEFF) raw = raw.slice(1);
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+function writeEnv(values: EnvValues): void {
+  const existing = readExistingEnv();
+  const merged = { ...existing, ...values };
+
+  const lines = [
+    '# Auto-generado por Arcality testRunner',
+    `BASE_URL=${escapeEnvValue(merged.BASE_URL ?? '')}`,
+    `LOGIN_USER=${escapeEnvValue(merged.LOGIN_USER ?? '')}`,
+    `LOGIN_PASSWORD=${escapeEnvValue(merged.LOGIN_PASSWORD ?? '')}`,
+  ];
+
+  if (merged.ARCALITY_PROJECT_ID) {
+    lines.push(`ARCALITY_PROJECT_ID=${escapeEnvValue(merged.ARCALITY_PROJECT_ID)}`);
+  }
+  lines.push('');
+
+  fs.writeFileSync(envPath(), lines.join('\n'), 'utf8');
+}
+
+function isValidBaseUrl(url: string): boolean {
+  try {
+    const u = new URL(url);
+    return u.protocol === 'http:' || u.protocol === 'https:';
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Ensures environment is configured for test execution.
+ * In single-config mode, reads from arcality.config first.
+ * Falls back to .env prompts for backward compatibility.
+ */
+export async function ensureEnvInteractive(): Promise<void> {
+  // Try to load arcality.config first
+  const arcalityConfig = loadArcalityConfig();
+
+  if (arcalityConfig) {
+    // Inject config values into process.env for the current session
+    if (arcalityConfig.project?.baseUrl) {
+      process.env.BASE_URL = arcalityConfig.project.baseUrl;
+    }
+    if (arcalityConfig.auth?.username) {
+      process.env.LOGIN_USER = arcalityConfig.auth.username;
+    }
+    if (arcalityConfig.auth?.password) {
+      process.env.LOGIN_PASSWORD = arcalityConfig.auth.password;
+    }
+    if (arcalityConfig.projectId) {
+      process.env.ARCALITY_PROJECT_ID = arcalityConfig.projectId;
+    }
+    if (arcalityConfig.apiKey) {
+      process.env.ARCALITY_API_KEY = arcalityConfig.apiKey;
+    }
+
+    // All good — no prompts needed
+    return;
+  }
+
+  // Fallback: prompt for missing .env values (legacy mode)
+  const existing = readExistingEnv();
+  const questions: prompts.PromptObject[] = [];
+
+  if (!existing.BASE_URL) {
+    questions.push({
+      type: 'text',
+      name: 'BASE_URL',
+      message: 'Base URL (ej: http://localhost:3000):',
+      initial: 'http://localhost:3000',
+      validate: (v: string) =>
+        isValidBaseUrl(v) ? true : 'URL inválida (usa http/https)',
+    });
+  }
+
+  if (!existing.LOGIN_USER) {
+    questions.push({
+      type: 'text',
+      name: 'LOGIN_USER',
+      message: 'Usuario:',
+      validate: (v: string) =>
+        v?.trim().length ? true : 'Usuario requerido',
+    });
+  }
+
+  if (!existing.LOGIN_PASSWORD) {
+    questions.push({
+      type: 'password',
+      name: 'LOGIN_PASSWORD',
+      message: 'Contraseña:',
+      validate: (v: string) =>
+        v?.length ? true : 'Contraseña requerida',
+    });
+  }
+
+  if (questions.length > 0) {
+    const res = await prompts(questions, {
+      onCancel: () => {
+        throw new UserCancelledError();
+      },
+    });
+
+    const merged: EnvValues = {
+      BASE_URL: res.BASE_URL ?? existing.BASE_URL,
+      LOGIN_USER: res.LOGIN_USER ?? existing.LOGIN_USER,
+      LOGIN_PASSWORD: res.LOGIN_PASSWORD ?? existing.LOGIN_PASSWORD,
+    };
+    writeEnv(merged);
+    console.log('Archivo .env actualizado.');
+  }
+}

package/src/index.ts

@@ -0,0 +1,25 @@
+import 'dotenv/config';
+import { showBanner } from './consoleBanner';
+import { promptAndRunPlaywrightTests } from './testRunner';
+import { KnowledgeService } from './KnowledgeService';
+import { ArcalityClient } from './arcalityClient';
+import { loadConfig } from './configLoader';
+
+async function main() {
+  showBanner();
+
+  const config = loadConfig();
+  const arcalityClient = new ArcalityClient(config.ARCALITY_API_KEY);
+  const knowledgeService = KnowledgeService.getInstance();
+
+  await promptAndRunPlaywrightTests(arcalityClient, knowledgeService);
+}
+
+main().catch((err) => {
+  // Normal user cancellation is not an error
+  if (err instanceof Error && err.name === 'UserCancelledError') {
+    process.exit(130);
+  }
+  console.error(err);
+  process.exit(1);
+});

package/src/projectInspector.ts

@@ -0,0 +1,42 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+export interface ProjectContext {
+    name: string;
+    version: string;
+    framework: 'next' | 'vite' | 'cra' | 'unknown';
+    scripts: string[];
+    dependencies: string[];
+}
+
+export function getProjectContext(projectRoot: string): ProjectContext {
+    const pkgPath = path.join(projectRoot, 'package.json');
+    const context: ProjectContext = {
+        name: 'Arcality Project',
+        version: '1.0.0',
+        framework: 'unknown',
+        scripts: [],
+        dependencies: []
+    };
+
+    if (!fs.existsSync(pkgPath)) return context;
+
+    try {
+        const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+        context.name = pkg.name || context.name;
+        context.version = pkg.version || context.version;
+
+        const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+        context.dependencies = Object.keys(deps);
+        context.scripts = pkg.scripts ? Object.keys(pkg.scripts) : [];
+
+        if (deps['next']) context.framework = 'next';
+        else if (deps['vite']) context.framework = 'vite';
+        else if (deps['react-scripts']) context.framework = 'cra';
+
+    } catch (e) {
+        // Ignorar errores de lectura
+    }
+
+    return context;
+}