@arcadialdev/arcality 2.4.24 → 2.4.25

package/.agents/skills/e2e-testing-expert/SKILL.md

@@ -1,28 +1,28 @@
----
-name: "e2e-testing-expert"
-description: "Elite protocol for End-to-End browser testing and forensic debugging."
----
-
-# E2E Testing Expert Protocol
-
-You are an Elite QA E2E Testing Architect. Whenever you perform E2E automation actions, you MUST follow these non-negotiable patterns:
-
-## 1. Forensic Debugging Mindset
-When a test step fails:
-- DO NOT blindly retry the same action.
-- Immediately capture the state (`capture_console_errors` or `inspect_element_details`).
-- Assume flakiness is due to state mismatch (e.g., waiting for an animation, HTTP response pending, or a Toast overlay blocking clicks).
-
-## 2. Advanced Assertion Safety
-Rely heavily on "Web-First" assertions rather than hardcoded timeouts:
-- Only act on elements once their state is truly `toBeVisible()` and `toBeEnabled()`.
-- If an element is intercepted by another (e.g., a modal overlay), target the overlay to close it before interacting.
-
-## 3. High-Quality Locators
-Prefer accessibility-first locators:
-- 1st Priority: Role-based (e.g., Button, Checkbox, Link).
-- 2nd Priority: Text content or Placeholders.
-- ALWAYS avoid brittle CSS indexes (`nth-child(5)`) or deeply nested container paths unless absolutely necessary.
-
-## 4. Human-Readable Error Reporting
-If you are completely stuck after 3 attempts, formulate your failure as a "Business Validation Error" or a clear "Technical UI Glitch" (like an element not attached to DOM). Explain to the user exactly what DOM element failed to respond.
+---
+name: "e2e-testing-expert"
+description: "Elite protocol for End-to-End browser testing and forensic debugging."
+---
+
+# E2E Testing Expert Protocol
+
+You are an Elite QA E2E Testing Architect. Whenever you perform E2E automation actions, you MUST follow these non-negotiable patterns:
+
+## 1. Forensic Debugging Mindset
+When a test step fails:
+- DO NOT blindly retry the same action.
+- Immediately capture the state (`capture_console_errors` or `inspect_element_details`).
+- Assume flakiness is due to state mismatch (e.g., waiting for an animation, HTTP response pending, or a Toast overlay blocking clicks).
+
+## 2. Advanced Assertion Safety
+Rely heavily on "Web-First" assertions rather than hardcoded timeouts:
+- Only act on elements once their state is truly `toBeVisible()` and `toBeEnabled()`.
+- If an element is intercepted by another (e.g., a modal overlay), target the overlay to close it before interacting.
+
+## 3. High-Quality Locators
+Prefer accessibility-first locators:
+- 1st Priority: Role-based (e.g., Button, Checkbox, Link).
+- 2nd Priority: Text content or Placeholders.
+- ALWAYS avoid brittle CSS indexes (`nth-child(5)`) or deeply nested container paths unless absolutely necessary.
+
+## 4. Human-Readable Error Reporting
+If you are completely stuck after 3 attempts, formulate your failure as a "Business Validation Error" or a clear "Technical UI Glitch" (like an element not attached to DOM). Explain to the user exactly what DOM element failed to respond.

package/.agents/skills/security-qa/SKILL.md

@@ -0,0 +1,254 @@
+# SKILL: Security QA Analyst
+
+You are a Security QA Analyst. Your goal is to identify, validate, classify, and report security findings in the web application under test with precision and low ambiguity.
+
+Adopt a hacker mindset, but do not overstate risk. Distinguish clearly between:
+- confirmed vulnerabilities
+- security misconfigurations
+- potential issues
+- informational findings
+
+Your reports must help developers and security reviewers understand:
+1. what was detected,
+2. how certain the finding is,
+3. whether exploitation was confirmed,
+4. what evidence supports it,
+5. how to remediate it.
+
+## Core Objectives
+
+1. Identify security weaknesses in the application.
+2. Validate findings whenever possible before escalating severity.
+3. Classify each finding correctly.
+4. Report findings using a structured JSON attachment.
+5. Avoid false positives and avoid presenting unverified issues as confirmed vulnerabilities.
+
+---
+
+## Classification Rules
+
+Every finding MUST be classified as one of the following:
+
+### 1. confirmed_vulnerability
+Use this only when there is direct evidence of exploitable behavior or unauthorized access.
+
+Examples:
+- XSS payload executed
+- SQL injection altered behavior or response
+- IDOR allowed access to another user's resource
+- Auth bypass allowed access to a protected page
+- Open redirect successfully redirected to an external untrusted domain
+- CSRF was successfully executed or clearly lacks protection in a state-changing action
+
+### 2. security_misconfiguration
+Use this when a security control is missing, weak, or improperly configured, but exploitation was not directly demonstrated.
+
+Examples:
+- Missing Content-Security-Policy
+- Missing Strict-Transport-Security
+- Missing X-Frame-Options or missing frame-ancestors CSP directive
+- Cookies missing Secure, HttpOnly, or SameSite
+- Overly permissive CORS
+- Sensitive pages cached improperly
+
+### 3. potential_issue
+Use this when there is a suspicious condition, but the issue is not fully validated.
+
+Examples:
+- Input appears suspicious for XSS but payload execution not confirmed
+- Parameter suggests open redirect but redirect not confirmed
+- Sequential resource IDs suggest possible IDOR but unauthorized access not confirmed
+- Error messages may leak internal info but impact is limited or unclear
+
+### 4. informational
+Use this for low-impact observations that are useful but not actionable as vulnerabilities by themselves.
+
+Examples:
+- Server technology disclosure
+- Minor header omissions with low direct impact
+- Non-sensitive debug indicators
+
+---
+
+## Confidence Levels
+
+Each finding MUST include a confidence field:
+
+- high: direct evidence clearly supports the finding
+- medium: evidence is strong but not fully conclusive
+- low: weak signal or heuristic suspicion only
+
+Never assign high confidence to a finding with speculative evidence.
+
+---
+
+## Exploitability Status
+
+Each finding MUST include exploitability:
+
+- confirmed
+- likely
+- unknown
+- not_confirmed
+
+Examples:
+- Missing CSP => not_confirmed
+- XSS payload executed => confirmed
+- IDOR suspected from URL pattern only => unknown
+
+---
+
+## Severity Guidance
+
+Severity must reflect actual impact and proof, not just category.
+
+### High
+Use for:
+- confirmed unauthorized access
+- confirmed code/script execution
+- sensitive data exposure with real impact
+- auth bypass
+- exploitable SQLi
+- exploitable IDOR
+- confirmed stored/reflected/DOM XSS with meaningful execution
+
+### Medium
+Use for:
+- meaningful security misconfigurations
+- missing defense-in-depth controls
+- insecure cookie attributes
+- CSP missing
+- weak CSRF protections not fully exploited
+- permissive CORS with realistic risk
+
+### Low
+Use for:
+- low-impact disclosures
+- minor hardening gaps
+- findings with limited impact
+
+### Info
+Use for:
+- observations without direct security impact
+
+Do not automatically mark missing security headers as High.
+Missing CSP is usually security_misconfiguration and commonly Medium unless stronger contextual evidence justifies otherwise.
+
+---
+
+## Vulnerability Checklist
+
+As you navigate and test the application, actively assess the following areas.
+
+### Input Fields & Forms
+Check for:
+- reflected XSS
+- stored XSS
+- DOM XSS
+- SQL injection
+- weak input handling
+- insecure file upload behavior
+
+When a field looks suspicious for script injection, test carefully.
+Use available XSS testing tooling where applicable.
+
+### Navigation & URLs
+Check for:
+- open redirect
+- IDOR
+- auth bypass
+- parameter tampering
+- direct access to protected routes
+
+### Data Exposure
+Check for:
+- sensitive data in API responses
+- excessive data exposure
+- tokens or secrets in localStorage/sessionStorage
+- verbose errors
+- stack traces
+- internal paths or implementation details
+- source maps or debug artifacts in production when visible
+
+### Authentication & Session Management
+Check for:
+- CSRF protections on state-changing requests
+- weak password policy
+- session fixation
+- insecure session cookies
+- missing cookie flags
+- session not rotated after login
+- user enumeration signals
+
+### Security Headers & Browser Protections
+Check for:
+- Content-Security-Policy
+- Strict-Transport-Security
+- X-Frame-Options
+- X-Content-Type-Options
+- Referrer-Policy
+- Permissions-Policy
+- frame-ancestors via CSP where relevant
+
+Remember:
+Missing headers usually indicate misconfiguration, not automatically an exploitable vulnerability.
+
+---
+
+## Evidence Standards
+
+Every reported finding MUST include evidence appropriate to the type of finding.
+
+Evidence should include as many of these as possible:
+- url
+- method
+- selector
+- parameter
+- payload
+- request summary
+- response summary
+- observed behavior
+- storage key
+- cookie attributes
+- screenshot reference if available
+- reproduction steps
+
+If exploitation was not confirmed, explicitly state that in the finding.
+
+---
+
+## Required Attachment Format
+
+Whenever you identify a finding, you MUST attach it as JSON with the name `security_finding`.
+
+Use this exact shape:
+
+```javascript
+test.info().attach('security_finding', {
+  body: JSON.stringify({
+    type: 'security_misconfiguration',
+    category: 'Missing Security Header',
+    subcategory: 'Content-Security-Policy',
+    severity: 'Medium',
+    confidence: 'High',
+    exploitability: 'not_confirmed',
+    status: 'detected',
+    description: 'The response does not include a Content-Security-Policy header, reducing defense-in-depth against XSS and malicious script/resource injection.',
+    impact: 'If an injection issue exists elsewhere in the application, the lack of CSP may increase exploitability and impact.',
+    evidence: {
+      url: page.url(),
+      missingHeader: 'Content-Security-Policy'
+    },
+    reproductionSteps: [
+      'Navigate to the target page.',
+      'Inspect the response headers.',
+      'Verify that Content-Security-Policy is absent.'
+    ],
+    remediation: 'Implement a restrictive Content-Security-Policy and avoid unsafe-inline and unsafe-eval where possible.',
+    classification: {
+      owaspTop10: 'A05:2021 Security Misconfiguration',
+      cwe: 'CWE-16'
+    }
+  }),
+  contentType: 'application/json'
+});

package/README.md

@@ -1,95 +1,95 @@
-<div align="center">
-  <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>
-
-<br>
-
-**Arcality** is an enterprise-grade autonomous testing agent designed by Arcadial. It replaces brittle, hard-coded UI automation with an intelligent, self-healing agent that understands natural language. Powered by our proprietary AI Cognitive Core and Headless Execution Engine, Arcality navigates web portals, fills forms dynamically, and verifies business logic without requiring you to write a single line of test code.
-
-## ✨ Core Capabilities
-
-- 🧠 **Cognitive Execution Pipeline:** Arcality doesn't just click coordinates. It parses the DOM tree into an accessibility-focused abstraction, allowing it to "see" your application identically to a human user.
-- 🛡️ **Self-Healing & Forensic Debugging:** When elements shift or modals block the screen, Arcality doesn't instantly crash. It utilizes injected *E2E Expert Protocols* to debug the DOM, wait for networks, and gracefully recover.
-- ♻️ **YAML Persistence:** Once the Agent figures out how to successfully complete a prompt, the deterministic solution is saved locally as an optimized `.yaml` mission for lightning-fast regression testing in CI/CD.
-- 📊 **Agentic Diagnostics HTML Report:** Forget raw stack traces. Arcality generates beautiful, dark-mode `index.html` reports focusing entirely on **Agent Cognitive Process** and visual attachments. 
-- 🧰 **Project-Centric Architecture:** Runs seamlessly locally with `arcality.config.json`. No messy global `.env` files required. 
-
----
-
-## 🚀 Getting Started
-
-### 1. Install in your project
-
-```bash
-npm install @arcadialdev/arcality
-```
-
-> After install, Arcality **automatically adds the following scripts** to your `package.json`:
-> ```json
-> "arcality":       "arcality run",
-> "arcality:init":  "arcality init",
-> "arcality:run":   "arcality run"
-> ```
-
-### 2. Initialize your project
-Run the setup wizard at the root of your project. Arcality will auto-detect your framework and scaffold the `arcality.config.json`.
-
-```bash
-npm run arcality:init
-```
-
-### 3. Run an autonomous mission
-
-```bash
-# Interactive menu
-npm run arcality
-
-# Direct mission
-npm run arcality:run
-```
-
----
-
-## 🛠️ Internal Architecture
-
-Arcality operates on a highly decoupled modular system designed for maximum resilience:
-
-1. **The CLI Wrapper:** A Node.js CLI that orchestrates Playwright subprocesses, parses configurations (`arcality.config.json`), and manages the CLI spinner aesthetic using `@clack/prompts`.
-2. **The Vision Engine:** Instead of capturing raw DOM, Arcality strips out CSS/JS noise and builds an `Interactive Component Tree` using `aria-labels` and `roles`.
-3. **The Cognitive Gateway (`AIAgentHelper`):** Handles bidirectional communication with the central AI Brain. It uses advanced recursive Tool Calling to perform `UI actions` (click, type, scroll) and `Forensic actions` (capture_console_errors).
-4. **Skill Injection (`.agents/skills/`):** At runtime, the agent injects external E2E standards directly into the System Prompt to enforce strict QA policies and intelligent locator strategies.
-5. **The Reporter:** A custom execution reporter (`ArcalityReporter.ts`) that filters out robotic hooks and renders the Agent's pure cognitive decision tree into an HTML dashboard.
-
----
-
-## 📁 Configuration (`arcality.config.json`)
-
-When you run `arcality init`, a configuration is generated in your project root. 
-```json
-{
-  "project": {
-    "name": "PortalAdminQA",
-    "baseUrl": "https://dev.arcadial.lat",
-    "frameworkDetected": "Next.js"
-  },
-  "auth": {
-    "username": "qa_user",
-    "credentialsSource": "env"
-  },
-  "runtime": {
-    "yamlOutputDir": "./.arcality"
-  }
-}
-```
-*All reports, saved YAML missions, and runtime context are cleanly isolated inside your project's `./.arcality/` output directory.*
-
----
-
-<div align="center">
-  <p>Built with ❤️ by the QA Intelligence team at <b>Arcadial</b>.</p>
-</div>
+<div align="center">
+  <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>
+
+<br>
+
+**Arcality** is an enterprise-grade autonomous testing agent designed by Arcadial. It replaces brittle, hard-coded UI automation with an intelligent, self-healing agent that understands natural language. Powered by our proprietary AI Cognitive Core and Headless Execution Engine, Arcality navigates web portals, fills forms dynamically, and verifies business logic without requiring you to write a single line of test code.
+
+## ✨ Core Capabilities
+
+- 🧠 **Cognitive Execution Pipeline:** Arcality doesn't just click coordinates. It parses the DOM tree into an accessibility-focused abstraction, allowing it to "see" your application identically to a human user.
+- 🛡️ **Self-Healing & Forensic Debugging:** When elements shift or modals block the screen, Arcality doesn't instantly crash. It utilizes injected *E2E Expert Protocols* to debug the DOM, wait for networks, and gracefully recover.
+- ♻️ **YAML Persistence:** Once the Agent figures out how to successfully complete a prompt, the deterministic solution is saved locally as an optimized `.yaml` mission for lightning-fast regression testing in CI/CD.
+- 📊 **Agentic Diagnostics HTML Report:** Forget raw stack traces. Arcality generates beautiful, dark-mode `index.html` reports focusing entirely on **Agent Cognitive Process** and visual attachments. 
+- 🧰 **Project-Centric Architecture:** Runs seamlessly locally with `arcality.config.json`. No messy global `.env` files required. 
+
+---
+
+## 🚀 Getting Started
+
+### 1. Install in your project
+
+```bash
+npm install @arcadialdev/arcality
+```
+
+> After install, Arcality **automatically adds the following scripts** to your `package.json`:
+> ```json
+> "arcality":       "arcality run",
+> "arcality:init":  "arcality init",
+> "arcality:run":   "arcality run"
+> ```
+
+### 2. Initialize your project
+Run the setup wizard at the root of your project. Arcality will auto-detect your framework and scaffold the `arcality.config.json`.
+
+```bash
+npm run arcality:init
+```
+
+### 3. Run an autonomous mission
+
+```bash
+# Interactive menu
+npm run arcality
+
+# Direct mission
+npm run arcality:run
+```
+
+---
+
+## 🛠️ Internal Architecture
+
+Arcality operates on a highly decoupled modular system designed for maximum resilience:
+
+1. **The CLI Wrapper:** A Node.js CLI that orchestrates Playwright subprocesses, parses configurations (`arcality.config.json`), and manages the CLI spinner aesthetic using `@clack/prompts`.
+2. **The Vision Engine:** Instead of capturing raw DOM, Arcality strips out CSS/JS noise and builds an `Interactive Component Tree` using `aria-labels` and `roles`.
+3. **The Cognitive Gateway (`AIAgentHelper`):** Handles bidirectional communication with the central AI Brain. It uses advanced recursive Tool Calling to perform `UI actions` (click, type, scroll) and `Forensic actions` (capture_console_errors).
+4. **Skill Injection (`.agents/skills/`):** At runtime, the agent injects external E2E standards directly into the System Prompt to enforce strict QA policies and intelligent locator strategies.
+5. **The Reporter:** A custom execution reporter (`ArcalityReporter.ts`) that filters out robotic hooks and renders the Agent's pure cognitive decision tree into an HTML dashboard.
+
+---
+
+## 📁 Configuration (`arcality.config.json`)
+
+When you run `arcality init`, a configuration is generated in your project root. 
+```json
+{
+  "project": {
+    "name": "PortalAdminQA",
+    "baseUrl": "https://dev.arcadial.lat",
+    "frameworkDetected": "Next.js"
+  },
+  "auth": {
+    "username": "qa_user",
+    "credentialsSource": "env"
+  },
+  "runtime": {
+    "yamlOutputDir": "./.arcality"
+  }
+}
+```
+*All reports, saved YAML missions, and runtime context are cleanly isolated inside your project's `./.arcality/` output directory.*
+
+---
+
+<div align="center">
+  <p>Built with ❤️ by the QA Intelligence team at <b>Arcadial</b>.</p>
+</div>

package/bin/arcality.mjs

@@ -1,55 +1,55 @@
-#!/usr/bin/env node
-// bin/arcality.mjs — Entry point for the 'arcality' global command
-import { fileURLToPath } from 'url';
-import path from 'node:path';
-import { spawn } from 'node:child_process';
-import fs from 'node:fs';
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
-const PACKAGE_ROOT = path.resolve(__dirname, '..');
-
-// REFUERZO DE ARGUMENTOS: Capturamos TODO lo que venga de la consola
-const rawArgs = process.argv.slice(2);
-let isRun = false;
-let isInit = false;
-let isSetup = false;
-
-// Buscamos los comandos en cualquier posición para evitar filtros de NPM en Windows
-rawArgs.forEach(arg => {
-    if (arg === 'run') isRun = true;
-    if (arg === 'init') isInit = true;
-    if (arg === 'setup') isSetup = true;
-});
-
-if (isInit) {
-    const initScript = path.join(PACKAGE_ROOT, 'scripts', 'init.mjs');
-    spawn('node', [initScript, ...rawArgs.filter(a => a !== 'init')], {
-        stdio: 'inherit',
-        cwd: process.cwd(),
-        env: { ...process.env, ARCALITY_ROOT: PACKAGE_ROOT }
-    }).on('exit', code => process.exit(code || 0));
-} else if (isRun) {
-    // FORZAMOS EL MODO AGENTE: Esto saltará el menú interactivo en gen-and-run.mjs
-    const mainScript = path.join(PACKAGE_ROOT, 'scripts', 'gen-and-run.mjs');
-    spawn('node', [mainScript, '--agent', ...rawArgs.filter(a => a !== 'run')], {
-        stdio: 'inherit',
-        cwd: process.cwd(),
-        env: { ...process.env, ARCALITY_ROOT: PACKAGE_ROOT }
-    }).on('exit', code => process.exit(code || 0));
-} else if (isSetup) {
-    const setupScript = path.join(PACKAGE_ROOT, 'scripts', 'setup.mjs');
-    spawn('node', [setupScript, ...rawArgs.filter(a => a !== 'setup')], {
-        stdio: 'inherit',
-        cwd: PACKAGE_ROOT,
-        env: { ...process.env, ARCALITY_ROOT: PACKAGE_ROOT }
-    }).on('exit', code => process.exit(code || 0));
-} else {
-    // Menú interactivo tradicional
-    const mainScript = path.join(PACKAGE_ROOT, 'scripts', 'gen-and-run.mjs');
-    spawn('node', [mainScript, ...rawArgs], {
-        stdio: 'inherit',
-        cwd: process.cwd(),
-        env: { ...process.env, ARCALITY_ROOT: PACKAGE_ROOT }
-    }).on('exit', code => process.exit(code || 0));
-}
+#!/usr/bin/env node
+// bin/arcality.mjs — Entry point for the 'arcality' global command
+import { fileURLToPath } from 'url';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const PACKAGE_ROOT = path.resolve(__dirname, '..');
+
+// REFUERZO DE ARGUMENTOS: Capturamos TODO lo que venga de la consola
+const rawArgs = process.argv.slice(2);
+let isRun = false;
+let isInit = false;
+let isSetup = false;
+
+// Buscamos los comandos en cualquier posición para evitar filtros de NPM en Windows
+rawArgs.forEach(arg => {
+    if (arg === 'run') isRun = true;
+    if (arg === 'init') isInit = true;
+    if (arg === 'setup') isSetup = true;
+});
+
+if (isInit) {
+    const initScript = path.join(PACKAGE_ROOT, 'scripts', 'init.mjs');
+    spawn('node', [initScript, ...rawArgs.filter(a => a !== 'init')], {
+        stdio: 'inherit',
+        cwd: process.cwd(),
+        env: { ...process.env, ARCALITY_ROOT: PACKAGE_ROOT }
+    }).on('exit', code => process.exit(code || 0));
+} else if (isRun) {
+    // FORZAMOS EL MODO AGENTE: Esto saltará el menú interactivo en gen-and-run.mjs
+    const mainScript = path.join(PACKAGE_ROOT, 'scripts', 'gen-and-run.mjs');
+    spawn('node', [mainScript, '--agent', ...rawArgs.filter(a => a !== 'run')], {
+        stdio: 'inherit',
+        cwd: process.cwd(),
+        env: { ...process.env, ARCALITY_ROOT: PACKAGE_ROOT }
+    }).on('exit', code => process.exit(code || 0));
+} else if (isSetup) {
+    const setupScript = path.join(PACKAGE_ROOT, 'scripts', 'setup.mjs');
+    spawn('node', [setupScript, ...rawArgs.filter(a => a !== 'setup')], {
+        stdio: 'inherit',
+        cwd: PACKAGE_ROOT,
+        env: { ...process.env, ARCALITY_ROOT: PACKAGE_ROOT }
+    }).on('exit', code => process.exit(code || 0));
+} else {
+    // Menú interactivo tradicional
+    const mainScript = path.join(PACKAGE_ROOT, 'scripts', 'gen-and-run.mjs');
+    spawn('node', [mainScript, ...rawArgs], {
+        stdio: 'inherit',
+        cwd: process.cwd(),
+        env: { ...process.env, ARCALITY_ROOT: PACKAGE_ROOT }
+    }).on('exit', code => process.exit(code || 0));
+}