laxy-verify 1.1.33 → 1.2.0

package/README.md

@@ -1,304 +1,322 @@
-# laxy-verify
-
-`laxy-verify` is a deployment blocker gate for frontend apps.
-
-Every verification run includes the same build, Lighthouse, E2E, multi-viewport, security, visual diff, and stability coverage regardless of plan.
-
-## Quick start
-
-Run it on a frontend app:
-
-```bash
-cd your-project
-npx laxy-verify .
-```
-
-Generate config plus GitHub Actions workflow:
-
-```bash
-npx laxy-verify --init
-```
-
-That creates:
-
-- `.laxy.yml`
-- `.github/workflows/laxy-verify.yml`
-
-Optional: log in to connect the CLI to your Laxy account:
-
-```bash
-npx laxy-verify login
-npx laxy-verify whoami
-```
-
-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?"
-- optional account-linked automation on top of the same verification run
-
-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
-
-Every run includes:
-
-- 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`
-- `.laxy-result.json` for CI and automation
-- `laxy-verify-report.md` for human review and AI handoff
-
-Grades still exist, but they are not the main point. The main point is whether the run found blockers you should stop on.
-
-## Quick start
-
-Run it on a frontend app:
-
-```bash
-cd your-project
-npx laxy-verify .
-```
-
-Generate config plus CI workflow:
-
-```bash
-npx laxy-verify --init
-```
-
-That creates:
-
-- `.laxy.yml`
-- `.github/workflows/laxy-verify.yml`
-
-Optional: log in to connect the CLI to your Laxy account:
-
-```bash
-npx laxy-verify login
-npx laxy-verify whoami
-```
-
-For CI, set `LAXY_TOKEN` instead of interactive login:
-
-```yaml
-env:
-  LAXY_TOKEN: ${{ secrets.LAXY_TOKEN }}
-```
-
-## Example workflow
-
-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.
-
-## Example output
-
-```text
-Decision: client-ready
-Grade: Gold
-
-Passed:
-- production build
-- Lighthouse thresholds
-- core user flows
-- desktop, tablet, and mobile viewport checks
-
-Artifacts:
-- .laxy-result.json
-- laxy-verify-report.md
-```
-
-## The decision it helps you make
-
-`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?
-
-All verification checks already run without a paid plan gate.
-
-## 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
-build_command: ""
-dev_command: ""
-package_manager: auto
-port: 3000
-build_timeout: 300
-dev_timeout: 60
-lighthouse_runs: 1
-fail_on: bronze
-
-thresholds:
-  performance: 70
-  accessibility: 85
-  seo: 80
-  best_practices: 80
-
-crawl: false
-max_crawl_depth: 3
-max_crawl_pages: 10
-browsers:
-  - chromium
-```
-
-Useful adjustments:
-
-- 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
-
-```text
-npx laxy-verify [project-dir]
-
-Options:
-  --format console|json
-  --ci
-  --config <path>
-  --fail-on unverified|bronze|silver|gold
-  --skip-lighthouse
-  --plan-override free|pro|team
-  --badge
-  --init
-  --multi-viewport
-  --help
-
-Subcommands:
-  login [email]
-  logout
-  whoami
-```
-
-`--plan-override` is only for plan-label and automation testing. Verification coverage stays the same on every plan.
-
-## Result files
-
-Every run writes `.laxy-result.json`.
-
-When the run finds something worth reviewing, it also writes `laxy-verify-report.md`.
-
-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 stop-or-ship decision in plain English
-- what passed
-- blockers and warnings
-- exact verification evidence
-- 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
-
-## What this is not
-
-`laxy-verify` is not trying to replace:
-
-- your full Playwright suite
-- deep visual QA by designers
-- production observability
-- manual exploratory testing
-
-It is a pre-merge and pre-release verification layer, not your entire quality system.
-
-## Limitations
-
-- 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
+# laxy-verify
+
+`laxy-verify` is a deployment blocker gate for frontend apps.
+
+Every verification run includes the same build, Lighthouse, E2E, multi-viewport, security, visual diff, and stability coverage regardless of plan.
+
+## Quick start
+
+Run it on a frontend app:
+
+```bash
+cd your-project
+npx laxy-verify .
+```
+
+Generate config plus GitHub Actions workflow:
+
+```bash
+npx laxy-verify --init
+```
+
+That creates:
+
+- `.laxy.yml`
+- `.github/workflows/laxy-verify.yml`
+
+Optional: log in to connect the CLI to your Laxy account:
+
+```bash
+npx laxy-verify login
+npx laxy-verify whoami
+```
+
+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?"
+- optional account-linked automation on top of the same verification run
+
+This is most useful if you ship frontend apps and want a practical gate before:
+
+- merge
+- client review
+- QA handoff
+- production release
+
+## vs other tools
+
+No single competitor covers this combination. Here is where each tool stops:
+
+|  | laxy-verify | LHCI | Checkly | Percy / Argos | Unlighthouse | QA Wolf |
+|--|--|--|--|--|--|--|
+| Build failure detection | yes | no | no | no | no | no |
+| Auto-generated E2E | yes | no | write your own | no | no | yes |
+| Security audit | yes | no | no | no | no | no |
+| Lighthouse (multi-run avg) | yes | yes | no | no | yes | no |
+| Visual diff | yes | no | no | yes | no | no |
+| Multi-viewport checks | yes | no | separate config | no | yes | no |
+| Ship/hold release decision | yes | score only | no | no | no | no |
+| Zero config to start | yes | no | no | no | partial | no |
+| Free full coverage | yes | yes | limited | limited | yes | enterprise |
+
+LHCI gives you Lighthouse. Percy gives you visual diffs. Checkly watches your production uptime. None of them produce a merge or release decision from one command.
+
+## 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
+
+Every run includes:
+
+- 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`
+- `.laxy-result.json` for CI and automation
+- `laxy-verify-report.md` for human review and AI handoff
+
+Grades still exist, but they are not the main point. The main point is whether the run found blockers you should stop on.
+
+## Quick start
+
+Run it on a frontend app:
+
+```bash
+cd your-project
+npx laxy-verify .
+```
+
+Generate config plus CI workflow:
+
+```bash
+npx laxy-verify --init
+```
+
+That creates:
+
+- `.laxy.yml`
+- `.github/workflows/laxy-verify.yml`
+
+Optional: log in to connect the CLI to your Laxy account:
+
+```bash
+npx laxy-verify login
+npx laxy-verify whoami
+```
+
+For CI, set `LAXY_TOKEN` instead of interactive login:
+
+```yaml
+env:
+  LAXY_TOKEN: ${{ secrets.LAXY_TOKEN }}
+```
+
+## Example workflow
+
+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.
+
+## Example output
+
+```text
+Decision: client-ready
+Grade: Gold
+
+Passed:
+- production build
+- Lighthouse thresholds
+- core user flows
+- desktop, tablet, and mobile viewport checks
+
+Artifacts:
+- .laxy-result.json
+- laxy-verify-report.md
+```
+
+## The decision it helps you make
+
+`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?
+
+All verification checks already run without a paid plan gate.
+
+## 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
+build_command: ""
+dev_command: ""
+package_manager: auto
+port: 3000
+build_timeout: 300
+dev_timeout: 60
+lighthouse_runs: 1
+fail_on: bronze
+
+thresholds:
+  performance: 70
+  accessibility: 85
+  seo: 80
+  best_practices: 80
+
+crawl: false
+max_crawl_depth: 3
+max_crawl_pages: 10
+browsers:
+  - chromium
+```
+
+Useful adjustments:
+
+- 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
+
+```text
+npx laxy-verify [project-dir]
+
+Options:
+  --format console|json
+  --ci
+  --config <path>
+  --fail-on unverified|bronze|silver|gold
+  --skip-lighthouse
+  --plan-override free|pro|team
+  --badge
+  --init
+  --multi-viewport
+  --help
+
+Subcommands:
+  login [email]
+  logout
+  whoami
+```
+
+`--plan-override` is only for plan-label and automation testing. Verification coverage stays the same on every plan.
+
+## Result files
+
+Every run writes `.laxy-result.json`.
+
+When the run finds something worth reviewing, it also writes `laxy-verify-report.md`.
+
+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 stop-or-ship decision in plain English
+- what passed
+- blockers and warnings
+- exact verification evidence
+- 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
+
+## What this is not
+
+`laxy-verify` is not trying to replace:
+
+- your full Playwright suite
+- deep visual QA by designers
+- production observability
+- manual exploratory testing
+
+It is a pre-merge and pre-release verification layer, not your entire quality system.
+
+## Limitations
+
+- 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

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

@@ -1,21 +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>;
+/**
+ * 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>;