sniff-qa 0.8.1 → 0.9.1

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 (176) hide show
  1. package/.claude-plugin/icon.png +0 -0
  2. package/.claude-plugin/plugin.json +9 -2
  3. package/CHANGELOG.md +73 -0
  4. package/NOTICE +7 -4
  5. package/README.md +169 -102
  6. package/THIRD-PARTY-NOTICES.md +1800 -0
  7. package/dist/{accessibility-JXRMWF5Y.js → accessibility-42JOUOGH.js} +8 -2
  8. package/dist/{anthropic-api-ZR3UEB3Z.js → anthropic-api-VSG2X6FS.js} +7 -5
  9. package/dist/assert-budget-WG4BRCLX.js +10 -0
  10. package/dist/{caps-G3ZGJI7B.js → caps-YZPFNPIN.js} +3 -2
  11. package/dist/{chunk-VEI2O6AK.js → chunk-33JL2AB5.js} +14 -6
  12. package/dist/{chunk-7ZOFYET5.js → chunk-3E4W4H6S.js} +36 -16
  13. package/dist/{chunk-EGANHIIE.js → chunk-3NR2K5B3.js} +49 -5
  14. package/dist/chunk-3ROWRVZE.js +422 -0
  15. package/dist/{chunk-MYWWSM3V.js → chunk-3YFE3H23.js} +2 -1
  16. package/dist/{chunk-MMISGY2Q.js → chunk-4F6ZXOPE.js} +2 -1
  17. package/dist/chunk-A4TTASVS.js +27862 -0
  18. package/dist/{chunk-IXDUD2UG.js → chunk-AA744N7E.js} +2 -1
  19. package/dist/chunk-DZMX3VT2.js +267 -0
  20. package/dist/{chunk-NG2IGCAK.js → chunk-FR5QCJLH.js} +2 -1
  21. package/dist/{chunk-GV27IOMC.js → chunk-GC47B6MM.js} +2 -1
  22. package/dist/chunk-HP4TY3UY.js +80 -0
  23. package/dist/chunk-LZAPYYNR.js +4595 -0
  24. package/dist/{chunk-ZM6MGWO4.js → chunk-NBJLMLDA.js} +2 -1
  25. package/dist/chunk-RAGYZ54R.js +15480 -0
  26. package/dist/{chunk-GX36BPK7.js → chunk-RSGFFRXQ.js} +2 -2
  27. package/dist/chunk-SOBWDC35.js +38 -0
  28. package/dist/{chunk-CZKMOAXU.js → chunk-US4HFUCH.js} +3 -2
  29. package/dist/chunk-YM22FEIA.js +5807 -0
  30. package/dist/{ci-ISCWZJD3.js → ci-F6FUXT3O.js} +5 -3
  31. package/dist/{classifier-MWQMQ727.js → classifier-5FQ2FBTO.js} +3 -1
  32. package/dist/{claude-code-ZFTBQXY4.js → claude-code-J43C22IR.js} +7 -5
  33. package/dist/{claude-exploration-provider-QJH6IPYU.js → claude-exploration-provider-EWQNNE7D.js} +4 -3
  34. package/dist/cli/index.js +87 -35
  35. package/dist/compiler-sfc.cjs-JX56AWNS.js +48568 -0
  36. package/dist/crawl-KN7SW753.js +26 -0
  37. package/dist/{crawl-command-RDWGHZC4.js → crawl-command-Y45FIXNK.js} +14 -9
  38. package/dist/{cross-reference-MHNPSLEN.js → cross-reference-XOOBW6UZ.js} +3 -1
  39. package/dist/{dev-server-detector-XQ5AYPDT.js → dev-server-detector-FMFVKDJR.js} +3 -1
  40. package/dist/{discover-QKGMYPHK.js → discover-HA63UA4K.js} +20 -18
  41. package/dist/dist-3CYER35S.js +8 -0
  42. package/dist/{domain-UQ34YE4B.js → domain-FU3WIW64.js} +45 -30
  43. package/dist/{edge-cases-ZADKDZHL.js → edge-cases-B6IV3IKK.js} +3 -1
  44. package/dist/{element-extractor-OZTFBVKZ.js → element-extractor-QAG4MRUO.js} +18 -6
  45. package/dist/engine-AXB5O4ZH.js +39 -0
  46. package/dist/ensure-browsers-TNMHMLRS.js +147 -0
  47. package/dist/errors-NWB25P4K.js +8 -0
  48. package/dist/esm-IMWPYLSN.js +3469 -0
  49. package/dist/{fix-R33D34NP.js → fix-IXOEHAOS.js} +12 -5
  50. package/dist/{flakiness-OLJAY7CS.js → flakiness-7SSSM4SW.js} +3 -2
  51. package/dist/flakiness-CBKV4U54.js +12 -0
  52. package/dist/formatter-N4CC7SCM.js +176 -0
  53. package/dist/{framework-detector-ISSM2Q2I.js → framework-detector-4ZVHNT7N.js} +3 -1
  54. package/dist/generator-GGJYWYI2.js +8 -0
  55. package/dist/index.d.ts +15 -5
  56. package/dist/index.js +9 -6
  57. package/dist/{init-IQKT4ANC.js → init-POX5ZJ6V.js} +4 -2
  58. package/dist/json-4VOVHDQG.js +10 -0
  59. package/dist/{junit-GL44ATRR.js → junit-V24COOSR.js} +3 -1
  60. package/dist/{llm-VJAI6H6G.js → llm-TZ2WZGRZ.js} +3 -1
  61. package/dist/{loader-Z2DUGG5Z.js → loader-AMM63AOJ.js} +12 -3
  62. package/dist/mcp/server.js +13049 -73
  63. package/dist/{model-SP6HJN6J.js → model-BL2AID5Q.js} +6 -5
  64. package/dist/page-hooks-SECSGZR6.js +14 -0
  65. package/dist/{page-state-extractor-GYYLYRFR.js → page-state-extractor-AP4FQVLY.js} +3 -1
  66. package/dist/{performance-7HWKY5O2.js → performance-JVEYVBTV.js} +9 -3
  67. package/dist/{persistence-XLFJ5EY4.js → persistence-SHKJVSIS.js} +5 -4
  68. package/dist/{persistence-KTCRIGHU.js → persistence-SQ6QT3HP.js} +3 -1
  69. package/dist/picocolors-3W2AX5TJ.js +6 -0
  70. package/dist/pixelmatch-GATIVDQX.js +188 -0
  71. package/dist/png-HTC2G4ZG.js +2093 -0
  72. package/dist/{prompt-builder-D3FBH534.js → prompt-builder-EI2BFKLZ.js} +4 -2
  73. package/dist/{provider-BCKFVPTN.js → provider-O3UOALQH.js} +14 -12
  74. package/dist/{quality-run-YAURB242.js → quality-run-CTLX5YA5.js} +12 -10
  75. package/dist/{redaction-CHAIVPCF.js → redaction-QNBV5QZ3.js} +4 -3
  76. package/dist/{registry-5XCXUAYJ.js → registry-JBBTSD7I.js} +3 -1
  77. package/dist/{repo-analyzer-4OURSITY.js → repo-analyzer-4XITIIAF.js} +6 -4
  78. package/dist/{report-SDZWX25B.js → report-4UVJL7QV.js} +3 -1
  79. package/dist/{report-7FQFH4HW.js → report-BOVSPRCR.js} +8 -6
  80. package/dist/{response-parser-PUGNWF7S.js → response-parser-GHVJSYXQ.js} +3 -2
  81. package/dist/{route-discoverer-QBZCRQLJ.js → route-discoverer-ZXYJQIYE.js} +15 -8
  82. package/dist/{runner-RDVVIGBU.js → runner-DOLCFA3S.js} +10 -5
  83. package/dist/{runner-QHSYX7J2.js → runner-MCSDHFLN.js} +12 -7
  84. package/dist/{runner-AXZXNWYH.js → runner-MUBXHOIG.js} +10 -4
  85. package/dist/{scenarios-I7YYVTD2.js → scenarios-T2U6ZDRL.js} +3 -1
  86. package/dist/sdk-FQKA5HSQ.js +7184 -0
  87. package/dist/{source-5LS2B7TN.js → source-T5MHBY5G.js} +14 -7
  88. package/dist/{tiebreak-L5UFNKU2.js → tiebreak-SXBXPT7B.js} +3 -1
  89. package/dist/{unified-YSOTPG5B.js → unified-NUR2X5JV.js} +23 -21
  90. package/dist/{update-baselines-JYKUUIZG.js → update-baselines-TMERPIDV.js} +4 -2
  91. package/dist/version-FEHABGAH.js +10 -0
  92. package/dist/{visual-EUZG2STF.js → visual-XHFPFQFX.js} +5 -3
  93. package/dist/{workflow-template-6DADGPHA.js → workflow-template-7C5CCK67.js} +13 -7
  94. package/dist/{write-report-6RJWN54I.js → write-report-6Q4MXBYD.js} +5 -4
  95. package/package.json +21 -14
  96. package/dist/accessibility-JXRMWF5Y.js.map +0 -1
  97. package/dist/anthropic-api-ZR3UEB3Z.js.map +0 -1
  98. package/dist/assert-budget-NBF3JYM7.js +0 -9
  99. package/dist/assert-budget-NBF3JYM7.js.map +0 -1
  100. package/dist/caps-G3ZGJI7B.js.map +0 -1
  101. package/dist/chunk-7ZOFYET5.js.map +0 -1
  102. package/dist/chunk-CZKMOAXU.js.map +0 -1
  103. package/dist/chunk-EGANHIIE.js.map +0 -1
  104. package/dist/chunk-GV27IOMC.js.map +0 -1
  105. package/dist/chunk-GX36BPK7.js.map +0 -1
  106. package/dist/chunk-IXDUD2UG.js.map +0 -1
  107. package/dist/chunk-MMISGY2Q.js.map +0 -1
  108. package/dist/chunk-MYWWSM3V.js.map +0 -1
  109. package/dist/chunk-NG2IGCAK.js.map +0 -1
  110. package/dist/chunk-VEI2O6AK.js.map +0 -1
  111. package/dist/chunk-ZM6MGWO4.js.map +0 -1
  112. package/dist/ci-ISCWZJD3.js.map +0 -1
  113. package/dist/classifier-MWQMQ727.js.map +0 -1
  114. package/dist/claude-code-ZFTBQXY4.js.map +0 -1
  115. package/dist/claude-exploration-provider-QJH6IPYU.js.map +0 -1
  116. package/dist/cli/index.js.map +0 -1
  117. package/dist/crawl-ZXZRF4Q7.js +0 -15
  118. package/dist/crawl-ZXZRF4Q7.js.map +0 -1
  119. package/dist/crawl-command-RDWGHZC4.js.map +0 -1
  120. package/dist/cross-reference-MHNPSLEN.js.map +0 -1
  121. package/dist/dev-server-detector-XQ5AYPDT.js.map +0 -1
  122. package/dist/discover-QKGMYPHK.js.map +0 -1
  123. package/dist/domain-UQ34YE4B.js.map +0 -1
  124. package/dist/edge-cases-ZADKDZHL.js.map +0 -1
  125. package/dist/element-extractor-OZTFBVKZ.js.map +0 -1
  126. package/dist/ensure-browsers-AYKMLUHV.js +0 -86
  127. package/dist/ensure-browsers-AYKMLUHV.js.map +0 -1
  128. package/dist/errors-RFEOR527.js +0 -7
  129. package/dist/errors-RFEOR527.js.map +0 -1
  130. package/dist/fix-R33D34NP.js.map +0 -1
  131. package/dist/flakiness-OLJAY7CS.js.map +0 -1
  132. package/dist/flakiness-OVC7KGN2.js +0 -11
  133. package/dist/flakiness-OVC7KGN2.js.map +0 -1
  134. package/dist/formatter-HC3LT3VH.js +0 -146
  135. package/dist/formatter-HC3LT3VH.js.map +0 -1
  136. package/dist/framework-detector-ISSM2Q2I.js.map +0 -1
  137. package/dist/generator-HIFV67NI.js +0 -7
  138. package/dist/generator-HIFV67NI.js.map +0 -1
  139. package/dist/index.js.map +0 -1
  140. package/dist/init-IQKT4ANC.js.map +0 -1
  141. package/dist/json-YDWEB33Q.js +0 -8
  142. package/dist/json-YDWEB33Q.js.map +0 -1
  143. package/dist/junit-GL44ATRR.js.map +0 -1
  144. package/dist/llm-VJAI6H6G.js.map +0 -1
  145. package/dist/loader-Z2DUGG5Z.js.map +0 -1
  146. package/dist/mcp/server.js.map +0 -1
  147. package/dist/model-SP6HJN6J.js.map +0 -1
  148. package/dist/page-hooks-6RALVZB5.js +0 -13
  149. package/dist/page-hooks-6RALVZB5.js.map +0 -1
  150. package/dist/page-state-extractor-GYYLYRFR.js.map +0 -1
  151. package/dist/performance-7HWKY5O2.js.map +0 -1
  152. package/dist/persistence-KTCRIGHU.js.map +0 -1
  153. package/dist/persistence-XLFJ5EY4.js.map +0 -1
  154. package/dist/prompt-builder-D3FBH534.js.map +0 -1
  155. package/dist/provider-BCKFVPTN.js.map +0 -1
  156. package/dist/quality-run-YAURB242.js.map +0 -1
  157. package/dist/redaction-CHAIVPCF.js.map +0 -1
  158. package/dist/registry-5XCXUAYJ.js.map +0 -1
  159. package/dist/repo-analyzer-4OURSITY.js.map +0 -1
  160. package/dist/report-7FQFH4HW.js.map +0 -1
  161. package/dist/report-SDZWX25B.js.map +0 -1
  162. package/dist/response-parser-PUGNWF7S.js.map +0 -1
  163. package/dist/route-discoverer-QBZCRQLJ.js.map +0 -1
  164. package/dist/runner-AXZXNWYH.js.map +0 -1
  165. package/dist/runner-QHSYX7J2.js.map +0 -1
  166. package/dist/runner-RDVVIGBU.js.map +0 -1
  167. package/dist/scenarios-I7YYVTD2.js.map +0 -1
  168. package/dist/source-5LS2B7TN.js.map +0 -1
  169. package/dist/tiebreak-L5UFNKU2.js.map +0 -1
  170. package/dist/unified-YSOTPG5B.js.map +0 -1
  171. package/dist/update-baselines-JYKUUIZG.js.map +0 -1
  172. package/dist/version-FLE7ZHDX.js +0 -7
  173. package/dist/version-FLE7ZHDX.js.map +0 -1
  174. package/dist/visual-EUZG2STF.js.map +0 -1
  175. package/dist/workflow-template-6DADGPHA.js.map +0 -1
  176. package/dist/write-report-6RJWN54I.js.map +0 -1
Binary file
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "sniff",
3
- "version": "0.8.1",
3
+ "version": "0.9.1",
4
4
  "description": "Autonomous QA scanner via sniff-qa: walks your running app in a real browser and reports real bugs (broken pages/links, console/network errors, broken forms, state-loss, empty/placeholder data, bad loading/error states, responsive + a11y) with reproduction proof, severity, confidence, and a fix. No API key.",
5
5
  "author": {
6
6
  "name": "Adam Boudjemaa",
@@ -9,5 +9,12 @@
9
9
  "homepage": "https://github.com/Aboudjem/sniff",
10
10
  "repository": "https://github.com/Aboudjem/sniff",
11
11
  "license": "Apache-2.0",
12
- "keywords": ["testing", "qa", "playwright", "accessibility", "mcp", "sniff-qa"]
12
+ "keywords": [
13
+ "testing",
14
+ "qa",
15
+ "playwright",
16
+ "accessibility",
17
+ "mcp",
18
+ "sniff-qa"
19
+ ]
13
20
  }
package/CHANGELOG.md CHANGED
@@ -7,6 +7,79 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
7
7
 
8
8
  ## [Unreleased]
9
9
 
10
+ ## [0.9.1] - 2026-11-17
11
+
12
+ The MCP server now connects on a new machine's first start.
13
+
14
+ ### Fixed
15
+
16
+ - **First start of the MCP server.** `npx -y sniff-qa --mcp` had to download about 250 MB of
17
+ dependencies before it could answer the handshake. On a cold machine that took 23 to 92 s, past
18
+ Claude Code's 30 s connect timeout, and a killed download could leave a broken npx cache. Two
19
+ changes fix it. The browser engine (Playwright, axe-core for Playwright, Lighthouse,
20
+ chrome-launcher) is no longer an npm dependency: sniff downloads it on first use. The other
21
+ runtime dependencies are bundled into `dist/`, so the package depends on `zod` alone. The first
22
+ start now downloads two small packages. `npm run cold-start` re-measures it.
23
+ - **Licenses of bundled code.** `THIRD-PARTY-NOTICES.md` ships in the package with the license
24
+ text of every bundled package.
25
+ - **No "packages it lists are not installed" note in `claude plugin list`.** Claude Code installs
26
+ a plugin's npm dependencies when it caches the plugin. The old dependency tree was too large for
27
+ that step; the new one installs in seconds.
28
+ - `--help` printed the `--fail-on` default twice.
29
+
30
+ ### Added
31
+
32
+ - **`sniff install [browsers...]`** downloads the browser engine (about 200 MB, once per sniff
33
+ version, into `~/.cache/sniff-qa/engine/<version>`) and Chromium, so the first walk starts at
34
+ once. `--with-deps` also installs the Linux system libraries; `--deps-only` installs only those.
35
+ `SNIFF_ENGINE_DIR` moves the engine folder.
36
+ - The first CLI walk still downloads everything it needs by itself, with progress on stderr.
37
+ - The `sniff_install` MCP tool now downloads the engine too. Browser tools still answer
38
+ `needsSetup: playwright-browsers` until it has run, so no tool call blocks on a silent download.
39
+ - `sniff doctor` says where the engine loads from, or that it is not downloaded yet.
40
+
41
+ ### Changed
42
+
43
+ - Install hints say `npx -y sniff-qa@<version> install <browser>` instead of
44
+ `npx playwright install <browser>`, which could fetch a Playwright that does not match sniff's.
45
+ - `sniff ci` writes a workflow that runs `sniff-qa install --with-deps chromium` and caches
46
+ `~/.cache/sniff-qa` next to the Playwright browsers.
47
+ - A project that installs `playwright` or `lighthouse` itself keeps using its own copy.
48
+
49
+ ## [0.9.0] - 2026-11-17
50
+
51
+ Every report now opens with the answer. The first walk on a new machine works.
52
+
53
+ ### Changed
54
+
55
+ - **Verdict first.** The terminal report, the HTML report and the MCP walk result now open with a
56
+ `PASS` or `FAIL` line and the three findings to fix first. The detail follows. In the
57
+ terminal the verdict follows the real exit decision, so `--fail-on` and `assert` budgets show in it.
58
+ - **Shorter report lines.** Screenshot paths print relative to the folder you ran sniff in.
59
+ - **Help that starts with the commands people type,** and the exit codes.
60
+ - **Pinned launchers.** `.mcp.json` and the plugin manifests run `sniff-qa@0.9.0`, so every plugin
61
+ user runs the same code.
62
+ - `npm test` runs the suite once (`vitest run`). Watch mode moved to `npm run test:watch`.
63
+
64
+ ### Fixed
65
+
66
+ - **The first walk no longer crashes when Chromium was never downloaded.** The browser check
67
+ tested a path Playwright returns even when the file is absent. It now tests the file, so sniff
68
+ downloads the browser. `sniff doctor` reports the browser correctly too.
69
+ - The browser download prints to stderr, so `--json` output stays parseable.
70
+ - `npm audit --omit=dev` reports 0 vulnerabilities after a lockfile refresh.
71
+
72
+ ### Added
73
+
74
+ - `server.json` lists the npm package, so MCP registry clients can install sniff.
75
+ The release workflow now publishes to the registry.
76
+ - `gemini-extension.json` for the Gemini CLI.
77
+ - `npm run proof` re-prints the fixture score the README quotes.
78
+ - A test keeps the version equal across every manifest and checks the README names each MCP tool.
79
+ - `.claude-plugin/icon.png`, so `claude plugin validate --strict` passes. The contributor notes moved
80
+ from `CLAUDE.md` to `.claude/CLAUDE.md`, which Claude Code still loads, so the plugin root holds
81
+ no file the plugin loader ignores.
82
+
10
83
  ## [0.8.1] - 2026-09-03
11
84
 
12
85
  A motion identity, and the literal synthwave scenery removed. No behaviour changes.
package/NOTICE CHANGED
@@ -8,7 +8,10 @@ If you use Sniff in your project, a mention or attribution is appreciated:
8
8
  - "QA powered by Sniff (https://github.com/Aboudjem/sniff)"
9
9
 
10
10
  Third-party licenses:
11
- - Playwright (Apache-2.0) - https://playwright.dev
12
- - axe-core (MPL-2.0) - https://www.deque.com/axe/
13
- - Lighthouse (Apache-2.0) - https://developer.chrome.com/docs/lighthouse
14
- - pixelmatch (ISC) - https://github.com/mapbox/pixelmatch
11
+ - The packages bundled into dist/ are listed, with their license texts, in
12
+ THIRD-PARTY-NOTICES.md.
13
+ - pixelmatch (ISC) - https://github.com/mapbox/pixelmatch (bundled)
14
+ - The browser engine is downloaded on first use, with its own licenses, not bundled:
15
+ - Playwright (Apache-2.0) - https://playwright.dev
16
+ - axe-core (MPL-2.0) - https://www.deque.com/axe/
17
+ - Lighthouse (Apache-2.0) - https://developer.chrome.com/docs/lighthouse
package/README.md CHANGED
@@ -8,100 +8,130 @@
8
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
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
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>
12
11
  </p>
13
12
 
14
13
  <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>
15
14
 
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>
15
+ <p align="center"><b>Point it at your running app. It clicks through your pages in a real browser and tells you what is broken, with the steps to reproduce it.</b></p>
17
16
 
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>
19
-
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%">
17
+ <p align="center"><a href="#what-you-get">What you get</a> · <a href="#install">Install</a> · <a href="#how-it-works">How it works</a> · <a href="#works-with">Works with</a> · <a href="#proof">Proof</a> · <a href="#faq">FAQ</a> · <a href="#limits">Limits</a></p>
21
18
 
22
19
  ```bash
23
- claude plugin marketplace add Aboudjem/10x
24
- claude plugin install sniff@10x
20
+ npx sniff-qa --url http://localhost:3000
25
21
  ```
26
22
 
27
- ## What it does
23
+ ## What you get
28
24
 
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.
25
+ A report that opens with the verdict, then the three things to fix first, then every finding.
26
+ This is the report from a real run on this repo's planted-bug fixture (2026-11-17, sniff 0.9.0).
27
+ The progress lines that print before it are left out.
32
28
 
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.
29
+ ```text
30
+ VERDICT FAIL: 26 findings (1 critical, 13 high, 11 medium, 1 low)
31
+ Walked 12 pages, checked 13 links, in 53.8s. 1 low-confidence finding hidden, show with --all.
39
32
 
40
- ## Install
33
+ Fix these first:
34
+ 1. Page returns HTTP 500 on /crash [critical]
35
+ 2. Page returns HTTP 404 on /dead [high]
36
+ 3. Page returns HTTP 404 on /missing [high]
41
37
 
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:
38
+ Every finding, with the steps that reproduce it:
44
39
 
45
- ```bash
46
- npx skills add Aboudjem/sniff
40
+ CRITICAL (1)
41
+ • [confirmed] Page returns HTTP 500
42
+ /crash (route/broken-page)
43
+ - Navigate to /crash
44
+ - Server responded with HTTP 500
45
+ fix: The route throws server-side. Check the server logs/handler for this path and return a valid page or a proper error page.
46
+ shot: sniff-reports/crawl/_crash-desktop.png
47
47
  ```
48
48
 
49
- To use it as a plain command line tool, with no editor involved:
49
+ Each finding carries a severity, a confidence label, the route, the steps, a fix and a screenshot.
50
+
51
+ To reproduce it from a clone, start the fixture, then walk it from a second terminal:
50
52
 
51
53
  ```bash
52
- npx sniff-qa --url http://localhost:3000
54
+ node sniff-tests/planted-bugs/server.mjs 4517
55
+ npx sniff-qa --url http://localhost:4517
53
56
  ```
54
57
 
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.
58
+ | Output | Flag | Use it for |
59
+ | :-------------- | :---------- | :------------------------------------------ |
60
+ | Terminal report | (default) | Reading the result now |
61
+ | HTML page | `--report` | Sending to someone, one self-contained file |
62
+ | JSON | `--json` | Scripts and other tools |
63
+ | Exit code | `--fail-on` | Failing CI on real bugs |
57
64
 
58
- <details>
59
- <summary>Node version, project install, and CI</summary>
65
+ | Exit code | Meaning |
66
+ | :-------- | :------------------------------------------------------------------------------ |
67
+ | `0` | No finding reached the `--fail-on` severities (default: critical and high) |
68
+ | `1` | A finding reached them, an `assert` budget was breached, or sniff could not run |
60
69
 
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>
70
+ <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%">
71
+
72
+ ## Install
64
73
 
65
- ## Use it
74
+ Node.js 22 or newer. Pick one path.
66
75
 
67
- **1. Start your app,** with whatever dev server your project already uses.
76
+ **Command line, no editor.** Start your app, then walk it from a second terminal:
68
77
 
69
78
  ```bash
70
- npm run dev
79
+ npx sniff-qa --url http://localhost:3000
71
80
  ```
72
81
 
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.
82
+ The npm package is `sniff-qa`. Do not run `npx sniff`: that is an unrelated package.
83
+
84
+ **Claude Code plugin**, through the [10x marketplace](https://github.com/Aboudjem/10x):
75
85
 
76
86
  ```bash
77
- npx sniff-qa --url http://localhost:3000
87
+ claude plugin marketplace add Aboudjem/10x
88
+ claude plugin install sniff@10x
78
89
  ```
79
90
 
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`:
91
+ **Skills for any agent**, through the Vercel skills CLI:
82
92
 
83
- ```text
84
- sniff v0.8.0 walking http://localhost:4321
93
+ ```bash
94
+ npx skills add Aboudjem/sniff
95
+ ```
85
96
 
86
- 26 findings (+1 low-confidence hidden; use --all)
97
+ **MCP server**, for any MCP client:
87
98
 
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
99
+ ```bash
100
+ claude mcp add sniff-qa -- npx -y sniff-qa --mcp
101
+ ```
102
+
103
+ The first walk downloads two things, once: the browser engine (Playwright, axe-core and
104
+ Lighthouse, about 200 MB) and Chromium (about 165 MB). Both took 159 s here on 2026-11-17.
105
+ To do it ahead of time, run:
95
106
 
96
- ✓ Scan complete: 26 issue(s) found. Exit code 1 so CI fails on bugs; pass --fail-on none to always exit 0.
107
+ ```bash
108
+ npx sniff-qa install
97
109
  ```
98
110
 
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.
111
+ It ends with the time it took. `npx sniff-qa doctor` checks Node, the browser and your dev server.
112
+
113
+ The MCP server starts before those downloads. On a cold machine (empty npm cache),
114
+ `npx -y sniff-qa@0.9.1 --mcp` answered its first handshake in 1.4 to 1.9 s (5 runs of the release build). Version 0.9.0 took 23 to 92 s,
115
+ past Claude Code's 30 s connect limit. `npm run cold-start` re-measures it in a clone of this repo.
116
+
117
+ <details>
118
+ <summary>Project install and CI</summary>
119
+
120
+ `npm install -D sniff-qa` adds it to a project. `npx sniff-qa ci` writes a GitHub Actions workflow
121
+ with browser caching and report artifacts.
122
+ </details>
123
+
124
+ ## How it works
101
125
 
102
126
  <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%">
103
127
 
104
- ## What you get
128
+ 1. **Find the app.** It uses `--url`, or a dev server on a common port.
129
+ 2. **Walk it.** A headless Chromium follows your links, clicks buttons and fills forms, like a user.
130
+ 3. **Judge what happened.** Each page is checked for 12 classes of bugs.
131
+ 4. **Prove it.** A finding needs a route, the steps, a screenshot and the console or network excerpt.
132
+ 5. **Report.** Verdict first, then the fix-first list, then the detail.
133
+
134
+ The 12 classes:
105
135
 
106
136
  <picture>
107
137
  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/Aboudjem/sniff/main/.github/assets/features-dark.svg">
@@ -109,73 +139,110 @@ the environment looks wrong.
109
139
  <img alt="The 12 classes of bugs sniff finds" src="https://raw.githubusercontent.com/Aboudjem/sniff/main/.github/assets/features-light.svg" width="100%">
110
140
  </picture>
111
141
 
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`.
142
+ With no app running, `sniff` reads your source instead (`sniff scan`). It flags debug statements,
143
+ placeholder text and broken imports, and tells you how to start the real walk.
116
144
 
117
- New in 0.8.0:
145
+ The MCP server exposes these tools:
118
146
 
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.
147
+ | Tool | What it does |
148
+ | :--------------- | :------------------------------------------------------ |
149
+ | `sniff` | One entry point: `mode: "walk"`, `"scan"` or `"report"` |
150
+ | `sniff_scan` | Source-only scan, no browser |
151
+ | `sniff_run` | Source scan plus browser checks |
152
+ | `sniff_discover` | Generates scenarios from your source and drives them |
153
+ | `sniff_install` | Downloads the Playwright browser |
154
+ | `sniff_report` | Reads the last saved results |
125
155
 
126
- ## Works in your editor
156
+ `--caps scan,report` narrows the server to `sniff_scan`, `sniff_report` and the unified `sniff` tool, with no browser at all.
127
157
 
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.
158
+ ## Works with
130
159
 
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) |
160
+ Each row was tested on 2026-11-17 against the sniff 0.9.0 build.
138
161
 
139
- <details>
140
- <summary>Add it as an MCP server instead</summary>
162
+ | Agent | What ran | Tested |
163
+ | :------------- | :------------------------------------------------------------------------------- | :--------- |
164
+ | Claude Code | `claude -p` with sniff as an MCP server called `sniff_scan` and read 2 findings | 2026-11-17 |
165
+ | Codex CLI | `codex exec` with sniff as an MCP server called `sniff_scan` and read 2 findings | 2026-11-17 |
166
+ | Gemini CLI | `gemini extensions validate .` accepted `gemini-extension.json` | 2026-11-17 |
167
+ | Any MCP client | `node sniff-tests/mcp-smoke.mjs` listed 6 tools and a walk returned 20 findings | 2026-11-17 |
168
+ | Skills CLI | `npx skills@1.9.0 add Aboudjem/sniff` installed the 3 skills into a temp folder | 2026-11-17 |
169
+
170
+ Documented, not tested today: Cursor, VS Code with Copilot, Windsurf, OpenCode and Zed.
171
+ Their snippets are in [docs/editors.md](docs/editors.md).
172
+
173
+ ## Proof
174
+
175
+ Three commands re-print the numbers on this page. The first prints the fixture score.
141
176
 
142
177
  ```bash
143
- claude mcp add sniff-qa npx -- -y sniff-qa --mcp
144
- codex mcp add sniff-qa -- npx -y sniff-qa --mcp
178
+ npm run build && npm run proof
145
179
  ```
146
180
 
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).
149
- </details>
181
+ It starts the planted-bug fixture, walks it, and scores the report. Output on 2026-11-17:
182
+
183
+ ```text
184
+ Recall: 21/21 (100%)
185
+ Findings: 27 deduped (27 raw)
186
+ Matched: 27 Candidate FP: 0 Precision proxy: 100%
187
+ Hard FP on clean page (/clean): 0
188
+ ```
189
+
190
+ The sample above shows 26 findings and this run counts 27. The proof run uses `--all`, which adds the 1 low-confidence finding.
191
+
192
+ The fixture holds 21 planted bugs across all 12 classes, plus a clean control page.
193
+ The scorer is [sniff-tests/score-fixture.mjs](sniff-tests/score-fixture.mjs).
194
+ The bugs are listed in [sniff-tests/planted-bugs/MANIFEST.json](sniff-tests/planted-bugs/MANIFEST.json).
195
+
196
+ ```bash
197
+ npm test
198
+ ```
199
+
200
+ Prints `Test Files 52 passed (52)` and `Tests 555 passed (555)` on 2026-11-17.
201
+ The suite includes the fixture gate. It fails the build if recall drops below 85%.
202
+ It also fails on any finding on the clean page.
203
+
204
+ ```bash
205
+ node sniff-tests/mcp-smoke.mjs
206
+ ```
207
+
208
+ Prints the 6 MCP tools and the 20 findings quoted in the table above.
209
+
210
+ ## FAQ
211
+
212
+ **Do I need an API key or an account?**
213
+ No. The walk and the source scan run on your machine. Nothing is sent anywhere unless you set up the optional AI exploration yourself.
214
+
215
+ **Will a walk change data in my app?**
216
+ It can. A walk clicks buttons and submits real forms, so point it at a dev or staging app.
217
+
218
+ **Why did it exit 1 when nothing crashed?**
219
+ Exit 1 means it found bugs at a failing severity, so CI fails the build. Pass `--fail-on none` to always exit 0.
220
+
221
+ **Will it edit my code?**
222
+ No. Walking and scanning never touch your source. Only `sniff fix` edits files, and only when you run it.
150
223
 
151
- ## Good to know
224
+ **Can it walk a logged-in app?**
225
+ Yes. Pass `--storage-state auth.json`. Cookie and token values from that file are redacted from the written reports.
152
226
 
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.
227
+ More answers are in [docs/faq.md](docs/faq.md).
157
228
 
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.
229
+ ## Limits
162
230
 
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.
231
+ - It needs a running app for the walk. Without one you only get the source scan.
232
+ - The first walk needs internet to download the browser engine and Chromium once, about 365 MB.
233
+ - Until then, MCP browser tools answer `needsSetup` and the agent calls `sniff_install` first.
234
+ - Dead-link checking follows external links, so a walk requests the third-party URLs your pages link to.
235
+ - Redaction covers report text, not screenshot pixels. A screenshot of a logged-in page can show private data.
236
+ - It finds what a user would see. It does not read your server logs or measure load.
169
237
 
170
238
  ## Learn more
171
239
 
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
240
+ - [docs/editors.md](docs/editors.md): install and MCP snippets for every agent
241
+ - [docs/authenticated-walks.md](docs/authenticated-walks.md): walking a logged-in app
242
+ - [docs/assert-budgets.md](docs/assert-budgets.md): capping findings by severity in `sniff.config`
243
+ - [docs/comparison.md](docs/comparison.md): how sniff differs from linters and E2E frameworks
177
244
  - [CHANGELOG.md](CHANGELOG.md) · [CONTRIBUTING.md](CONTRIBUTING.md) · [LICENSE](LICENSE)
178
245
 
179
246
  ---
180
247
 
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>
248
+ <p align="center"><sub>Built by <a href="https://github.com/Aboudjem">Adam Boudjemaa</a> · <a href="LICENSE">Apache 2.0</a> · built on <a href="https://playwright.dev">Playwright</a> and <a href="https://github.com/dequelabs/axe-core">axe-core</a></sub></p>