sniff-qa 0.7.0 → 0.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (71) hide show
  1. package/.claude-plugin/plugin.json +2 -2
  2. package/CHANGELOG.md +70 -0
  3. package/NOTICE +1 -1
  4. package/README.md +109 -380
  5. package/dist/assert-budget-NBF3JYM7.js +9 -0
  6. package/dist/caps-G3ZGJI7B.js +21 -0
  7. package/dist/caps-G3ZGJI7B.js.map +1 -0
  8. package/dist/{chunk-LJYT4MD5.js → chunk-7ZOFYET5.js} +18 -97
  9. package/dist/chunk-7ZOFYET5.js.map +1 -0
  10. package/dist/chunk-EGANHIIE.js +91 -0
  11. package/dist/chunk-EGANHIIE.js.map +1 -0
  12. package/dist/chunk-GV27IOMC.js +106 -0
  13. package/dist/chunk-GV27IOMC.js.map +1 -0
  14. package/dist/chunk-GX36BPK7.js +161 -0
  15. package/dist/chunk-GX36BPK7.js.map +1 -0
  16. package/dist/chunk-NG2IGCAK.js +45 -0
  17. package/dist/chunk-NG2IGCAK.js.map +1 -0
  18. package/dist/cli/index.js +27 -16
  19. package/dist/cli/index.js.map +1 -1
  20. package/dist/crawl-ZXZRF4Q7.js +15 -0
  21. package/dist/crawl-ZXZRF4Q7.js.map +1 -0
  22. package/dist/crawl-command-RDWGHZC4.js +76 -0
  23. package/dist/crawl-command-RDWGHZC4.js.map +1 -0
  24. package/dist/{discover-Q363YJ5X.js → discover-QKGMYPHK.js} +15 -7
  25. package/dist/discover-QKGMYPHK.js.map +1 -0
  26. package/dist/{domain-NNL2PPRK.js → domain-UQ34YE4B.js} +1 -1
  27. package/dist/index.d.ts +15 -0
  28. package/dist/index.js +6 -2
  29. package/dist/index.js.map +1 -1
  30. package/dist/{loader-UG2XADG7.js → loader-Z2DUGG5Z.js} +18 -2
  31. package/dist/loader-Z2DUGG5Z.js.map +1 -0
  32. package/dist/mcp/server.d.ts +20 -1
  33. package/dist/mcp/server.js +37 -28
  34. package/dist/mcp/server.js.map +1 -1
  35. package/dist/{model-2DTSAX7T.js → model-SP6HJN6J.js} +4 -2
  36. package/dist/model-SP6HJN6J.js.map +1 -0
  37. package/dist/{persistence-RHUFBQAY.js → persistence-XLFJ5EY4.js} +6 -2
  38. package/dist/persistence-XLFJ5EY4.js.map +1 -0
  39. package/dist/{quality-run-LLBZZI7X.js → quality-run-YAURB242.js} +6 -5
  40. package/dist/{quality-run-LLBZZI7X.js.map → quality-run-YAURB242.js.map} +1 -1
  41. package/dist/redaction-CHAIVPCF.js +30 -0
  42. package/dist/redaction-CHAIVPCF.js.map +1 -0
  43. package/dist/{repo-analyzer-WK5WP7NT.js → repo-analyzer-4OURSITY.js} +1 -1
  44. package/dist/{report-IKRVVIW4.js → report-7FQFH4HW.js} +3 -3
  45. package/dist/{runner-HFJDHS2I.js → runner-QHSYX7J2.js} +1 -1
  46. package/dist/{runner-II7BPB63.js → runner-RDVVIGBU.js} +7 -2
  47. package/dist/runner-RDVVIGBU.js.map +1 -0
  48. package/dist/{unified-67Z6YA64.js → unified-YSOTPG5B.js} +12 -10
  49. package/dist/{unified-67Z6YA64.js.map → unified-YSOTPG5B.js.map} +1 -1
  50. package/dist/{update-baselines-UCAW3SDN.js → update-baselines-JYKUUIZG.js} +2 -2
  51. package/dist/write-report-6RJWN54I.js +31 -0
  52. package/dist/write-report-6RJWN54I.js.map +1 -0
  53. package/package.json +5 -4
  54. package/skills/sniff/SKILL.md +10 -10
  55. package/skills/sniff-fix/SKILL.md +3 -0
  56. package/skills/sniff-report/SKILL.md +3 -0
  57. package/dist/chunk-LJYT4MD5.js.map +0 -1
  58. package/dist/crawl-666NLYDC.js +0 -11
  59. package/dist/crawl-command-3OB4IUBU.js +0 -54
  60. package/dist/crawl-command-3OB4IUBU.js.map +0 -1
  61. package/dist/discover-Q363YJ5X.js.map +0 -1
  62. package/dist/loader-UG2XADG7.js.map +0 -1
  63. package/dist/model-2DTSAX7T.js.map +0 -1
  64. package/dist/persistence-RHUFBQAY.js.map +0 -1
  65. package/dist/runner-II7BPB63.js.map +0 -1
  66. /package/dist/{crawl-666NLYDC.js.map → assert-budget-NBF3JYM7.js.map} +0 -0
  67. /package/dist/{domain-NNL2PPRK.js.map → domain-UQ34YE4B.js.map} +0 -0
  68. /package/dist/{repo-analyzer-WK5WP7NT.js.map → repo-analyzer-4OURSITY.js.map} +0 -0
  69. /package/dist/{report-IKRVVIW4.js.map → report-7FQFH4HW.js.map} +0 -0
  70. /package/dist/{runner-HFJDHS2I.js.map → runner-QHSYX7J2.js.map} +0 -0
  71. /package/dist/{update-baselines-UCAW3SDN.js.map → update-baselines-JYKUUIZG.js.map} +0 -0
package/README.md CHANGED
@@ -1,452 +1,181 @@
1
1
  <picture>
2
- <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/Aboudjem/sniff/main/.github/assets/logo-dark.svg">
3
- <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/Aboudjem/sniff/main/.github/assets/logo-light.svg">
4
- <img alt="Sniff" src="https://raw.githubusercontent.com/Aboudjem/sniff/main/.github/assets/logo-light.svg" width="100%">
2
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/Aboudjem/sniff/main/.github/assets/hero-dark.svg">
3
+ <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/Aboudjem/sniff/main/.github/assets/hero-light.svg">
4
+ <img alt="sniff" src="https://raw.githubusercontent.com/Aboudjem/sniff/main/.github/assets/hero-light.svg" width="100%">
5
5
  </picture>
6
6
 
7
7
  <p align="center">
8
- <a href="https://www.npmjs.com/package/sniff-qa"><img src="https://img.shields.io/npm/v/sniff-qa?color=ef4444&logo=npm&label=npm&style=flat-square" alt="npm"></a>
9
- <a href="https://www.npmjs.com/package/sniff-qa"><img src="https://img.shields.io/npm/dm/sniff-qa?color=ef4444&logo=npm&label=downloads&style=flat-square" alt="npm downloads"></a>
10
- <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache_2.0-ef4444?style=flat-square" alt="License"></a>
11
- <a href="https://github.com/Aboudjem/sniff/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/Aboudjem/sniff/ci.yml?style=flat-square&label=CI" alt="CI"></a>
12
- <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%E2%89%A522-339933?style=flat-square&logo=node.js&logoColor=white" alt="Node"></a>
13
- <a href="https://github.com/Aboudjem/10x"><img src="https://img.shields.io/badge/10x-marketplace-ef4444?style=flat-square" alt="10x marketplace"></a>
14
- <a href="https://github.com/Aboudjem/sniff/stargazers"><img src="https://img.shields.io/github/stars/Aboudjem/sniff?style=flat-square&color=ef4444" alt="Stars"></a>
8
+ <a href="https://www.npmjs.com/package/sniff-qa"><img src="https://img.shields.io/npm/v/sniff-qa?style=flat-square&color=FF006E&logo=npm&label=npm" alt="npm version"></a>
9
+ <a href="https://github.com/Aboudjem/sniff/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/Aboudjem/sniff/ci.yml?style=flat-square&color=00D4FF&label=CI" alt="CI"></a>
10
+ <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache_2.0-7C3AED?style=flat-square" alt="License Apache 2.0"></a>
11
+ <a href="https://github.com/Aboudjem/sniff/stargazers"><img src="https://img.shields.io/github/stars/Aboudjem/sniff?style=flat-square&color=2BE8C8" alt="Stars"></a>
15
12
  </p>
16
13
 
17
- <p align="center">
18
- <b>English</b> ·
19
- <a href="READMEs/zh-CN.md">简体中文</a> ·
20
- <a href="READMEs/ja.md">日本語</a> ·
21
- <a href="READMEs/es.md">Español</a> ·
22
- <a href="READMEs/fr.md">Français</a>
23
- </p>
24
-
25
- <p align="center"><b>Point it at your running app. It walks your real user flows in a real browser and tells you what's actually broken, with proof.</b></p>
26
-
27
- <p align="center">
28
- <a href="#get-started">Get started</a> ·
29
- <a href="#what-it-finds">What it finds</a> ·
30
- <a href="#why-you-can-trust-it">Why trust it</a> ·
31
- <a href="#how-it-works">How it works</a> ·
32
- <a href="#demo">Demo</a> ·
33
- <a href="#faq">FAQ</a>
34
- </p>
35
-
36
- ![sniff demo](.github/assets/demo.gif)
37
-
38
- <picture>
39
- <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/Aboudjem/sniff/main/.github/assets/sniff-diagram.svg">
40
- <img alt="Sniff flow: your running app -> headless browser walk -> findings with proof" src="https://raw.githubusercontent.com/Aboudjem/sniff/main/.github/assets/sniff-diagram.svg" width="100%">
41
- </picture>
14
+ <p align="center"><b>English</b> · <a href="READMEs/zh-CN.md">简体中文</a> · <a href="READMEs/ja.md">日本語</a> · <a href="READMEs/es.md">Español</a> · <a href="READMEs/fr.md">Français</a></p>
42
15
 
43
- ---
44
-
45
- ## What is this?
46
-
47
- Sniff is an autonomous QA scanner. You point it at a running web app and it **walks your app's real user flows in a real (headless) browser** (clicking buttons, filling forms, following links) and reports what's actually broken.
16
+ <p align="center"><b>Point it at your running app. It walks your real user flows in a real browser and tells you what is actually broken, with proof.</b></p>
48
17
 
49
- It is **not** a linter and **not** a static scanner. It opens your pages, interacts with them like a user would, and watches what happens.
18
+ <p align="center"><a href="#what-it-does">What it does</a> · <a href="#install">Install</a> · <a href="#use-it">Use it</a> · <a href="#what-you-get">What you get</a> · <a href="#works-in-your-editor">Works in your editor</a> · <a href="#good-to-know">Good to know</a></p>
50
19
 
51
- Every bug it reports comes with **proof**: the exact page, the ordered steps to reproduce it, a screenshot, and the console or network excerpt that caught it. A finding without reproduction proof is not a finding.
20
+ <img alt="sniff walking a buggy app and streaming findings with severity, confidence, steps to reproduce, and a fix" src="https://raw.githubusercontent.com/Aboudjem/sniff/main/.github/assets/demo.gif" width="100%">
52
21
 
53
22
  ```bash
54
- npx sniff-qa --url http://localhost:3000
23
+ claude plugin marketplace add Aboudjem/10x
24
+ claude plugin install sniff@10x
55
25
  ```
56
26
 
57
- One command, no config, no API key, no Playwright setup. Point it at your running app, or just run `npx sniff-qa` from your project and it auto-detects a dev server on common ports.
58
-
59
- > Sniff walks a **running app**. If no dev server is running, it falls back to a source-code scan and tells you exactly how to start the real walk. See [Get started](#get-started).
27
+ ## What it does
60
28
 
61
- ---
29
+ Most linters read your source without ever running your app, and end-to-end frameworks ask you to
30
+ write and maintain the tests yourself. sniff opens your running app in a real browser, clicks and
31
+ fills things like a user would, and judges what actually happened.
62
32
 
63
- ## Get started
33
+ - **It finds 12 classes of bugs**, from HTTP 500 routes and dead links to placeholder data, dead
34
+ submit buttons, forms wiped by the back button, stuck spinners, and mobile overflow.
35
+ - **It proves every one.** Every finding carries the route and the ordered steps that produced it,
36
+ plus the screenshot and the console or network excerpt the check captured. No steps, no finding.
37
+ - **It has been measured.** On a fixture app planted with 21 bugs across all 12 classes, plus a
38
+ clean control page, sniff finds 21 of 21 and reports nothing on the control page.
64
39
 
65
- You need **Node.js 22+** and a web app you can run locally (or a URL).
40
+ ## Install
66
41
 
67
- > **Naming:** the npm package is **`sniff-qa`**, so use `npx sniff-qa` or `npm install -D sniff-qa`. Once installed, the binary is **`sniff`** (the `sniff-qa` binary works too). Don't run `npx sniff`, that's a different package.
68
-
69
- ### 1. Start your app
42
+ The block above is the Claude Code path, through the [10x marketplace](https://github.com/Aboudjem/10x).
43
+ For any other agent, the Vercel skills CLI installs the same three skills:
70
44
 
71
45
  ```bash
72
- npm run dev # or however you start your app
46
+ npx skills add Aboudjem/sniff
73
47
  ```
74
48
 
75
- ### 2. Walk it
76
-
77
- In another terminal:
49
+ To use it as a plain command line tool, with no editor involved:
78
50
 
79
51
  ```bash
80
- npx sniff-qa --url http://localhost:3000 # point it at your running app
52
+ npx sniff-qa --url http://localhost:3000
81
53
  ```
82
54
 
83
- That's the reliable one-liner. Sniff also **auto-detects** a dev server on common ports, so from your project folder you can often just run `npx sniff-qa` with no flags. If your app is on a non-standard port (or auto-detect misses it), pass `--url` (that always works). It also walks a deployed URL:
55
+ The npm package is `sniff-qa` and the binary it installs is `sniff`. Do not run `npx sniff`, which
56
+ is an unrelated package.
84
57
 
85
- ```bash
86
- npx sniff-qa --url https://staging.myapp.com
87
- ```
88
-
89
- > **Found bugs? It exits non-zero, on purpose.** A walk that finds issues exits with code `1` so CI fails the build; it is **not** a crash (you'll see a `✓ Scan complete` line). Pass `--fail-on none` to always exit `0`.
58
+ <details>
59
+ <summary>Node version, project install, and CI</summary>
90
60
 
91
- > **First run downloads a browser.** The first time Sniff opens a browser it downloads a Chromium build (~165 MB, one-time). You'll see the progress. You need internet access for that first run; after that it's cached.
61
+ Node.js 22 or newer. `npm install -D sniff-qa` adds it to a project's devDependencies, and
62
+ `npx sniff-qa ci` writes a GitHub Actions workflow with browser caching and report artifacts.
63
+ </details>
92
64
 
93
- ### 3. Read the report
65
+ ## Use it
94
66
 
95
- Findings print to your terminal, grouped by severity, each with steps to reproduce. Want a shareable page?
67
+ **1. Start your app,** with whatever dev server your project already uses.
96
68
 
97
69
  ```bash
98
- npx sniff-qa --url http://localhost:3000 --report # runs a walk, then writes sniff-reports/sniff-report.html (self-contained)
70
+ npm run dev
99
71
  ```
100
72
 
101
- **No app running?** Sniff doesn't fail silently. It runs a source-only scan and prints a clear next step (start your dev server or pass `--url`) so you can get to the real flow-walk. You can also run the source scan on purpose:
73
+ **2. Walk it,** from a second terminal. sniff auto-detects a dev server on the common ports, so
74
+ `--url` is optional, but passing it takes the guesswork out.
102
75
 
103
76
  ```bash
104
- npx sniff-qa scan # source-only scan, no browser
77
+ npx sniff-qa --url http://localhost:3000
105
78
  ```
106
79
 
107
- Stuck? Run `npx sniff-qa doctor` to check your environment (Node, browser, dev server).
80
+ **3. Read the findings.** They print grouped by severity. Below is an abridged real run against this
81
+ repo's own planted-bug fixture, from `npx sniff-qa --url http://localhost:4321 --ci --max-pages 12`:
108
82
 
109
- ---
83
+ ```text
84
+ sniff v0.8.0 walking http://localhost:4321
110
85
 
111
- ## What it finds
86
+ 26 findings (+1 low-confidence hidden; use --all)
112
87
 
113
- Sniff walks your app and looks for **12 classes of real bugs**:
88
+ CRITICAL (1)
89
+ • [confirmed] Page returns HTTP 500
90
+ /crash (route/broken-page)
91
+ - Navigate to /crash
92
+ - Server responded with HTTP 500
93
+ fix: The route throws server-side. Check the server logs/handler for this path and return a valid page or a proper error page.
94
+ shot: sniff-reports/crawl/_crash-desktop.png
95
+
96
+ ✓ Scan complete: 26 issue(s) found. Exit code 1 so CI fails on bugs; pass --fail-on none to always exit 0.
97
+ ```
114
98
 
115
- | # | Class | Examples |
116
- |:--|:------|:---------|
117
- | 1 | **Broken pages / routes** | 4xx/5xx responses, blank renders, crash screens |
118
- | 2 | **Broken links** | Dead internal and external links |
119
- | 3 | **Console & network errors** | Uncaught exceptions and failed requests *during interaction* |
120
- | 4 | **Empty & fake data** | Missing data, plus placeholders like `lorem ipsum`, `TODO`, `test@test.com` |
121
- | 5 | **Broken forms** | Dead submit buttons, validation that never fires |
122
- | 6 | **State loss** | Fill a form, hit back, and it's wiped |
123
- | 7 | **Flow regressions / dead-ends** | A journey that can't be completed |
124
- | 8 | **Bad loading & error states** | Infinite spinners, missing error states |
125
- | 9 | **Broken async outcomes** | Submitted but no success feedback (flagged "needs out-of-band verification") |
126
- | 10 | **Responsive issues** | Overflow and tiny tap targets (a 375px mobile pass) |
127
- | 11 | **Accessibility** | Missing alt text and labels, contrast, via [axe-core](https://github.com/dequelabs/axe-core) |
128
- | 12 | **Unclear primary actions** | The main call-to-action is buried or ambiguous |
99
+ Add `--report` for a self-contained HTML page you can send to someone. Run `npx sniff-qa doctor` if
100
+ the environment looks wrong.
129
101
 
130
- Each finding ships with:
102
+ <img alt="How sniff works: crawl, act, assert, prove, report" src="https://raw.githubusercontent.com/Aboudjem/sniff/main/.github/assets/how-it-works.svg" width="100%">
131
103
 
132
- - **Reproduction proof**: the exact route, the ordered steps, a screenshot, and the console/network excerpt.
133
- - **A severity**, so you fix the right thing first.
134
- - **A confidence**: `confirmed`, `likely`, or `uncertain`. Uncertain findings are hidden by default; add `--all` to see them.
135
- - **A suggested fix.**
104
+ ## What you get
136
105
 
137
106
  <picture>
138
107
  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/Aboudjem/sniff/main/.github/assets/features-dark.svg">
139
108
  <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/Aboudjem/sniff/main/.github/assets/features-light.svg">
140
- <img alt="The bug classes Sniff finds" src="https://raw.githubusercontent.com/Aboudjem/sniff/main/.github/assets/features-light.svg" width="100%">
109
+ <img alt="The 12 classes of bugs sniff finds" src="https://raw.githubusercontent.com/Aboudjem/sniff/main/.github/assets/features-light.svg" width="100%">
141
110
  </picture>
142
111
 
143
- ---
144
-
145
- ## Why you can trust it
146
-
147
- Most scanners drown you in false positives until you stop reading them. Sniff is built the opposite way.
148
-
149
- We measured it on a fixture app planted with **21 bugs across all 12 classes**, plus a clean control page that should produce zero findings:
150
-
151
- | | Old engine | New engine |
152
- |:--|:--|:--|
153
- | Bugs found | 9 / 21 (43%) | **21 / 21 (100%)** |
154
- | Precision | ~13% | **100%** |
155
- | False positives | 125 | **0** |
156
- | Findings on the clean page | n/a | **0** |
157
- | Flagship command | crashed | works |
158
-
159
- Those numbers are locked as a regression test. The full suite is **441 tests**.
160
-
161
- **How it keeps false positives near zero:**
162
-
163
- - A first-party **noise filter** drops the junk that isn't your bug: favicons, analytics, hot-module-reload chatter, expected auth redirects, engine aborts.
164
- - Accessibility findings are backed by **axe-core**, which is zero-false-positive by design.
165
- - **Uncertain findings are suppressed by default** (use `--all` to see them).
166
- - A broken page is reported **once**, not re-flagged on every link that points to it.
167
-
168
- If Sniff can't prove a bug, it doesn't claim one.
112
+ - **A terminal report** grouped by severity, each finding with steps, a fix, and a screenshot path.
113
+ - **A shareable file**, a self-contained HTML report with `--report` or JSON with `--json`.
114
+ - **An exit code**, non-zero when findings reach the `--fail-on` severity, so CI fails on real bugs.
115
+ - **A confidence label** on each. `uncertain` is hidden from the terminal unless you pass `--all`.
169
116
 
170
- ---
171
-
172
- ## How is it different?
173
-
174
- Linters read your source. End-to-end frameworks make *you* write the tests. Link checkers only check links. Sniff drives your real app and judges the result.
175
-
176
- | | **Sniff** | linkinator | pa11y | Playwright codegen | QA-Wolf-style services |
177
- |:--|:--|:--|:--|:--|:--|
178
- | Walks real user flows in a browser | **Yes** | No | No | You script it | Yes |
179
- | Zero setup, zero test-writing | **Yes** | Yes | Yes | No (you write tests) | No (onboarding) |
180
- | Broken links | **Yes** | Yes | No | Manual | Manual |
181
- | Accessibility (axe-core) | **Yes** | No | **Yes** | Manual | Some |
182
- | Empty / placeholder / fake data | **Yes** | No | No | No | No |
183
- | State-loss (back-button wipes a form) | **Yes** | No | No | Manual | Manual |
184
- | One-shot reproduction proof per finding | **Yes** | No | Partial | No | Varies |
185
- | Self-contained HTML report | **Yes** | No | Partial | No | Dashboard |
186
- | Runs locally, no account, no API key | **Yes** | Yes | Yes | Yes | No (service) |
187
-
188
- What Sniff uniquely does in one command: catch **empty/placeholder data**, **state-loss**, and **broken async outcomes**, and hand you a single proof report, with **no scripts to write and no service to sign up for**.
189
-
190
- ---
191
-
192
- ## Commands
193
-
194
- ```
195
- sniff Walk your app (auto-detects the dev server). The default.
196
- sniff --url <url> Walk a specific URL
197
- sniff scan Source-only scan, no browser (placeholders, TODOs, dead links, etc.)
198
- sniff report Show the results from the last run
199
- sniff doctor Check your environment (Node, browser, config, dev server)
200
- sniff ci Generate a GitHub Actions workflow
201
- sniff fix Auto-fix safe issues (console.log, debugger, etc.)
202
- sniff --help Show every command and flag
203
- sniff --version Show the version
204
- ```
205
-
206
- ### Useful flags
207
-
208
- | Flag | What it does |
209
- |:-----|:-------------|
210
- | `--url <url>` | Walk this URL instead of auto-detecting |
211
- | `--report` | Write a self-contained HTML report to `sniff-reports/sniff-report.html` |
212
- | `--all` | Also show low-confidence (`uncertain`) findings |
213
- | `--max-pages <n>` | Cap how many pages to walk (default: 25) |
214
- | `--no-mobile` | Skip the 375px responsive pass |
215
- | `--headed` | Show the browser window while it walks |
216
- | `--json` | Machine-readable JSON output |
217
- | `--ci` | CI mode (stable output, non-interactive) |
218
- | `--fail-on <sev>` | Exit non-zero on findings at or above this severity |
219
-
220
- ---
221
-
222
- ## Demo
223
-
224
- A real run against a buggy app: 21 real issues, zero false positives, every finding with severity, confidence, reproduction steps, and a fix. Watch Sniff walk the app and stream findings in (the animated demo plays at the top of this README, [`.github/assets/demo.gif`](.github/assets/demo.gif)).
225
-
226
- Below is the same run as a stylized terminal still:
227
-
228
- <img alt="Sniff walking a buggy app and reporting 21 real issues with zero false positives" src="https://raw.githubusercontent.com/Aboudjem/sniff/main/.github/assets/demo.svg" width="100%">
229
-
230
- ---
231
-
232
- ## Use it from your AI editor
233
-
234
- Sniff ships as an MCP server too. Add it once, then just ask your assistant *"scan this project for bugs"* or *"walk my app."* If your app is running, Sniff auto-detects it, so you don't have to pass a URL.
235
-
236
- **One unified `sniff` tool, three modes:**
237
-
238
- - `walk`: **recommended.** Walks your running app's real flows (the flow-walk above).
239
- - `scan`: source-only scan, no browser.
240
- - `report`: show the last run's results.
241
-
242
- (`run` and `discover` are legacy modes kept for back-compat.)
243
-
244
- ### Slash commands and MCP tools
245
-
246
- As a Claude Code plugin, Sniff adds three slash commands:
247
-
248
- | Slash command | What it does |
249
- |:--------------|:-------------|
250
- | `/sniff` | Walk your running app and find real bugs (the flow-walk). |
251
- | `/sniff-fix` | Scan and auto-fix safe issues (stray `console.log`, `debugger`, etc.). |
252
- | `/sniff-report` | Show the results from the last run. |
253
-
254
- As an MCP server, the surface is **one unified `sniff` tool** that takes `{ mode, rootDir, baseUrl? }`. The three modes above (`walk` / `scan` / `report`) are how you drive it, and the unified tool is what you should use. Narrow, single-purpose tools (`sniff_scan`, `sniff_run`, `sniff_report`, plus `sniff_discover` and `sniff_install`) stay registered for back-compat and scoped capabilities, but new work should go through the unified `sniff` tool.
117
+ New in 0.8.0:
255
118
 
256
- ### Install the skills into any AI CLI
119
+ - `--caps scan,report` narrows the MCP server to the source scan and the saved-results reader, with
120
+ no browser launch and no browser download.
121
+ - `--storage-state auth.json` walks a logged-in app. Cookie and token values from that file are
122
+ redacted from the text of every written report, though not from screenshot pixels.
123
+ - An `assert` block in `sniff.config` caps findings by severity (`maxCritical`, `maxHigh`,
124
+ `maxTotal`), enforced on the command line by the walk, the source scan, and discovery.
257
125
 
258
- The MCP server above works in every MCP-capable client. To also load the `/sniff` skills directly into another CLI, run the one-line installer. It symlinks the three skills into that CLI's skills directory; `--update` pulls the latest and relinks, `--uninstall` removes them.
126
+ ## Works in your editor
259
127
 
260
- ```bash
261
- curl -fsSL https://raw.githubusercontent.com/Aboudjem/sniff/main/install.sh | bash -s codex
262
- ```
263
-
264
- On Windows, run `install.ps1 <platform>` from a checkout (Developer Mode or an elevated shell is needed for symlinks).
128
+ Works in Claude Code, Cursor, Codex, Copilot, Gemini CLI, and 70+ other agents through
129
+ `npx skills add`. The skills are Markdown, so they run on whatever model your editor points at.
265
130
 
266
- | Platform | Skills directory | One-liner |
267
- |:--|:--|:--|
268
- | Claude Code | (plugin) | `claude plugin install sniff@10x` |
269
- | Codex / Gemini / OpenCode / Pi | `~/.agents/skills` | `install.sh codex` |
270
- | VS Code (Copilot) | `~/.copilot/skills` | `install.sh copilot` |
271
- | Trae | `~/.trae/skills` | `install.sh trae` |
272
- | Vibe | `~/.vibe/skills` | `install.sh vibe` |
273
- | OpenClaw | `~/.openclaw/skills` | `install.sh openclaw` |
274
- | Antigravity | `~/.gemini/antigravity/skills` | `install.sh antigravity` |
275
- | Hermes / Cline / Kimi | `~/.<cli>/skills` | `install.sh hermes` |
276
-
277
- Skill-directory conventions change between CLI releases. If a link does not resolve, fall back to the MCP server (it works everywhere). Run `install.sh all` to link every platform at once.
131
+ | Agent | One-line install |
132
+ |:--|:--|
133
+ | Claude Code | `claude plugin install sniff@10x` |
134
+ | Any of 70+ agents | `npx skills add Aboudjem/sniff` |
135
+ | Codex, Gemini CLI, OpenCode, Pi | `./install.sh codex` |
136
+ | VS Code (Copilot) | `./install.sh copilot` |
137
+ | Everything else | see [docs/editors.md](docs/editors.md) |
278
138
 
279
139
  <details>
280
- <summary><b>Claude Code</b></summary>
281
-
282
- One-command plugin install from the [10x marketplace](https://github.com/Aboudjem/10x):
283
-
284
- ```bash
285
- claude plugin marketplace add Aboudjem/10x
286
- claude plugin install sniff@10x
287
- ```
288
-
289
- Or add just the MCP server:
140
+ <summary>Add it as an MCP server instead</summary>
290
141
 
291
142
  ```bash
292
143
  claude mcp add sniff-qa npx -- -y sniff-qa --mcp
293
- ```
294
- </details>
295
-
296
- <details>
297
- <summary><b>Cursor</b></summary>
298
-
299
- Add to `~/.cursor/mcp.json`:
300
-
301
- ```json
302
- { "mcpServers": { "sniff-qa": { "command": "npx", "args": ["-y", "sniff-qa", "--mcp"] } } }
303
- ```
304
- </details>
305
-
306
- <details>
307
- <summary><b>VS Code (Copilot)</b></summary>
308
-
309
- Add to `.vscode/mcp.json`:
310
-
311
- ```json
312
- { "servers": { "sniff-qa": { "type": "stdio", "command": "npx", "args": ["-y", "sniff-qa", "--mcp"] } } }
313
- ```
314
- </details>
315
-
316
- <details>
317
- <summary><b>Codex CLI</b></summary>
318
-
319
- ```bash
320
144
  codex mcp add sniff-qa -- npx -y sniff-qa --mcp
321
145
  ```
322
- </details>
323
-
324
- <details>
325
- <summary><b>Gemini CLI</b></summary>
326
-
327
- Add to `~/.gemini/mcp_config.json`:
328
-
329
- ```json
330
- { "mcpServers": { "sniff-qa": { "command": "npx", "args": ["-y", "sniff-qa", "--mcp"] } } }
331
- ```
332
- </details>
333
-
334
- <details>
335
- <summary><b>Windsurf</b></summary>
336
146
 
337
- Add to `~/.codeium/windsurf/mcp_config.json`:
338
-
339
- ```json
340
- { "mcpServers": { "sniff-qa": { "command": "npx", "args": ["-y", "sniff-qa", "--mcp"] } } }
341
- ```
147
+ Cursor, VS Code, Gemini CLI, Windsurf, Continue, OpenCode, and Zed take the same command as a JSON
148
+ or TOML entry. Every per-editor snippet is in [docs/editors.md](docs/editors.md).
342
149
  </details>
343
150
 
344
- <details>
345
- <summary><b>Continue.dev</b></summary>
346
-
347
- Add to `.continue/mcpServers/sniff-qa.yaml`:
348
-
349
- ```yaml
350
- mcpServers:
351
- sniff-qa: { command: npx, args: ["-y", "sniff-qa", "--mcp"], type: stdio }
352
- ```
353
- </details>
151
+ ## Good to know
354
152
 
355
- > The first browser-based walk downloads Chromium (~165 MB). Over MCP, Sniff returns a structured `needsSetup` payload instead of blocking the editor on a long download: run the install it shows you, then ask again.
153
+ > [!IMPORTANT]
154
+ > No API key, no account, no signup, and no AI provider unless you set one up yourself. Walking and
155
+ > scanning never edit your source. `sniff fix` is the only command that rewrites code, and only when
156
+ > you run it.
356
157
 
357
- ---
158
+ > [!NOTE]
159
+ > A walk clicks buttons and submits real forms, so it can create real data. Point it at a dev or
160
+ > staging app, not at production. The first walk also downloads a Chromium build and caches it, so
161
+ > that one run needs internet access.
358
162
 
359
- ## How it works
163
+ - **It wants a running app.** With no dev server up it falls back to a source-only scan and tells
164
+ you how to start the real walk. `npx sniff-qa scan` runs that scan on purpose.
165
+ - **Dead-link checking follows external links,** so a walk makes requests to the third-party URLs
166
+ your own pages already link to.
167
+ - **A walk that finds bugs exits 1** on purpose, so CI fails the build. That is not a crash.
168
+ `--fail-on none` turns off the severity gate, though an `assert` budget can still fail the run.
360
169
 
361
- 1. **Find the app.** Sniff auto-detects your running dev server (or you pass `--url`).
362
- 2. **Walk the flows.** It opens pages in a headless browser and interacts with them like a user (clicking, filling forms, following links) across desktop and a 375px mobile pass.
363
- 3. **Watch everything.** It records console errors, failed network requests, broken renders, missing feedback, and accessibility issues as it goes.
364
- 4. **Filter the noise.** The first-party noise filter and axe-core drop the false positives; uncertain findings are held back.
365
- 5. **Report with proof.** Each surviving finding gets a severity, a confidence, reproduction steps, a screenshot, and a suggested fix, in the terminal and an optional HTML report.
170
+ ## Learn more
366
171
 
367
- <img alt="How sniff works: crawl, act, assert, prove, report" src="https://raw.githubusercontent.com/Aboudjem/sniff/main/.github/assets/how-it-works.svg" width="100%">
172
+ - [docs/editors.md](docs/editors.md), install and MCP snippets for every supported agent
173
+ - [docs/authenticated-walks.md](docs/authenticated-walks.md), walking a logged-in app with `--storage-state`
174
+ - [docs/assert-budgets.md](docs/assert-budgets.md), capping findings by severity in `sniff.config`
175
+ - [docs/comparison.md](docs/comparison.md), how sniff differs from linters, link checkers, and E2E frameworks
176
+ - [docs/faq.md](docs/faq.md), the questions this page does not answer
177
+ - [CHANGELOG.md](CHANGELOG.md) · [CONTRIBUTING.md](CONTRIBUTING.md) · [LICENSE](LICENSE)
368
178
 
369
179
  ---
370
180
 
371
- ## CI integration
372
-
373
- Run Sniff in your pipeline and fail the build on real bugs:
374
-
375
- ```bash
376
- npx sniff-qa --ci --fail-on high
377
- ```
378
-
379
- Generate a ready-to-commit GitHub Actions workflow:
380
-
381
- ```bash
382
- npx sniff-qa ci
383
- ```
384
-
385
- This writes `.github/workflows/sniff.yml` with browser caching and report artifacts.
386
-
387
- ---
388
-
389
- ## FAQ
390
-
391
- **Does it work without a dev server?**
392
- Sniff is built to walk a *running* app, so that's where it shines. If no server is running, it doesn't fail silently: it runs a source-only scan and tells you exactly how to start the real walk (start your dev server or pass `--url`). You can also run `npx sniff-qa scan` to get the source scan on purpose.
393
-
394
- **What gets downloaded on first run?**
395
- The first time Sniff opens a browser, it downloads a Chromium build (~165 MB, one-time, then cached). You'll see the progress, and you need internet access for that first run. Nothing else is installed and no account is created.
396
-
397
- **Do I need an API key?**
398
- No. Sniff runs entirely on your machine with no API key and no signup. Your code and your app never leave your computer.
399
-
400
- **How is it different from a linter?**
401
- A linter reads your source files and never runs your app, so it can't see a dead submit button, an infinite spinner, a wiped form, or a 500 page. Sniff opens your real app, interacts with it, and reports what actually broke, with a screenshot and steps to reproduce.
402
-
403
- **How is it different from Playwright codegen (or writing E2E tests)?**
404
- Playwright codegen records a script that *you* author and maintain; it tests only the path you clicked. Sniff writes nothing for you to maintain: it explores your flows on its own and judges the outcome, catching things a recorded happy-path never checks (empty/placeholder data, state-loss, missing success feedback).
405
-
406
- **Will it change my code?**
407
- No, not during a walk. Walking and scanning are read-only. The separate `sniff fix` command applies safe auto-fixes (like stray `console.log`/`debugger`) and only when you run it.
408
-
409
- **What stacks does it work with?**
410
- Any web app you can open in a browser: React, Next.js, Vue, Svelte, Angular, Remix, SvelteKit, Astro, plain HTML, and more. It walks the rendered app, so the framework doesn't matter for the browser checks.
411
-
412
- ---
413
-
414
- ## Works first-class in
415
-
416
- Claude Code · Cursor · VS Code (Copilot) · Codex · Gemini CLI · Windsurf · Continue.dev, via the MCP server (command `npx`, args `["-y", "sniff-qa", "--mcp"]`) or the CLI directly.
417
-
418
- ---
419
-
420
- ## Star History
421
-
422
- <a href="https://star-history.com/#Aboudjem/sniff&Date">
423
- <picture>
424
- <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=Aboudjem/sniff&type=Date&theme=dark" />
425
- <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=Aboudjem/sniff&type=Date" />
426
- <img alt="Star history chart for Aboudjem/sniff" src="https://api.star-history.com/svg?repos=Aboudjem/sniff&type=Date" width="70%" />
427
- </picture>
428
- </a>
429
-
430
- ---
431
-
432
- ## Contributing
433
-
434
- Issues and PRs welcome. See [CONTRIBUTING.md](CONTRIBUTING.md).
435
-
436
- ---
437
-
438
- <p align="center">
439
- <sub>
440
- Built on <a href="https://playwright.dev">Playwright</a> · <a href="https://github.com/dequelabs/axe-core">axe-core</a> · <a href="https://developer.chrome.com/docs/lighthouse">Lighthouse</a> · <a href="https://github.com/mapbox/pixelmatch">pixelmatch</a> · <a href="https://zod.dev">Zod</a> · <a href="https://github.com/modelcontextprotocol/typescript-sdk">MCP SDK</a>
441
- </sub>
442
- </p>
443
-
444
- <p align="center">
445
- <a href="https://www.linkedin.com/in/adam-boudjemaa/"><img src="https://img.shields.io/badge/LinkedIn-0A66C2?style=flat-square&logo=linkedin&logoColor=white" alt="LinkedIn"></a>
446
- <a href="https://x.com/AdamBoudj"><img src="https://img.shields.io/badge/X-000000?style=flat-square&logo=x&logoColor=white" alt="X"></a>
447
- <a href="https://adam-boudjemaa.com/"><img src="https://img.shields.io/badge/Website-ef4444?style=flat-square&logo=googlechrome&logoColor=white" alt="Website"></a>
448
- </p>
449
-
450
- <p align="center">
451
- <sub>Built by <a href="https://github.com/Aboudjem">Adam Boudjemaa</a> · <a href="LICENSE">Apache 2.0</a></sub>
452
- </p>
181
+ <p align="center"><sub>Built by <a href="https://github.com/Aboudjem">Adam Boudjemaa</a> · <a href="LICENSE">Apache 2.0</a> · standing on <a href="https://playwright.dev">Playwright</a> and <a href="https://github.com/dequelabs/axe-core">axe-core</a></sub></p>
@@ -0,0 +1,9 @@
1
+ import {
2
+ evaluateSeverityBudget,
3
+ printBudgetViolations
4
+ } from "./chunk-NG2IGCAK.js";
5
+ export {
6
+ evaluateSeverityBudget,
7
+ printBudgetViolations
8
+ };
9
+ //# sourceMappingURL=assert-budget-NBF3JYM7.js.map
@@ -0,0 +1,21 @@
1
+ import {
2
+ CAPABILITIES,
3
+ CAPABILITY_TOOL,
4
+ CapsError,
5
+ MODE_CAPABILITY,
6
+ UNIFIED_MODES,
7
+ expandCaps,
8
+ parseCaps,
9
+ resolveTools
10
+ } from "./chunk-GV27IOMC.js";
11
+ export {
12
+ CAPABILITIES,
13
+ CAPABILITY_TOOL,
14
+ CapsError,
15
+ MODE_CAPABILITY,
16
+ UNIFIED_MODES,
17
+ expandCaps,
18
+ parseCaps,
19
+ resolveTools
20
+ };
21
+ //# sourceMappingURL=caps-G3ZGJI7B.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}