argusqa-os 9.9.0 → 10.0.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.
- package/README.md +524 -419
- package/glama.json +1 -1
- package/package.json +10 -3
- package/src/mcp-server.js +25 -12
- package/src/orchestration/report-processor.js +45 -2
- package/src/utils/governance-seam.js +237 -0
- package/src/utils/redaction-policy.js +278 -0
- package/src/utils/secret-patterns.js +444 -428
- package/src/utils/sensitivity-classifier.js +563 -498
- package/src/utils/team-vault.js +166 -0
package/README.md
CHANGED
|
@@ -1,419 +1,524 @@
|
|
|
1
|
-
<div align="center">
|
|
2
|
-
|
|
3
|
-
# Argus — AI-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
[](https://glama.ai/mcp/servers/ironclawdevs27/Argus)
|
|
8
|
+
|
|
9
|
+
[](https://www.npmjs.com/package/argusqa-os)
|
|
10
|
+
[](test-harness/)
|
|
11
|
+
[](LICENSE)
|
|
12
|
+
|
|
13
|
+
One line in your MCP config gives Claude (or any MCP agent) a real Chrome audit engine —
|
|
14
|
+
**67 audit categories · 149 finding types · zero test files to write or maintain.**
|
|
15
|
+
And with **Aegis**, what it finds **never leaks your secrets to the LLM**.
|
|
16
|
+
|
|
17
|
+
<!-- TODO(GTM): record the 30-second "Argus catches a real bug" GIF and embed it here.
|
|
18
|
+
This is the single highest-leverage asset in the repo. Until then the landing link stands in. -->
|
|
19
|
+
**[▶ See it in action → argus-qa.com](https://argus-qa.com)**
|
|
20
|
+
|
|
21
|
+
[Quick Start](#quick-start) · [The Fix Loop](#the-fix-loop) · [What It Catches](#what-argus-catches) · [Your Stack](#works-with-your-stack) · [MCP Tools](#mcp-tools) · [Full Setup](#full-setup) · [Reference](REFERENCE.md)
|
|
22
|
+
|
|
23
|
+
</div>
|
|
24
|
+
|
|
25
|
+
---
|
|
26
|
+
|
|
27
|
+
## Why Argus Exists
|
|
28
|
+
|
|
29
|
+
AI agents now write most of the code — and they judge their own work by whether it *compiles and looks done*, not by what actually happens in the browser. The uncaught exception on the third click. The form that posts credentials over HTTP. The 4-second LCP. The button that vanished in dark mode. The API endpoint hammered in an infinite loop.
|
|
30
|
+
|
|
31
|
+
**Argus closes that gap.** It drives a real Chrome (via the Chrome DevTools Protocol) against your locally-running app and hands the agent — or you — a structured, severity-ranked bug report. The agent fixes; Argus re-checks; the loop closes *before* the code leaves your machine.
|
|
32
|
+
|
|
33
|
+
| | |
|
|
34
|
+
|---|---|
|
|
35
|
+
| 🧪 **No test files, ever** | Argus audits the *rendered app* — DOM, console, network, pixels — not your source. Nothing to write, nothing to maintain when the agent refactors |
|
|
36
|
+
| 🤖 **Built for the agent loop** | The only QA engine Claude can call natively over MCP. Audit → fix → re-audit without leaving the conversation |
|
|
37
|
+
| 🔒 **Safe for agents by default** | **Aegis**: findings are redacted at every egress boundary — secrets, PII, and exploit detail never reach the LLM's context window (OWASP LLM02, default-ON, fail-closed) |
|
|
38
|
+
| 🧰 **Also a normal QA tool** | CLI batch audits, a GitHub Action PR gate, Slack reports with screenshots, dev-vs-staging diffs, watch mode — with or without an agent |
|
|
39
|
+
|
|
40
|
+
---
|
|
41
|
+
|
|
42
|
+
## Quick Start
|
|
43
|
+
|
|
44
|
+
> **No install.** `npx` fetches Argus on first run.
|
|
45
|
+
|
|
46
|
+
**1 — Add two lines to `.mcp.json`** in your project root:
|
|
47
|
+
|
|
48
|
+
```json
|
|
49
|
+
{
|
|
50
|
+
"mcpServers": {
|
|
51
|
+
"chrome-devtools": { "command": "npx", "args": ["-y", "chrome-devtools-mcp@latest"] },
|
|
52
|
+
"argus": { "command": "npx", "args": ["-y", "argusqa-os"] }
|
|
53
|
+
}
|
|
54
|
+
}
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
Or via the Claude Code CLI:
|
|
58
|
+
|
|
59
|
+
```bash
|
|
60
|
+
claude mcp add chrome-devtools -- npx -y chrome-devtools-mcp@latest
|
|
61
|
+
claude mcp add argus -- npx -y argusqa-os
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
**2 — Launch Chrome** (auto-detects your Chrome, sets the right flags):
|
|
65
|
+
|
|
66
|
+
```bash
|
|
67
|
+
npx -y -p argusqa-os argus-chrome
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
<details>
|
|
71
|
+
<summary>Prefer launching Chrome manually? (macOS / Windows / Linux commands)</summary>
|
|
72
|
+
|
|
73
|
+
```bash
|
|
74
|
+
# macOS
|
|
75
|
+
open -a "Google Chrome" --args --remote-debugging-port=9222 --headless=new
|
|
76
|
+
|
|
77
|
+
# Windows (PowerShell)
|
|
78
|
+
& "C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222 --headless=new --no-sandbox --disable-gpu --user-data-dir="$env:TEMP\chrome-argus"
|
|
79
|
+
|
|
80
|
+
# Linux
|
|
81
|
+
google-chrome --remote-debugging-port=9222 --headless=new --no-sandbox
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
</details>
|
|
85
|
+
|
|
86
|
+
**3 — Ask your agent:**
|
|
87
|
+
|
|
88
|
+
```
|
|
89
|
+
Run argus_audit on http://localhost:3000
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
That's it. Findings come back structured and severity-ranked — into the conversation, to Slack, or as a local `report.html`. Something off? `npx -y -p argusqa-os argus-doctor` diagnoses your setup in one command.
|
|
93
|
+
|
|
94
|
+
---
|
|
95
|
+
|
|
96
|
+
## The Fix Loop
|
|
97
|
+
|
|
98
|
+
This is what Argus looks like inside an agentic coding session:
|
|
99
|
+
|
|
100
|
+
```
|
|
101
|
+
You: Build me a checkout page with a card form.
|
|
102
|
+
Agent: [writes the code, dev server renders it]
|
|
103
|
+
|
|
104
|
+
You: Run argus_audit on http://localhost:3000/checkout
|
|
105
|
+
Argus: ● 2 critical · 3 warnings
|
|
106
|
+
● uncaught TypeError in checkout.js (visible on submit)
|
|
107
|
+
● form posts over HTTP — security_no_https
|
|
108
|
+
▲ card inputs missing labels + autocomplete (a11y/WCAG)
|
|
109
|
+
▲ LCP 4.1s — hero image unoptimized
|
|
110
|
+
▲ duplicate POST /api/cart ×7 — likely render loop
|
|
111
|
+
|
|
112
|
+
Agent: [fixes all five]
|
|
113
|
+
|
|
114
|
+
You: Run argus_get_context
|
|
115
|
+
Argus: ✓ resolved: 5 · persisting: 0 · new: 0
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
`argus_get_context` diffs against the previous snapshot, so the agent knows exactly what it fixed, what it broke, and what remains — no re-reading walls of output.
|
|
119
|
+
|
|
120
|
+
**"But my agent can already drive a browser…"** — it can. Driving isn't judging. A raw browser MCP (Playwright MCP, bare chrome-devtools-mcp) gives the agent hands and eyes; the agent must then *re-derive what to check* every session, burning context on console-log spelunking. Argus is the judgment layer on top: 149 codified finding types with thresholds, severity policy, cross-run baselines, flakiness filtering, dedup, root-cause hints — returned in one call, redacted by default.
|
|
121
|
+
|
|
122
|
+
---
|
|
123
|
+
|
|
124
|
+
## What Argus Catches
|
|
125
|
+
|
|
126
|
+
32 analysis engines, 149 distinct issue types, zero test-file maintenance:
|
|
127
|
+
|
|
128
|
+
| Category | What it detects |
|
|
129
|
+
|---|---|
|
|
130
|
+
| **JavaScript** | Uncaught exceptions, unhandled promise rejections, `console.error` on critical routes |
|
|
131
|
+
| **Network & API** | HTTP 5xx, 401/403 auth failures, duplicate API calls (infinite loops), 4xx errors, broken links |
|
|
132
|
+
| **Performance** | LCP > 2500ms, CLS > 0.1, TTFB > 800ms, slow APIs > 1s/3s, payloads > 500KB/2MB, JS bundles > 500KB |
|
|
133
|
+
| **Accessibility** | axe-core (80+ WCAG rules), color-blind simulation, missing ARIA, keyboard focus, heading hierarchy |
|
|
134
|
+
| **SEO** | Missing meta description, OG tags, canonical, viewport, h1 |
|
|
135
|
+
| **Security** | Auth tokens in localStorage/URL, `eval()`, missing CSP/X-Frame-Options, CSP violations, missing SRI on external scripts, source map exposure, open redirects, npm CVEs |
|
|
136
|
+
| **CSS** | Cascade overrides, component style leaks, unused rules, React inline style conflicts |
|
|
137
|
+
| **Content** | `null`/`undefined` as visible text, lorem ipsum, broken images, empty data lists |
|
|
138
|
+
| **Responsive** | Horizontal overflow at 375px/768px, touch targets < 44×44px |
|
|
139
|
+
| **Memory** | Detached DOM nodes via V8 heap snapshot, heap growth across navigation |
|
|
140
|
+
| **Visual** | Pixel-level screenshot regression via pixelmatch (≥0.1% warning, ≥5% critical) |
|
|
141
|
+
| **Figma** | Design-to-implementation fidelity — 13 property types (color, spacing, typography, shadows, etc.) |
|
|
142
|
+
| **Forms** | Missing `required`, `autocomplete`, `aria-describedby`; unlabelled inputs |
|
|
143
|
+
| **Fonts** | FOIT, FOUT, missing fallbacks, slow loads > 1s, suboptimal formats |
|
|
144
|
+
| **Motion** | `prefers-reduced-motion` violations, `autoplay` without pause controls |
|
|
145
|
+
| **Theme** | Dark-mode gaps — static CSS vars, missing `prefers-color-scheme` handling |
|
|
146
|
+
| **Network baseline** | New requests, missing requests, status-code regressions vs saved HAR baseline |
|
|
147
|
+
| **Environment diff** | Dev vs staging — screenshot diff, DOM changes, console/network regressions |
|
|
148
|
+
|
|
149
|
+
And every finding is post-processed with:
|
|
150
|
+
|
|
151
|
+
| Post-processor | What it adds |
|
|
152
|
+
|---|---|
|
|
153
|
+
| **Intelligent baseline filtering** | Findings that flip-flop across runs are tagged `noisy` and downgraded to info — pure cross-run heuristics, no API calls (`ARGUS_NOISE_FILTER=0` to disable) |
|
|
154
|
+
| **Root cause linking** | New findings are annotated with the recent git commits and files most likely to have caused them (`ARGUS_ROOT_CAUSE=0` to disable) |
|
|
155
|
+
|
|
156
|
+
> All findings are classified as `critical` / `warning` / `info` and routed to the right Slack channel — or surfaced in the local HTML report. For per-finding severity tables and detection methods, see [REFERENCE.md](REFERENCE.md).
|
|
157
|
+
|
|
158
|
+
---
|
|
159
|
+
|
|
160
|
+
## Works With Your Stack
|
|
161
|
+
|
|
162
|
+
Argus audits the **rendered output**, not your source — so it is framework-agnostic by construction. **If it runs in Chrome, Argus can audit it:**
|
|
163
|
+
|
|
164
|
+
| | |
|
|
165
|
+
|---|---|
|
|
166
|
+
| **SPA frameworks** | React, Vue, Angular, Svelte/SvelteKit, Solid, Preact, Astro… |
|
|
167
|
+
| **Meta-frameworks** | Next.js, Nuxt, Remix, Gatsby — plus **framework-aware extras**: Next.js & React Router route discovery, import-graph PR mapping ("this component changed → audit only the routes that render it"), monorepo path awareness |
|
|
168
|
+
| **Server-rendered** | Rails, Django, Laravel, Flask, Spring, PHP — anything that serves HTML to a browser |
|
|
169
|
+
| **Static / no framework** | Plain HTML/CSS/JS, docs sites, landing pages |
|
|
170
|
+
| **APIs (via the page)** | Response schema validation, status/timing checks on every request the page makes |
|
|
171
|
+
|
|
172
|
+
**Honest limits:** Chrome/Chromium rendering only (no Safari/Firefox engine differences), web only (no native mobile/desktop apps), and backend services are checked through the traffic the page generates — not as standalone API test suites.
|
|
173
|
+
|
|
174
|
+
---
|
|
175
|
+
|
|
176
|
+
## Confidentiality — Aegis Egress Boundary
|
|
177
|
+
|
|
178
|
+
> **Default ON.** Argus audits your app for *secrets and vulnerabilities* — so its findings are exactly the data you least want leaving your machine. **Aegis** redacts them at every external boundary before they cross. For teams adopting AI agents, this is the difference between "we use an AI QA tool" and "we can tell our security lead exactly why it's safe."
|
|
179
|
+
|
|
180
|
+
A finding sent to an external sink — an **MCP tool response** (which lands in the calling agent's context window and transits to that agent's model provider), a **Slack** message, a **GitHub** PR comment + its `::error` annotations, the **hosted/CI HTML report**, or **CI logs** — is reduced to a need-to-know projection: a **sensitive** finding crosses as its `type` + `route` + `severity` + a `🔒` marker, and **never** its raw payload (`message`, `evidence`, request/response bodies, headers, cookies, stack). URLs are projected with the query string stripped (tokens hide there). A **benign** finding keeps its message — but that message is still scrubbed for any accidentally-embedded secret or PII.
|
|
181
|
+
|
|
182
|
+
| Principle | Behavior |
|
|
183
|
+
|---|---|
|
|
184
|
+
| **Local fidelity preserved** | The on-disk JSON report and the locally-opened HTML keep **100%** detail — redaction only removes detail on the way *out* |
|
|
185
|
+
| **Fail-closed** | On any classifier error or unknown finding shape, Aegis redacts *more*, never less |
|
|
186
|
+
| **Deny-by-default** | Only an explicit allowlist of safe fields ever crosses; a new field leaks nothing until deliberately allowlisted |
|
|
187
|
+
| **5-layer detection** | Category rules ∪ 13 secret regexes ∪ statistical rarity (entropy / token-efficiency) ∪ 7 Luhn-validated PII rules ∪ context boosting |
|
|
188
|
+
| **Opt-out** | `ARGUS_REDACT_SENSITIVE=0` → output is byte-identical to pre-Aegis |
|
|
189
|
+
|
|
190
|
+
This implements the **OWASP LLM02:2025 — Sensitive Information Disclosure** mitigations (data minimization, redaction, deny-by-default egress filtering) at Argus's own boundaries. An optional, local-only re-hydration vault (`ARGUS_REDACT_VAULT=1`) can mint reversible, information-free tokens for diff-stable artifacts — re-inflate locally with `npm run report:rehydrate`. Full behavior change is documented in [CHANGELOG.md](CHANGELOG.md).
|
|
191
|
+
|
|
192
|
+
---
|
|
193
|
+
|
|
194
|
+
## MCP Tools
|
|
195
|
+
|
|
196
|
+
Ask Claude (or any MCP client) — no terminal required:
|
|
197
|
+
|
|
198
|
+
| Tool | Description |
|
|
199
|
+
|---|---|
|
|
200
|
+
| `argus_audit` | Fast pass — JS, network, accessibility, SEO, security, CSS, content |
|
|
201
|
+
| `argus_audit_full` | Deep pass — adds Lighthouse, responsive checks, memory leak detection, hover-state bugs |
|
|
202
|
+
| `argus_compare` | Diff dev vs staging — screenshots, findings delta, environment regressions |
|
|
203
|
+
| `argus_get_context` | Capture everything broken on the open tab — with `resolved / new / persisting` diff vs the last snapshot (the fix loop) |
|
|
204
|
+
| `argus_watch_snapshot` | Snapshot the open tab without navigating (preserves auth/form state) |
|
|
205
|
+
| `argus_last_report` | Return last JSON report without re-running |
|
|
206
|
+
| `argus_design_audit` | Figma URL → 13 design-token finding types (color, spacing, typography, shadows, etc.) |
|
|
207
|
+
| `argus_visual_diff` | Screenshot baseline comparison. Pass `updateBaseline: true` to reset. |
|
|
208
|
+
| `argus_pr_validate` | Fetch GitHub PR diff → map changed files to affected routes → targeted audit → baseline-aware block decision (blocks on findings the PR *introduces*) + idempotent PR comment + Check Run → `{ blocked, findings, baseline, reporting }` |
|
|
209
|
+
|
|
210
|
+
> Every tool response is projected through the [Aegis egress boundary](#confidentiality--aegis-egress-boundary) before it reaches the agent, and carries an optional `redaction` rider (`{ redacted, total }`) when sensitive detail was withheld.
|
|
211
|
+
|
|
212
|
+
**Example prompts:**
|
|
213
|
+
|
|
214
|
+
```
|
|
215
|
+
Run argus_audit on http://localhost:3000/checkout
|
|
216
|
+
Run argus_audit_full on http://localhost:3000/dashboard
|
|
217
|
+
Run argus_compare
|
|
218
|
+
Run argus_get_context
|
|
219
|
+
```
|
|
220
|
+
|
|
221
|
+
---
|
|
222
|
+
|
|
223
|
+
## Battle-Tested, Not Vibe-Tested
|
|
224
|
+
|
|
225
|
+
Argus's own correctness is enforced the way it audits yours:
|
|
226
|
+
|
|
227
|
+
- **998/998 hard assertions** across a 171-block integration harness driving real Chrome against 64 fixture pages — including per-category negative controls (zero over-fire), golden response schemas for all 9 MCP tools, and an upstream-drift canary that catches chrome-devtools-mcp API changes at version-bump time
|
|
228
|
+
- **495 Chrome-free unit tests** (Vitest) + property-based parser fuzzing
|
|
229
|
+
- **`npm audit`: 0 vulnerabilities** · CodeQL + Dependabot on every PR · [Socket.dev](https://socket.dev/npm/package/argusqa-os): 100/100/100 on vulnerability/quality/license
|
|
230
|
+
- Session files and captured tokens written `0600`, owner-only
|
|
231
|
+
|
|
232
|
+
---
|
|
233
|
+
|
|
234
|
+
## Full Setup
|
|
235
|
+
|
|
236
|
+
### Prerequisites
|
|
237
|
+
|
|
238
|
+
| Requirement | Version |
|
|
239
|
+
|---|---|
|
|
240
|
+
| Node.js | v20.19+ |
|
|
241
|
+
| Chrome | Stable (desktop or headless) |
|
|
242
|
+
| Claude Code | Latest (`npm install -g @anthropic-ai/claude-code`) — or any MCP client |
|
|
243
|
+
| Slack workspace | **Optional** — omit for local `report.html` mode |
|
|
244
|
+
|
|
245
|
+
---
|
|
246
|
+
|
|
247
|
+
### Option A — MCP Server *(recommended for Claude Code users)*
|
|
248
|
+
|
|
249
|
+
No local install needed. Use the [Quick Start](#quick-start) above, then add your target URL:
|
|
250
|
+
|
|
251
|
+
```env
|
|
252
|
+
# .env in your project root
|
|
253
|
+
TARGET_DEV_URL=http://localhost:3000
|
|
254
|
+
TARGET_STAGING_URL=https://staging.example.com # optional — enables argus_compare
|
|
255
|
+
```
|
|
256
|
+
|
|
257
|
+
**Optional — Slack notifications:**
|
|
258
|
+
|
|
259
|
+
1. [api.slack.com/apps](https://api.slack.com/apps) → Create New App → name it **BugBot**
|
|
260
|
+
2. OAuth & Permissions → Bot Token Scopes: `chat:write`, `files:write`, `files:read`
|
|
261
|
+
3. Install to workspace → copy the `xoxb-...` token
|
|
262
|
+
4. Create channels `#bugs-critical`, `#bugs-warnings`, `#bugs-digest` and run `/invite @BugBot` in each
|
|
263
|
+
|
|
264
|
+
```env
|
|
265
|
+
SLACK_BOT_TOKEN=xoxb-...
|
|
266
|
+
SLACK_CHANNEL_CRITICAL=C0000000000
|
|
267
|
+
SLACK_CHANNEL_WARNINGS=C0000000001
|
|
268
|
+
SLACK_CHANNEL_DIGEST=C0000000002
|
|
269
|
+
```
|
|
270
|
+
|
|
271
|
+
> Without Slack: Argus auto-generates `reports/report.html` and opens it in your browser — zero extra config.
|
|
272
|
+
|
|
273
|
+
---
|
|
274
|
+
|
|
275
|
+
### Option B — npm Package (CI / dev dependency)
|
|
276
|
+
|
|
277
|
+
```bash
|
|
278
|
+
npm install --save-dev argusqa-os
|
|
279
|
+
npx argus init # interactive wizard — detects framework, discovers routes, writes .env
|
|
280
|
+
npm run crawl # run after Chrome is started
|
|
281
|
+
```
|
|
282
|
+
|
|
283
|
+
---
|
|
284
|
+
|
|
285
|
+
### Option C — Clone the Repository (contributors / full source)
|
|
286
|
+
|
|
287
|
+
```bash
|
|
288
|
+
git clone https://github.com/ironclawdevs27/Argus.git
|
|
289
|
+
cd Argus
|
|
290
|
+
npm install
|
|
291
|
+
npm run init # interactive setup wizard
|
|
292
|
+
```
|
|
293
|
+
|
|
294
|
+
**Manual setup (skip the wizard):**
|
|
295
|
+
|
|
296
|
+
```bash
|
|
297
|
+
cp .env.example .env
|
|
298
|
+
# Fill in TARGET_DEV_URL and optional Slack tokens
|
|
299
|
+
```
|
|
300
|
+
|
|
301
|
+
Then configure your routes in [src/config/targets.js](src/config/targets.js):
|
|
302
|
+
|
|
303
|
+
```js
|
|
304
|
+
export const routes = [
|
|
305
|
+
{ path: '/', name: 'Home', critical: true, waitFor: 'main' },
|
|
306
|
+
{ path: '/login', name: 'Login', critical: true, waitFor: 'form' },
|
|
307
|
+
{ path: '/dashboard', name: 'Dashboard', critical: true, waitFor: '[data-testid="dashboard"]' },
|
|
308
|
+
{ path: '/settings', name: 'Settings', critical: false, waitFor: null },
|
|
309
|
+
];
|
|
310
|
+
```
|
|
311
|
+
|
|
312
|
+
- `critical: true` — errors on this route go to `#bugs-critical`
|
|
313
|
+
- `waitFor` — CSS selector Argus waits for before capturing (signals page-ready)
|
|
314
|
+
|
|
315
|
+
---
|
|
316
|
+
|
|
317
|
+
## CLI Commands
|
|
318
|
+
|
|
319
|
+
```bash
|
|
320
|
+
npm run chrome # Launch Chrome with --remote-debugging-port=9222 (auto-detects binary)
|
|
321
|
+
npm run doctor # Pre-flight check: Chrome reachable, .mcp.json valid, .env has TARGET_DEV_URL
|
|
322
|
+
npm run crawl # Batch audit of all configured routes
|
|
323
|
+
npm run compare # Dev vs staging diff (CSS-only if no staging URL)
|
|
324
|
+
npm run watch # Passive monitor — polls open Chrome tab every 1s
|
|
325
|
+
npm run report:html # Generate reports/report.html from last JSON audit
|
|
326
|
+
npm run report:pdf # Export HTML report to A4 PDF (requires: npm install puppeteer)
|
|
327
|
+
npm run server # Start Slack slash-command server (port 3001)
|
|
328
|
+
npm run init # Interactive setup wizard
|
|
329
|
+
npm run test:unit # 495 unit tests — no Chrome required
|
|
330
|
+
npm run test:harness # 171-block correctness harness — requires Chrome
|
|
331
|
+
npm run test:harness:log # same, but tees full output to harness-results.txt
|
|
332
|
+
npm run test:coverage # merged unit + harness coverage gate (requires Chrome)
|
|
333
|
+
```
|
|
334
|
+
|
|
335
|
+
**Watch mode** — live monitoring as you (or your agent) develop:
|
|
336
|
+
|
|
337
|
+
```bash
|
|
338
|
+
# Terminal 1: start your app
|
|
339
|
+
npm run dev
|
|
340
|
+
|
|
341
|
+
# Terminal 2: start Argus watcher
|
|
342
|
+
npm run watch
|
|
343
|
+
# Ctrl+C → stops monitor and writes reports/report.html
|
|
344
|
+
```
|
|
345
|
+
|
|
346
|
+
**Slack slash command** (on-demand from any channel):
|
|
347
|
+
|
|
348
|
+
```
|
|
349
|
+
/argus-retest https://staging.example.com/checkout
|
|
350
|
+
```
|
|
351
|
+
|
|
352
|
+
To expose the server via tunnel: `cloudflared tunnel --url http://localhost:3001` (free, no account required). Set the resulting URL as the Request URL in Slack App → Slash Commands.
|
|
353
|
+
|
|
354
|
+
---
|
|
355
|
+
|
|
356
|
+
## GitHub Actions CI — PR Gate
|
|
357
|
+
|
|
358
|
+
Argus ships as a composite GitHub Action: on every PR it maps the diff to affected routes, audits them, and blocks the merge **only on findings the PR introduces** (baseline-aware) — with an idempotent PR comment and a Check Run.
|
|
359
|
+
|
|
360
|
+
Add to your repo's secrets (Settings → Secrets → Actions):
|
|
361
|
+
|
|
362
|
+
| Secret | Required | Value |
|
|
363
|
+
|---|---|---|
|
|
364
|
+
| `TARGET_STAGING_URL` | Yes | Your staging base URL |
|
|
365
|
+
| `SLACK_BOT_TOKEN` | No | `xoxb-...` token (omit for HTML-only mode) |
|
|
366
|
+
| `SLACK_CHANNEL_CRITICAL` | No* | Channel ID (needed when Slack is configured) |
|
|
367
|
+
| `SLACK_CHANNEL_WARNINGS` | No* | Channel ID |
|
|
368
|
+
| `SLACK_CHANNEL_DIGEST` | No* | Channel ID |
|
|
369
|
+
| `GITHUB_TOKEN` | No | Auto-injected by Actions for PR comments + Check Runs |
|
|
370
|
+
|
|
371
|
+
The included [workflow](.github/workflows/argus.yml) runs on push to `main`, daily at 6 AM UTC, and on manual trigger. If critical issues are found, the pipeline fails.
|
|
372
|
+
|
|
373
|
+
---
|
|
374
|
+
|
|
375
|
+
## Environment Variables
|
|
376
|
+
|
|
377
|
+
<details>
|
|
378
|
+
<summary>Full reference (click to expand)</summary>
|
|
379
|
+
|
|
380
|
+
| Variable | Default | Description |
|
|
381
|
+
|---|---|---|
|
|
382
|
+
| `TARGET_DEV_URL` | — | **Required.** Base URL of your dev environment |
|
|
383
|
+
| `TARGET_STAGING_URL` | — | Staging URL — enables `argus_compare`; omit for CSS-only mode |
|
|
384
|
+
| `SLACK_BOT_TOKEN` | — | `xoxb-...` token. Omit for local `report.html` mode |
|
|
385
|
+
| `SLACK_SIGNING_SECRET` | — | For `/argus-retest` slash command verification |
|
|
386
|
+
| `SLACK_CHANNEL_CRITICAL` | — | Channel ID for critical bugs |
|
|
387
|
+
| `SLACK_CHANNEL_WARNINGS` | — | Channel ID for warnings |
|
|
388
|
+
| `SLACK_CHANNEL_DIGEST` | — | Channel ID for info / daily digest |
|
|
389
|
+
| `PORT` | `3001` | Slack slash-command server port |
|
|
390
|
+
| `REPORT_OUTPUT_DIR` | `./reports` | Where to write JSON reports |
|
|
391
|
+
| `ARGUS_CONCURRENCY` | `1` | Parallel MCP clients for route crawling |
|
|
392
|
+
| `ARGUS_LOG_LEVEL` | `info` | `trace` / `debug` / `info` / `warn` / `error` |
|
|
393
|
+
| `ARGUS_LOG_PRETTY` | — | Set `1` for human-readable logs in dev |
|
|
394
|
+
| `ARGUS_RETRY_ATTEMPTS` | `3` | Max retries for `navigate`/`fill` MCP calls |
|
|
395
|
+
| `ARGUS_WATCH_INTERVAL_MS` | `1000` | Watch mode poll interval (ms) |
|
|
396
|
+
| `ARGUS_WATCH_UI_PORT` | `3002` | Watch mode web dashboard port |
|
|
397
|
+
| `ARGUS_SOURCE_DIR` | — | App source path — enables env-var / feature-flag / dead-route analysis **and** framework-aware PR route mapping (import-graph: a changed component/stylesheet → only the routes that render it) |
|
|
398
|
+
| `ARGUS_ENV_FILE` | — | Path to app `.env` for codebase cross-reference |
|
|
399
|
+
| `SCREENSHOT_DIFF_THRESHOLD` | `0.5` | Pixel diff % threshold for environment comparison |
|
|
400
|
+
| `GITHUB_TOKEN` | — | For PR comments + Check Runs |
|
|
401
|
+
| `GITHUB_REPOSITORY` | — | `owner/repo` format |
|
|
402
|
+
| `GITHUB_PR_NUMBER` | — | Auto-injected by Actions from PR context |
|
|
403
|
+
| `ARGUS_CRITICAL_THRESHOLD` | `1` | New criticals before blocking merge (0 = never block) |
|
|
404
|
+
| `ARGUS_DIFF_IMAGE_URL` | — | Visual diff image URL to embed in PR comment |
|
|
405
|
+
| `OTEL_EXPORTER_OTLP_ENDPOINT` | — | OTLP collector for Jaeger / Grafana Tempo |
|
|
406
|
+
| `FIGMA_API_TOKEN` | — | Required for `argus_design_audit` |
|
|
407
|
+
| `FONT_SLOW_MS` | `1000` | Slow web font load threshold (ms) |
|
|
408
|
+
| `A11Y_CONTRAST_AA` | `4.5` | WCAG AA min contrast ratio for CVD simulation |
|
|
409
|
+
| `ARGUS_REDACT_SENSITIVE` | `ON` | **Aegis** egress redaction. `0` disables (byte-identical pre-Aegis output) |
|
|
410
|
+
| `ARGUS_REDACT_MODE` | `mask` | Matched-span style: `mask` / `label` / `hash` / `token` / `drop` |
|
|
411
|
+
| `ARGUS_REDACT_HTML` | off local / ON in CI | `1` redacts the hosted HTML report too |
|
|
412
|
+
| `ARGUS_REDACT_VAULT` | `OFF` | `1` (with `ARGUS_REDACT_MODE=token`) mints reversible `AEGIS_<hmac16>` tokens into a local `0600` vault; re-inflate with `npm run report:rehydrate` |
|
|
413
|
+
|
|
414
|
+
</details>
|
|
415
|
+
|
|
416
|
+
---
|
|
417
|
+
|
|
418
|
+
## Troubleshooting
|
|
419
|
+
|
|
420
|
+
> First stop for anything broken: `npx -y -p argusqa-os argus-doctor` — it checks Chrome reachability, MCP config validity, and required env keys, and prints the exact fix for each failure.
|
|
421
|
+
|
|
422
|
+
**Chrome DevTools MCP not connecting**
|
|
423
|
+
```bash
|
|
424
|
+
claude mcp add chrome-devtools -- npx chrome-devtools-mcp@latest
|
|
425
|
+
# Restart Claude Code after adding
|
|
426
|
+
```
|
|
427
|
+
|
|
428
|
+
**Slack messages not posting**
|
|
429
|
+
- Token must start with `xoxb-` (not `xoxp-`, `xoxe-`, or `xapp-`)
|
|
430
|
+
- Run `/invite @BugBot` in each channel
|
|
431
|
+
- Required scopes: `chat:write`, `files:write`, `files:read`
|
|
432
|
+
|
|
433
|
+
**Screenshots are blank**
|
|
434
|
+
- Page hasn't settled — increase `pageSettleMs` in `src/config/targets.js` or add a `waitFor` selector for the route
|
|
435
|
+
|
|
436
|
+
**`/argus-retest` returns "dispatch_failed"**
|
|
437
|
+
- Tunnel URL changed — update the Request URL in Slack App → Slash Commands and reinstall
|
|
438
|
+
|
|
439
|
+
**CSS analysis returns empty results**
|
|
440
|
+
- Page may be behind auth — ensure you're logged in on the Chrome instance Argus is controlling
|
|
441
|
+
|
|
442
|
+
**CI pipeline fails immediately**
|
|
443
|
+
- Chrome may not start fast enough — increase `sleep 3` to `sleep 5` in [.github/workflows/argus.yml](.github/workflows/argus.yml)
|
|
444
|
+
|
|
445
|
+
---
|
|
446
|
+
|
|
447
|
+
## How Argus Differs From Playwright / Cypress
|
|
448
|
+
|
|
449
|
+
Argus is a **complementary layer**, not a replacement for unit or E2E tests:
|
|
450
|
+
|
|
451
|
+
| | Playwright / Cypress | Raw browser MCP (Playwright MCP, chrome-devtools-mcp) | Argus |
|
|
452
|
+
|---|---|---|---|
|
|
453
|
+
| **Purpose** | Test your logic and API contracts | Give an agent browser hands & eyes | Give the agent (and you) **judgment** about what's broken |
|
|
454
|
+
| **What you get** | Pass / fail on scripts you wrote | Raw DOM/console/network access | 149 codified finding types, severities, baselines, noise filtering, root-cause hints |
|
|
455
|
+
| **Maintenance** | Test files, forever | Re-prompt the checks every session | Zero — audits the rendered app |
|
|
456
|
+
| **When it runs** | In your test suite | When the agent thinks to look | On demand, in CI as a PR gate, or continuously (watch mode) |
|
|
457
|
+
| **Output** | Pass / fail | Whatever the agent noticed | Structured reports with screenshots — Slack, HTML, PR comments — secrets redacted |
|
|
458
|
+
|
|
459
|
+
---
|
|
460
|
+
|
|
461
|
+
## Known Limitations
|
|
462
|
+
|
|
463
|
+
All 998 harness assertions pass (`998/998`) — there are currently no known MCP- or Chrome-layer restrictions. Lighthouse runs headless (after the `lighthouse_audit` argument fix); the remaining soft assertions (perf traces, GC-dependent heap-growth) are promoted to counted hard assertions only in the weekly strict-soft lane (`harness-strict.yml`) via `ARGUS_HARNESS_STRICT_SOFT`. Scope limits: Chrome/Chromium only, web apps only — see [Works With Your Stack](#works-with-your-stack).
|
|
464
|
+
|
|
465
|
+
---
|
|
466
|
+
|
|
467
|
+
## Hosted Argus — Founding Members
|
|
468
|
+
|
|
469
|
+
Want audits without running Chrome or npm — with history, trends, schedules, and a team dashboard? **Argus Cloud** is in founding-member early access: **$19/month, locked forever** (regular $29).
|
|
470
|
+
|
|
471
|
+
**[Become a founding member → argus-qa.com](https://argus-qa.com#pricing)**
|
|
472
|
+
|
|
473
|
+
The open-source engine on this page stays MIT and fully-featured, always — the hosted tier sells convenience and memory, never detections.
|
|
474
|
+
|
|
475
|
+
---
|
|
476
|
+
|
|
477
|
+
## Project Structure
|
|
478
|
+
|
|
479
|
+
```
|
|
480
|
+
src/
|
|
481
|
+
argus.js — single-page audit entry point
|
|
482
|
+
mcp-server.js — 9 MCP tools exposed to Claude / any MCP client
|
|
483
|
+
orchestration/ — crawl loop, Slack/GitHub dispatch, env comparison, watch mode
|
|
484
|
+
utils/ — 32 analysis engines (accessibility, security, performance, PDF, recording, etc.)
|
|
485
|
+
adapters/browser.js — CdpBrowserAdapter — wraps all chrome-devtools-mcp calls
|
|
486
|
+
config/targets.js — routes, thresholds, auth steps
|
|
487
|
+
cli/
|
|
488
|
+
init.js — argus init interactive setup wizard
|
|
489
|
+
chrome-launcher.js — npm run chrome / argus-chrome — launches Chrome with correct flags
|
|
490
|
+
doctor.js — npm run doctor / argus-doctor — pre-flight checks
|
|
491
|
+
pr-validate.js — headless CI entry point for GitHub Actions
|
|
492
|
+
test-harness/ — 171-block correctness harness, 998 hard assertions, 64 fixture pages
|
|
493
|
+
test/unit/ — 495 Vitest unit tests (no Chrome required)
|
|
494
|
+
landing/ — Product landing page (React 19 + Vite + Tailwind)
|
|
495
|
+
```
|
|
496
|
+
|
|
497
|
+
Full source map → [CLAUDE.md](CLAUDE.md) · MCP/DSL reference → [SKILL.md](SKILL.md)
|
|
498
|
+
|
|
499
|
+
---
|
|
500
|
+
|
|
501
|
+
## Contributing
|
|
502
|
+
|
|
503
|
+
Contributions are welcome — fixture pages, new detection categories, framework route-discovery, docs. Start with [CONTRIBUTING.md](CONTRIBUTING.md).
|
|
504
|
+
|
|
505
|
+
1. Fork the repo and create a branch
|
|
506
|
+
2. `npm run test:unit` — verify without Chrome (495 tests)
|
|
507
|
+
3. `npm run test:harness` — full integration coverage (requires Chrome on port 9222)
|
|
508
|
+
4. Open a PR — Argus audits itself via the CI workflow
|
|
509
|
+
|
|
510
|
+
---
|
|
511
|
+
|
|
512
|
+
## License
|
|
513
|
+
|
|
514
|
+
MIT © [ironclawdevs27](https://github.com/ironclawdevs27)
|
|
515
|
+
|
|
516
|
+
---
|
|
517
|
+
|
|
518
|
+
<div align="center">
|
|
519
|
+
|
|
520
|
+
*Argus Panoptes — the all-seeing giant of Greek mythology who never slept.*
|
|
521
|
+
|
|
522
|
+
[argus-qa.com](https://argus-qa.com) · [npm](https://www.npmjs.com/package/argusqa-os) · [MCP Registry](https://glama.ai/mcp/servers/ironclawdevs27/Argus)
|
|
523
|
+
|
|
524
|
+
</div>
|