laxy-verify 1.1.18 → 1.1.20

package/README.md

@@ -1,119 +1,163 @@
-# laxy-verify
-
-CLI verification for frontend apps.
-
-`laxy-verify` runs production build checks, Lighthouse, tiered verify E2E, and plan-gated verification features for Free, Pro, and Pro+ accounts.
-It is designed around three user questions:
-
-- Free: "Will it break in production?"
-- Pro: "Would a client accept this?"
-- Pro+: "Can I ship this today?"
-
-```bash
-npx laxy-verify --init --run
+# laxy-verify
+
+A frontend verification CLI that catches build breaks, regressions, and client-visible issues before you ship.
+
+`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: "Any critical issues right now?"
+- Pro: "Ready to show a client?"
+- Pro+: "Ready for production?"
+
+```bash
+npx laxy-verify --init --run
 npx laxy-verify .
 npx laxy-verify . --plan-override pro
 npx laxy-verify login
-npx laxy-verify whoami
-npx laxy-verify --help
-```
-
-## Quick Start
-
-### 1. Initialize
-
-```bash
-cd your-project
-npx laxy-verify --init
-```
-
-This generates `.laxy.yml` and a GitHub Actions workflow.
-
-### 2. Run locally
-
-```bash
-npx laxy-verify .
-```
-
-### 3. Add to CI
-
-Commit the generated workflow. Each PR gets a verification run, grade output, and optional GitHub reporting.
-
-## Verification Tiers
-
-| Plan | Question it answers |
-|------|---------------------|
-| Free | Will it break in production? |
-| Pro | Would a client accept this? |
-| Pro+ | Can I ship this today? |
+npx laxy-verify whoami
+npx laxy-verify --help
+```
+
+What you get from one run:
+
+- 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
+
+## Quick Start
+
+### 1. 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
+
+```bash
+npx laxy-verify --init
+```
+
+This 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
+
+```bash
+npx laxy-verify login
+npx laxy-verify whoami
+```
+
+For CI, set `LAXY_TOKEN` instead of using 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 |
-
-## Paid Features
-
-Log in with your Laxy account to unlock paid plan features.
-
-```bash
-npx laxy-verify login
-npx laxy-verify whoami
-npx laxy-verify logout
-```
-
-| Feature | Free | Pro | Pro+ |
-|---------|------|-----|------|
-| Build verification | Yes | Yes | Yes |
-| Lighthouse | 1 run | 3 runs | 3 runs |
-| Verify E2E | Smoke | Deeper client-send checks | Deeper client-send checks |
-| 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 |
-
-Pro is for delivery verification.
-Pro+ is for release-confidence verification with extra evidence before you say "ship it."
-
-For CI, set `LAXY_TOKEN` instead of using interactive login.
-
-```yaml
-env:
-  LAXY_TOKEN: ${{ secrets.LAXY_TOKEN }}
-```
-
-## Configuration
-
-All fields are optional in `.laxy.yml`.
-
-```yaml
-framework: "auto"
-build_command: ""
-dev_command: ""
+| 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 |
+
+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.
+
+## Sample Output
+
+```text
+Plan: Pro+
+Grade: Gold
+Verdict: release-ready
+
+Passed:
+- production build
+- Lighthouse thresholds
+- core E2E flows
+- desktop, tablet, and mobile viewport checks
+
+Artifacts:
+- .laxy-result.json
+- laxy-verify-report.md
+```
+
+## Configuration
+
+All fields are optional in `.laxy.yml`.
+
+```yaml
+framework: "auto"
+build_command: ""
+dev_command: ""
 package_manager: "auto"
 port: 3000
 build_timeout: 300
 dev_timeout: 60
 lighthouse_runs: 1
 
-thresholds:
-  performance: 70
-  accessibility: 85
-  seo: 80
-  best_practices: 80
-
-fail_on: "bronze"
-```
-
-## CLI Options
-
-```text
-npx laxy-verify [project-dir]
+thresholds:
+  performance: 70
+  accessibility: 85
+  seo: 80
+  best_practices: 80
+
+fail_on: "bronze"
+```
+
+Typical cases:
+
+- 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
+
+## CLI Options
+
+```text
+npx laxy-verify [project-dir]
 
 Options:
   --format console|json
@@ -129,21 +173,21 @@ Options:
 
 Subcommands:
   login [email]
-  logout
-  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`: blocker-focused delivery report
+  logout
+  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.
@@ -173,13 +217,13 @@ Exit behavior follows the verification verdict, not just the legacy grade.
     "report": { "verdict": "release-ready" }
   },
   "exitCode": 0,
-  "_plan": "pro_plus"
-}
-```
-
-### `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.
+  "_plan": "pro_plus"
+}
+```
+
+### `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.
 
 It includes:
 
@@ -187,21 +231,33 @@ It includes:
 - 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
-
-## Regression Fixtures
-
-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.
-
-## 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.
-
-## License
-
-MIT
+- failed E2E scenarios
+- a `Copy For AI` section you can paste directly into Codex, Cursor, Claude, or ChatGPT
+
+## Environment Notes
+
+- 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.
+
+## Regression Fixtures
+
+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.
+
+## 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.
+
+## Links
+
+- GitHub: https://github.com/psungmin24/Laxy/tree/main/laxy-verify
+- Issues: https://github.com/psungmin24/Laxy/issues
+
+## License
+
+MIT

package/dist/report-markdown.js

@@ -66,6 +66,8 @@ function formatTimestamp(iso) {
 function sentenceForVerdict(view) {
     const isReleaseTier = view.tier === "pro_plus";
     switch (view.verdict) {
+        case "client-ready":
+            return "Yes. This run collected enough evidence to support a client-ready call.";
         case "release-ready":
             return isReleaseTier
                 ? "Yes. This run collected enough evidence to support a release-ready call."
@@ -95,10 +97,14 @@ function defaultNextActions(result) {
     if (view.nextActions.length > 0)
         return view.nextActions;
     switch (view.verdict) {
+        case "client-ready":
+            return ["Send this version to the client, or rerun verification after meaningful UI or flow changes."];
         case "release-ready":
             return ["Ship this version, or archive this report as release evidence."];
         case "investigate":
-            return ["Collect the missing verification evidence, then rerun the command before release."];
+            return view.tier === "pro_plus"
+                ? ["Collect the missing verification evidence, then rerun the command before release."]
+                : ["Collect the missing verification evidence, then rerun the command before sending this to a client."];
         case "build-failed":
             return ["Fix the production build first, then rerun the verification command."];
         case "quick-pass":
@@ -266,9 +272,11 @@ function renderCopyForAI(result, flavor) {
     const evidence = view.failureEvidence.map((item) => `- ${item}`);
     const closingLine = view.verdict === "release-ready"
         ? "Use this as release evidence, or rerun after any code change that could affect quality."
-        : view.verdict === "investigate" && view.blockers.length === 0
-            ? "Collect the missing verification evidence, then rerun the command and compare the new report."
-            : "Please fix the blockers first, then rerun the verification command and compare the new report.";
+        : view.verdict === "client-ready"
+            ? "Use this as client handoff evidence, or rerun after any code change that could affect user-facing flows."
+            : view.verdict === "investigate" && view.blockers.length === 0
+                ? "Collect the missing verification evidence, then rerun the command and compare the new report."
+                : "Please fix the blockers first, then rerun the verification command and compare the new report.";
     const openingLine = flavor === "release"
         ? "Use this release report to decide whether the project is truly ready to ship."
         : flavor === "delivery"
@@ -277,7 +285,7 @@ function renderCopyForAI(result, flavor) {
     const targetLine = flavor === "release"
         ? "Goal: reach a release-ready verdict with strong viewport, visual, and user-flow evidence."
         : flavor === "delivery"
-            ? "Goal: remove client-visible blockers and reach a confident delivery call."
+            ? "Goal: remove client-visible blockers and reach a confident client-ready call."
             : "Goal: fix the blockers and improve confidence on the next run.";
     return [
         `## ${sectionTitle(flavor, "copy")}`,
@@ -333,7 +341,7 @@ function buildMarkdownReport(projectDir, result) {
     const decisionLead = flavor === "release"
         ? "This section answers whether the current build is strong enough to call release-ready."
         : flavor === "delivery"
-            ? "This section answers whether the current build is strong enough to send to a client."
+            ? "This section answers whether the current build is strong enough to call client-ready."
             : "This section explains the outcome of the current verification run.";
     const atAGlanceLead = flavor === "release"
         ? "This report is written for a ship or hold decision."

package/dist/verification-core/report.js

@@ -351,14 +351,14 @@ function buildVerificationReport(input, options) {
         summary = `Core checks passed, but release-ready confidence still needs ${missingEvidence.join(" and ")}.`;
     }
     else if (tier === "pro" && coreChecksPassed && !hasWarnings) {
-        verdict = "release-ready";
+        verdict = "client-ready";
         confidence = "medium";
-        summary = "No blocking issues found. Build, E2E, and Lighthouse checks passed. Safe to send to client.";
+        summary = "No blocking issues found. Build, E2E, and Lighthouse checks passed. This run supports a client-ready call.";
     }
     else if (tier === "pro" && coreChecksPassed && hasWarnings) {
         verdict = "investigate";
         confidence = "medium";
-        summary = "Core checks passed, but warning-level risks remain. Review warnings before sending this to a client.";
+        summary = "Core checks passed, but warning-level risks remain. Review warnings before calling this run client-ready.";
     }
     else if (tier === "free") {
         if (evidence.hasConsoleErrors) {

package/dist/verification-core/tier-policy.js

@@ -43,11 +43,11 @@ function planToVerificationTier(plan) {
 function getVerificationTierQuestion(tier) {
     switch (tier) {
         case "pro":
-            return "Is this strong enough to send to a client?";
+            return "Ready to show a client?";
         case "pro_plus":
-            return "Can I call this release-ready with confidence?";
+            return "Ready for production?";
         default:
-            return "Is this likely to break right now?";
+            return "Any critical issues right now?";
     }
 }
 function getTierVerificationView(report) {

package/dist/verification-core/types.d.ts

@@ -1,6 +1,6 @@
 export type VerificationGrade = "gold" | "silver" | "bronze" | "unverified";
 export type VerificationTier = "free" | "pro" | "pro_plus";
-export type ReleaseVerdict = "quick-pass" | "investigate" | "hold" | "release-ready" | "build-failed";
+export type ReleaseVerdict = "quick-pass" | "client-ready" | "investigate" | "hold" | "release-ready" | "build-failed";
 export interface LighthouseThresholds {
     performance: number;
     accessibility: number;

package/package.json

@@ -1,12 +1,36 @@
-{
-  "name": "laxy-verify",
-  "version": "1.1.18",
-  "description": "Frontend quality gate: build, Lighthouse, tiered E2E, and release-confidence verification",
-  "license": "MIT",
-  "type": "commonjs",
-  "bin": {
-    "laxy-verify": "dist/cli.js"
-  },
+{
+  "name": "laxy-verify",
+  "version": "1.1.20",
+  "description": "Frontend verification CLI for build checks, Lighthouse, E2E, and release readiness",
+  "license": "MIT",
+  "type": "commonjs",
+  "homepage": "https://github.com/psungmin24/Laxy/tree/main/laxy-verify#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/psungmin24/Laxy.git",
+    "directory": "laxy-verify"
+  },
+  "bugs": {
+    "url": "https://github.com/psungmin24/Laxy/issues"
+  },
+  "keywords": [
+    "frontend",
+    "verification",
+    "quality-gate",
+    "release-readiness",
+    "lighthouse",
+    "e2e",
+    "qa",
+    "cli",
+    "nextjs",
+    "vite"
+  ],
+  "engines": {
+    "node": ">=20.18.0 <25"
+  },
+  "bin": {
+    "laxy-verify": "dist/cli.js"
+  },
   "files": [
     "dist/"
   ],