laxy-verify 1.1.8 → 1.1.10

package/README.md

@@ -1,372 +1,150 @@
-# laxy-verify
-
-Frontend quality gate for AI-generated code. Build + Lighthouse verification with grade output (Gold/Silver/Bronze/Unverified).
-
-```bash
-npx laxy-verify --init --run  # 설정 생성 + 즉시 검증 (원커맨드)
-npx laxy-verify --init        # Auto-detect framework, generate config
-npx laxy-verify .             # Run verification
-npx laxy-verify login         # Log in for Pro/Pro+ features
-npx laxy-verify --badge       # Show shields.io badge
-npx laxy-verify --help        # 도움말 보기
-```
-
-## Quick Start
-
-### 1. Initialize
-
-```bash
-cd your-project
-npx laxy-verify --init
-```
-
-This generates `.laxy.yml` and `.github/workflows/laxy-verify.yml` automatically by detecting your framework and package manager.
-
-### 2. Run Locally
-
-```bash
-npx laxy-verify .
-```
-
-### 3. Add to CI
-
-Push the generated workflow file. Every PR gets a quality gate with grade comment and status check.
-
-## Grades
-
-| Grade | Requirement |
-|-------|------------|
-| **Gold** | Build passes + all Lighthouse thresholds pass + all viewports pass (Pro+ only) |
-| **Silver** | Build passes + Lighthouse exceeds all thresholds |
-| **Bronze** | Build passes (Lighthouse not run or below threshold) |
-| **Unverified** | Build failed |
-
-`fail_on` controls the minimum acceptable grade. Default: `bronze`.
-
-> **Gold grade** is only achievable with a Pro+ account. It requires multi-viewport Lighthouse (desktop/tablet/mobile) to all pass in addition to the standard thresholds.
-
-## Pro / Pro+ Features
-
-Log in to unlock paid plan features:
-
-```bash
-npx laxy-verify login        # Log in with your laxy-blue.vercel.app account
-npx laxy-verify whoami       # Check current login status
-npx laxy-verify logout       # Remove saved credentials
-```
-
-| Feature | Free | Pro | Pro+ |
-|---------|------|-----|------|
-| Build verification | ✅ | ✅ | ✅ |
-| Lighthouse (1 run) | ✅ | ✅ | ✅ |
-| Silver grade | ✅ | ✅ | ✅ |
-| Bronze grade | ✅ | ✅ | ✅ |
-| Lighthouse (3 runs, averaged) | ❌ | ✅ | ✅ |
-| Gold grade eligibility | ❌ | ✅ | ✅ |
-| Verbose failure output | ❌ | ✅ | ✅ |
-| Multi-viewport Lighthouse (desktop/tablet/mobile) | ❌ | ❌ | ✅ |
-| Failure analysis report | ❌ | ❌ | ✅ |
-| Fast Lane (priority queue) | ❌ | ❌ | ✅ |
-
-### Login
-
-```bash
-npx laxy-verify login
-# Enter your email and password for laxy-blue.vercel.app
-```
-
-Credentials are stored in `~/.laxy/credentials.json` (chmod 600). Token expires after 30 days.
-
-For CI environments, set the `LAXY_TOKEN` environment variable instead of logging in interactively:
-
-```yaml
-env:
-  LAXY_TOKEN: ${{ secrets.LAXY_TOKEN }}
-```
-
-**LAXY_TOKEN을 GitHub Secrets에 등록하는 방법:**
-
-1. 로컬에서 로그인: `npx laxy-verify login`
-2. 토큰 복사: `cat ~/.laxy/credentials.json` → `"token"` 값을 복사
-3. GitHub 리포 → Settings → Secrets and variables → Actions → **New repository secret**
-4. Name: `LAXY_TOKEN`, Value: 복사한 토큰 붙여넣기
-5. `--init` 으로 생성된 workflow 파일은 이미 `LAXY_TOKEN`을 포함합니다
-
-### Multi-viewport (Pro+)
-
-```bash
-npx laxy-verify --multi-viewport .
-```
-
-Runs Lighthouse on three viewports: desktop, tablet (1024×768), and mobile. Gold grade requires all three to pass the configured thresholds.
-
-## Configuration
-
-All fields optional in `.laxy.yml`:
-
-```yaml
-framework: "auto"           # auto | nextjs | vite | cra | sveltekit
-build_command: ""           # default: auto-detected from package.json
-dev_command: ""             # default: auto-detected
-package_manager: "auto"     # auto | npm | pnpm | yarn | bun
-port: 3000                  # dev server port
-build_timeout: 300          # seconds (default 5m)
-dev_timeout: 60             # seconds for dev server start (90 in CI mode)
-lighthouse_runs: 1          # @lhci/cli runs (CI mode auto-sets to 3)
-
-thresholds:
-  performance: 70           # CI mode applies -10 offset (effective: 60)
-  accessibility: 85
-  seo: 80
-  best_practices: 80
-
-fail_on: "bronze"           # unverified | bronze | silver | gold
-                            # unverified = never fail (informational only)
-```
-
-**fail_on vs build failure:** Build failure always produces grade `Unverified` and exit code 1, regardless of `fail_on`. `fail_on: unverified` means informational only (always exit 0).
-
-**--ci flag:** Lowers Performance threshold by 10, sets `lighthouse_runs=3` (when not explicitly set), and increases `dev_timeout` to 90s. Auto-set when `CI=true` env var exists.
-
-## CLI Options
-
-```
-npx laxy-verify [project-dir]   Default: current directory
-
-Options:
-  --format   console | json       Output format (default: console)
-  --ci                            CI mode: -10 Performance, runs=3
-  --config   <path>               Path to .laxy.yml
-  --fail-on  unverified|bronze|silver|gold  Override fail_on
-  --skip-lighthouse               Build-only verification (max Bronze)
-  --badge                         Show shields.io badge (reads .laxy-result.json)
-  --init                          Generate .laxy.yml + GitHub workflow
-  --multi-viewport                Pro+: run Lighthouse on desktop/tablet/mobile
-
-Subcommands:
-  login [email]                   Log in to unlock Pro/Pro+ features
-  logout                          Remove saved credentials
-  whoami                          Show current login status
-```
-
-## exit codes
-
-| Code | Meaning |
-|------|--------|
-| 0 | Grade meets or exceeds `fail_on` threshold |
-| 1 | Grade worse than `fail_on`, or build failed |
-| 2 | Configuration error (no package.json, invalid YAML, etc.) |
-
-## GitHub Action
-
-```yaml
-- uses: psungmin24/laxy-verify@v1
-  with:
-    github-token: ${{ secrets.GITHUB_TOKEN }}
-    fail-on: silver    # optional, default: bronze
-    config: .laxy.yml  # optional
-```
-
-Posts a PR comment with grade and Lighthouse scores, and sets a commit status check.
-
-For Pro/Pro+ features in CI, add `LAXY_TOKEN` to your repository secrets:
-
-```yaml
-- uses: psungmin24/laxy-verify@v1
-  with:
-    github-token: ${{ secrets.GITHUB_TOKEN }}
-    fail-on: gold      # Gold requires Pro+ account
-  env:
-    LAXY_TOKEN: ${{ secrets.LAXY_TOKEN }}
-```
-
-## Limitations (v1)
-
-- **Monorepos:** Not supported. Run `npx laxy-verify apps/web` for the app subdirectory.
-- **Lighthouse accuracy:** Scores are measured in dev mode (`npm run dev`). Production scores are typically higher.
-- **Fork PRs:** Comments and status checks are not posted on PRs from forks (GitHub security restriction).
-- **Yarn Berry:** May require manual `package_manager` configuration if using Corepack.
-- **Gold grade:** Requires Pro+ plan and `--multi-viewport` flag. All three viewports must pass Lighthouse thresholds.
-
-## Expected CI Timing
-
-- Build: 15-30s
-- Dev server start: 5-20s
-- Lighthouse (1 run): ~15s
-- Lighthouse (3 runs CI): ~45s
-- Multi-viewport (Pro+, 3 viewports): ~60s
-- **Total: 35-95s per PR**
-
-## .laxy-result.json
-
-Written after every run:
-
-```json
-{
-  "grade": "Silver",
-  "timestamp": "2026-04-07T10:30:00Z",
-  "build": { "success": true, "durationMs": 12300, "errors": [] },
-  "lighthouse": { "performance": 87, "accessibility": 92, "seo": 88, "bestPractices": 90, "runs": 1 },
-  "thresholds": { "performance": 70, "accessibility": 85, "seo": 80, "bestPractices": 80 },
-  "ciMode": false,
-  "framework": "nextjs",
-  "exitCode": 0,
-  "config_fail_on": "bronze"
-}
-```
-
-Use `npx laxy-verify --badge` to output a shields.io badge markdown from this file.
-
-## Badge
-
-```bash
-npx laxy-verify --badge
-```
-
-Output: `![Laxy Verify: Silver](https://img.shields.io/badge/laxy_verify-silver-brightgreen)`
-
-## License
-
-MIT
-
-
-## Quick Start
-
-### 1. Initialize
-
-```bash
-cd your-project
-npx laxy-verify --init
-```
-
-This generates `.laxy.yml` and `.github/workflows/laxy-verify.yml` automatically by detecting your framework and package manager.
-
-### 2. Run Locally
-
-```bash
-npx laxy-verify .
-```
-
-### 3. Add to CI
-
-Push the generated workflow file. Every PR gets a quality gate with grade comment and status check.
-
-## Grades
-
-| Grade | Requirement |
-|-------|------------|
-| **Silver** | Build passes + Lighthouse exceeds all thresholds |
-| **Bronze** | Build passes (Lighthouse not run or below threshold) |
-| **Unverified** | Build failed |
-
-`fail_on` controls the minimum acceptable grade. Default: `bronze`.
-
-## Configuration
-
-All fields optional in `.laxy.yml`:
-
-```yaml
-framework: "auto"           # auto | nextjs | vite | cra | sveltekit
-build_command: ""           # default: auto-detected from package.json
-dev_command: ""             # default: auto-detected
-package_manager: "auto"     # auto | npm | pnpm | yarn | bun
-port: 3000                  # dev server port
-build_timeout: 300          # seconds (default 5m)
-dev_timeout: 60             # seconds for dev server start (90 in CI mode)
-lighthouse_runs: 1          # @lhci/cli runs (CI mode auto-sets to 3)
-
-thresholds:
-  performance: 70           # CI mode applies -10 offset (effective: 60)
-  accessibility: 85
-  seo: 80
-  best_practices: 80
-
-fail_on: "bronze"           # unverified | bronze | silver | gold
-                            # unverified = never fail (informational only)
-```
-
-**fail_on vs build failure:** Build failure always produces grade `Unverified` and exit code 1, regardless of `fail_on`. `fail_on: unverified` means informational only (always exit 0).
-
-**--ci flag:** Lowers Performance threshold by 10, sets `lighthouse_runs=3` (when not explicitly set), and increases `dev_timeout` to 90s. Auto-set when `CI=true` env var exists.
-
-## CLI Options
-
-```
-npx laxy-verify [project-dir]   Default: current directory
-
-Options:
-  --format   console | json       Output format (default: console)
-  --ci                            CI mode: -10 Performance, runs=3
-  --config   <path>               Path to .laxy.yml
-  --fail-on  unverified|bronze|silver|gold  Override fail_on
-  --skip-lighthouse               Build-only verification (max Bronze)
-  --badge                         Show shields.io badge (reads .laxy-result.json)
-  --init                          Generate .laxy.yml + GitHub workflow
-```
-
-## exit codes
-
-| Code | Meaning |
-|------|--------|
-| 0 | Grade meets or exceeds `fail_on` threshold |
-| 1 | Grade worse than `fail_on`, or build failed |
-| 2 | Configuration error (no package.json, invalid YAML, etc.) |
-
-## GitHub Action
-
-```yaml
-- uses: psungmin24/laxy-verify@v1
-  with:
-    github-token: ${{ secrets.GITHUB_TOKEN }}
-    fail-on: silver    # optional, default: bronze
-    config: .laxy.yml  # optional
-```
-
-Posts a PR comment with grade and Lighthouse scores, and sets a commit status check.
-
-## Limitations (v1)
-
-- **Monorepos:** Not supported. Run `npx laxy-verify apps/web` for the app subdirectory.
-- **Lighthouse accuracy:** Scores are measured in dev mode (`npm run dev`). Production scores are typically higher.
-- **Fork PRs:** Comments and status checks are not posted on PRs from forks (GitHub security restriction).
-- **Yarn Berry:** May require manual `package_manager` configuration if using Corepack.
-
-## Expected CI Timing
-
-- Build: 15-30s
-- Dev server start: 5-20s
-- Lighthouse (1 run): ~15s
-- Lighthouse (3 runs CI): ~45s
-- **Total: 35-95s per PR**
-
-## .laxy-result.json
-
-Written after every run:
-
-```json
-{
-  "grade": "Silver",
-  "timestamp": "2026-04-07T10:30:00Z",
-  "build": { "success": true, "durationMs": 12300, "errors": [] },
-  "lighthouse": { "performance": 87, "accessibility": 92, "seo": 88, "bestPractices": 90, "runs": 1 },
-  "thresholds": { "performance": 70, "accessibility": 85, "seo": 80, "bestPractices": 80 },
-  "ciMode": false,
-  "framework": "nextjs",
-  "exitCode": 0,
-  "config_fail_on": "bronze"
-}
-```
-
-Use `npx laxy-verify --badge` to output a shields.io badge markdown from this file.
-
-## Badge
-
-```bash
-npx laxy-verify --badge
-```
-
-Output: `![Laxy Verify: Silver](https://img.shields.io/badge/laxy_verify-silver-brightgreen)`
-
-## License
-
-MIT
+# 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.
+
+```bash
+npx laxy-verify --init --run
+npx laxy-verify .
+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 | Is this likely to break right now? |
+| Pro | Is this strong enough to send to a client? |
+| Pro+ | Can I call this release-ready with confidence? |
+
+## 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 |
+| Report export | No | Yes | Yes |
+| Multi-viewport verification | No | No | Yes |
+| Visual diff | No | No | Yes |
+| Failure analysis signals | No | No | Yes |
+
+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: ""
+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]
+
+Options:
+  --format console|json
+  --ci
+  --config <path>
+  --fail-on unverified|bronze|silver|gold
+  --skip-lighthouse
+  --badge
+  --init
+  --multi-viewport
+  --help
+
+Subcommands:
+  login [email]
+  logout
+  whoami
+```
+
+## Result File
+
+Each run writes `.laxy-result.json`.
+
+```json
+{
+  "grade": "Silver",
+  "timestamp": "2026-04-09T09:00:00Z",
+  "build": { "success": true, "durationMs": 12000, "errors": [] },
+  "e2e": { "passed": 4, "failed": 0, "total": 4, "results": [] },
+  "lighthouse": { "performance": 82, "accessibility": 94, "seo": 90, "bestPractices": 92, "runs": 3 },
+  "exitCode": 0,
+  "_plan": "pro"
+}
+```
+
+## 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.
+
+## License
+
+MIT