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.
Files changed (106) hide show
  1. package/.claude-plugin/marketplace.json +26 -0
  2. package/.claude-plugin/plugin.json +22 -0
  3. package/.env.example +27 -0
  4. package/CHANGELOG.md +259 -0
  5. package/README.md +472 -204
  6. package/agents/qa-diff-indexer-agent.md +81 -0
  7. package/agents/qa-gather-agent.md +41 -0
  8. package/agents/qa-page-mapper-agent.md +74 -0
  9. package/agents/qa-reporting-agent.md +103 -0
  10. package/{scripts → bin}/doctor-mobile.sh +57 -18
  11. package/bin/mcli +15 -9
  12. package/bin/mobile-cli.mjs +574 -286
  13. package/bin/qualiow +30 -0
  14. package/{scripts → bin}/setup-mobile.sh +56 -19
  15. package/bin/wadb +10 -4
  16. package/bin/wk-ios +29 -17
  17. package/bin/wkeval.mjs +7 -1
  18. package/data/domains/_default.yml +1 -1
  19. package/data/knowledge/changelog.yml +30 -12
  20. package/data/knowledge/manifest.yml +355 -127
  21. package/data/knowledge/releases/v0.1.0/entries/technique-business-logic-race-conditions.yml +1 -1
  22. package/data/knowledge/releases/v0.1.0/release.yml +8 -1
  23. package/data/knowledge/releases/v0.6.0/entries/technique-async-callback-contracts.yml +98 -0
  24. package/data/knowledge/releases/v0.6.0/entries/technique-exactly-once-verification.yml +116 -0
  25. package/data/knowledge/releases/v0.6.0/release.yml +30 -0
  26. package/data/security/SECURITY-POLICY.md +273 -0
  27. package/data/targets/_default.yml +1 -1
  28. package/data/targets/_example-api-only.yml +80 -0
  29. package/data/targets/_example-mobile-emulation.yml +2 -2
  30. package/data/targets/_example-native-mobile.yml +2 -2
  31. package/data/targets/_example-sim-android-chrome.yml +1 -1
  32. package/data/targets/_example-sim-ios-safari.yml +1 -1
  33. package/data/templates/api-probe-matrix.md +3 -3
  34. package/data/templates/bug-report.md +29 -151
  35. package/data/templates/coverage-map.md +9 -6
  36. package/data/templates/expected-behaviour.md +3 -2
  37. package/data/templates/session-charter.md +3 -0
  38. package/data/templates/session-report.md +57 -80
  39. package/dist/cli/index.js +2286 -701
  40. package/dist/index.d.ts +637 -81
  41. package/dist/index.js +2058 -228
  42. package/docs/BACKEND-VERIFICATION.md +39 -9
  43. package/docs/GETTING-STARTED.md +300 -121
  44. package/docs/MOBILE-SETUP.md +149 -18
  45. package/hooks/hooks.json +27 -0
  46. package/hooks/scripts/read-guard.mjs +95 -0
  47. package/hooks/scripts/secret-patterns.d.mts +8 -0
  48. package/hooks/scripts/secret-patterns.mjs +136 -0
  49. package/hooks/scripts/write-guard.mjs +87 -0
  50. package/package.json +33 -18
  51. package/skills/qa-explore/SKILL.md +32 -25
  52. package/skills/qa-explore/phases/00-setup.md +76 -42
  53. package/skills/qa-explore/phases/01-auth.md +32 -15
  54. package/skills/qa-explore/phases/02-charter.md +16 -5
  55. package/skills/qa-explore/phases/03-discovery.md +93 -27
  56. package/skills/qa-explore/phases/04-journeys.md +2 -2
  57. package/skills/qa-explore/phases/05-features.md +39 -24
  58. package/skills/qa-explore/phases/06-edge-cases.md +24 -13
  59. package/skills/qa-explore/phases/07-reporting.md +102 -142
  60. package/skills/qa-explore/references/context-integration.md +1 -1
  61. package/skills/qa-explore/references/delegation-rules.md +82 -0
  62. package/skills/qa-explore/references/output-contract.md +192 -0
  63. package/skills/qa-explore/references/paths.md +108 -0
  64. package/skills/qa-explore/references/playwright-agents-integration.md +61 -84
  65. package/skills/qa-explore/references/security-rules.md +70 -25
  66. package/skills/qa-explore/references/session-rules.md +2 -1
  67. package/skills/qa-explore/references/severity-guide.md +31 -4
  68. package/skills/qa-explore-cleanup/SKILL.md +51 -15
  69. package/skills/qa-explore-feedback/SKILL.md +23 -5
  70. package/skills/qa-explore-mobile/SKILL.md +86 -64
  71. package/skills/qa-explore-mobile/phases/00-setup.md +71 -62
  72. package/skills/qa-explore-mobile/phases/01-auth.md +28 -31
  73. package/skills/qa-explore-mobile/phases/02-charter.md +8 -4
  74. package/skills/qa-explore-mobile/phases/03-discovery.md +17 -11
  75. package/skills/qa-explore-mobile/phases/04-journeys.md +6 -6
  76. package/skills/qa-explore-mobile/phases/05-features.md +9 -9
  77. package/skills/qa-explore-mobile/phases/06-edge-cases.md +35 -40
  78. package/skills/qa-explore-mobile/phases/07-reporting.md +108 -60
  79. package/skills/qa-explore-mobile/references/mobile-edges.md +26 -26
  80. package/skills/qa-explore-quick/SKILL.md +71 -26
  81. package/skills/qa-explore-report/SKILL.md +65 -35
  82. package/skills/qa-gather/SKILL.md +44 -8
  83. package/skills/qa-knowledge-add/SKILL.md +25 -9
  84. package/skills/qa-knowledge-list/SKILL.md +37 -40
  85. package/skills/qa-target-setup/SKILL.md +63 -41
  86. package/skills/qa-verify-backend/SKILL.md +31 -19
  87. package/skills/qa-verify-backend/phases/00-setup.md +57 -12
  88. package/skills/qa-verify-backend/phases/01-ac-decomposition.md +2 -2
  89. package/skills/qa-verify-backend/phases/02-static-review.md +11 -0
  90. package/skills/qa-verify-backend/phases/03-live-verification.md +5 -3
  91. package/skills/qa-verify-backend/phases/03b-api-verification.md +24 -9
  92. package/skills/qa-verify-backend/phases/04-e2e-trigger.md +18 -2
  93. package/skills/qa-verify-backend/phases/05-reporting.md +72 -12
  94. package/skills/qa-verify-backend/references/api-probes.md +28 -1
  95. package/skills/qa-verify-backend/references/payload-verification.md +1 -1
  96. package/skills/qa-verify-backend/references/release-readiness.md +1 -1
  97. package/skills/qa-verify-backend/references/safety-rules.md +13 -8
  98. package/data/domains/_default.md +0 -181
  99. package/data/domains/ecommerce.md +0 -192
  100. package/data/domains/fintech.md +0 -200
  101. package/data/domains/identity.md +0 -88
  102. package/data/domains/marketing.md +0 -194
  103. package/data/domains/saas.md +0 -197
  104. package/dist/cli/index.d.ts +0 -1
  105. package/dist/cli/index.js.map +0 -1
  106. package/dist/index.js.map +0 -1
@@ -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
- scripts/setup-mobile.sh # or --android / --ios, add --yes for non-interactive
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
- scripts/doctor-mobile.sh
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
- # e.g. iOS Safari against your mobile web app:
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
- `scripts/setup-mobile.sh` automates everything it can and **prints clear MANUAL steps**
24
- for the few things it can't (Xcode + the iOS runtime). It finishes by running the doctor.
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 ≥ 18 | runs `mobile-cli.mjs` | ✅ |
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-commandline-tools` |
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
- Then re-run `scripts/setup-mobile.sh` — it will create the `qa-iphone` device.
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
- adb shell pm list packages | grep chrome
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` and defaults `ANDROID_HOME` to `~/Library/Android/sdk`.
83
- Export them explicitly if your SDK lives elsewhere.
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
- This covers iOS Simulator + Android Emulator (browser **and** native modes). It does **not**
91
- provision physical devices, CI runners, or the desktop web path (`/qa-explore`, which only
92
- needs `playwright-cli`).
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`).
@@ -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
+ }