@arcadialdev/arcality 3.0.4 → 4.0.0

package/README.md

@@ -53,11 +53,44 @@ Run the following to get the latest version:
 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.
-
-
----
+### ⚙️ 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
+
+If local business rules conflict with backend memory, Arcality now prioritizes the local file.
+
+Example `.arcality/qa-context.meta.json`:
+
+```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"]
+}
+```
+
+Governance enforcement modes:
+
+- `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
+
+In CI, Arcality defaults to `strict` governance mode unless you override `ARCALITY_QA_CONTEXT_GOVERNANCE`.
+
+
+---
 
 ## 💻 CLI Commands Cheatsheet
 
@@ -65,8 +98,10 @@ The Arcality flow is designed to be used globally or project-wide via `npx`. Bel
 
 | 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` | **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. |
 
@@ -76,6 +111,40 @@ When running a saved collection from the interactive CLI, Arcality can execute m
 
 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`.
 
+### `generate` command
+
+`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.
+
+Examples:
+
+```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
+```
+
+Current behavior:
+
+- 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.
+
+Notes:
+
+- `--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.
+
+- Discovery and mission generation are covered by regression tests.
+
 
 ---
 

package/bin/arcality.mjs

@@ -12,36 +12,45 @@ 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 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 === '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 (isLogs) {
-    const logsScript = path.join(PACKAGE_ROOT, 'scripts', 'arcality-logs.mjs');
-    spawn('node', [logsScript, ...rawArgs.filter(a => a !== 'logs' && a !== '--logs')], {
+    const logsScript = path.join(PACKAGE_ROOT, 'scripts', 'arcality-logs.mjs');
+    spawn('node', [logsScript, ...rawArgs.filter(a => a !== 'logs' && a !== '--logs')], {
         stdio: 'inherit',
         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 (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,11 +1,12 @@
 {
   "name": "@arcadialdev/arcality",
-  "version": "3.0.4",
+  "version": "4.0.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",

package/playwright.config.js

@@ -1,38 +1,39 @@
 // playwright.config.js
 'use strict';
 const { defineConfig, devices } = require('@playwright/test');
+const os = require('os');
 const path = require('path');
 
 // ── Dynamic reporter: JUnit is added when running in CI (Azure DevOps, GitHub Actions) ──
 // The JUnit XML file enables native test result publishing in your pipeline dashboard.
 // In local/interactive mode, the JUnit reporter is skipped — only Arcality's HTML reporter runs.
-const reportsDir = process.env.REPORTS_DIR || path.join(__dirname, 'tests-report');
-const playwrightOutputDir = process.env.PLAYWRIGHT_OUTPUT_DIR || path.join(reportsDir, '..', 'playwright-output');
-const isCI = process.env.CI === 'true';
-
-const reporters = [
-    ['line'],
-    [path.join(__dirname, 'tests', '_helpers', 'ArcalityReporter.js'), { outputDir: reportsDir }],
-];
-
-if (isCI) {
-    reporters.push(['junit', { outputFile: path.join(reportsDir, 'results.xml') }]);
-}
+const reportsDir = process.env.REPORTS_DIR || path.join(os.tmpdir(), 'arcality', 'reports');
+const playwrightOutputDir = process.env.PLAYWRIGHT_OUTPUT_DIR || path.join(os.tmpdir(), 'arcality', 'playwright-output');
+const isCI = process.env.CI === 'true';
 
-module.exports = defineConfig({
-  testDir: path.join(__dirname, 'tests', '_helpers'),
-  testMatch: ['agentic-runner.bundle.spec.js'],
-  reporter: reporters,
-  outputDir: playwrightOutputDir,
-  use: {
+const reporters = [
+    ['line'],
+    [path.join(__dirname, 'tests', '_helpers', 'ArcalityReporter.js'), { outputDir: reportsDir }],
+];
+
+if (isCI) {
+    reporters.push(['junit', { outputFile: path.join(reportsDir, 'results.xml') }]);
+}
+
+module.exports = defineConfig({
+  testDir: path.join(__dirname, 'tests', '_helpers'),
+  testMatch: ['agentic-runner.bundle.spec.js'],
+  reporter: reporters,
+  outputDir: playwrightOutputDir,
+  use: {
     // ── Dynamic BASE_URL ──
     // Priority: CLI --base-url flag → arcality.config baseUrl → BASE_URL env → default
     // This allows pipelines to inject the target environment dynamically:
     //   arcality --run-all --base-url=https://staging.myapp.com
     baseURL: process.env.BASE_URL || 'http://localhost:3000',
-    video: 'on',
-    screenshot: 'on',
-    trace: 'on',
+    video: 'retain-on-failure',
+    screenshot: 'only-on-failure',
+    trace: 'retain-on-failure',
     colorScheme: 'dark',
     // In CI: headless is enforced by Playwright automatically when CI=true
     headless: isCI ? true : undefined,