sniff-qa 0.6.1 → 0.7.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.
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "sniff",
3
- "version": "0.6.1",
3
+ "version": "0.7.0",
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 Boudj",
package/CHANGELOG.md CHANGED
@@ -5,7 +5,33 @@ All notable changes to this project will be documented in this file.
5
5
  The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6
6
  and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
7
 
8
- ## [Unreleased]
8
+ ## [0.7.0] - 2026-05-29
9
+
10
+ Portability and discoverability layer: a multi-CLI installer, auto-discovery manifests, a GitHub Pages demo, and localized READMEs, on top of the earlier documentation polish. No change to the scanner engine or its findings.
11
+
12
+ ### Added
13
+
14
+ - Multi-CLI installer: `install.sh` and `install.ps1` symlink the `/sniff`, `/sniff-fix`, and `/sniff-report` skills into a target CLI's skills directory, with `--update` and `--uninstall` and a one-line curl install. The MCP server stays the universal fallback.
15
+ - Auto-discovery manifests: `.cursor-plugin/plugin.json` and `.copilot-plugin/plugin.json`, mirroring `.claude-plugin/plugin.json`.
16
+ - GitHub Pages demo: `site/index.html` plus `.github/workflows/deploy-pages.yml`, reusing the existing demo assets and a sample report.
17
+ - README: a language-switcher row, a multi-platform install matrix with a one-line curl, an npm downloads badge, and a Star History chart.
18
+ - Localized READMEs under `READMEs/` for zh-CN, ja, es, and fr (machine-assisted; English stays the source of truth).
19
+ - Demo video: `.github/assets/demo.gif` (hero) plus an `.mp4` and an embed guide.
20
+
21
+ ### Changed
22
+
23
+ - Rebuilt the features and hero SVGs around the flow-walk model, and removed emoji from them.
24
+ - Named the slash commands and MCP tools in the README.
25
+
26
+ ### Removed
27
+
28
+ - Stale pre-0.6.0 SVG assets and the internal rebuild docs.
29
+
30
+ ### Fixed
31
+
32
+ - `.github/FUNDING.yml`: corrected the GitHub Sponsors handle to `Aboudjem` (the previous value did not resolve).
33
+ - Animated SVGs now respect `prefers-reduced-motion`.
34
+ - Removed sentence-break em-dashes from the docs.
9
35
 
10
36
  ## [0.6.1] - 2026-05-28
11
37
 
package/README.md CHANGED
@@ -6,6 +6,7 @@
6
6
 
7
7
  <p align="center">
8
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>
9
10
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache_2.0-ef4444?style=flat-square" alt="License"></a>
10
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>
11
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,7 +14,15 @@
13
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>
14
15
  </p>
15
16
 
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's actually broken — with proof.</b></p>
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>
17
26
 
18
27
  <p align="center">
19
28
  <a href="#get-started">Get started</a> ·
@@ -24,6 +33,8 @@
24
33
  <a href="#faq">FAQ</a>
25
34
  </p>
26
35
 
36
+ ![sniff demo](.github/assets/demo.gif)
37
+
27
38
  <picture>
28
39
  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/Aboudjem/sniff/main/.github/assets/sniff-diagram.svg">
29
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%">
@@ -33,7 +44,7 @@
33
44
 
34
45
  ## What is this?
35
46
 
36
- 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.
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.
37
48
 
38
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.
39
50
 
@@ -43,7 +54,7 @@ Every bug it reports comes with **proof**: the exact page, the ordered steps to
43
54
  npx sniff-qa --url http://localhost:3000
44
55
  ```
45
56
 
46
- 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.
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.
47
58
 
48
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).
49
60
 
@@ -53,7 +64,7 @@ One command — no config, no API key, no Playwright setup. Point it at your run
53
64
 
54
65
  You need **Node.js 22+** and a web app you can run locally (or a URL).
55
66
 
56
- > **Naming:** the npm package is **`sniff-qa`** — 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.
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.
57
68
 
58
69
  ### 1. Start your app
59
70
 
@@ -69,13 +80,13 @@ In another terminal:
69
80
  npx sniff-qa --url http://localhost:3000 # point it at your running app
70
81
  ```
71
82
 
72
- 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:
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:
73
84
 
74
85
  ```bash
75
86
  npx sniff-qa --url https://staging.myapp.com
76
87
  ```
77
88
 
78
- > **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`.
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`.
79
90
 
80
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.
81
92
 
@@ -87,7 +98,7 @@ Findings print to your terminal, grouped by severity, each with steps to reprodu
87
98
  npx sniff-qa --url http://localhost:3000 --report # runs a walk, then writes sniff-reports/sniff-report.html (self-contained)
88
99
  ```
89
100
 
90
- **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:
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:
91
102
 
92
103
  ```bash
93
104
  npx sniff-qa scan # source-only scan, no browser
@@ -113,14 +124,14 @@ Sniff walks your app and looks for **12 classes of real bugs**:
113
124
  | 8 | **Bad loading & error states** | Infinite spinners, missing error states |
114
125
  | 9 | **Broken async outcomes** | Submitted but no success feedback (flagged "needs out-of-band verification") |
115
126
  | 10 | **Responsive issues** | Overflow and tiny tap targets (a 375px mobile pass) |
116
- | 11 | **Accessibility** | Missing alt text and labels, contrast — via [axe-core](https://github.com/dequelabs/axe-core) |
127
+ | 11 | **Accessibility** | Missing alt text and labels, contrast, via [axe-core](https://github.com/dequelabs/axe-core) |
117
128
  | 12 | **Unclear primary actions** | The main call-to-action is buried or ambiguous |
118
129
 
119
130
  Each finding ships with:
120
131
 
121
- - **Reproduction proof** — the exact route, the ordered steps, a screenshot, and the console/network excerpt.
122
- - **A severity** — so you fix the right thing first.
123
- - **A confidence** — `confirmed`, `likely`, or `uncertain`. Uncertain findings are hidden by default; add `--all` to see them.
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.
124
135
  - **A suggested fix.**
125
136
 
126
137
  <picture>
@@ -142,14 +153,14 @@ We measured it on a fixture app planted with **21 bugs across all 12 classes**,
142
153
  | Bugs found | 9 / 21 (43%) | **21 / 21 (100%)** |
143
154
  | Precision | ~13% | **100%** |
144
155
  | False positives | 125 | **0** |
145
- | Findings on the clean page | — | **0** |
156
+ | Findings on the clean page | n/a | **0** |
146
157
  | Flagship command | crashed | works |
147
158
 
148
159
  Those numbers are locked as a regression test. The full suite is **441 tests**.
149
160
 
150
161
  **How it keeps false positives near zero:**
151
162
 
152
- - A first-party **noise filter** drops the junk that isn't your bug — favicons, analytics, hot-module-reload chatter, expected auth redirects, engine aborts.
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.
153
164
  - Accessibility findings are backed by **axe-core**, which is zero-false-positive by design.
154
165
  - **Uncertain findings are suppressed by default** (use `--all` to see them).
155
166
  - A broken page is reported **once**, not re-flagged on every link that points to it.
@@ -174,7 +185,7 @@ Linters read your source. End-to-end frameworks make *you* write the tests. Link
174
185
  | Self-contained HTML report | **Yes** | No | Partial | No | Dashboard |
175
186
  | Runs locally, no account, no API key | **Yes** | Yes | Yes | Yes | No (service) |
176
187
 
177
- 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**.
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**.
178
189
 
179
190
  ---
180
191
 
@@ -210,7 +221,9 @@ sniff --version Show the version
210
221
 
211
222
  ## Demo
212
223
 
213
- A real run against a buggy app — 21 real issues, zero false positives, every finding with severity, confidence, reproduction steps, and a fix:
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:
214
227
 
215
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%">
216
229
 
@@ -218,16 +231,51 @@ A real run against a buggy app — 21 real issues, zero false positives, every f
218
231
 
219
232
  ## Use it from your AI editor
220
233
 
221
- 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 — you don't have to pass a URL.
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.
222
235
 
223
236
  **One unified `sniff` tool, three modes:**
224
237
 
225
- - `walk` — **recommended.** Walks your running app's real flows (the flow-walk above).
226
- - `scan` — source-only scan, no browser.
227
- - `report` — show the last run's results.
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.
228
241
 
229
242
  (`run` and `discover` are legacy modes kept for back-compat.)
230
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.
255
+
256
+ ### Install the skills into any AI CLI
257
+
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.
259
+
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).
265
+
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.
278
+
231
279
  <details>
232
280
  <summary><b>Claude Code</b></summary>
233
281
 
@@ -304,17 +352,17 @@ mcpServers:
304
352
  ```
305
353
  </details>
306
354
 
307
- > 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.
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.
308
356
 
309
357
  ---
310
358
 
311
359
  ## How it works
312
360
 
313
361
  1. **Find the app.** Sniff auto-detects your running dev server (or you pass `--url`).
314
- 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.
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.
315
363
  3. **Watch everything.** It records console errors, failed network requests, broken renders, missing feedback, and accessibility issues as it goes.
316
364
  4. **Filter the noise.** The first-party noise filter and axe-core drop the false positives; uncertain findings are held back.
317
- 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.
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.
318
366
 
319
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%">
320
368
 
@@ -341,7 +389,7 @@ This writes `.github/workflows/sniff.yml` with browser caching and report artifa
341
389
  ## FAQ
342
390
 
343
391
  **Does it work without a dev server?**
344
- 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.
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.
345
393
 
346
394
  **What gets downloaded on first run?**
347
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.
@@ -350,22 +398,34 @@ The first time Sniff opens a browser, it downloads a Chromium build (~165 MB, on
350
398
  No. Sniff runs entirely on your machine with no API key and no signup. Your code and your app never leave your computer.
351
399
 
352
400
  **How is it different from a linter?**
353
- 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.
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.
354
402
 
355
403
  **How is it different from Playwright codegen (or writing E2E tests)?**
356
- 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).
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).
357
405
 
358
406
  **Will it change my code?**
359
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.
360
408
 
361
409
  **What stacks does it work with?**
362
- 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.
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.
363
411
 
364
412
  ---
365
413
 
366
414
  ## Works first-class in
367
415
 
368
- 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.
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>
369
429
 
370
430
  ---
371
431
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "sniff-qa",
3
- "version": "0.6.1",
3
+ "version": "0.7.0",
4
4
  "description": "Autonomous QA scanner: point it at your running app and it walks the real user flows in a headless browser and reports what's actually broken — broken pages/links, console & network errors, empty/placeholder data, broken forms, state-loss, bad loading/error states, responsive and accessibility issues — each with reproduction proof, severity, confidence, and a fix. CLI + MCP server. No API key. Uses Playwright and axe-core.",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",