qualiow-exploratory-testing 2.3.0 → 2.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (54) hide show
  1. package/.claude-plugin/marketplace.json +1 -1
  2. package/.claude-plugin/plugin.json +1 -1
  3. package/CHANGELOG.md +177 -0
  4. package/README.md +71 -21
  5. package/agents/qa-bug-judge.md +1 -1
  6. package/agents/qa-diff-indexer-agent.md +1 -1
  7. package/agents/qa-gather-agent.md +1 -1
  8. package/agents/qa-page-mapper-agent.md +3 -1
  9. package/agents/qa-reporting-agent.md +28 -14
  10. package/bin/mobile-cli.mjs +74 -26
  11. package/bin/qualiow +7 -2
  12. package/bin/wk-ios +60 -6
  13. package/bin/wkeval.mjs +7 -2
  14. package/data/security/SECURITY-POLICY.md +22 -3
  15. package/data/targets/parabank.yml +13 -0
  16. package/data/targets/saucedemo.yml +13 -0
  17. package/data/templates/bug-report.md +3 -0
  18. package/data/templates/session-charter.md +7 -5
  19. package/data/templates/session-report.md +7 -1
  20. package/dist/cli/index.js +2060 -361
  21. package/dist/index.d.ts +813 -26
  22. package/dist/index.js +2694 -704
  23. package/docs/GETTING-STARTED.md +71 -17
  24. package/docs/MOBILE-SETUP.md +31 -0
  25. package/hooks/hooks.json +12 -2
  26. package/hooks/scripts/bash-guard.mjs +242 -0
  27. package/hooks/scripts/secret-patterns.d.mts +4 -1
  28. package/hooks/scripts/secret-patterns.mjs +126 -34
  29. package/hooks/scripts/write-guard.mjs +70 -15
  30. package/package.json +3 -2
  31. package/skills/qa-explore/SKILL.md +10 -3
  32. package/skills/qa-explore/phases/00-setup.md +40 -3
  33. package/skills/qa-explore/phases/02-charter.md +25 -5
  34. package/skills/qa-explore/phases/04-journeys.md +14 -0
  35. package/skills/qa-explore/phases/05-features.md +10 -0
  36. package/skills/qa-explore/phases/06-edge-cases.md +10 -0
  37. package/skills/qa-explore/phases/07-reporting.md +93 -11
  38. package/skills/qa-explore/references/delegation-rules.md +12 -1
  39. package/skills/qa-explore/references/evidence-triage.md +44 -12
  40. package/skills/qa-explore/references/output-contract.md +69 -7
  41. package/skills/qa-explore/references/security-rules.md +25 -3
  42. package/skills/qa-explore-cleanup/SKILL.md +1 -1
  43. package/skills/qa-explore-mobile/SKILL.md +13 -3
  44. package/skills/qa-explore-mobile/phases/02-charter.md +2 -1
  45. package/skills/qa-explore-mobile/phases/07-reporting.md +2 -0
  46. package/skills/qa-explore-mobile/references/mobile-edges.md +3 -1
  47. package/skills/qa-explore-quick/SKILL.md +48 -9
  48. package/skills/qa-explore-report/SKILL.md +6 -2
  49. package/skills/qa-gather/SKILL.md +1 -1
  50. package/skills/qa-knowledge-add/SKILL.md +1 -1
  51. package/skills/qa-knowledge-list/SKILL.md +1 -1
  52. package/skills/qa-verify-backend/SKILL.md +1 -1
  53. package/skills/qa-verify-backend/phases/05-reporting.md +2 -1
  54. package/data/targets/testers-ai.yml +0 -14
@@ -32,7 +32,7 @@ That writes:
32
32
  | the 11 skills | `.claude/skills/qa-*/` |
33
33
  | the five sub-agents | `.claude/agents/` |
34
34
  | knowledge base, domain profiles, templates, security policy | `data/knowledge/`, `data/domains/`, `data/templates/`, `data/security/` |
35
- | the `_default` target (add `--include-examples` for the `_example-*` templates and `testers-ai.yml`) | `data/targets/` |
35
+ | the `_default` target (add `--include-examples` for the `_example-*` templates and the `parabank.yml` and `saucedemo.yml` demo targets) | `data/targets/` |
36
36
  | the mobile driver plus `setup-mobile.sh` and `doctor-mobile.sh`, executable | `qa/bin/` |
37
37
  | the credential template | `qa/.env.example` |
38
38
  | empty session/bug/context trees and the auth directory | `output/sessions/`, `output/bugs/`, `output/context/`, `.auth/` |
@@ -52,18 +52,22 @@ npx playwright-cli install --skills # optional: the official Playwright skill
52
52
  qualiow init --hooks
53
53
  ```
54
54
 
55
- Optional, and only for npm projects — a plugin install already ships the same two hooks and
55
+ Optional, and only for npm projects — a plugin install already ships the same three hooks and
56
56
  has them on by default, so do not enable both in one project. `--hooks` copies the guard
57
- scripts to `qa/hooks/` and merges into `.claude/settings.json` two `PreToolUse` entries and
58
- three `permissions.allow` rules. The merge is by exact string: running it again changes
59
- nothing, and hooks you already had are kept.
57
+ scripts to `qa/hooks/` and merges into `.claude/settings.json` three `PreToolUse` entries and
58
+ three `permissions.allow` rules. Running it again changes nothing, and hooks you already had
59
+ are kept; an older qualiow-only write-guard entry gets the new matcher. If `settings.json`
60
+ does not parse (a comment, a trailing comma), init stops without writing anything and prints
61
+ the entries to merge by hand.
60
62
 
61
63
  What the guards do: `read-guard.mjs` denies a whole-file `Read` of a qualiow file over
62
64
  `QUALIOW_READ_MAX_LINES` lines (default 300) — the knowledge manifest, a knowledge release
63
65
  file, a session phase file or a raw snapshot — and names the cheaper route in the refusal; a
64
66
  `Read` with `offset` or `limit` passes. `write-guard.mjs` refuses a `Write` or `Edit` under
65
- `output/` whose content matches the redaction list, so a secret never reaches disk. Neither
66
- one looks at anything else in your project. `QUALIOW_HOOKS=off` disables both.
67
+ `output/` whose content matches the redaction list, so a secret never reaches disk.
68
+ `bash-guard.mjs` sees every `Bash` command but only acts on a few: it asks before
69
+ `playwright-cli run-code` and before `git` options that can run a shell, and denies `npx -c`
70
+ or `npx -y` of an unknown package. `QUALIOW_HOOKS=off` disables all three.
67
71
 
68
72
  To write it by hand instead, this is the whole of it:
69
73
 
@@ -78,10 +82,16 @@ To write it by hand instead, this is the whole of it:
78
82
  ]
79
83
  },
80
84
  {
81
- "matcher": "Write|Edit|MultiEdit",
85
+ "matcher": "Write|Edit|MultiEdit|NotebookEdit",
82
86
  "hooks": [
83
87
  { "type": "command", "command": "node \"$CLAUDE_PROJECT_DIR/qa/hooks/write-guard.mjs\"" }
84
88
  ]
89
+ },
90
+ {
91
+ "matcher": "Bash",
92
+ "hooks": [
93
+ { "type": "command", "command": "node \"$CLAUDE_PROJECT_DIR/qa/hooks/bash-guard.mjs\"" }
94
+ ]
85
95
  }
86
96
  ]
87
97
  },
@@ -123,11 +133,13 @@ of that path needs network. A plain git checkout is described in the project REA
123
133
 
124
134
  ### Option A: explore a public site
125
135
 
126
- Point `/qa-explore` at any public site. A good first target is
127
- <https://testers.ai/testing/>, which ships as the `testers-ai` target config.
136
+ Point `/qa-explore` at any public site. Two public demo apps ship as target configs (install
137
+ them with `npx qualiow init --include-examples`): `parabank`, a demo online bank
138
+ (<https://parabank.parasoft.com/>), and `saucedemo`, a small e-commerce shop
139
+ (<https://www.saucedemo.com/>).
128
140
 
129
141
  ```bash
130
- /qa-explore https://testers.ai/testing/
142
+ /qa-explore --target parabank
131
143
  ```
132
144
 
133
145
  Claude will:
@@ -141,8 +153,10 @@ Claude will:
141
153
  6. Draft one bug report per finding, then have the `qa-bug-judge` sub-agent try to refute each
142
154
  one from a fresh context; survivors go to `bugs/`, refuted candidates to `bugs/refuted/`
143
155
  7. Write `phase-7-notes.md` — the executive summary, coverage map, recommendations and
144
- reflection — then hand the assembly of `session-report.md` and the
145
- `qualiow session finalize <session-dir>` call to the `qa-reporting-agent` sub-agent
156
+ reflection — and `stats.json` with one `coverage.areas` entry per charter area, run
157
+ `qualiow session level <session-dir> --write` to compute the coverage level, then hand the
158
+ assembly of `session-report.md` and the `qualiow session finalize <session-dir>` call to
159
+ the `qa-reporting-agent` sub-agent
146
160
 
147
161
  The eight phases and their share of the 45-minute cap:
148
162
 
@@ -174,7 +188,7 @@ phase 7; a bug it cannot reach (model unavailable, timeout, budget spent) still
174
188
  `Unverified`. To skip it for one run:
175
189
 
176
190
  ```bash
177
- /qa-explore https://testers.ai/testing/ --no-judge
191
+ /qa-explore --target saucedemo --no-judge
178
192
  ```
179
193
 
180
194
  or set it off for a target in its YAML:
@@ -186,6 +200,20 @@ verification:
186
200
 
187
201
  With the judge off, phase 7 writes `bugs/` directly and no `verification/` directory appears.
188
202
 
203
+ The 45-minute cap means some areas are not reached. They are not dropped: the session marks
204
+ them `deferred` in `stats.json`, the CLI renders them into `backlog.md`, and the next session
205
+ can start from them:
206
+
207
+ ```bash
208
+ /qa-explore --target my-app --continue latest
209
+ ```
210
+
211
+ `--continue` takes a session directory name or `latest`, and only a finalized session of the
212
+ same target. The new session never opens the old one's files; it runs
213
+ `qualiow session continue-check latest --target my-app`, which prints a fenced, redacted,
214
+ path-only summary (risk rows, backlog, site-map paths) that is treated as data, and puts the
215
+ backlog rows first in its charter with their IDs.
216
+
189
217
  ### Option B: quick check on one page
190
218
 
191
219
  ```bash
@@ -234,9 +262,14 @@ output/sessions/2026-09-08-1813-explore-parabank/
234
262
  verification/ # claim cards and verdicts (judge on)
235
263
  screenshots/
236
264
  BUG-001.png
265
+ A1-login.png # per-area evidence, named after the charter ID
237
266
  snapshots/ # raw page snapshots — working files, never part of the report
238
267
  videos/
268
+ traces/ # Playwright traces kept as evidence
269
+ evidence/ # any other evidence file an area or bug cites
239
270
  session-report.md # the deliverable
271
+ evidence-level.md # coverage level, written by `qualiow session level --write`
272
+ backlog.md # areas not tested, rendered by the same command
240
273
  stats.json # machine-readable session metrics
241
274
  ```
242
275
 
@@ -259,13 +292,31 @@ qualiow session finalize latest # validate, then append the rows
259
292
 
260
293
  Finalizing twice changes nothing — the rows are appended once.
261
294
 
295
+ Explore and quick sessions from 2.4.0 are **contract 2** (`"contract": 2` in `stats.json`), and
296
+ finalize checks their coverage record too: a `coverage.areas` entry for every charter row,
297
+ evidence files that exist under `screenshots/`, `videos/`, `traces/`, `logs/` or `evidence/`
298
+ (an `A<N>-` screenshot for every tested area), a reason for every area not tested, an
299
+ `**Area:**` line on every bug, and a coverage level that matches all of that. The level is
300
+ computed, never typed:
301
+
302
+ ```bash
303
+ qualiow session level latest # validate and print the level
304
+ qualiow session level latest --write # also write evidence-level.md, backlog.md, stats.coverage_level
305
+ ```
306
+
307
+ The level — `unassessed`, `incomplete`, `qualified` or `complete`, overall and per risk tier — says
308
+ how much of the charter was covered with evidence. It is a coverage fact, never a ship
309
+ probability or a release verdict; the findings line beside it is separate. Edit the stats, the
310
+ charter or a bug after `--write` and finalize asks you to run it again. Sessions written before
311
+ 2.4.0, and mobile and backend sessions, are contract 1 and are checked as before.
312
+
262
313
  ### Bug report structure
263
314
 
264
315
  Each report opens with the confidentiality blockquote, then:
265
316
 
266
317
  - **Title** — `# BUG-NNN: [Component] fails [Condition] causing [Impact]`
267
318
  - **Severity** — Critical, High, Medium or Low (conservative by design) — plus Priority,
268
- Component, URL, Environment and reproduction rate
319
+ Component, Area (the charter ID, explore and quick), URL, Environment and reproduction rate
269
320
  - **Summary**, **Expected Behavior**, **Actual Behavior**
270
321
  - **Steps to Reproduce** — numbered, specific enough for someone else to follow
271
322
  - **Business Impact** — revenue, trust, regulatory, data and scale. Mandatory
@@ -275,6 +326,7 @@ Each report opens with the confidentiality blockquote, then:
275
326
  ### Session report structure
276
327
 
277
328
  - Session metadata and executive summary
329
+ - **Coverage level** (contract 2) — `evidence-level.md` copied verbatim
278
330
  - Summary stats and the bug table
279
331
  - **Coverage map** (`| Area | Risk | Status | Bugs | Notes |`) — including what was *not* tested
280
332
  - Observations that are not bugs but are worth discussing
@@ -406,14 +458,16 @@ decide which entries a skill always gets without touching the skill itself.
406
458
 
407
459
  ```bash
408
460
  qualiow init --dry-run # preview what init would write
409
- qualiow init --hooks # add the read/write guards to .claude/settings.json
461
+ qualiow init --hooks # add the read/write/bash guards to .claude/settings.json
410
462
  qualiow validate --all # targets + qa/target.yml + domains + knowledge base
411
463
  qualiow list sessions # also: knowledge | targets | domains
412
464
  qualiow list knowledge --stats # also: --domain --tag --type --entry <id> --changelog
413
- qualiow report -s latest -f html -o report.html
465
+ qualiow report -s latest -f html -o report.html # writes output/report.html
414
466
  qualiow kb check
415
467
  qualiow kb digest --for explore # the knowledge a session loads
468
+ qualiow session level latest --write # compute a contract-2 session's coverage level
416
469
  qualiow session finalize latest # validate a finished session and index it
470
+ qualiow session continue-check latest --target my-app # what --continue would carry forward
417
471
  qualiow session prune --older-than 30 # dry-run; add --yes to remove
418
472
  ```
419
473
 
@@ -181,6 +181,37 @@ Requires `ios-webkit-debug-proxy`, `python3`, Node ≥ 22.4 (`wkeval.mjs` uses t
181
181
  `WebSocket`), and a booted Simulator with Safari on a page. `WK_IOS_PORT` (default 9221) sets
182
182
  the iwdp device-list port; pages are served on `WK_IOS_PORT + 1`.
183
183
 
184
+ > **⚠️ The proxy listens on every network interface, without authentication.**
185
+ > `ios-webkit-debug-proxy` (1.9.x) has no bind-address option, so ports `WK_IOS_PORT` to
186
+ > `WK_IOS_PORT + 101` are reachable from your LAN while it runs, and anyone who can reach them
187
+ > can evaluate JavaScript in the Simulator's pages — including their logged-in sessions. The
188
+ > proxy stays up between calls so each eval is fast; `wk-ios` prints a warning when it starts
189
+ > it. **Run `bin/wk-ios --stop` as soon as the session ends**, keep the macOS firewall on
190
+ > (System Settings → Network → Firewall), and avoid using the bridge on untrusted networks.
191
+
192
+ Safari keeps old tabs inspectable, so the newest page is not always the one under test. Set
193
+ `WK_PAGE_FILTER` to pin it. The filter is matched against the parsed page URL — never as a raw
194
+ substring, so a page cannot win by carrying the filter in its query string or fragment — and the
195
+ newest matching page is used:
196
+
197
+ | `WK_PAGE_FILTER` | Matches |
198
+ |---|---|
199
+ | `/account` | any page whose path starts with `/account` (any host) |
200
+ | `staging.example.com` | that host or any subdomain of it; `host:port` matches that exact host and port |
201
+ | `staging.example.com/account` | exactly that host, path starting with `/account` |
202
+ | `https://staging.example.com/account` | same scheme and host[:port], path starting with `/account` |
203
+
204
+ When no page matches, `wk-ios` stops with an error rather than evaluating in another tab. Prefer
205
+ a host-qualified form: a bare `/path` does not pin the host.
206
+
207
+ ```bash
208
+ WK_PAGE_FILTER=staging.example.com/account bin/wk-ios 'document.title'
209
+ ```
210
+
211
+ The proxy's pid and log files live in a private per-user directory,
212
+ `${TMPDIR:-/tmp}/wk-ios-<uid>/` (mode 700). Page values printed by `wk-ios`, and app labels
213
+ printed by `mcli snapshot` and `mcli logs`, have terminal control characters stripped.
214
+
184
215
  ## Why a Google **Play** (or `google_apis`) Android image
185
216
 
186
217
  A stock **AOSP** system image ships **no `com.android.chrome`** — only a basic AOSP
package/hooks/hooks.json CHANGED
@@ -1,5 +1,5 @@
1
1
  {
2
- "description": "qualiow routing guards: whole-file reads of qualiow data over the line threshold, and secrets in session output",
2
+ "description": "qualiow routing guards: whole-file reads of qualiow data over the line threshold, secrets in session output, and code-execution routes in Bash (playwright-cli run-code, arbitrary npx)",
3
3
  "hooks": {
4
4
  "PreToolUse": [
5
5
  {
@@ -13,7 +13,7 @@
13
13
  ]
14
14
  },
15
15
  {
16
- "matcher": "Write|Edit|MultiEdit",
16
+ "matcher": "Write|Edit|MultiEdit|NotebookEdit",
17
17
  "hooks": [
18
18
  {
19
19
  "type": "command",
@@ -21,6 +21,16 @@
21
21
  "timeout": 10
22
22
  }
23
23
  ]
24
+ },
25
+ {
26
+ "matcher": "Bash",
27
+ "hooks": [
28
+ {
29
+ "type": "command",
30
+ "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/scripts/bash-guard.mjs\"",
31
+ "timeout": 10
32
+ }
33
+ ]
24
34
  }
25
35
  ]
26
36
  }
@@ -0,0 +1,242 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * PreToolUse hook (matcher: Bash).
4
+ *
5
+ * Code-execution routes that a pre-approved `Bash(playwright-cli:*)`,
6
+ * `Bash(git -C:*)` or a permissive `npx` rule would otherwise let through
7
+ * without a prompt:
8
+ *
9
+ * - `playwright-cli run-code` (direct or via `npx playwright-cli`) runs its
10
+ * JavaScript in the Playwright node process, not in the browser sandbox —
11
+ * the `vm` context holding `page` is escapable to the host `process`. It is
12
+ * used legitimately, so the decision is `ask`: the user confirms every call.
13
+ * - `npx -c/--call <shell>`, and `npx -y`/`-p` of a package outside a short
14
+ * allowlist, install or run arbitrary code. The decision is `deny`.
15
+ * - `git -c <key>=<value>`, `--config-env`, `--upload-pack`, `--receive-pack`,
16
+ * `--exec`, `--ext-diff` and `--output` run a program or write an arbitrary
17
+ * file from an otherwise read-only git call — the skills pre-approve
18
+ * `git -C <repo> …` for the repository under test. The decision is `ask`.
19
+ *
20
+ * Compound commands are split on `&&`, `||`, `;`, `|`, `&` and newlines;
21
+ * leading `VAR=value` assignments and `env`/`command`/`exec`/`time`/`nohup`
22
+ * wrappers are skipped; `bash|sh|zsh -c '<cmd>'`, `eval`, `$(…)` and backticks
23
+ * are inspected as nested commands. A `deny` anywhere wins over an `ask`.
24
+ *
25
+ * Node built-ins only — a git-sourced plugin install has neither `dist/` nor
26
+ * `node_modules`. Never throws and never blocks on its own failure: any error
27
+ * here lets the command through (exit 0, no stdout) to the normal permission
28
+ * check rather than breaking the caller because of a hook bug.
29
+ */
30
+ import { readFileSync } from 'node:fs';
31
+
32
+ const NPX_ALLOWED_PACKAGES = new Set(['playwright-cli', '@playwright/cli', 'qualiow-exploratory-testing']);
33
+ const PLAYWRIGHT_CLI_NAMES = new Set(['playwright-cli', '@playwright/cli']);
34
+ const WRAPPERS = new Set(['env', 'command', 'exec', 'time', 'nohup']);
35
+ const SHELLS = new Set(['bash', 'sh', 'zsh', 'dash']);
36
+ const MAX_DEPTH = 4;
37
+
38
+ function decide(permissionDecision, reason) {
39
+ process.stdout.write(
40
+ JSON.stringify({
41
+ hookSpecificOutput: {
42
+ hookEventName: 'PreToolUse',
43
+ permissionDecision,
44
+ permissionDecisionReason: reason,
45
+ },
46
+ }),
47
+ );
48
+ }
49
+
50
+ /**
51
+ * Splits a command line into segments of words. Honours single and double
52
+ * quotes and backslash escapes; splits on unquoted && || ; | & and newlines.
53
+ */
54
+ function segments(command) {
55
+ const out = [];
56
+ let words = [];
57
+ let word = '';
58
+ let inWord = false;
59
+ let quote = null;
60
+ const endWord = () => {
61
+ if (inWord) words.push(word);
62
+ word = '';
63
+ inWord = false;
64
+ };
65
+ const endSegment = () => {
66
+ endWord();
67
+ if (words.length) out.push(words);
68
+ words = [];
69
+ };
70
+ for (let i = 0; i < command.length; i++) {
71
+ const c = command[i];
72
+ if (quote) {
73
+ if (c === quote) quote = null;
74
+ else if (c === '\\' && quote === '"' && i + 1 < command.length) word += command[++i];
75
+ else word += c;
76
+ continue;
77
+ }
78
+ if (c === '"' || c === "'") {
79
+ quote = c;
80
+ inWord = true;
81
+ } else if (c === '\\' && i + 1 < command.length) {
82
+ word += command[++i];
83
+ inWord = true;
84
+ } else if (c === ';' || c === '|' || c === '&' || c === '\n') {
85
+ endSegment();
86
+ } else if (c === ' ' || c === '\t' || c === '(' || c === ')' || c === '{' || c === '}') {
87
+ endWord();
88
+ } else {
89
+ word += c;
90
+ inWord = true;
91
+ }
92
+ }
93
+ endSegment();
94
+ return out;
95
+ }
96
+
97
+ /** `$(…)` and backtick bodies, inspected as nested commands. */
98
+ function substitutions(command) {
99
+ const found = [];
100
+ for (const m of command.matchAll(/\$\(([^()]*)\)/g)) found.push(m[1]);
101
+ for (const m of command.matchAll(/`([^`]*)`/g)) found.push(m[1]);
102
+ return found;
103
+ }
104
+
105
+ function basename(word) {
106
+ const parts = word.split('/');
107
+ return parts[parts.length - 1];
108
+ }
109
+
110
+ /** `@scope/name@1.2.3` → `@scope/name`, `name@latest` → `name`. */
111
+ function packageName(spec) {
112
+ const at = spec.lastIndexOf('@');
113
+ return at > 0 ? spec.slice(0, at) : spec;
114
+ }
115
+
116
+ function runCodeIn(words) {
117
+ return words.includes('run-code');
118
+ }
119
+
120
+ const ASK_RUN_CODE =
121
+ 'ask:playwright-cli run-code executes JavaScript in the Playwright node process (outside the browser sandbox); ' +
122
+ 'confirm the code is yours and contains no text taken from page content. Set QUALIOW_HOOKS=off to disable.';
123
+
124
+ const GIT_EXEC_OPTION = /^(--upload-pack|--receive-pack|--exec|--ext-diff|--output|--config-env)(=|$)/;
125
+
126
+ /** A git option that runs a program or writes a file outside the read-only calls the skills make. */
127
+ function gitExecOption(words) {
128
+ let k = 0;
129
+ // Global options before the subcommand: `-c` is a config override there (and a
130
+ // harmless diff flag after it, as in `git log -c`).
131
+ while (k < words.length && words[k].startsWith('-')) {
132
+ if (words[k] === '-c') return '-c';
133
+ k += /^(-C|--git-dir|--work-tree|--namespace)$/.test(words[k]) ? 2 : 1;
134
+ }
135
+ const hit = words.slice(k).find((w) => GIT_EXEC_OPTION.test(w)) || words.slice(0, k).find((w) => GIT_EXEC_OPTION.test(w));
136
+ return hit ? hit.split('=')[0] : null;
137
+ }
138
+
139
+ /** Returns 'deny:<reason>', 'ask:<reason>' or null for one segment's words. */
140
+ function checkWords(words, depth) {
141
+ let i = 0;
142
+ while (i < words.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(words[i])) i++;
143
+ while (i < words.length && WRAPPERS.has(basename(words[i]))) {
144
+ i++;
145
+ while (i < words.length && (/^[A-Za-z_][A-Za-z0-9_]*=/.test(words[i]) || words[i].startsWith('-'))) i++;
146
+ }
147
+ if (i >= words.length) return null;
148
+ const program = basename(words[i]);
149
+ const rest = words.slice(i + 1);
150
+
151
+ if (SHELLS.has(program)) {
152
+ const c = rest.findIndex((w) => /^-[a-z]*c$/.test(w));
153
+ if (c >= 0 && rest[c + 1] != null) return checkCommand(rest[c + 1], depth + 1);
154
+ return null;
155
+ }
156
+ if (program === 'eval') return checkCommand(rest.join(' '), depth + 1);
157
+
158
+ if (program === 'playwright-cli') return runCodeIn(rest) ? ASK_RUN_CODE : null;
159
+
160
+ if (program === 'git') {
161
+ const option = gitExecOption(rest);
162
+ return option
163
+ ? `ask:git ${option} can run a program or write an arbitrary file; confirm it is intended. Set QUALIOW_HOOKS=off to disable.`
164
+ : null;
165
+ }
166
+
167
+ if (program !== 'npx') return null;
168
+
169
+ let yes = false;
170
+ const packages = [];
171
+ let j = 0;
172
+ for (; j < rest.length; j++) {
173
+ const w = rest[j];
174
+ if (w === '--') {
175
+ j++;
176
+ break;
177
+ }
178
+ if (!w.startsWith('-')) break;
179
+ if (w === '-c' || w === '--call' || w.startsWith('--call=')) {
180
+ return 'deny:npx -c/--call runs an arbitrary shell string; call the tool directly instead. Set QUALIOW_HOOKS=off to disable.';
181
+ }
182
+ if (w === '-y' || w === '--yes' || w.startsWith('--yes=')) yes = true;
183
+ else if (w === '-p' || w === '--package') {
184
+ if (rest[j + 1] != null) packages.push(rest[++j]);
185
+ } else if (w.startsWith('--package=')) packages.push(w.slice('--package='.length));
186
+ }
187
+ const command = rest.slice(j);
188
+ const candidates = packages.length ? packages : command.length ? [command[0]] : [];
189
+ if (packages.length || yes) {
190
+ const unknown = candidates.map(packageName).filter((p) => !NPX_ALLOWED_PACKAGES.has(p));
191
+ if (unknown.length) {
192
+ return (
193
+ `deny:npx would install and run ${unknown.join(', ')}, which is not on the qualiow allowlist ` +
194
+ `(${[...NPX_ALLOWED_PACKAGES].join(', ')}). Install it deliberately instead. Set QUALIOW_HOOKS=off to disable.`
195
+ );
196
+ }
197
+ }
198
+ if (command.length) {
199
+ const bin = PLAYWRIGHT_CLI_NAMES.has(packageName(command[0])) ? 'playwright-cli' : basename(command[0]);
200
+ if (bin === 'playwright-cli' && runCodeIn(command.slice(1))) return ASK_RUN_CODE;
201
+ }
202
+ return null;
203
+ }
204
+
205
+ /** Worst decision across every segment and nested command. */
206
+ function checkCommand(command, depth = 0) {
207
+ if (typeof command !== 'string' || depth > MAX_DEPTH) return null;
208
+ let ask = null;
209
+ const nested = substitutions(command).map((s) => checkCommand(s, depth + 1));
210
+ const direct = segments(command).map((w) => checkWords(w, depth));
211
+ for (const r of [...nested, ...direct]) {
212
+ if (!r) continue;
213
+ if (r.startsWith('deny:')) return r;
214
+ ask = ask || r;
215
+ }
216
+ return ask;
217
+ }
218
+
219
+ try {
220
+ if (process.env.QUALIOW_HOOKS === 'off') process.exit(0);
221
+
222
+ let raw = '';
223
+ try {
224
+ raw = readFileSync(0, 'utf-8');
225
+ } catch {
226
+ process.exit(0);
227
+ }
228
+ if (!raw || !raw.trim()) process.exit(0);
229
+
230
+ const input = JSON.parse(raw);
231
+ if (input.tool_name !== 'Bash') process.exit(0);
232
+
233
+ const command = (input.tool_input || {}).command;
234
+ if (!command || typeof command !== 'string') process.exit(0);
235
+
236
+ const result = checkCommand(command);
237
+ if (result && result.startsWith('deny:')) decide('deny', result.slice('deny:'.length));
238
+ else if (result && result.startsWith('ask:')) decide('ask', result.slice('ask:'.length));
239
+ process.exit(0);
240
+ } catch {
241
+ process.exit(0);
242
+ }
@@ -1,8 +1,11 @@
1
1
  export interface SecretPattern {
2
2
  category: string;
3
3
  re: RegExp;
4
- filter?: (match: string) => boolean;
4
+ /** Receives the match and its capture groups, as `String.prototype.replace` would. */
5
+ filter?: (match: string, ...groups: string[]) => boolean;
5
6
  }
6
7
  export const SECRET_PATTERNS: SecretPattern[];
7
8
  /** Category names of every secret-shaped pattern found in `text`; never the matched text. */
8
9
  export function findSecretCategories(text: string): string[];
10
+ /** Number of secret-shaped matches per category in `text`; never the matched text. */
11
+ export function countSecrets(text: string): Map<string, number>;