laxy-verify 1.1.22 → 1.1.24

package/README.md

@@ -1,123 +1,156 @@
 # laxy-verify
 
-A frontend verification CLI that catches build breaks, regressions, and client-visible issues before you ship.
+`laxy-verify` is a deployment blocker gate for frontend apps.
 
-`laxy-verify` runs production build checks, Lighthouse, tiered verify E2E, and plan-gated verification for Free, Pro, and Pro+ accounts.
-It is built around three simple questions:
+**Free**: Run verification manually on any project.  
+**Pro**: GitHub Actions auto-runs it on every PR + Slack/Discord alerts when things break.
 
-- Free: "Any critical issues right now?"
-- Pro: "Ready to show a client?"
-- Pro+: "Ready for production?"
+## Quick start
+
+Run it on a frontend app:
 
 ```bash
-npx laxy-verify --init --run
+cd your-project
 npx laxy-verify .
-npx laxy-verify . --plan-override pro
+```
+
+Generate config plus GitHub Actions workflow:
+
+```bash
+npx laxy-verify --init
+```
+
+That creates:
+
+- `.laxy.yml`
+- `.github/workflows/laxy-verify.yml`
+
+Log in to unlock Pro features:
+
+```bash
 npx laxy-verify login
 npx laxy-verify whoami
-npx laxy-verify --help
 ```
 
-What you get from one run:
+For CI, set `LAXY_TOKEN` instead of interactive login:
+
+```yaml
+env:
+  LAXY_TOKEN: ${{ secrets.LAXY_TOKEN }}
+```
+
+## Why laxy-verify?
+
+Most teams already have some mix of:
+
+- `npm run build`
+- Lighthouse
+- Playwright or smoke checks
+- CI status rules
+
+The gap is not "can these tools exist together?" The gap is "who turns that pile of output into a safe merge or release decision?"
+
+`laxy-verify` gives you:
+
+- one command instead of a custom build plus audit plus smoke-check script stack
+- one result file instead of scattered logs
+- one blocker-first decision instead of "build passed, but do we actually trust this release?"
+- **Pro**: GitHub Actions auto-run + Slack/Discord alerts so you never miss a failure
+
+This is most useful if you ship frontend apps and want a practical gate before:
+
+- merge
+- client review
+- QA handoff
+- production release
+
+## The failures it is meant to catch
+
+Use `laxy-verify` when you want to catch things like:
 
+- the production build passes locally but fails in CI
+- the app opens, but a key button or form flow is broken
+- desktop looks fine, but a mobile CTA is pushed out of view
+- Lighthouse looks acceptable, but the user-visible path is still not safe to ship
+- a PR needs a clear hold reason instead of a vague "something failed"
+
+## What it actually checks
+
+A standard run includes:
+
+- production build success
+- Lighthouse thresholds (3 runs for stable evidence)
+- E2E scenarios for user-visible flows
+- multi-viewport checks (desktop, tablet, mobile)
+- blocker-aware reporting and release decisions
+
+With a logged-in account, additional checks run:
+
+- security audit
+- visual diff evidence
+- stability pass (second E2E run)
+
+## What you get from one run
+
+- a release decision such as `quick-pass`, `client-ready`, `release-ready`, `hold`, or `investigate`
 - a verification grade: `Gold`, `Silver`, `Bronze`, or `Unverified`
-- a decision-oriented verdict such as `client-ready`, `release-ready`, `hold`, or `investigate`
-- `.laxy-result.json` for automation
-- `laxy-verify-report.md` on paid plans for human review and AI handoff
+- `.laxy-result.json` for CI and automation
+- `laxy-verify-report.md` for human review and AI handoff
 
-## Quick Start
+Grades still exist, but they are not the main point. The main point is whether the run found blockers you should stop on.
 
-### 1. Run it on a frontend app
+## Quick start
+
+Run it on a frontend app:
 
 ```bash
 cd your-project
 npx laxy-verify .
 ```
 
-This runs the default verification flow in the current app directory.
-
-### 2. Generate config and CI workflow
+Generate config plus CI workflow:
 
 ```bash
 npx laxy-verify --init
 ```
 
-This creates:
+That creates:
 
 - `.laxy.yml`
 - `.github/workflows/laxy-verify.yml`
 
-### 3. Commit the workflow
-
-Once committed, each PR gets a verification run, grade output, and optional GitHub reporting.
-
-### 4. Unlock paid plan features
+Log in to unlock paid plan features:
 
 ```bash
 npx laxy-verify login
 npx laxy-verify whoami
 ```
 
-For CI, set `LAXY_TOKEN` instead of using interactive login.
+For CI, set `LAXY_TOKEN` instead of interactive login:
 
 ```yaml
 env:
   LAXY_TOKEN: ${{ secrets.LAXY_TOKEN }}
 ```
 
-## What It Checks
-
-- production build success
-- Lighthouse thresholds
-- verify E2E scenarios for real user flows
-- Pro+ viewport and visual regression evidence
-- plan-aware verdicts for local runs and CI
-
-## Verification Tiers
-
-| Plan | Question it answers |
-|------|---------------------|
-| Free | Any critical issues right now? |
-| Pro | Ready to show a client? |
-| Pro+ | Ready for production? |
-
-## Grades
-
-| Grade | Meaning |
-|-------|---------|
-| Gold | Build passed + E2E passed + Lighthouse passed + Pro+ viewport evidence passed |
-| Silver | Build passed + E2E passed |
-| Bronze | Build passed |
-| Unverified | Build failed |
-
-## Plan Differences
-
-| Feature | Free | Pro | Pro+ |
-|---------|------|-----|------|
-| Build verification | Yes | Yes | Yes |
-| Lighthouse | 1 run | 3 runs | 3 runs |
-| Verify E2E | Smoke checks | Client-facing flow checks | Client-facing flow checks + release evidence |
-| Detailed report view | No | Yes | Yes |
-| `laxy-verify-report.md` export | No | Yes | Yes |
-| Multi-viewport verification | No | No | Yes |
-| Visual diff | No | No | Yes |
-| Failure analysis signals | No | No | Yes |
+## Example workflow
 
-Free tells you whether the app is basically standing.
-Pro tells you whether the app is strong enough to call client-ready.
-Pro+ adds the extra evidence needed for a real release-ready call.
+1. Run `npx laxy-verify .` locally before opening or merging a PR.
+2. Fix broken builds, broken flows, and visible regressions.
+3. Commit `.laxy.yml`.
+4. Run `npx laxy-verify --init`.
+5. Let the GitHub Action apply the same gate on every PR.
 
-## Sample Output
+## Example output
 
 ```text
-Plan: Pro+
+Decision: release-ready
 Grade: Gold
-Verdict: release-ready
 
 Passed:
 - production build
 - Lighthouse thresholds
-- core E2E flows
+- core user flows
 - desktop, tablet, and mobile viewport checks
 
 Artifacts:
@@ -125,19 +158,46 @@ Artifacts:
 - laxy-verify-report.md
 ```
 
-## Configuration
+## The decision it helps you make
 
-All fields are optional in `.laxy.yml`.
+`laxy-verify` answers a delivery decision, not just a score:
+
+- Would this break for real users right now?
+- What would block a client demo or QA handoff?
+- Is there enough evidence to merge or release with confidence?
+
+Log in to unlock deeper checks (security audit, visual diff, stability pass).
+
+## Grades
+
+| Grade | Meaning |
+|---|---|
+| Gold | Build passed, E2E passed, Lighthouse passed, and release-level evidence passed |
+| Silver | Build passed and E2E passed |
+| Bronze | Build passed |
+| Unverified | Build failed |
+
+Default Lighthouse thresholds:
+
+- Performance `>= 70`
+- Accessibility `>= 85`
+- SEO `>= 80`
+- Best Practices `>= 80`
+
+## Config
+
+All fields in `.laxy.yml` are optional.
 
 ```yaml
-framework: "auto"
+framework: auto
 build_command: ""
 dev_command: ""
-package_manager: "auto"
+package_manager: auto
 port: 3000
 build_timeout: 300
 dev_timeout: 60
 lighthouse_runs: 1
+fail_on: bronze
 
 thresholds:
   performance: 70
@@ -145,16 +205,21 @@ thresholds:
   seo: 80
   best_practices: 80
 
-fail_on: "bronze"
+crawl: false
+max_crawl_depth: 3
+max_crawl_pages: 10
+browsers:
+  - chromium
 ```
 
-Typical cases:
+Useful adjustments:
 
-- raise `fail_on` to `silver` or `gold` in CI when you want stricter gates
-- set `framework`, `build_command`, or `dev_command` if auto-detection is not enough
-- increase `lighthouse_runs` when you want more stable performance evidence
+- raise `fail_on` in CI when you want stricter gates
+- set `build_command` or `dev_command` if auto-detection is not enough
+- increase `lighthouse_runs` for more stable performance evidence
+- point the CLI at the actual app directory in a monorepo
 
-## CLI Options
+## CLI
 
 ```text
 npx laxy-verify [project-dir]
@@ -165,7 +230,7 @@ Options:
   --config <path>
   --fail-on unverified|bronze|silver|gold
   --skip-lighthouse
-  --plan-override free|pro|pro_plus
+  --plan-override free|pro|team
   --badge
   --init
   --multi-viewport
@@ -177,87 +242,64 @@ Subcommands:
   whoami
 ```
 
-`--plan-override` is for downgrade testing only.
-Example: if your account is Pro+, you can run `--plan-override pro` or `--plan-override free` to verify the lower-tier behavior without changing your subscription.
-It will reject upgrades above your real entitlement.
-
-## Result Files
-
-Each run writes `.laxy-result.json`.
-
-Paid plans also write a readable markdown summary to `laxy-verify-report.md`.
-
-- `Pro`: client-ready delivery report
-- `Pro+`: release-readiness report with viewport and visual evidence
-
-Exit behavior follows the verification verdict, not just the legacy grade.
-
-- `build-failed` -> exit 1
-- `hold` -> exit 1
-- `Pro+ investigate` -> exit 1
-- plain lower-tier pass states can still exit 0
-
-```json
-{
-  "grade": "Gold",
-  "timestamp": "2026-04-09T09:00:00Z",
-  "build": { "success": true, "durationMs": 12000, "errors": [] },
-  "e2e": { "passed": 5, "failed": 0, "total": 5, "results": [] },
-  "lighthouse": { "performance": 82, "accessibility": 94, "seo": 90, "bestPractices": 92, "runs": 3 },
-  "multiViewport": {
-    "allPassed": true,
-    "summary": "Desktop, tablet, and mobile checks passed."
-  },
-  "visualDiff": {
-    "verdict": "pass",
-    "differencePercentage": 0
-  },
-  "verification": {
-    "tier": "pro_plus",
-    "report": { "verdict": "release-ready" }
-  },
-  "exitCode": 0,
-  "_plan": "pro_plus"
-}
-```
+`--plan-override` is for downgrade testing only. It can simulate lower tiers, but it will not let you exceed your real entitlement.
+
+## Result files
+
+Every run writes `.laxy-result.json`.
 
-### `laxy-verify-report.md`
+When the run finds something worth reviewing, it also writes `laxy-verify-report.md`.
 
-For Pro and Pro+ runs, the markdown report is designed to be easy to read and easy to paste into an AI coding tool.
+Typical use:
+
+- `.laxy-result.json` for CI parsing and machine decisions
+- `laxy-verify-report.md` for human review, PR discussion, or AI-assisted fixes
+
+The markdown report is designed to be readable and easy to paste into coding tools.
 
 It includes:
 
-- the main decision in plain English
+- the main stop-or-ship decision in plain English
 - what passed
 - blockers and warnings
 - exact verification evidence
-- failed E2E scenarios
-- a `Copy For AI` section you can paste directly into Codex, Cursor, Claude, or ChatGPT
+- failed scenarios
+- a `Copy For AI` section
+
+## What this is good at
+
+Use `laxy-verify` when you want:
+
+- a merge or release gate for frontend apps
+- one repeatable command for build plus audit plus visible-flow verification
+- a decision that non-authors can understand
+- JSON output for automation without building your own wrapper
 
-## Environment Notes
+## What this is not
 
-- Best on current LTS Node releases. `Node 20.18+` is recommended.
-- Monorepos should point `laxy-verify` at the actual app directory.
-- `playwright` is optional. The CLI can run without it.
-- Pro+ viewport and visual checks increase runtime.
+`laxy-verify` is not trying to replace:
 
-## Regression Fixtures
+- your full Playwright suite
+- deep visual QA by designers
+- production observability
+- manual exploratory testing
 
-The repo also includes dedicated regression fixtures under `.qa-regression-fixtures/`.
-They intentionally break build, navigation, coverage, performance, viewport behavior, and visual stability so the verifier can be tested against known failure modes.
+It is a pre-merge and pre-release verification layer, not your entire quality system.
 
 ## Limitations
 
-- Monorepos require targeting the app subdirectory explicitly.
-- Dev-server-based Lighthouse can differ from production hosting.
-- Pro+ visual diff and viewport checks increase runtime.
-- Local verification is most stable on current LTS Node releases.
+- monorepos should target the real app subdirectory
+- dev-server-based Lighthouse is not identical to production hosting
+- visual diff and viewport checks increase runtime
+- best stability is on current LTS Node releases
+
+## Requirements
+
+- Node `>=20.18.0 <25`
+- a frontend app with a runnable build flow
+- optional: `playwright` if your project already uses it
 
 ## Links
 
 - GitHub: https://github.com/SUNgm24/Laxy/tree/main/laxy-verify
 - Issues: https://github.com/SUNgm24/Laxy/issues
-
-## License
-
-MIT

package/dist/audit/broken-links.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Broken-links audit.
+ * Uses the crawl result to find all internal links, then validates each
+ * with an HTTP HEAD/GET request. Links that return 4xx/5xx or timeout are
+ * reported as blockers.
+ */
+import { type CrawlResult } from "../crawler.js";
+export interface BrokenLink {
+    url: string;
+    path: string;
+    status: number;
+    statusText: string;
+    severity: "critical" | "high";
+}
+export interface BrokenLinksResult {
+    brokenLinks: BrokenLink[];
+    checkedCount: number;
+    hasBrokenLinks: boolean;
+    summary: string;
+}
+export declare function auditBrokenLinks(crawlResult: CrawlResult, baseUrl: string, abortSignal?: AbortSignal): Promise<BrokenLinksResult>;

package/dist/audit/broken-links.js

@@ -0,0 +1,86 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.auditBrokenLinks = auditBrokenLinks;
+const TIMEOUT_MS = 5000;
+const VALID_OK_STATUS = [200, 201, 202, 203, 204, 301, 302, 303, 307, 308];
+function isSuccessStatus(n) {
+    return VALID_OK_STATUS.includes(n);
+}
+async function auditBrokenLinks(crawlResult, baseUrl, abortSignal) {
+    const origin = new URL(baseUrl).origin;
+    const allUrls = [];
+    for (const page of crawlResult.pages) {
+        for (const href of page.internalLinks) {
+            try {
+                const url = new URL(href, baseUrl).href;
+                if (!allUrls.includes(url))
+                    allUrls.push(url);
+            }
+            catch {
+                // skip malformed URLs
+            }
+        }
+    }
+    const uniqueUrls = allUrls;
+    const brokenLinks = [];
+    await Promise.all(uniqueUrls.map(async (url) => {
+        if (abortSignal?.aborted)
+            return;
+        try {
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), TIMEOUT_MS);
+            let status = 0;
+            let statusText = "";
+            try {
+                const res = await fetch(url, {
+                    method: "HEAD",
+                    redirect: "follow",
+                    signal: controller.signal,
+                });
+                status = res.status;
+                statusText = res.statusText;
+            }
+            catch {
+                // Fall back to GET if HEAD is not allowed
+                const controller2 = new AbortController();
+                const timer2 = setTimeout(() => controller2.abort(), TIMEOUT_MS);
+                try {
+                    const res = await fetch(url, {
+                        method: "GET",
+                        redirect: "follow",
+                        signal: controller2.signal,
+                    });
+                    status = res.status;
+                    statusText = res.statusText;
+                }
+                catch {
+                    status = 0;
+                    statusText = "timeout or network error";
+                }
+                clearTimeout(timer2);
+            }
+            clearTimeout(timer);
+            if (!isSuccessStatus(status)) {
+                const severity = status >= 500 ? "critical" : "high";
+                let path = url;
+                try {
+                    path = new URL(url).pathname;
+                }
+                catch { }
+                brokenLinks.push({ url, path, status, statusText, severity });
+            }
+        }
+        catch {
+            // skip
+        }
+    }));
+    const summary = brokenLinks.length === 0
+        ? `All ${uniqueUrls.length} links OK`
+        : `${brokenLinks.length} broken link(s) found`;
+    return {
+        brokenLinks,
+        checkedCount: uniqueUrls.length,
+        hasBrokenLinks: brokenLinks.length > 0,
+        summary,
+    };
+}