qualiow-exploratory-testing 1.3.0 → 2.2.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/.claude-plugin/marketplace.json +26 -0
- package/.claude-plugin/plugin.json +22 -0
- package/.env.example +27 -0
- package/CHANGELOG.md +259 -0
- package/README.md +472 -204
- package/agents/qa-diff-indexer-agent.md +81 -0
- package/agents/qa-gather-agent.md +41 -0
- package/agents/qa-page-mapper-agent.md +74 -0
- package/agents/qa-reporting-agent.md +103 -0
- package/{scripts → bin}/doctor-mobile.sh +57 -18
- package/bin/mcli +15 -9
- package/bin/mobile-cli.mjs +574 -286
- package/bin/qualiow +30 -0
- package/{scripts → bin}/setup-mobile.sh +56 -19
- package/bin/wadb +10 -4
- package/bin/wk-ios +29 -17
- package/bin/wkeval.mjs +7 -1
- package/data/domains/_default.yml +1 -1
- package/data/knowledge/changelog.yml +30 -12
- package/data/knowledge/manifest.yml +355 -127
- package/data/knowledge/releases/v0.1.0/entries/technique-business-logic-race-conditions.yml +1 -1
- package/data/knowledge/releases/v0.1.0/release.yml +8 -1
- package/data/knowledge/releases/v0.6.0/entries/technique-async-callback-contracts.yml +98 -0
- package/data/knowledge/releases/v0.6.0/entries/technique-exactly-once-verification.yml +116 -0
- package/data/knowledge/releases/v0.6.0/release.yml +30 -0
- package/data/security/SECURITY-POLICY.md +273 -0
- package/data/targets/_default.yml +1 -1
- package/data/targets/_example-api-only.yml +80 -0
- package/data/targets/_example-mobile-emulation.yml +2 -2
- package/data/targets/_example-native-mobile.yml +2 -2
- package/data/targets/_example-sim-android-chrome.yml +1 -1
- package/data/targets/_example-sim-ios-safari.yml +1 -1
- package/data/templates/api-probe-matrix.md +3 -3
- package/data/templates/bug-report.md +29 -151
- package/data/templates/coverage-map.md +9 -6
- package/data/templates/expected-behaviour.md +3 -2
- package/data/templates/session-charter.md +3 -0
- package/data/templates/session-report.md +57 -80
- package/dist/cli/index.js +2286 -701
- package/dist/index.d.ts +637 -81
- package/dist/index.js +2058 -228
- package/docs/BACKEND-VERIFICATION.md +39 -9
- package/docs/GETTING-STARTED.md +300 -121
- package/docs/MOBILE-SETUP.md +149 -18
- package/hooks/hooks.json +27 -0
- package/hooks/scripts/read-guard.mjs +95 -0
- package/hooks/scripts/secret-patterns.d.mts +8 -0
- package/hooks/scripts/secret-patterns.mjs +136 -0
- package/hooks/scripts/write-guard.mjs +87 -0
- package/package.json +33 -18
- package/skills/qa-explore/SKILL.md +32 -25
- package/skills/qa-explore/phases/00-setup.md +76 -42
- package/skills/qa-explore/phases/01-auth.md +32 -15
- package/skills/qa-explore/phases/02-charter.md +16 -5
- package/skills/qa-explore/phases/03-discovery.md +93 -27
- package/skills/qa-explore/phases/04-journeys.md +2 -2
- package/skills/qa-explore/phases/05-features.md +39 -24
- package/skills/qa-explore/phases/06-edge-cases.md +24 -13
- package/skills/qa-explore/phases/07-reporting.md +102 -142
- package/skills/qa-explore/references/context-integration.md +1 -1
- package/skills/qa-explore/references/delegation-rules.md +82 -0
- package/skills/qa-explore/references/output-contract.md +192 -0
- package/skills/qa-explore/references/paths.md +108 -0
- package/skills/qa-explore/references/playwright-agents-integration.md +61 -84
- package/skills/qa-explore/references/security-rules.md +70 -25
- package/skills/qa-explore/references/session-rules.md +2 -1
- package/skills/qa-explore/references/severity-guide.md +31 -4
- package/skills/qa-explore-cleanup/SKILL.md +51 -15
- package/skills/qa-explore-feedback/SKILL.md +23 -5
- package/skills/qa-explore-mobile/SKILL.md +86 -64
- package/skills/qa-explore-mobile/phases/00-setup.md +71 -62
- package/skills/qa-explore-mobile/phases/01-auth.md +28 -31
- package/skills/qa-explore-mobile/phases/02-charter.md +8 -4
- package/skills/qa-explore-mobile/phases/03-discovery.md +17 -11
- package/skills/qa-explore-mobile/phases/04-journeys.md +6 -6
- package/skills/qa-explore-mobile/phases/05-features.md +9 -9
- package/skills/qa-explore-mobile/phases/06-edge-cases.md +35 -40
- package/skills/qa-explore-mobile/phases/07-reporting.md +108 -60
- package/skills/qa-explore-mobile/references/mobile-edges.md +26 -26
- package/skills/qa-explore-quick/SKILL.md +71 -26
- package/skills/qa-explore-report/SKILL.md +65 -35
- package/skills/qa-gather/SKILL.md +44 -8
- package/skills/qa-knowledge-add/SKILL.md +25 -9
- package/skills/qa-knowledge-list/SKILL.md +37 -40
- package/skills/qa-target-setup/SKILL.md +63 -41
- package/skills/qa-verify-backend/SKILL.md +31 -19
- package/skills/qa-verify-backend/phases/00-setup.md +57 -12
- package/skills/qa-verify-backend/phases/01-ac-decomposition.md +2 -2
- package/skills/qa-verify-backend/phases/02-static-review.md +11 -0
- package/skills/qa-verify-backend/phases/03-live-verification.md +5 -3
- package/skills/qa-verify-backend/phases/03b-api-verification.md +24 -9
- package/skills/qa-verify-backend/phases/04-e2e-trigger.md +18 -2
- package/skills/qa-verify-backend/phases/05-reporting.md +72 -12
- package/skills/qa-verify-backend/references/api-probes.md +28 -1
- package/skills/qa-verify-backend/references/payload-verification.md +1 -1
- package/skills/qa-verify-backend/references/release-readiness.md +1 -1
- package/skills/qa-verify-backend/references/safety-rules.md +13 -8
- package/data/domains/_default.md +0 -181
- package/data/domains/ecommerce.md +0 -192
- package/data/domains/fintech.md +0 -200
- package/data/domains/identity.md +0 -88
- package/data/domains/marketing.md +0 -194
- package/data/domains/saas.md +0 -197
- package/dist/cli/index.d.ts +0 -1
- package/dist/cli/index.js.map +0 -1
- package/dist/index.js.map +0 -1
package/docs/MOBILE-SETUP.md
CHANGED
|
@@ -6,32 +6,35 @@ The mobile skill drives **real** simulator/emulator browsers and native apps via
|
|
|
6
6
|
and/or Android toolchains being installed on the machine. This guide gets a clean Mac to
|
|
7
7
|
the point where a session can start.
|
|
8
8
|
|
|
9
|
+
Paths below are written as `bin/…` (a git checkout or a plugin install). In a project you
|
|
10
|
+
ran `qualiow init` in, the same files are at `qa/bin/…`; a global npm install also puts
|
|
11
|
+
`mcli`, `wadb`, `wk-ios`, `qualiow-doctor-mobile` and `qualiow-setup-mobile` on your `PATH`.
|
|
12
|
+
|
|
9
13
|
## TL;DR
|
|
10
14
|
|
|
11
15
|
```bash
|
|
12
16
|
# 1. Install everything scriptable + create standard devices (idempotent, re-runnable)
|
|
13
|
-
|
|
17
|
+
bin/setup-mobile.sh # or --android / --ios; --yes for non-interactive
|
|
14
18
|
|
|
15
19
|
# 2. Confirm the machine is ready (read-only; installs nothing)
|
|
16
|
-
|
|
20
|
+
bin/doctor-mobile.sh # add --quiet to print only failures + the verdict
|
|
17
21
|
|
|
18
22
|
# 3. Run a mobile session (once doctor says READY)
|
|
19
|
-
|
|
20
|
-
# drive via bin/mcli — see the target config notes in data/targets/_example-sim-*.yml
|
|
23
|
+
/qa-explore-mobile --target my-mobile-target
|
|
21
24
|
```
|
|
22
25
|
|
|
23
|
-
`
|
|
24
|
-
|
|
26
|
+
`bin/setup-mobile.sh` automates everything it can and **prints clear MANUAL steps** for the
|
|
27
|
+
few things it can't (Xcode + the iOS runtime). It finishes by running the doctor.
|
|
25
28
|
|
|
26
29
|
## What gets installed / created
|
|
27
30
|
|
|
28
31
|
| Component | Needed for | Auto by `setup-mobile.sh`? |
|
|
29
32
|
|-----------|-----------|----------------------------|
|
|
30
|
-
| Homebrew | base | ✅ (offers to install) |
|
|
31
|
-
| Node ≥
|
|
32
|
-
| **Maestro** | the driver (hierarchy/tap/input) | ✅ (`get.maestro.mobile.dev`) |
|
|
33
|
-
| **JDK 17** | Android SDK tooling | ✅ `brew install openjdk@17` |
|
|
34
|
-
| Android cmdline-tools | `sdkmanager`/`avdmanager` | ✅ `brew install --cask android-
|
|
33
|
+
| Homebrew | base | ✅ (offers to install; `curl \| bash`) |
|
|
34
|
+
| **Node ≥ 22.4** | runs `mobile-cli.mjs`, `wkeval.mjs` | ✅ |
|
|
35
|
+
| **Maestro** (pinned, default 2.10.0) | the driver (hierarchy/tap/input) | ✅ (`get.maestro.mobile.dev`, `curl \| bash`) |
|
|
36
|
+
| **JDK 17** | Maestro and the Android SDK tooling | ✅ `brew install openjdk@17` |
|
|
37
|
+
| Android cmdline-tools | `sdkmanager`/`avdmanager` | ✅ `brew install --cask android-commandlinetools` |
|
|
35
38
|
| platform-tools (`adb`), `emulator` | drive Android | ✅ `sdkmanager` |
|
|
36
39
|
| Google **Play** system image (API 35) | **Chrome must be present** | ✅ `sdkmanager` |
|
|
37
40
|
| SDK licenses | unblock installs | ✅ `sdkmanager --licenses` |
|
|
@@ -39,10 +42,31 @@ for the few things it can't (Xcode + the iOS runtime). It finishes by running th
|
|
|
39
42
|
| **Xcode** + CLI tools | iOS simulators at all | ⚠️ **manual** (App Store, multi-GB) |
|
|
40
43
|
| iOS runtime | a simulator OS to run | ⚠️ **manual** if none installed (Xcode ▸ Settings ▸ Components) |
|
|
41
44
|
| iOS simulator device `qa-iphone` | a device to boot | ✅ `simctl create` (once Xcode + a runtime exist) |
|
|
45
|
+
| `ios-webkit-debug-proxy` + `python3` | the `bin/wk-ios` DOM bridge (iOS Safari) | ✅ `brew install ios-webkit-debug-proxy` (python3 warned if absent) |
|
|
42
46
|
| Safari / Chrome (the browsers) | web-mode SUT | ✅ preinstalled (Safari always; Chrome via the Play image) |
|
|
43
47
|
|
|
48
|
+
### Flags
|
|
49
|
+
|
|
50
|
+
```bash
|
|
51
|
+
bin/setup-mobile.sh # both platforms, interactive
|
|
52
|
+
bin/setup-mobile.sh --android # scope to one platform
|
|
53
|
+
bin/setup-mobile.sh --ios
|
|
54
|
+
bin/setup-mobile.sh --yes # non-interactive: assume yes to prompts
|
|
55
|
+
bin/setup-mobile.sh --yes --allow-curl-bash # ...and let the curl|bash installers run too
|
|
56
|
+
MAESTRO_VERSION=2.10.0 bin/setup-mobile.sh # pin a specific Maestro release
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
The two `curl | bash` installers (Homebrew and Maestro) **always ask first**. Under `--yes`
|
|
60
|
+
they are *skipped* with the exact command printed, unless `--allow-curl-bash` is also given —
|
|
61
|
+
so an unattended run never pipes a remote script into a shell behind your back.
|
|
62
|
+
|
|
63
|
+
Other environment overrides: `ANDROID_API` (default 35), `ANDROID_AVD_NAME`, `IOS_DEVICE_NAME`,
|
|
64
|
+
`ANDROID_HOME`.
|
|
65
|
+
|
|
44
66
|
### The two genuinely manual iOS steps
|
|
67
|
+
|
|
45
68
|
Xcode can't be reliably scripted:
|
|
69
|
+
|
|
46
70
|
```bash
|
|
47
71
|
# After installing Xcode from the App Store:
|
|
48
72
|
sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
|
|
@@ -50,9 +74,32 @@ sudo xcodebuild -license accept
|
|
|
50
74
|
# If no iOS runtime is installed:
|
|
51
75
|
xcodebuild -downloadPlatform iOS # or Xcode ▸ Settings ▸ Components
|
|
52
76
|
```
|
|
53
|
-
|
|
77
|
+
|
|
78
|
+
Then re-run `bin/setup-mobile.sh` — it will create the `qa-iphone` device.
|
|
79
|
+
|
|
80
|
+
## The preflight
|
|
81
|
+
|
|
82
|
+
```bash
|
|
83
|
+
bin/doctor-mobile.sh # check both platforms
|
|
84
|
+
bin/doctor-mobile.sh --ios # iOS only
|
|
85
|
+
bin/doctor-mobile.sh --android # Android only
|
|
86
|
+
bin/doctor-mobile.sh --quiet # only failures + the final verdict
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
Read-only: it installs nothing and prints `✓`/`✗` with the exact fix command for each gap.
|
|
90
|
+
The mobile session's `00-setup` phase runs it first, so a fresh machine fails fast with
|
|
91
|
+
actionable guidance instead of a cryptic error deep in a session. Exit code 0 means every
|
|
92
|
+
REQUIRED check for the requested platform passed.
|
|
93
|
+
|
|
94
|
+
It checks macOS, Homebrew, **Node ≥ 22.4**, **Maestro ≥ 2.6.0** (`MAESTRO_MIN_VERSION` —
|
|
95
|
+
`mobile-cli` parses the JSON-only `maestro hierarchy` introduced in 2.6), then per platform:
|
|
96
|
+
JDK 17, the SDK root, `adb`, `emulator`, `sdkmanager`/`avdmanager` and an AVD for Android;
|
|
97
|
+
Xcode CLT + full Xcode, an iOS runtime and an iPhone simulator for iOS. `ios-webkit-debug-proxy`
|
|
98
|
+
and `python3` are reported as **warnings** — without them the `bin/wk-ios` DOM bridge is
|
|
99
|
+
unavailable, but a session can still run.
|
|
54
100
|
|
|
55
101
|
## Standard device names (referenced by the target configs)
|
|
102
|
+
|
|
56
103
|
- Android AVD: **`qa_pixel_api35`** (Google-Play API 35) — set `ANDROID_AVD_NAME` to override.
|
|
57
104
|
- iOS sim: **`qa-iphone`** — set `IOS_DEVICE_NAME` to override.
|
|
58
105
|
|
|
@@ -60,15 +107,92 @@ The `data/targets/_example-sim-*.yml` configs resolve the device **by name** (no
|
|
|
60
107
|
hardcoded UDID) so they're portable across machines. `00-setup` boots the named device,
|
|
61
108
|
creating it if missing.
|
|
62
109
|
|
|
110
|
+
## Driving the device
|
|
111
|
+
|
|
112
|
+
```bash
|
|
113
|
+
bin/mcli boot qa_pixel_api35 # boots an AVD or an iOS sim by name, waits, set-devices it
|
|
114
|
+
bin/mcli set-device emulator-5554 --platform android # adb serial, iOS UDID, or iOS sim NAME
|
|
115
|
+
bin/mcli set-app com.android.chrome # or com.apple.mobilesafari, or your app id
|
|
116
|
+
bin/mcli launch
|
|
117
|
+
bin/mcli open-url https://staging.m.example.com # web mode (alias of deep-link)
|
|
118
|
+
bin/mcli snapshot # a11y tree as refs e1, e2, … — refs expire after 60 s
|
|
119
|
+
bin/mcli fill e4 my-username
|
|
120
|
+
bin/mcli snapshot # ALWAYS re-snapshot after the keyboard appears
|
|
121
|
+
bin/mcli click e7
|
|
122
|
+
bin/mcli info # resolved device/app + which state file is in use
|
|
123
|
+
bin/mcli --help # the full command surface
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
`set-device` resolves the platform by matching the id against `xcrun simctl list devices` and
|
|
127
|
+
`adb devices`; pass `--platform ios|android` when it cannot tell. `boot` handles the
|
|
128
|
+
`emulator -avd …` / `simctl boot && open -a Simulator` dance for you.
|
|
129
|
+
|
|
130
|
+
**State.** Device and app selection is stored in a small JSON file. `--state <file>` (or
|
|
131
|
+
`$MOBILE_CLI_STATE`) picks it explicitly; otherwise `set-device` chooses
|
|
132
|
+
`~/.mobile-cli/<device>.json`. Give each concurrent session its own state file:
|
|
133
|
+
|
|
134
|
+
```bash
|
|
135
|
+
bin/mcli --state /tmp/run-a.json set-device qa-iphone
|
|
136
|
+
bin/mcli --state /tmp/run-a.json set-app com.apple.mobilesafari
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
**Exit codes.** `0` ok · `1` command failed · `2` usage · `3` stale or unknown ref (re-run
|
|
140
|
+
`snapshot`) · `4` no device or app set. A stale ref is not a flake: the tree is renumbered on
|
|
141
|
+
every snapshot, so a ref older than `MCLI_REF_TTL_MS` (default 60 000) is rejected rather than
|
|
142
|
+
tapped at a coordinate that has since moved.
|
|
143
|
+
|
|
144
|
+
**Evidence.** `screenshot <path>` needs no app. `logs [--since <sec>] [--errors]` reads logcat
|
|
145
|
+
or `simctl log`; `logs-clear` empties the Android buffer. `record-start <path>.mp4` /
|
|
146
|
+
`record-stop` produce mp4 on both platforms (Android caps a single recording at 180 s).
|
|
147
|
+
|
|
148
|
+
## The helper wrappers
|
|
149
|
+
|
|
150
|
+
`bin/mcli`, `bin/wadb` and `bin/wk-ios` exist because Claude Code permission rules match on
|
|
151
|
+
the **first token** of a Bash command — a compound `export JAVA_HOME=…; node …` line can never
|
|
152
|
+
be pre-approved. Each wrapper resolves the environment internally and then execs the real tool.
|
|
153
|
+
|
|
154
|
+
### `bin/wadb` — raw adb, environment resolved
|
|
155
|
+
|
|
156
|
+
```bash
|
|
157
|
+
bin/wadb devices
|
|
158
|
+
bin/wadb logcat -d | tail -50
|
|
159
|
+
bin/wadb shell pm list packages | grep chrome
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
It uses the `adb` already on `PATH` when there is one, else the SDK copy under `ANDROID_HOME`
|
|
163
|
+
(default `~/Library/Android/sdk`).
|
|
164
|
+
|
|
165
|
+
### `bin/wk-ios` — real JS/DOM in iOS Simulator Safari
|
|
166
|
+
|
|
167
|
+
Maestro reads the native XCUITest accessibility tree, which collapses Safari's web content
|
|
168
|
+
into unlabeled nodes. The DOM itself is fully addressable through WebKit's Remote Inspector,
|
|
169
|
+
and `wk-ios` wires `ios-webkit-debug-proxy` up to the running Simulator so you can evaluate JS
|
|
170
|
+
in the frontmost page — the same power `playwright-cli eval` gives you on desktop, but on the
|
|
171
|
+
real iOS engine.
|
|
172
|
+
|
|
173
|
+
```bash
|
|
174
|
+
bin/wk-ios 'document.title'
|
|
175
|
+
bin/wk-ios 'document.querySelectorAll(".cart_item").length'
|
|
176
|
+
bin/wk-ios --url # print the page WebSocket URL
|
|
177
|
+
bin/wk-ios --stop # stop the proxy this script started (never anyone else's)
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
Requires `ios-webkit-debug-proxy`, `python3`, Node ≥ 22.4 (`wkeval.mjs` uses the global
|
|
181
|
+
`WebSocket`), and a booted Simulator with Safari on a page. `WK_IOS_PORT` (default 9221) sets
|
|
182
|
+
the iwdp device-list port; pages are served on `WK_IOS_PORT + 1`.
|
|
183
|
+
|
|
63
184
|
## Why a Google **Play** (or `google_apis`) Android image
|
|
185
|
+
|
|
64
186
|
A stock **AOSP** system image ships **no `com.android.chrome`** — only a basic AOSP
|
|
65
187
|
browser or none. Web-mode Android targets need Chrome, so `setup-mobile.sh` installs a
|
|
66
188
|
`google_apis_playstore` image. Verify on any AVD with:
|
|
189
|
+
|
|
67
190
|
```bash
|
|
68
|
-
|
|
191
|
+
bin/wadb shell pm list packages | grep chrome
|
|
69
192
|
```
|
|
70
193
|
|
|
71
194
|
## Auth reality (web targets)
|
|
195
|
+
|
|
72
196
|
There is **no transferable `storage_state`** for a real device browser (unlike Playwright).
|
|
73
197
|
SSO + MFA logins are done **once, interactively, by a human** in the sim/emulator browser;
|
|
74
198
|
the device persists the browser profile across launches. Never script MFA. Never
|
|
@@ -76,17 +200,24 @@ the device persists the browser profile across launches. Never script MFA. Never
|
|
|
76
200
|
`notes:` blocks in `data/targets/_example-sim-*.yml`.
|
|
77
201
|
|
|
78
202
|
## Troubleshooting
|
|
203
|
+
|
|
79
204
|
- **`doctor-mobile.sh` says NOT READY** → fix each `✗` with the printed command, or run
|
|
80
205
|
`setup-mobile.sh`, then re-run the doctor.
|
|
81
206
|
- **`JAVA_HOME` / `adb` not found mid-session** → `bin/mcli` resolves JDK 17 via
|
|
82
|
-
`/usr/libexec/java_home -v 17`
|
|
83
|
-
Export them explicitly if your SDK lives
|
|
207
|
+
`/usr/libexec/java_home -v 17` (falling back to the Homebrew `openjdk@17` prefixes) and
|
|
208
|
+
defaults `ANDROID_HOME` to `~/Library/Android/sdk`. Export them explicitly if your SDK lives
|
|
209
|
+
elsewhere.
|
|
210
|
+
- **Maestro too old** → `mobile-cli` needs the JSON-only `maestro hierarchy` of 2.6.0+.
|
|
211
|
+
Reinstall pinned: `curl -Ls https://get.maestro.mobile.dev | MAESTRO_VERSION=2.10.0 bash`.
|
|
212
|
+
- **Every tap hits the wrong element** → your refs expired. Re-run `snapshot`; exit code 3
|
|
213
|
+
means exactly this.
|
|
84
214
|
- **Intel Mac** → `setup-mobile.sh` selects `x86_64` system images automatically (`arm64`
|
|
85
215
|
Macs get `arm64-v8a`).
|
|
86
216
|
- **Emulator slow/flaky to boot or Chrome absent** → fall back to the iOS Safari target;
|
|
87
217
|
both engines are independent.
|
|
88
218
|
|
|
89
219
|
## Scope
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
220
|
+
|
|
221
|
+
This covers iOS Simulator + Android Emulator (browser **and** native modes) on macOS. It does
|
|
222
|
+
**not** provision physical devices, CI runners, Windows/Linux hosts, or the desktop web path
|
|
223
|
+
(`/qa-explore`, which only needs `playwright-cli`).
|
package/hooks/hooks.json
ADDED
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
{
|
|
2
|
+
"description": "qualiow routing guards: whole-file reads of qualiow data over the line threshold, and secrets in session output",
|
|
3
|
+
"hooks": {
|
|
4
|
+
"PreToolUse": [
|
|
5
|
+
{
|
|
6
|
+
"matcher": "Read",
|
|
7
|
+
"hooks": [
|
|
8
|
+
{
|
|
9
|
+
"type": "command",
|
|
10
|
+
"command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/scripts/read-guard.mjs\"",
|
|
11
|
+
"timeout": 10
|
|
12
|
+
}
|
|
13
|
+
]
|
|
14
|
+
},
|
|
15
|
+
{
|
|
16
|
+
"matcher": "Write|Edit|MultiEdit",
|
|
17
|
+
"hooks": [
|
|
18
|
+
{
|
|
19
|
+
"type": "command",
|
|
20
|
+
"command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/scripts/write-guard.mjs\"",
|
|
21
|
+
"timeout": 10
|
|
22
|
+
}
|
|
23
|
+
]
|
|
24
|
+
}
|
|
25
|
+
]
|
|
26
|
+
}
|
|
27
|
+
}
|
|
@@ -0,0 +1,95 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
/**
|
|
3
|
+
* PreToolUse hook (matcher: Read).
|
|
4
|
+
*
|
|
5
|
+
* Denies a whole-file Read of a qualiow data/session file once it crosses a
|
|
6
|
+
* line threshold, and names the cheaper route instead (`qualiow kb digest`,
|
|
7
|
+
* `qualiow list knowledge --entry`, offset/limit + Grep, or the
|
|
8
|
+
* qa-page-mapper-agent) — see delegation-rules.md. A Read that already
|
|
9
|
+
* carries `offset`/`limit` is always allowed: the caller is already reading
|
|
10
|
+
* a slice.
|
|
11
|
+
*
|
|
12
|
+
* Node built-ins only — a git-sourced plugin install has neither `dist/` nor
|
|
13
|
+
* `node_modules`. Never throws and never blocks on its own failure: any
|
|
14
|
+
* error here allows the read through (exit 0, no stdout) rather than
|
|
15
|
+
* breaking the caller because of a hook bug.
|
|
16
|
+
*/
|
|
17
|
+
import { readFileSync, existsSync } from 'node:fs';
|
|
18
|
+
import { isAbsolute, resolve } from 'node:path';
|
|
19
|
+
|
|
20
|
+
const GUARDED = [
|
|
21
|
+
{
|
|
22
|
+
re: /(^|\/)data\/knowledge\/(manifest\.ya?ml|releases\/)/,
|
|
23
|
+
route:
|
|
24
|
+
'knowledge manifest or release entry \u2192 `qualiow kb digest --for <explore|backend|mobile>` or `qualiow list knowledge --entry <id>`',
|
|
25
|
+
},
|
|
26
|
+
{
|
|
27
|
+
re: /(^|\/)output\/sessions\/[^/]+\/phase-\d[^/]*\.md/,
|
|
28
|
+
route: "phase file \u2192 Read with offset/limit after Grep '^## '",
|
|
29
|
+
},
|
|
30
|
+
{
|
|
31
|
+
re: /(^|\/)output\/sessions\/[^/]+\/snapshots\//,
|
|
32
|
+
route: 'raw snapshot \u2192 qa-page-mapper-agent',
|
|
33
|
+
},
|
|
34
|
+
];
|
|
35
|
+
|
|
36
|
+
function deny(reason) {
|
|
37
|
+
process.stdout.write(
|
|
38
|
+
JSON.stringify({
|
|
39
|
+
hookSpecificOutput: {
|
|
40
|
+
hookEventName: 'PreToolUse',
|
|
41
|
+
permissionDecision: 'deny',
|
|
42
|
+
permissionDecisionReason: reason,
|
|
43
|
+
},
|
|
44
|
+
}),
|
|
45
|
+
);
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
/** Number of \n plus one if the last line has no trailing newline. */
|
|
49
|
+
function countLines(text) {
|
|
50
|
+
if (text.length === 0) return 0;
|
|
51
|
+
const newlines = (text.match(/\n/g) || []).length;
|
|
52
|
+
return text.endsWith('\n') ? newlines : newlines + 1;
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
try {
|
|
56
|
+
if (process.env.QUALIOW_HOOKS === 'off') process.exit(0);
|
|
57
|
+
|
|
58
|
+
let raw = '';
|
|
59
|
+
try {
|
|
60
|
+
raw = readFileSync(0, 'utf-8');
|
|
61
|
+
} catch {
|
|
62
|
+
process.exit(0);
|
|
63
|
+
}
|
|
64
|
+
if (!raw || !raw.trim()) process.exit(0);
|
|
65
|
+
|
|
66
|
+
const input = JSON.parse(raw);
|
|
67
|
+
if (input.tool_name !== 'Read') process.exit(0);
|
|
68
|
+
|
|
69
|
+
const toolInput = input.tool_input || {};
|
|
70
|
+
if (toolInput.offset != null || toolInput.limit != null) process.exit(0);
|
|
71
|
+
|
|
72
|
+
const filePath = toolInput.file_path;
|
|
73
|
+
if (!filePath || typeof filePath !== 'string') process.exit(0);
|
|
74
|
+
|
|
75
|
+
const normalized = filePath.split('\\').join('/');
|
|
76
|
+
const matched = GUARDED.find((g) => g.re.test(normalized));
|
|
77
|
+
if (!matched) process.exit(0);
|
|
78
|
+
|
|
79
|
+
const abs = isAbsolute(filePath) ? filePath : resolve(input.cwd || process.cwd(), filePath);
|
|
80
|
+
if (!existsSync(abs)) process.exit(0);
|
|
81
|
+
|
|
82
|
+
const content = readFileSync(abs, 'utf-8');
|
|
83
|
+
const lineCount = countLines(content);
|
|
84
|
+
const threshold = Number(process.env.QUALIOW_READ_MAX_LINES) || 300;
|
|
85
|
+
|
|
86
|
+
if (lineCount > threshold) {
|
|
87
|
+
deny(
|
|
88
|
+
`${filePath} is ${lineCount} lines (limit ${threshold}). Route: ${matched.route}. ` +
|
|
89
|
+
'Set QUALIOW_HOOKS=off to disable.',
|
|
90
|
+
);
|
|
91
|
+
}
|
|
92
|
+
process.exit(0);
|
|
93
|
+
} catch {
|
|
94
|
+
process.exit(0);
|
|
95
|
+
}
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
export interface SecretPattern {
|
|
2
|
+
category: string;
|
|
3
|
+
re: RegExp;
|
|
4
|
+
filter?: (match: string) => boolean;
|
|
5
|
+
}
|
|
6
|
+
export const SECRET_PATTERNS: SecretPattern[];
|
|
7
|
+
/** Category names of every secret-shaped pattern found in `text`; never the matched text. */
|
|
8
|
+
export function findSecretCategories(text: string): string[];
|
|
@@ -0,0 +1,136 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Secret detection for the write-guard hook.
|
|
3
|
+
*
|
|
4
|
+
* Mirrors the categories and patterns in `src/utils/redact.ts` as closely as
|
|
5
|
+
* possible, so a hook denial matches what `qualiow session finalize --redact`
|
|
6
|
+
* would flag on the same text. Kept as a standalone, dependency-free ES
|
|
7
|
+
* module (Node built-ins only, no TS import) because a git-sourced plugin
|
|
8
|
+
* install has neither `dist/` nor `node_modules` to pull the real util from.
|
|
9
|
+
*
|
|
10
|
+
* `findSecretCategories` never returns the matched text itself — only
|
|
11
|
+
* category names — so the hook that calls it can safely put the result in a
|
|
12
|
+
* denial reason without leaking the secret it found.
|
|
13
|
+
*/
|
|
14
|
+
|
|
15
|
+
const EMAIL_ALLOW = /(?:@|\.)(?:example\.(?:com|org|net)|localhost)$/i;
|
|
16
|
+
|
|
17
|
+
function luhnValid(digits) {
|
|
18
|
+
let sum = 0;
|
|
19
|
+
let alt = false;
|
|
20
|
+
for (let i = digits.length - 1; i >= 0; i--) {
|
|
21
|
+
const d0 = digits.charCodeAt(i) - 48;
|
|
22
|
+
if (d0 < 0 || d0 > 9) return false;
|
|
23
|
+
let d = d0;
|
|
24
|
+
if (alt) {
|
|
25
|
+
d *= 2;
|
|
26
|
+
if (d > 9) d -= 9;
|
|
27
|
+
}
|
|
28
|
+
sum += d;
|
|
29
|
+
alt = !alt;
|
|
30
|
+
}
|
|
31
|
+
return sum % 10 === 0;
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
/**
|
|
35
|
+
* category: name surfaced in denial reasons (never the matched text).
|
|
36
|
+
* re: detection pattern (mirrors redact.ts; capture groups dropped since
|
|
37
|
+
* only presence, not replacement, is needed here).
|
|
38
|
+
* filter(match): optional extra check a raw regex match can't express
|
|
39
|
+
* (Luhn validity, the example.com/localhost allow-list).
|
|
40
|
+
*/
|
|
41
|
+
export const SECRET_PATTERNS = [
|
|
42
|
+
{
|
|
43
|
+
category: 'Private key',
|
|
44
|
+
re: /-----BEGIN (?:[A-Z0-9 ]+ )?PRIVATE KEY-----[\s\S]*?-----END (?:[A-Z0-9 ]+ )?PRIVATE KEY-----/g,
|
|
45
|
+
},
|
|
46
|
+
{
|
|
47
|
+
category: 'JWT',
|
|
48
|
+
re: /\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{6,}\.[A-Za-z0-9_-]{6,}\b/g,
|
|
49
|
+
},
|
|
50
|
+
{
|
|
51
|
+
category: 'Authorization header',
|
|
52
|
+
re: /authorization\s*[:=]\s*\S[^\n\r]*/gi,
|
|
53
|
+
},
|
|
54
|
+
{
|
|
55
|
+
category: 'Cookie header',
|
|
56
|
+
re: /^(?:set-cookie|cookie)\s*:\s*.+$/gim,
|
|
57
|
+
},
|
|
58
|
+
{
|
|
59
|
+
category: 'AWS access key id',
|
|
60
|
+
re: /\b(?:AKIA|ASIA|AROA|AIDA)[0-9A-Z]{16}\b/g,
|
|
61
|
+
},
|
|
62
|
+
{
|
|
63
|
+
category: 'AWS secret access key',
|
|
64
|
+
re: /aws_secret_access_key\s*[:=]\s*\S+/gi,
|
|
65
|
+
},
|
|
66
|
+
{
|
|
67
|
+
category: 'OpenAI-style key',
|
|
68
|
+
re: /\bsk-(?:proj-)?[A-Za-z0-9_-]{20,}\b/g,
|
|
69
|
+
},
|
|
70
|
+
{
|
|
71
|
+
category: 'GitHub token',
|
|
72
|
+
re: /\b(?:gh[pousr]_[A-Za-z0-9]{20,}|github_pat_[A-Za-z0-9_]{20,})\b/g,
|
|
73
|
+
},
|
|
74
|
+
{
|
|
75
|
+
category: 'Slack token',
|
|
76
|
+
re: /\bxox[abposr]-[A-Za-z0-9-]{10,}\b/g,
|
|
77
|
+
},
|
|
78
|
+
{
|
|
79
|
+
category: 'API key',
|
|
80
|
+
re: /(?:x-api-key|api[_-]?key)\s*[:=]\s*["']?[A-Za-z0-9._-]{8,}["']?/gi,
|
|
81
|
+
},
|
|
82
|
+
{
|
|
83
|
+
category: 'Password',
|
|
84
|
+
re: /(?:password|passwd|pwd)\s*[:=]\s*["']?[^\s,}"']+["']?/gi,
|
|
85
|
+
},
|
|
86
|
+
{
|
|
87
|
+
category: 'Token',
|
|
88
|
+
re: /(?:access[_-]?token|refresh[_-]?token|token)\s*[:=]\s*["']?[A-Za-z0-9._-]{8,}["']?/gi,
|
|
89
|
+
},
|
|
90
|
+
{
|
|
91
|
+
category: 'Secret',
|
|
92
|
+
re: /[a-z_]*secret\s*[:=]\s*["']?[^\s,}"']+["']?/gi,
|
|
93
|
+
},
|
|
94
|
+
{
|
|
95
|
+
category: 'SSN',
|
|
96
|
+
re: /\b\d{3}-\d{2}-\d{4}\b/g,
|
|
97
|
+
},
|
|
98
|
+
{
|
|
99
|
+
category: 'Email',
|
|
100
|
+
re: /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/g,
|
|
101
|
+
filter: (match) => !EMAIL_ALLOW.test(match),
|
|
102
|
+
},
|
|
103
|
+
{
|
|
104
|
+
category: 'Credit card number',
|
|
105
|
+
re: /\b\d(?:[ -]?\d){12,18}\b/g,
|
|
106
|
+
filter: (match) => {
|
|
107
|
+
const digits = match.replace(/\D/g, '');
|
|
108
|
+
if (digits.length < 13 || digits.length > 19) return false;
|
|
109
|
+
if (!/^[3-6]/.test(digits)) return false;
|
|
110
|
+
return luhnValid(digits);
|
|
111
|
+
},
|
|
112
|
+
},
|
|
113
|
+
];
|
|
114
|
+
|
|
115
|
+
/** Returns the category names of every secret-shaped pattern found in `text`. */
|
|
116
|
+
export function findSecretCategories(text) {
|
|
117
|
+
const found = new Set();
|
|
118
|
+
for (const { category, re, filter } of SECRET_PATTERNS) {
|
|
119
|
+
re.lastIndex = 0;
|
|
120
|
+
let match;
|
|
121
|
+
while ((match = re.exec(text)) !== null) {
|
|
122
|
+
// A value that is already a redaction placeholder is clean: redact.ts leaves it
|
|
123
|
+
// untouched, so containsSecrets() is false for it and this must agree.
|
|
124
|
+
if (/REDACTED\]/.test(match[0])) {
|
|
125
|
+
if (match[0].length === 0) re.lastIndex += 1;
|
|
126
|
+
continue;
|
|
127
|
+
}
|
|
128
|
+
if (!filter || filter(match[0])) {
|
|
129
|
+
found.add(category);
|
|
130
|
+
break;
|
|
131
|
+
}
|
|
132
|
+
if (match[0].length === 0) re.lastIndex += 1;
|
|
133
|
+
}
|
|
134
|
+
}
|
|
135
|
+
return [...found];
|
|
136
|
+
}
|
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
/**
|
|
3
|
+
* PreToolUse hook (matcher: Write|Edit|MultiEdit).
|
|
4
|
+
*
|
|
5
|
+
* Denies writing a secret-shaped string into anything under `output/`
|
|
6
|
+
* (excluding `output/**\/snapshots/`, which never ships a report and is
|
|
7
|
+
* excluded from the secrets scan the same way `qualiow session finalize`
|
|
8
|
+
* excludes it). Mechanises security rule 3 (redact before disk) instead of
|
|
9
|
+
* relying on the model remembering it.
|
|
10
|
+
*
|
|
11
|
+
* Node built-ins only, plus the sibling `secret-patterns.mjs` — a
|
|
12
|
+
* git-sourced plugin install has neither `dist/` nor `node_modules`. Never
|
|
13
|
+
* throws and never echoes the matched text back: the denial reason names
|
|
14
|
+
* categories only.
|
|
15
|
+
*/
|
|
16
|
+
import { readFileSync } from 'node:fs';
|
|
17
|
+
import { findSecretCategories } from './secret-patterns.mjs';
|
|
18
|
+
|
|
19
|
+
const WRITE_TOOLS = new Set(['Write', 'Edit', 'MultiEdit']);
|
|
20
|
+
|
|
21
|
+
function deny(reason) {
|
|
22
|
+
process.stdout.write(
|
|
23
|
+
JSON.stringify({
|
|
24
|
+
hookSpecificOutput: {
|
|
25
|
+
hookEventName: 'PreToolUse',
|
|
26
|
+
permissionDecision: 'deny',
|
|
27
|
+
permissionDecisionReason: reason,
|
|
28
|
+
},
|
|
29
|
+
}),
|
|
30
|
+
);
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
function collectText(toolName, toolInput) {
|
|
34
|
+
if (!toolInput) return '';
|
|
35
|
+
if (toolName === 'Write') {
|
|
36
|
+
return typeof toolInput.content === 'string' ? toolInput.content : '';
|
|
37
|
+
}
|
|
38
|
+
if (toolName === 'Edit') {
|
|
39
|
+
return typeof toolInput.new_string === 'string' ? toolInput.new_string : '';
|
|
40
|
+
}
|
|
41
|
+
if (toolName === 'MultiEdit') {
|
|
42
|
+
const edits = Array.isArray(toolInput.edits) ? toolInput.edits : [];
|
|
43
|
+
return edits
|
|
44
|
+
.map((e) => (e && typeof e.new_string === 'string' ? e.new_string : ''))
|
|
45
|
+
.join('\n');
|
|
46
|
+
}
|
|
47
|
+
return '';
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
try {
|
|
51
|
+
if (process.env.QUALIOW_HOOKS === 'off') process.exit(0);
|
|
52
|
+
|
|
53
|
+
let raw = '';
|
|
54
|
+
try {
|
|
55
|
+
raw = readFileSync(0, 'utf-8');
|
|
56
|
+
} catch {
|
|
57
|
+
process.exit(0);
|
|
58
|
+
}
|
|
59
|
+
if (!raw || !raw.trim()) process.exit(0);
|
|
60
|
+
|
|
61
|
+
const input = JSON.parse(raw);
|
|
62
|
+
if (!WRITE_TOOLS.has(input.tool_name)) process.exit(0);
|
|
63
|
+
|
|
64
|
+
const toolInput = input.tool_input || {};
|
|
65
|
+
const filePath = toolInput.file_path;
|
|
66
|
+
if (!filePath || typeof filePath !== 'string') process.exit(0);
|
|
67
|
+
|
|
68
|
+
const normalized = filePath.split('\\').join('/');
|
|
69
|
+
if (!/(^|\/)output\//.test(normalized)) process.exit(0);
|
|
70
|
+
if (normalized.includes('/snapshots/')) process.exit(0);
|
|
71
|
+
|
|
72
|
+
const text = collectText(input.tool_name, toolInput);
|
|
73
|
+
if (!text) process.exit(0);
|
|
74
|
+
|
|
75
|
+
const categories = findSecretCategories(text);
|
|
76
|
+
if (categories.length > 0) {
|
|
77
|
+
deny(
|
|
78
|
+
`Refusing to write ${filePath}: it contains ${categories.join(', ')}. ` +
|
|
79
|
+
'Redact per security-rules.md ([REDACTED]) before writing; ' +
|
|
80
|
+
'qualiow session finalize --redact rewrites an existing file. ' +
|
|
81
|
+
'Set QUALIOW_HOOKS=off to disable.',
|
|
82
|
+
);
|
|
83
|
+
}
|
|
84
|
+
process.exit(0);
|
|
85
|
+
} catch {
|
|
86
|
+
process.exit(0);
|
|
87
|
+
}
|