@veraxhq/verax 0.4.0 → 0.4.5

package/README.md

@@ -1,276 +1,305 @@
-# 🛡️ VERAX
+# VERAX v0.4.5
 
-A forensic observation engine for real user outcomes
+Catch buttons and forms that do nothing.
+No AI. No guessing. Just evidence.
 
-VERAX observes and reports gaps between what your code explicitly promises and what users can actually observe.
+Silent failure detection for public user flows (pre-authentication only)
 
-Silent user failures don’t crash your site.
-They don’t throw errors.
-They simply lose users quietly.
+The Problem
 
-VERAX exists to surface those gaps — with evidence, not guesses.
+Silent user failures don’t crash your app.
+They quietly make users leave.
 
-🤔 What is VERAX?
+Common examples:
 
-A silent user failure happens when your code clearly implies that something should happen —
-but from the user’s point of view, nothing meaningful does.
+A button looks clickable but does nothing
 
-Concrete examples:
+A form submits with no confirmation
 
-A button click that should navigate… but doesn’t.
+A link is clicked but navigation never happens
 
-A form submission that triggers an API call… but shows no feedback.
+Validation triggers, but feedback isn’t shown
 
-A state update that runs in code… but never reaches the UI.
+Your logs are clean.
+Your tests pass.
+Monitoring shows nothing.
 
-These issues are frustrating for users and notoriously hard for teams to notice.
+From the user’s perspective, the promise was broken.
 
-VERAX reads your source code to understand what is promised, then opens your site in a real browser and experiences it like a user.
-When expectations and reality don’t align, VERAX reports the gap clearly and honestly.
+VERAX exists to reveal these gaps — with evidence.
 
-VERAX does not guess intent.
-It only reports observations backed by explicit code promises.
+How VERAX Works
 
-🧠 Clarification: “Silent failure”
+VERAX compares what your code promises with what users actually experience.
 
-In VERAX, a silent failure is not a judgment about correctness.
+Learn Promises
+Parse source code to extract user-visible promises:
+navigation, forms, and feedback signals.
 
-It means:
+Observe Behavior
+Execute real interactions in a real browser
+(clicks, submits, typing).
 
-For a promised interaction (for example, a click expected to navigate or save),
-no observable, user-visible effect could be verified
-(no URL change, no network request, no feedback).
+Detect Gaps
+Compare promised outcomes vs observed results.
 
-This does not mean your code is wrong.
-It means the observation produced no verifiable effect for the promise being evaluated.
+Report Findings
+Produce evidence-backed findings:
+screenshots, DOM diffs, traces.
 
-✅ What VERAX does (today)
+Result: You see exactly where users get stuck — with reproducible proof.
 
-🔍 Observes and reports gaps between code promises and user-visible outcomes
-(by comparing code-derived expectations with real browser behavior)
+2-Minute Quick Start
+Option 1: Try the built-in demo
+git clone https://github.com/odavlstudio/verax.git
+cd verax
+npm install
 
-🧠 Extracts expectations from source code using static analysis:
+npm run demo         # Terminal 1: demo at http://127.0.0.1:4000
+npm run verax:demo   # Terminal 2: run VERAX against demo
 
-Navigation from HTML links, React Router, Vue Router, and Next.js routes
+Artifacts are written to:
 
-Network actions from fetch / axios calls with static URLs
+.verax/runs/<runId>/
 
-State mutations from React useState, Redux, Vuex, Pinia, Zustand set operations
+Option 2: Run on your own site
+npm install -g @veraxhq/verax
+verax run --url https://your-site.test --src /path/to/repo
 
-🖱️ Observes websites like a real user using Playwright
-(clicks, forms, navigation, scrolling)
+Important: LIMITED mode
 
-📊 Assigns confidence levels (HIGH / MEDIUM / LOW) based on evidence strength and coverage
+VERAX needs source code to extract promises.
 
-🧾 Provides concrete evidence for every reported discrepancy:
+If source code is not detected:
 
-Screenshots
+VERAX runs in LIMITED mode
 
-Network activity
+Result is always INCOMPLETE (exit code 30)
 
-Console logs
+This prevents false “green” CI signals
 
-DOM and state changes
+verax run --url https://your-site.test --src ./   # Full detection
+verax run --url https://your-site.test           # LIMITED mode only
 
-💻 Runs as a CLI tool via `verax run` (and inspects results with `verax inspect`)
+Inspect results
+verax inspect .verax/runs/<runId>
 
-🧱 Supports real-world projects:
+Key artifacts:
 
-**Fully verified (production-ready):**
-- Static HTML sites
-- React SPAs (with react-router-dom)
+verax-summary.md — Human-readable summary
 
-**Supported (learn-only / partial observation):**
-- Next.js (App Router & Pages Router)
-- Vue.js (with Vue Router)
-- Angular
-- SvelteKit
+summary.json — Verdict, coverage, counts
 
-🔐 Protects privacy by automatically redacting secrets and sensitive data
+findings.json — Evidence-backed findings
 
-🚫 What VERAX does NOT do
+evidence/ — Screenshots, DOM diffs, traces
 
-❌ Does not guess intent — no heuristics, no assumptions
+Understanding Results
+✅ SUCCESS (exit code 0)
 
-❌ Does not support dynamic routes (e.g. /user/${id} is intentionally skipped)
+All observable public flows were tested.
+No silent failures were detected within scope.
 
-❌ Does not replace QA or tests — it complements them
+Does NOT mean:
 
-❌ Does not monitor production traffic
+The app is bug-free
 
-❌ Does not work for every framework
+All edge cases are covered
 
-❌ Does not detect every bug — only gaps backed by explicit code promises
+Means:
 
-❌ Does not use AI — all results are deterministic and explainable
+No silent failures were observed
 
-🔄 How VERAX works (high-level)
+Evidence guarantees were satisfied
 
-VERAX runs three phases automatically:
+RESULT SUCCESS
+REASON Scanned 12 interactions; 12 completed; 0 silent failures
+ACTION Continue with other testing
 
-1) **Learn**
-Analyze source code to derive explicit, proven expectations
-(routes, static network actions, state changes).
+🔍 FINDINGS (exit code 20)
 
-2) **Observe**
-Open the site in a real browser and execute user interactions safely,
-recording what actually happens.
+One or more silent failures were confirmed with evidence.
 
-3) **Detect**
-Compare code-derived expectations with observed outcomes and report:
-- Discrepancies
-- Coverage gaps
-- Unknowns
-- Safety blocks
+Each finding includes:
 
-All with evidence.
+The promised behavior (from code)
 
-📦 Installation
+What actually happened (from browser)
 
-Requirements: Node.js 18+
+Before/after screenshots
 
-From npm:
+DOM and network evidence
 
-npm install -g @veraxhq/verax
+RESULT FINDINGS
+REASON 1 silent failure: “Sign up” button does nothing
+ACTION Fix the issue and re-run VERAX
 
-From source:
+⚠️ INCOMPLETE (exit code 30)
 
-git clone <repository-url>
-cd verax
-npm install
-npm link
+The run could not be trusted.
 
-## Commands
+Common reasons:
 
-VERAX provides these CLI commands:
+Source code not detected (LIMITED mode)
 
-- `verax` — Interactive mode (detects URL or prompts for it)
-- `verax run --url <url> [--src <path>] [--out <path>]` — Non-interactive CI mode (strict, explicit)
-- `verax inspect <runPath>` — Inspect results from a previous run
-- `verax doctor [--json]` — Verify environment (Node, Playwright, Chromium binary)
-- `verax --version` — Show CLI version
-- `verax --help` — Show help text
+Coverage below threshold
 
-## Examples
+Observation timeout
 
-Run a non-interactive scan (ideal for CI):
+Authenticated flows (out of scope)
 
-```bash
-verax run --url http://localhost:3000 --src . --out .verax
-```
+INCOMPLETE is not safe. Do not ignore it.
 
-Run interactive mode (default auto-detection):
+RESULT INCOMPLETE
+REASON Source code not detected (limited runtime-only mode)
+ACTION Provide --src <path>
 
-```bash
-verax
-```
+🚫 USAGE_ERROR (exit code 64)
 
-Check environment readiness:
+Invalid CLI usage:
 
-```bash
-verax doctor --json
-```
+Missing --url
 
-Inspect a previous run:
+Unknown flags
 
-```bash
-verax inspect .verax/runs/2026-01-11T12-34-56Z_abc123
-```
+Invalid --min-coverage
 
-📁 Output (CI-friendly)
+🔴 INVARIANT_VIOLATION (exit code 50)
 
-Run a scan:
+Internal error or artifact corruption
+(always investigate).
 
-```bash
-verax run --url http://localhost:3000 --src . --out .verax
-```
+Detection Scope
+✅ What VERAX Detects (Guaranteed)
 
-Artifacts are written to:
+Navigation
+
+Link clicks → route / URL changes
+
+Forms
+
+Submissions with user-visible feedback
+
+Validation messages
+
+Feedback signals
+
+aria-live
 
-`.verax/runs/<runId>/`
+role="alert" / role="status"
 
-Including:
+Stable text nodes
 
-- `summary.json` — overall observation summary with digest counts
-- `findings.json` — reported discrepancies with evidence
-- `learn.json` — code-derived expectations
-- `observe.json` — browser observations and outcomes
-- `evidence/` — screenshots and logs
+Attributes: disabled, aria-invalid, data-loading
 
-🚦 Exit codes (tool-only semantics)
+Observable outcomes
 
-Exit codes reflect tool execution status only.
-They do not represent site quality or correctness and must not be used as a pass/fail gate without explicit user logic.
+DOM changes
 
-0 — VERAX executed successfully (regardless of findings, gaps, or confidence)
+Network activity correlated to actions
 
-2 — Tool crashed or failed internally
+Navigation events
 
-64 — Invalid CLI usage (missing args, invalid flags)
+❌ Out of Scope (By Design)
 
-65 — Invalid input data (e.g. malformed JSON, unreadable manifest)
+Visual-only changes (spinners, colors, animations)
+→ Use visual regression tools
 
-📊 Reading results (observer-first)
+Ambiguous ARIA attributes (aria-expanded, etc.)
 
-Each reported discrepancy includes:
+Transient flashes < 100ms
 
-Promise context: navigation, network action, state change, feedback
+Authenticated flows
 
-Outcome classification: silent failure, coverage gap, unproven interaction, safety block, informational
+Backend-dependent dynamic routes
 
-Evidence: screenshots, network artifacts, console logs, trace references
+CLI Reference
+verax run
+verax run --url <url> [options]
 
-Confidence: coverage ratio and silence impact
+Options
 
-Confidence (observer truth)
+--url <url> (required)
 
-Confidence reflects the quality and completeness of observation,
-not the quality or correctness of the site.
+--src <path> — Source directory
 
-HIGH (≥80) — strong evidence and coverage; observations are reliable
+--out <path> — Output directory (default: .verax)
 
-MEDIUM (60–79) — likely discrepancy with some ambiguity
+--min-coverage <0.0-1.0> — Default: 0.50 first run, 0.90 after
 
-LOW (<60) — weak or partial evidence; interpret cautiously
+--force-post-auth — EXPERIMENTAL (always INCOMPLETE)
 
-🧭 When VERAX is a good fit
+--timeout <ms>
 
-SaaS signup and pricing flows
+--json
 
-React and Next.js projects
+--debug
 
-CI pipelines that need UX reality checks
+verax inspect
+verax inspect <runPath>
 
-Teams that value evidence over assumptions
+verax doctor
+verax doctor [--json]
+
+Checks Node.js, Playwright, and write permissions.
+
+Guarantees & Limitations
+Guarantees
+
+Read-only
+
+Deterministic
+
+Evidence-backed
+
+Conservative (uncertainty → INCOMPLETE)
+
+Limitations
+
+Pre-auth only
+
+Public flows only
+
+Not a test framework
+
+Not runtime monitoring
+
+CI/CD Usage
+verax run --url https://staging.example.com --src ./
+case $? in
+  0)  echo "✓ No silent failures"; exit 0 ;;
+  20) echo "✗ Silent failures detected"; exit 1 ;;
+  30) echo "⚠️ Incomplete coverage"; exit 1 ;;
+  *)  echo "✗ VERAX error"; exit 1 ;;
+esac
+
+Installation
+npm install -g @veraxhq/verax
 
-🚫 When VERAX is NOT a good fit
+Requirements
 
-Internal admin dashboards
+Node.js 18+
 
-Authentication-heavy systems
+Playwright (auto-installed)
 
-Apps built around highly dynamic routing
+Supported Frameworks
 
-Unsupported frameworks
+Full
 
-Teams expecting a full QA replacement
+React
 
-🧪 Project status
+Next.js
 
-VERAX is a production-grade CLI tool in active development.
-It is designed for early adopters and technical teams.
+Static HTML
 
-VERAX is not a SaaS product.
-It runs locally or in CI. There is no hosted service.
+Partial
 
-⚠ Important
+Vue 3
 
-VERAX does not certify correctness.
-Zero findings do not mean a site is safe.
+Angular
 
-VERAX exists to prevent false certainty, not to grant confidence.
-Use the Decision Snapshot and evidence to make a human judgment.
+SvelteKit
 
-📄 License
+License
 
-MIT
+MIT © VERAX

package/bin/verax.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 
 /**
  * VERAX CLI Shim
@@ -9,3 +9,7 @@ import('../src/cli/entry.js').catch((error) => {
   console.error(`Failed to load CLI: ${error.message}`);
   process.exit(2);
 });
+
+
+
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@veraxhq/verax",
-  "version": "0.4.0",
+  "version": "0.4.5",
   "description": "Public Flow Sanity Guard — Trust-Locked, Deterministic, CI-Safe.",
   "keywords": [
     "public-flows",
@@ -15,11 +15,11 @@
   "license": "MIT",
   "type": "module",
   "bin": {
-    "verax": "bin/verax.js"
+    "verax": "./bin/verax.js"
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/odavlstudio/verax.git"
+    "url": "https://github.com/odavlstudio/verax.git"
   },
   "bugs": {
     "url": "https://github.com/odavlstudio/verax/issues"
@@ -33,10 +33,17 @@
   ],
   "scripts": {
     "test": "node test/infrastructure/test-runner-wrapper.js",
+    "test:integration": "cross-env VERAX_TEST_INTEGRATION=1 node test/infrastructure/test-runner-wrapper.js",
+    "test:all": "npm test && npm run test:integration",
     "test:pack": "node test/infrastructure/test-pack.js",
     "verify-release": "node scripts/verify-release.js",
+    "prepublishOnly": "node scripts/prepublish-check.js",
     "lint": "eslint . --max-warnings 0",
-    "typecheck": "tsc -p tsconfig.json --noEmit"
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "clean": "node -e \"const fs = require('fs'); const path = require('path'); const dirs = ['.verax', 'tmp'].map(d => path.join(__dirname, d)); dirs.forEach(dir => { if (fs.existsSync(dir)) { fs.rmSync(dir, { recursive: true, force: true }); console.log('Cleaned:', dir); } });\"",
+    "demo": "cross-env VERAX_FIXTURE_DIR=./demos/hello-verax VERAX_FIXTURE_PORT=4000 node scripts/fixture-server.js",
+    "verax:demo": "cross-env VERAX_FIXTURE_DIR=./demos/hello-verax VERAX_FIXTURE_PORT=4000 node bin/verax.js run --url http://127.0.0.1:4000 --src demos/hello-verax --out .verax/demo --min-coverage 0.6",
+    "postpack": "node -e \"if (process.env.VERAX_SKIP_POSTPACK_CLEANUP !== '1') { const fs = require('fs'); const glob = require('glob'); glob.sync('*.tgz').forEach(f => { fs.unlinkSync(f); console.log('Auto-removed pack artifact:', f); }); } else { console.log('Postpack cleanup skipped (test mode)'); }\""
   },
   "dependencies": {
     "@babel/parser": "^7.28.5",
@@ -45,7 +52,8 @@
     "inquirer": "^9.2.15",
     "node-html-parser": "^7.0.1",
     "playwright": "^1.40.0",
-    "typescript": "^5.9.3"
+    "typescript": "^5.9.3",
+    "yaml": "^2.8.2"
   },
   "optionalDependencies": {
     "pngjs": "^7.0.0"
@@ -56,6 +64,7 @@
   "devDependencies": {
     "@reduxjs/toolkit": "^2.11.2",
     "@types/node": "^18.0.0",
+    "cross-env": "^7.0.3",
     "eslint": "^8.57.0",
     "next": "^16.1.1",
     "react": "^19.2.3",