@arcadialdev/arcality 4.1.0 → 4.1.1

package/README.md

@@ -1,188 +1,128 @@
-<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
-```
-
-
-### 2. Initialize your project
-Run the setup wizard to connect your project and generate the configuration.
-
-```bash
-npx arcality init
-```
-
-### 3. Run your first mission
-```bash
-# Open interactive menu
-npx arcality
-
-# Or run directly (Ghost Mode)
-npx arcality run
-```
-
-
-### 📦 Updating Arcality
-Run the following to get the latest version:
-```bash
-npm update @arcadialdev/arcality
-```
-
-### ⚙️ Configuration (`arcality.config.json`)
-After initializing with `npx arcality init`, a config file is created in the project root. Edit it to set your project name, base URL, and authentication details. The CLI reads this file on every run, ensuring consistent environment variables.
-
-### QA Context Governance
-Arcality can load local business rules from `.arcality/qa-context.md` and governance metadata from `.arcality/qa-context.meta.json`.
-
-The effective precedence order is:
-
-1. Local `qa-context.md`
-2. Backend collective memory
-3. Base QA heuristics
+<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>
 
-If local business rules conflict with backend memory, Arcality now prioritizes the local file.
+<br>
 
-Example `.arcality/qa-context.meta.json`:
+<br>
 
-```json
-{
-  "version": "1.0.0",
-  "updated_by": "qa.owner@company.com",
-  "approved_by": "qa.lead@company.com",
-  "owner_team": "QA",
-  "effective_from": "2026-06-15",
-  "change_summary": "Initial governance metadata for customer-specific QA rules.",
-  "tags": ["business-rules", "ui-navigation"]
-}
-```
+**Arcality** is a QA agent for web applications that helps teams describe flows in natural language, execute them with resilience, and preserve successful runs as reusable missions with evidence that is easier to review.
 
-Governance enforcement modes:
+## What Arcality Gives You
 
-- `ARCALITY_QA_CONTEXT_GOVERNANCE=off`: disables governance checks
-- `ARCALITY_QA_CONTEXT_GOVERNANCE=warn`: reports warnings but does not block execution
-- `ARCALITY_QA_CONTEXT_GOVERNANCE=strict`: blocks execution when `qa-context.md` exists but governance metadata is missing or incomplete
+- Natural-language driven QA flows for real web applications
+- Reusable local mission files that help teams keep coverage organized
+- Visual evidence and execution summaries that are easier to share
+- Project-scoped configuration, context, and artifacts
+- Optional database corroboration for high-confidence validation
 
-In CI, Arcality defaults to `strict` governance mode unless you override `ARCALITY_QA_CONTEXT_GOVERNANCE`.
+---
 
+## Getting Started
 
----
-
-## 💻 CLI Commands Cheatsheet
-
-The Arcality flow is designed to be used globally or project-wide via `npx`. Below are all currently supported commands:
-
-| Command | Description | Internal Behavior |
-| :--- | :--- | :--- |
-| `npx arcality` | **Interactive Menu**<br/>Launches a visual menu in the terminal to guide the user. | Prompts for the Mission to execute. Ideal for new users who want a guided experience. |
-| `npx arcality init` | **Initial Configuration**<br/>Connects the current project to Arcadial. | Prompts for your API Key and Project ID, generates `arcality.config.json`, and validates the portal connection. |
-| `npx arcality generate --dry-run` | **Dynamic Mission Discovery**<br/>Inspects the target codebase and previews the routes/pages that can become generated missions. | Runs framework detection, route discovery, context-aware mission planning, and prints a dry-run summary without writing YAML files. |
-| `npx arcality generate --count 5` | **Generated Mission Writer**<br/>Creates YAML missions automatically from the discovered routes. | Generates validated Arcality YAML missions, deduplicates existing output, and stores cache metadata in `.arcality/cache/generate-state.json`. |
-| `npx arcality run` | **Mission Runner (Agent Mode)**<br/>Launches the QA Agent directly. | Skips the interactive menu, scans the _package.json_ ("Ghost Mode"), and unleashes the AI agent. Ideal for CI/CD. |
-| `npx arcality logs` | **Mission Logs**<br/>Shows the last 3 executed missions in a concise QA-friendly format. | Reads the local `.arcality/out` mission summaries and displays result, failure reason, last relevant steps, and report path. |
+### 1. Install in your project
 
-### Parallel collection execution
+```bash
+npm install @arcadialdev/arcality
+```
+
+### 2. Initialize your project
 
-When running a saved collection from the interactive CLI, Arcality can execute multiple missions at the same time. The default is `3` simultaneous missions and the maximum allowed value is `5`.
+```bash
+npx arcality init
+```
 
-Parallel execution opens multiple independent browser sessions. Arcality cannot validate the tested portal's internal session rules, user lock policies, shared test data constraints, or limits for multiple logins with the same account. If the portal does not support parallel sessions safely, run the collection sequentially with concurrency `1`.
+### 3. Run your first mission
 
-### `generate` command
+```bash
+# Open the interactive menu
+npx arcality
 
-`npx arcality generate` is the mission-generation entrypoint. It analyzes the current codebase, discovers supported routes, enriches them with route signals, and writes Arcality mission YAML files under the configured output directory.
+# Or launch the agent directly
+npx arcality run
+```
 
-Examples:
+### Update Arcality
 
 ```bash
-npx arcality generate --dry-run
-npx arcality generate --count 5
-npx arcality generate --page "/users,/settings" --count 4
-npx arcality generate --page "/checkout" --prompt "focus on validation and payment edge cases"
-npx arcality generate --output-dir ".arcality/generated-review"
-npx arcality generate --debug
+npm update @arcadialdev/arcality
 ```
 
-Current behavior:
+---
+
+## Local Project Setup
+
+Arcality stores its project configuration in `arcality.config.json` and keeps runtime artifacts under `.arcality/`.
 
-- Supports automatic discovery for `Next.js`, `React Router` object configs, `React Router` nested JSX routes, and filesystem fallbacks for simpler SPA layouts.
-- Detects route metadata such as dynamic params, example paths, and route families.
-- Applies optional customer guidance from `.arcality/qa-context.md` and governance metadata from `.arcality/qa-context.meta.json`.
-- Generates only the most useful route variants to reduce noise.
-- Validates every generated mission against the Arcality mission schema before writing files.
-- Deduplicates previously generated missions by mission identity.
+For existing projects, the interactive menu now separates:
+- `Editar configuracion del proyecto`: recalibrates the current local setup
+- `Reconectar backend / proyecto nuevo`: reruns the full onboarding flow
 
-Notes:
+This makes it easier to refine a project without rebuilding everything from zero.
 
-- `--prompt` is supported and refines the generated mission focus.
-- `--page` accepts route fragments or exact route values.
-- Generated missions are written under `<yamlOutputDir>/generated` by default.
-- Local cache metadata is stored in `.arcality/cache/generate-state.json`.
-- Regression coverage for this command is available through `npm.cmd run test:generate` on Windows or `npm run test:generate` where shell policy allows it.
+---
+
+## Database Corroboration
+
+Arcality can validate mission outcomes against PostgreSQL during local runs without placing secrets inside mission files.
 
-- Discovery and mission generation are covered by regression tests.
+Recommended approach:
+- keep connection data in `.env`
+- keep reusable validation queries in `.arcality/db-validations.yaml`
+- use MCP mode only when your team already has an approved PostgreSQL bridge
 
+The recalibration flow can help you:
+- register or update the connection profile
+- choose direct PostgreSQL or MCP mode
+- run a lightweight health check before leaving setup
 
 ---
-
-## 🛠️ 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 `npx 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>
+
+## QA Context
+
+Arcality can load local business rules from `.arcality/qa-context.md` and optional governance metadata from `.arcality/qa-context.meta.json`.
+
+Precedence order:
+1. Local QA context file
+2. Backend collective memory
+3. Base QA heuristics
+
+If your team wants stronger control, governance can be enforced in `off`, `warn`, or `strict` mode.
+
+---
+
+## CLI Commands
+
+| Command | Purpose |
+| :--- | :--- |
+| `npx arcality` | Open the interactive menu |
+| `npx arcality init` | Configure a project for first use |
+| `npx arcality run` | Launch the agent directly |
+| `npx arcality generate --dry-run` | Preview candidate missions |
+| `npx arcality generate --count 5` | Generate a limited mission batch |
+| `npx arcality logs` | Review recent mission summaries |
+
+### Parallel collections
+
+Arcality can execute multiple saved missions in parallel. Use this only when the target application safely supports concurrent sessions and shared test data will not collide.
+
+### Generate missions
+
+`npx arcality generate` helps teams bootstrap reusable mission files from the current project. It is meant to accelerate authoring, not replace QA judgment.
+
+---
+
+## Product Overview
+
+Arcality is designed to help QA teams move faster without depending on brittle hard-coded automation. It keeps configuration, local context, generated missions, and evidence close to the application under test so teams can evolve coverage in a practical way.
+
+---
+
+<div align="center">
+  <p>Built by the QA Intelligence team at <b>Arcadial</b>.</p>
+</div>

package/bin/arcality.mjs

@@ -12,22 +12,22 @@ 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;
-let isLogs = false;
-let isRunAll = false; // CI/CD mode: runs all missions from API headlessly
-let isGenerate = false;
+let isInit = false;
+let isSetup = false;
+let isLogs = false;
+let isRunAll = false; // CI/CD mode: runs all missions from API headlessly
+let isGenerate = 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 (arg === 'logs') isLogs = true;
-    if (arg === '--logs') isLogs = true;
-    if (arg === '--run-all') isRunAll = true;
-    if (arg === 'generate') isGenerate = true;
-});
+    if (arg === 'logs') isLogs = true;
+    if (arg === '--logs') isLogs = true;
+    if (arg === '--run-all') isRunAll = true;
+    if (arg === 'generate') isGenerate = true;
+});
 
 if (isLogs) {
     const logsScript = path.join(PACKAGE_ROOT, 'scripts', 'arcality-logs.mjs');
@@ -36,21 +36,21 @@ if (isLogs) {
         cwd: process.cwd(),
         env: { ...process.env, ARCALITY_ROOT: PACKAGE_ROOT }
     }).on('exit', code => process.exit(code || 0));
-} else 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 (isGenerate) {
-    const generateScript = path.join(PACKAGE_ROOT, 'scripts', 'generate.mjs');
-    spawn('node', [generateScript, ...rawArgs.filter(a => a !== 'generate')], {
-        stdio: 'inherit',
-        cwd: process.cwd(),
-        env: { ...process.env, ARCALITY_ROOT: PACKAGE_ROOT }
-    }).on('exit', code => process.exit(code || 0));
-} else if (isRunAll) {
+} else 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 (isGenerate) {
+    const generateScript = path.join(PACKAGE_ROOT, 'scripts', 'generate.mjs');
+    spawn('node', [generateScript, ...rawArgs.filter(a => a !== 'generate')], {
+        stdio: 'inherit',
+        cwd: process.cwd(),
+        env: { ...process.env, ARCALITY_ROOT: PACKAGE_ROOT }
+    }).on('exit', code => process.exit(code || 0));
+} else if (isRunAll) {
     // CI/CD HEADLESS MODE: Descarga y ejecuta todas las misiones del proyecto desde la API
     // Uso: arcality --run-all [--workers=4] [--tags=smoke,regression] [--project-id=xxx]
     const mainScript = path.join(PACKAGE_ROOT, 'scripts', 'gen-and-run.mjs');

package/package.json

@@ -1,75 +1,75 @@
-{
-  "name": "@arcadialdev/arcality",
-  "version": "4.1.0",
-  "description": "El primer ingeniero QA Autónomo integrado al CI/CD. Creado por Arcadial.",
-  "main": "index.js",
-  "scripts": {
-    "dev": "node scripts/gen-and-run.mjs",
-    "arcality": "node scripts/gen-and-run.mjs",
-    "test:generate": "node --test tests/generate/*.test.mjs",
-    "postinstall": "node scripts/postinstall.mjs",
-    "setup": "node scripts/setup.mjs",
-    "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": {
-    "arcality": "bin/arcality.mjs"
-  },
-  "files": [
-    "bin/",
-    "scripts/",
-    "src/",
-    "public/",
-    ".agent/",
-    ".agents/",
-    "tests/_helpers/agentic-runner.bundle.spec.js",
-    "tests/_helpers/ArcalityReporter.js",
-    "playwright.config.js",
-    "README.md"
-  ],
-  "publishConfig": {
-    "access": "public"
-  },
-  "repository": {
-    "type": "git",
-    "url": "https://dev.azure.com/arcadial/_git/ArcalityQA"
-  },
-  "keywords": [
-    "qa",
-    "testing",
-    "ai",
-    "playwright",
-    "autonomous",
-    "arcadial"
-  ],
-  "author": "Arcadial",
-  "license": "ISC",
-  "type": "commonjs",
-  "bugs": {
-    "url": "https://dev.azure.com/arcadial/_git/ArcalityQA"
-  },
-  "homepage": "https://dev.azure.com/arcadial/_git/ArcalityQA",
-  "devDependencies": {
-    "@types/figlet": "^1.7.0",
-    "@types/node": "^25.0.9",
-    "@types/prompts": "^2.4.9",
-    "esbuild": "^0.20.2",
-    "typescript": "^6.0.3"
-  },
-  "dependencies": {
-    "@azure/storage-blob": "^12.31.0",
-    "@clack/prompts": "^1.0.1",
-    "@inquirer/prompts": "^8.2.0",
-    "@playwright/test": "^1.57.0",
-    "axios": "^1.13.6",
-    "chalk": "^5.6.2",
-    "dotenv": "^17.2.3",
-    "figlet": "^1.9.4",
-    "js-yaml": "^4.1.1",
-    "mime-types": "^3.0.2",
-    "node-fetch": "^3.3.2",
-    "prompts": "^2.4.2",
-    "terminal-image": "^1.1.0",
-    "tsx": "^4.21.0"
-  }
-}
+{
+  "name": "@arcadialdev/arcality",
+  "version": "4.1.1",
+  "description": "El primer ingeniero QA Autónomo integrado al CI/CD. Creado por Arcadial.",
+  "main": "index.js",
+  "scripts": {
+    "dev": "node scripts/gen-and-run.mjs",
+    "arcality": "node scripts/gen-and-run.mjs",
+    "test:generate": "node --test tests/generate/*.test.mjs",
+    "postinstall": "node scripts/postinstall.mjs",
+    "setup": "node scripts/setup.mjs",
+    "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": {
+    "arcality": "bin/arcality.mjs"
+  },
+  "files": [
+    "bin/",
+    "scripts/",
+    "src/",
+    "public/",
+    ".agents/",
+    "tests/_helpers/agentic-runner.bundle.spec.js",
+    "tests/_helpers/ArcalityReporter.js",
+    "playwright.config.js",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://dev.azure.com/arcadial/_git/ArcalityQA"
+  },
+  "keywords": [
+    "qa",
+    "testing",
+    "ai",
+    "playwright",
+    "autonomous",
+    "arcadial"
+  ],
+  "author": "Arcadial",
+  "license": "ISC",
+  "type": "commonjs",
+  "bugs": {
+    "url": "https://dev.azure.com/arcadial/_git/ArcalityQA"
+  },
+  "homepage": "https://dev.azure.com/arcadial/_git/ArcalityQA",
+  "devDependencies": {
+    "@types/figlet": "^1.7.0",
+    "@types/node": "^25.0.9",
+    "@types/prompts": "^2.4.9",
+    "esbuild": "^0.20.2",
+    "typescript": "^6.0.3"
+  },
+  "dependencies": {
+    "@azure/storage-blob": "^12.31.0",
+    "@clack/prompts": "^1.0.1",
+    "@inquirer/prompts": "^8.2.0",
+    "@playwright/test": "^1.57.0",
+    "axios": "^1.13.6",
+    "chalk": "^5.6.2",
+    "dotenv": "^17.2.3",
+    "figlet": "^1.9.4",
+    "js-yaml": "^4.1.1",
+    "mime-types": "^3.0.2",
+    "node-fetch": "^3.3.2",
+    "pg": "^8.22.0",
+    "prompts": "^2.4.2",
+    "terminal-image": "^1.1.0",
+    "tsx": "^4.21.0"
+  }
+}