qualiow-exploratory-testing 2.3.0 → 2.3.1

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 (37) hide show
  1. package/.claude-plugin/marketplace.json +1 -1
  2. package/.claude-plugin/plugin.json +1 -1
  3. package/CHANGELOG.md +80 -0
  4. package/README.md +20 -13
  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-reporting-agent.md +1 -1
  9. package/bin/mobile-cli.mjs +74 -26
  10. package/bin/qualiow +7 -2
  11. package/bin/wk-ios +60 -6
  12. package/bin/wkeval.mjs +7 -2
  13. package/dist/cli/index.js +718 -172
  14. package/dist/index.d.ts +63 -19
  15. package/dist/index.js +586 -136
  16. package/docs/GETTING-STARTED.md +19 -9
  17. package/docs/MOBILE-SETUP.md +31 -0
  18. package/hooks/hooks.json +12 -2
  19. package/hooks/scripts/bash-guard.mjs +242 -0
  20. package/hooks/scripts/secret-patterns.d.mts +4 -1
  21. package/hooks/scripts/secret-patterns.mjs +126 -34
  22. package/hooks/scripts/write-guard.mjs +70 -15
  23. package/package.json +1 -1
  24. package/skills/qa-explore/SKILL.md +1 -1
  25. package/skills/qa-explore/references/evidence-triage.md +44 -12
  26. package/skills/qa-explore/references/output-contract.md +1 -1
  27. package/skills/qa-explore/references/security-rules.md +14 -2
  28. package/skills/qa-explore-cleanup/SKILL.md +1 -1
  29. package/skills/qa-explore-mobile/SKILL.md +13 -3
  30. package/skills/qa-explore-mobile/references/mobile-edges.md +3 -1
  31. package/skills/qa-explore-quick/SKILL.md +1 -1
  32. package/skills/qa-explore-report/SKILL.md +1 -1
  33. package/skills/qa-gather/SKILL.md +1 -1
  34. package/skills/qa-knowledge-add/SKILL.md +1 -1
  35. package/skills/qa-knowledge-list/SKILL.md +1 -1
  36. package/skills/qa-verify-backend/SKILL.md +1 -1
  37. package/skills/qa-verify-backend/phases/05-reporting.md +2 -1
@@ -12,7 +12,7 @@
12
12
  "name": "qualiow",
13
13
  "source": "./",
14
14
  "description": "AI-driven exploratory testing for Claude Code: web (playwright-cli), iOS/Android simulators (Maestro via mobile-cli), and backend/API acceptance-criteria verification — with a versioned QA knowledge base.",
15
- "version": "2.3.0",
15
+ "version": "2.3.1",
16
16
  "category": "testing",
17
17
  "keywords": [
18
18
  "exploratory-testing",
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "qualiow",
3
3
  "displayName": "Qualiow Exploratory Testing",
4
- "version": "2.3.0",
4
+ "version": "2.3.1",
5
5
  "description": "AI-driven exploratory testing for Claude Code: web (playwright-cli), iOS/Android simulators (Maestro via mobile-cli), and backend/API acceptance-criteria verification — with a versioned QA knowledge base.",
6
6
  "author": {
7
7
  "name": "William Oliveira",
package/CHANGELOG.md CHANGED
@@ -1,5 +1,85 @@
1
1
  # Changelog
2
2
 
3
+ ## [2.3.1] - 2026-10-04
4
+
5
+ Security hardening from a review of the 2.3.0 changes. Nothing here changes what a session
6
+ finds; it narrows what a session can do and what leaves the machine.
7
+
8
+ **Upgrading**
9
+
10
+ - A proxy started by an older `wk-ios` is not found by the new `--stop`; kill it once by hand
11
+ (`pkill ios_webkit_debug_proxy`).
12
+ - npm projects with hooks: run `npx qualiow init --hooks` again to add the new bash guard and
13
+ the `NotebookEdit` write-guard matcher; skills need `init --force` for the narrowed grants.
14
+ - `qualiow report -o <file>` now writes under `output/` (`-o report.html` → `output/report.html`).
15
+ - `playwright-cli run-code` now asks for confirmation every time, including in `/qa-explore`
16
+ phases 3, 6 and 7.
17
+
18
+ ### Security
19
+
20
+ - **Redaction caught nothing inside JSON.** `"password":"…"`, `"Authorization":"Bearer …"`,
21
+ `"access_token"`, `"client_secret"`, `"apiKey"` and indented or mid-line `Cookie:` passed the
22
+ redaction list behind `session finalize`, the formatters, the write guard and the triage
23
+ scrubber. Quoted keys are now matched and the JSON stays valid. Added Stripe, Google API and
24
+ OAuth, npm, GitLab, Slack `xoxe-` and webhook, STS `SecretAccessKey`/`SessionToken`, `Bearer`
25
+ under any label, PGP and truncated private keys; `*.example.com` subdomain emails are no
26
+ longer exempt. Every rule runs in linear time; `redact.ts` and the hook's copy are checked
27
+ identical by a test.
28
+ - **Triage could send the storage state.** The evidence collector followed symlinks out of the
29
+ session, and the session directory was taken from the claim card's parent folders alone. The
30
+ card must now sit in `output/sessions/<dir>/verification/claims/` of a real session, every
31
+ evidence path is checked after resolving symlinks, `.auth/` and storage-state-shaped files
32
+ are refused, and reads are size-capped. `claimed_severity`, `reproduction_rate` and file names
33
+ are now scrubbed; any `scheme://`, JSON-escaped and scheme-less URLs lose credentials and
34
+ query. The provider response is rebuilt from the questions asked (choice allow-listed, model
35
+ name flattened, body size-capped), so it cannot inject text into stdout or the block file.
36
+ The saved request is now the exact body sent.
37
+ - **Skill and agent grants narrowed.** Bare `Bash(npx:*)`, `Bash(node:*)` and `Bash(git:*)` are
38
+ gone from every skill and agent; each lists the commands it uses.
39
+ - **New `bash-guard.mjs` hook** (plugin default; `init --hooks` for npm): asks before
40
+ `playwright-cli run-code` (it runs in the Playwright node process, not the browser) and before
41
+ `git` options that can run a shell; denies `npx -c` and `npx -y`/`-p` of a package outside
42
+ the allowlist.
43
+ - **Write guard** checks an `Edit` against the file as it will read afterwards, normalises
44
+ `..`, matches `output/` case-insensitively and covers `NotebookEdit`.
45
+ - **`session finalize`** scans every text file whatever its extension (`.txt`, `.har`, `.csv`…),
46
+ skips only the top-level `snapshots/`, and refuses a symlink leading outside the session or a
47
+ text file over 32MB.
48
+ - **`init --hooks`** refuses to overwrite a `settings.json` it cannot parse (it used to replace
49
+ it, dropping deny rules) and upgrades the matcher of an existing qualiow-only entry.
50
+ - **`report -o`** is confined to `output/`.
51
+ - `INDEX.md` / `all-bugs.md` cells escape `|` and newlines, and row dedupe/delete match the
52
+ exact Report cell instead of a substring.
53
+ - `session prune --older-than` accepts plain decimals only.
54
+ - `session finalize` reads UTF-16 files (with or without a byte-order mark) as text instead of
55
+ skipping them as binary, and `--redact` writes them back in their own encoding.
56
+ - `list knowledge --entry` and `kb digest --entry` refuse an id that is a path, so they cannot
57
+ print a `.yml` file outside the knowledge base.
58
+ - **Mobile driver.** `adb shell` re-parses its arguments in the device shell, so a deep link with
59
+ `;` ran a command on the device and every link with `&` was cut short (the skill's own
60
+ deep-link edge cases silently tested a truncated URL on Android). Every device-shell argument
61
+ is now single-quoted and app ids are validated at `set-app`. Typed text escapes Maestro's
62
+ `${…}` evaluation so it is typed literally, and a testID containing `${` is refused. Control
63
+ characters from the app are stripped from snapshots, logs and `wkeval` output.
64
+ - **`wk-ios`.** `ios_webkit_debug_proxy` 1.9.2 has no localhost-only bind, so the proxy listens
65
+ on every interface without authentication; `wk-ios` now says so when it starts it, the docs
66
+ and the mobile skill make `wk-ios --stop` mandatory, and the pid and log files moved to a
67
+ private `${TMPDIR}/wk-ios-<uid>/`. `WK_PAGE_FILTER` matches the parsed URL (host or subdomain,
68
+ `host:port`, path prefix) instead of a substring anywhere in it.
69
+ - `bin/qualiow` refuses to run when it cannot read an exact version from `plugin.json`, instead
70
+ of falling back to `npx …@latest`.
71
+ - CI runs with a read-only token, pins its actions by commit SHA and pins the `claude-code`
72
+ used for `plugin validate`. `brace-expansion` 5.0.7 → 5.0.12 (advisories reachable through
73
+ `glob`).
74
+
75
+ ### Fixed
76
+
77
+ - **`wk-ios` can evaluate in a stale Safari tab.** Safari keeps old tabs inspectable, so the
78
+ newest non-blank page is not always the page under test. A new optional `WK_PAGE_FILTER`
79
+ (a substring of the page URL) picks the newest page whose URL contains it, and no match is an
80
+ error that names the filter instead of a silent fallback to another tab. Unset, the selection
81
+ is unchanged. Documented in `docs/MOBILE-SETUP.md` and the `qa-explore-mobile` skill.
82
+
3
83
  ## [2.3.0] - 2026-10-03
4
84
 
5
85
  A second opinion before a bug ships. `/qa-explore` now sends every candidate bug to an
package/README.md CHANGED
@@ -48,7 +48,7 @@ It also creates `output/{sessions,bugs,context}`, `.auth/` and `qa/`, and append
48
48
  `.playwright-cli/`, `*.trace.zip`, `*.webm`).
49
49
 
50
50
  Re-running `init` is a no-op — existing files are kept unless you pass `--force`, and
51
- `--dry-run` prints the plan without writing anything. Add `--hooks` to install the two guard
51
+ `--dry-run` prints the plan without writing anything. Add `--hooks` to install the three guard
52
52
  hooks into the project as well — see [Hooks](#hooks).
53
53
 
54
54
  ```bash
@@ -110,7 +110,7 @@ from the shell.
110
110
  | `qualiow explore [url]` | `-t <target>` `-c <context>` `--time-box 45m` `--dry-run` | **Pre-flight only.** Validates the inputs, creates the session directory skeleton, and prints the `/qa-explore … --session <dir>` command to paste into Claude Code. It does not drive a browser |
111
111
  | `qualiow validate` | `--targets` `--domains` `--knowledge` `--kb` `--all` | Validate configs against their schemas; exits 1 on any failure. `--all` also checks a project-local `qa/target.yml` and cross-checks the knowledge base against its manifest |
112
112
  | `qualiow list <type>` | `sessions` \| `knowledge` \| `targets` \| `domains`; for `knowledge` also `--domain` `--tag` `--type` `--entry <id>` `--changelog` `--stats` | List what is installed or recorded. `list knowledge --entry <id>` prints that entry's YAML; `--changelog` and `--stats` read the knowledge changelog and the manifest counts |
113
- | `qualiow report` | `-s <id>\|latest` `-f md\|html\|json\|jira` `-o <file>` `--stdout` | Export an existing session. `md` writes `session-summary.md`; html/json/jira carry the confidentiality header and pass through redaction |
113
+ | `qualiow report` | `-s <id>\|latest` `-f md\|html\|json\|jira` `-o <file>` `--stdout` | Export an existing session. `-o` is confined to `output/` (relative paths resolve inside it; `..` is refused). `md` writes `session-summary.md`; html/json/jira carry the confidentiality header and pass through redaction |
114
114
  | `qualiow kb <sync\|check>` | — | Regenerate or validate `data/knowledge/manifest.yml` from the release files |
115
115
  | `qualiow kb digest` | `--for explore\|backend\|mobile` `--domain <id>` `--tag <t...>` `--entry <id>` `--data <dir>` `--max-lines <n>` | Print a compact digest of the knowledge entries a session needs, instead of the manifest and the entries read whole. `--entry <id>` prints one entry in full |
116
116
  | `qualiow session finalize <dir\|latest>` | `--check` `--redact` | Close a session: validate it against the output contract, then append the INDEX row, the bug rows and the metrics line. `--check` writes nothing; `--redact` rewrites files that still carry a secret |
@@ -205,8 +205,9 @@ reference: [`skills/qa-explore/references/evidence-triage.md`](skills/qa-explore
205
205
 
206
206
  ### Hooks
207
207
 
208
- Two `PreToolUse` hooks enforce what the delegation rules ask for, and they are scoped to
209
- qualiow-owned paths so they never interfere with ordinary coding in the same project:
208
+ Three `PreToolUse` hooks enforce what the delegation and security rules ask for. The read and
209
+ write guards are scoped to qualiow-owned paths; the bash guard sees every `Bash` command but
210
+ only acts on the few patterns below, so ordinary coding in the same project is unaffected:
210
211
 
211
212
  - **`read-guard.mjs`** (matcher `Read`) fires only for `data/knowledge/manifest.yml`,
212
213
  `data/knowledge/releases/**`, `output/sessions/*/phase-*.md` and
@@ -215,12 +216,18 @@ qualiow-owned paths so they never interfere with ordinary coding in the same pro
215
216
  reason — `qualiow kb digest`, `qualiow list knowledge --entry <id>`, a `Grep` plus a `Read`
216
217
  with `offset`/`limit`, or `qa-page-mapper-agent`. A `Read` that already carries `offset` or
217
218
  `limit` passes untouched.
218
- - **`write-guard.mjs`** (matcher `Write|Edit|MultiEdit`) fires only for files under `output/`
219
- and never inside `snapshots/`. It denies content matching the same redaction list the
220
- formatters and `qualiow session finalize` apply, naming the categories it matched, so a
221
- secret is caught before it reaches disk rather than after.
222
-
223
- Set `QUALIOW_HOOKS=off` to disable both, and `QUALIOW_READ_MAX_LINES` to move the threshold —
219
+ - **`write-guard.mjs`** (matcher `Write|Edit|MultiEdit|NotebookEdit`) fires only for files
220
+ under `output/` and never inside `snapshots/`. It denies content matching the same redaction
221
+ list the formatters and `qualiow session finalize` apply — for an `Edit`, the file as it will
222
+ read after the edit — naming the categories it matched, so a secret is caught before it
223
+ reaches disk rather than after.
224
+ - **`bash-guard.mjs`** (matcher `Bash`) asks before `playwright-cli run-code` (it runs in the
225
+ Playwright node process, not the browser sandbox), asks before `git` with options that can
226
+ run a shell (`-c`, `--upload-pack`, `--ext-diff`…), and denies `npx -c` and `npx -y`/`-p` of a
227
+ package outside `playwright-cli`, `@playwright/cli` and `qualiow-exploratory-testing`. It is a
228
+ safety net, not a sandbox.
229
+
230
+ Set `QUALIOW_HOOKS=off` to disable all three, and `QUALIOW_READ_MAX_LINES` to move the threshold —
224
231
  in `.claude/settings.json` under `env`:
225
232
 
226
233
  ```json
@@ -229,7 +236,7 @@ in `.claude/settings.json` under `env`:
229
236
 
230
237
  **Plugin installs get the hooks by default** — `hooks/hooks.json` ships with the plugin and is
231
238
  discovered without any configuration. **npm projects opt in** with `qualiow init --hooks`,
232
- which copies the scripts to `qa/hooks/` and merges into `.claude/settings.json` the two hook
239
+ which copies the scripts to `qa/hooks/` and merges into `.claude/settings.json` the three hook
233
240
  entries plus `permissions.allow` rules for `Bash(playwright-cli:*)`,
234
241
  `Bash(npx playwright-cli:*)` and `Bash(qualiow:*)`. The merge is by exact string, so running
235
242
  it twice changes nothing and hooks you already had are left alone. `docs/GETTING-STARTED.md`
@@ -551,7 +558,7 @@ Full guide: **[docs/BACKEND-VERIFICATION.md](docs/BACKEND-VERIFICATION.md)**. Sa
551
558
  confidentiality header and runs through the same redaction list as the skills.
552
559
 
553
560
  ```bash
554
- qualiow report -s latest -f html -o report.html
561
+ qualiow report -s latest -f html -o report.html # writes output/report.html
555
562
  qualiow report -s 2026-09-08-1813-explore-parabank -f jira -o bugs.csv
556
563
  qualiow report -s latest -f json --stdout
557
564
  ```
@@ -613,7 +620,7 @@ qualiow-exploratory-testing-skills/
613
620
  marketplace.json # the repo is its own marketplace (source: "./")
614
621
  hooks/
615
622
  hooks.json # PreToolUse registrations (plugin default discovery path)
616
- scripts/ # read-guard.mjs, write-guard.mjs, secret-patterns.mjs
623
+ scripts/ # read-guard.mjs, write-guard.mjs, bash-guard.mjs, secret-patterns.mjs
617
624
  bin/
618
625
  qualiow # CLI launcher shim (local build, else npx the npm package)
619
626
  mcli, mobile-cli.mjs # Maestro/simctl/adb shim + permission-friendly wrapper
@@ -7,7 +7,7 @@ description: >
7
7
  re-reproduction in its own browser session and by evidence review, and returns one fenced
8
8
  verdict block (CONFIRMED, CONFIRMED-ADJUSTED, REFUTED, UNREPRODUCIBLE or UNVERIFIED). It
9
9
  never writes a bug report, never decides what ships, never assigns business impact.
10
- tools: Read, Glob, Grep, Bash(playwright-cli:*), Bash(npx:*), Bash(bin/mcli:*), Bash(qa/bin/mcli:*)
10
+ tools: Read, Glob, Grep, Bash(playwright-cli:*), Bash(npx playwright-cli:*), Bash(bin/mcli:*), Bash(qa/bin/mcli:*)
11
11
  model: opus
12
12
  effort: high
13
13
  maxTurns: 40
@@ -6,7 +6,7 @@ description: >
6
6
  candidate AC ids, plus the files no AC claims and the ACs no file serves. Use it when
7
7
  `git diff --stat` reports 25 or more files or 1,500 or more changed lines, so the session
8
8
  reads only the code that maps to an AC. It returns a map, never a verdict.
9
- tools: Read, Grep, Bash(git:*), Bash(wc:*)
9
+ tools: Read, Grep, Bash(git diff:*), Bash(git show:*), Bash(wc:*)
10
10
  model: haiku
11
11
  effort: low
12
12
  maxTurns: 25
@@ -5,7 +5,7 @@ description: >
5
5
  text, diffs) and writes a structured context file for exploratory testing sessions.
6
6
  The /qa-gather skill runs inside this agent; invoke it directly for long or multi-source
7
7
  gathers that should run in the background.
8
- tools: Read, Write, Glob, Grep, WebFetch, Bash(git:*), Bash(wc:*)
8
+ tools: Read, Write, Glob, Grep, WebFetch, Bash(git diff:*), Bash(git log:*), Bash(git show:*), Bash(wc:*)
9
9
  model: sonnet
10
10
  maxTurns: 40
11
11
  ---
@@ -6,7 +6,7 @@ description: >
6
6
  `qualiow session finalize` to append the index rows. Use it once a session has written its
7
7
  bugs, its stats and its phase-7 notes. It copies the judgement already recorded in the
8
8
  notes — it never grades a bug and never writes a summary of its own.
9
- tools: Read, Write, Glob, Grep, Bash(qualiow:*), Bash(npx:*), Bash(wc:*)
9
+ tools: Read, Write, Glob, Grep, Bash(qualiow:*), Bash(npx -y -p qualiow-exploratory-testing qualiow:*), Bash(wc:*)
10
10
  model: sonnet
11
11
  effort: low
12
12
  maxTurns: 30
@@ -35,7 +35,14 @@
35
35
  //
36
36
  // Every Maestro flow is generated by buildFlow(), which serialises each scalar with
37
37
  // JSON.stringify — a JSON string is a valid YAML double-quoted scalar, so quotes,
38
- // newlines and backslashes in typed text can never inject extra flow steps.
38
+ // newlines and backslashes in typed text can never inject extra flow steps. That only
39
+ // closes the YAML layer: Maestro then evaluates every `${...}` in a string parameter as
40
+ // GraalJS on the host (it can make HTTP calls). Typed text goes through maestroLiteral(),
41
+ // which escapes each `${...}` so it is typed verbatim; testIDs containing `${` are refused.
42
+ //
43
+ // Every value after `adb shell` goes through shq(): adb joins its arguments with spaces
44
+ // and the DEVICE's /system/bin/sh re-parses the result, so an unquoted `&` or `;` in a
45
+ // URL would truncate it or run a command on the device. App ids are validated at set-app.
39
46
 
40
47
  import { execFileSync, spawn } from 'node:child_process';
41
48
  import {
@@ -126,9 +133,50 @@ function reqDevice(s) {
126
133
  function reqApp(s) {
127
134
  reqDevice(s);
128
135
  if (!s.appId) throw new CliError('No app set. Run: mobile-cli set-app <bundleId|package>', EXIT.NO_DEVICE);
136
+ validateAppId(s.appId); // also catches a hand-edited state file
129
137
  return s;
130
138
  }
131
139
 
140
+ // ---- argument hygiene (pure, exported for tests) ----
141
+ // Android package names are [A-Za-z0-9_.]; iOS bundle ids also allow '-'. A leading
142
+ // alphanumeric keeps an id from being read as an option by am/pm/simctl.
143
+ const APP_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
144
+ export function validateAppId(id) {
145
+ if (!APP_ID_RE.test(String(id || ''))) {
146
+ throw new CliError(`Invalid app id '${id}': use a bundle id or package name (letters, digits, '.', '_', '-')`, EXIT.USAGE);
147
+ }
148
+ return id;
149
+ }
150
+ // pkg/.Activity or pkg/fully.qualified.Activity ('$' for nested classes).
151
+ const COMPONENT_RE = /^[A-Za-z0-9._-]+\/[A-Za-z0-9._$]+$/;
152
+ export function isComponentName(c) { return COMPONENT_RE.test(String(c || '')); }
153
+
154
+ // Single-quote one argument for the device's POSIX sh: ' becomes '\''.
155
+ export function shq(v) { return `'${String(v).replace(/'/g, `'\\''`)}'`; }
156
+ function adbShell(device, ...cmd) {
157
+ return runOk('adb', ['-s', device, 'shell', ...cmd.map(shq)]);
158
+ }
159
+
160
+ // Maestro evaluates `${...}` (no '$' inside, closed by '}') unless preceded by a backslash,
161
+ // then strips that backslash — Env.evaluateScripts in Maestro 2.x. Escaping exactly the
162
+ // spans its regex would evaluate makes the text arrive verbatim, a user-typed `\${x}` included.
163
+ export function maestroLiteral(text) {
164
+ return String(text).replace(/\$\{[^$]*\}/g, (m) => `\\${m}`);
165
+ }
166
+ function refuseScript(id, what) {
167
+ if (String(id).includes('${')) {
168
+ throw new CliError(`${what} contains '\${' — Maestro would evaluate it as JavaScript. Use a snapshot ref instead.`, EXIT.USAGE);
169
+ }
170
+ return id;
171
+ }
172
+
173
+ // Terminal hygiene for app-/page-provided strings: drop C0/C1 controls (ESC, BEL, CR, ...).
174
+ // keepNewlines leaves \n and \t for multi-line output such as logs.
175
+ export function stripControls(s, { keepNewlines = false } = {}) {
176
+ const re = keepNewlines ? /[\u0000-\u0008\u000B-\u001F\u007F-\u009F]/g : /[\u0000-\u001F\u007F-\u009F]/g;
177
+ return String(s).replace(re, '');
178
+ }
179
+
132
180
  // ---- device detection (pure parts are exported for tests) ----
133
181
  export function parseAdbDevices(out) {
134
182
  return String(out || '')
@@ -396,8 +444,8 @@ export function assignRefs(json, opts = {}) {
396
444
  bounds: [bounds.x1, bounds.y1, bounds.x2, bounds.y2],
397
445
  kind,
398
446
  };
399
- const idPart = id ? ` id=${id}` : '';
400
- const textPart = text ? ` "${text.replace(/\s+/g, ' ').slice(0, 80)}"` : '';
447
+ const idPart = id ? ` id=${stripControls(id)}` : '';
448
+ const textPart = text ? ` "${stripControls(text.replace(/\s+/g, ' ')).slice(0, 80)}"` : '';
401
449
  const indent = ' '.repeat(Math.min(depth, 6));
402
450
  lines.push(`${indent}- [${ref}] ${kind}${textPart}${idPart}`);
403
451
  }
@@ -433,24 +481,24 @@ function tap(state, ref) {
433
481
  reqDevice(state);
434
482
  const r = getRef(state, ref);
435
483
  if (state.platform === 'android') {
436
- return runOk('adb', ['-s', state.device, 'shell', 'input', 'tap', String(r.x), String(r.y)]);
484
+ return adbShell(state.device, 'input', 'tap', String(r.x), String(r.y));
437
485
  }
438
486
  // iOS sim — simctl has no `io tap` and Maestro has no one-shot tap; run a tapOn-point flow.
439
487
  return runFlow(state, [{ tapOn: { point: `${r.x},${r.y}` } }]);
440
488
  }
441
489
  function tapById(state, id) {
442
490
  if (!id) throw new CliError('tap-id <testID> required', EXIT.USAGE);
443
- return runFlow(state, [{ tapOn: { id } }]);
491
+ return runFlow(state, [{ tapOn: { id: refuseScript(id, 'testID') } }]);
444
492
  }
445
493
  function fill(state, ref, text) {
446
494
  const tapRes = tap(state, ref);
447
495
  if (!tapRes.ok) return tapRes;
448
496
  sleep(250);
449
- return runFlow(state, [{ inputText: text }]);
497
+ return runFlow(state, [{ inputText: maestroLiteral(text) }]);
450
498
  }
451
499
  function fillById(state, id, text) {
452
500
  if (!id) throw new CliError('fill-id <testID> <text...> required', EXIT.USAGE);
453
- return runFlow(state, [{ tapOn: { id } }, { inputText: text }]);
501
+ return runFlow(state, [{ tapOn: { id: refuseScript(id, 'testID') } }, { inputText: maestroLiteral(text) }]);
454
502
  }
455
503
  function clearField(state, ref) {
456
504
  const tapRes = tap(state, ref);
@@ -482,7 +530,7 @@ function press(state, key) {
482
530
  if (!k) throw new CliError(`Unknown key: ${key}. One of: ${Object.keys(ANDROID_KEYS).join(', ')}`, EXIT.USAGE);
483
531
  reqDevice(state);
484
532
  if (state.platform === 'android') {
485
- return runOk('adb', ['-s', state.device, 'shell', 'input', 'keyevent', k]);
533
+ return adbShell(state.device, 'input', 'keyevent', k);
486
534
  }
487
535
  // iOS sim: no hardware keys, but Maestro can synthesize Enter and Home.
488
536
  if (IOS_KEYS[K]) return runFlow(state, [{ pressKey: IOS_KEYS[K] }]);
@@ -493,25 +541,25 @@ function launch(state) {
493
541
  reqApp(state);
494
542
  if (state.platform === 'android') {
495
543
  // Resolve the launcher activity and am start it; `monkey` breaks on newer images.
496
- const res = runOk('adb', ['-s', state.device, 'shell', 'cmd', 'package', 'resolve-activity', '--brief', '-c', 'android.intent.category.LAUNCHER', state.appId]);
544
+ const res = adbShell(state.device, 'cmd', 'package', 'resolve-activity', '--brief', '-c', 'android.intent.category.LAUNCHER', state.appId);
497
545
  const comp = (res.out || '').trim().split('\n').pop()?.trim();
498
- if (res.ok && comp && comp.includes('/')) {
499
- return runOk('adb', ['-s', state.device, 'shell', 'am', 'start', '-n', comp]);
546
+ if (res.ok && isComponentName(comp)) {
547
+ return adbShell(state.device, 'am', 'start', '-n', comp);
500
548
  }
501
- return runOk('adb', ['-s', state.device, 'shell', 'monkey', '-p', state.appId, '-c', 'android.intent.category.LAUNCHER', '1']);
549
+ return adbShell(state.device, 'monkey', '-p', state.appId, '-c', 'android.intent.category.LAUNCHER', '1');
502
550
  }
503
551
  return runOk('xcrun', ['simctl', 'launch', state.device, state.appId]);
504
552
  }
505
553
  function stop(state) {
506
554
  reqApp(state);
507
- if (state.platform === 'android') return runOk('adb', ['-s', state.device, 'shell', 'am', 'force-stop', state.appId]);
555
+ if (state.platform === 'android') return adbShell(state.device, 'am', 'force-stop', state.appId);
508
556
  return runOk('xcrun', ['simctl', 'terminate', state.device, state.appId]);
509
557
  }
510
558
  function relaunchClean(state) {
511
559
  reqApp(state);
512
560
  if (state.platform !== 'android') throw new CliError('relaunch-clean is android-only (use stop+launch on ios).', EXIT.USAGE);
513
561
  stop(state);
514
- runOk('adb', ['-s', state.device, 'shell', 'pm', 'clear', state.appId]);
562
+ adbShell(state.device, 'pm', 'clear', state.appId);
515
563
  return launch(state);
516
564
  }
517
565
 
@@ -538,7 +586,7 @@ function deepLink(state, url) {
538
586
  reqApp(state);
539
587
  if (!url) throw new CliError('deep-link|open-url <url> required', EXIT.USAGE);
540
588
  if (state.platform === 'android') {
541
- return runOk('adb', ['-s', state.device, 'shell', 'am', 'start', '-W', '-a', 'android.intent.action.VIEW', '-d', url, state.appId]);
589
+ return adbShell(state.device, 'am', 'start', '-W', '-a', 'android.intent.action.VIEW', '-d', url, state.appId);
542
590
  }
543
591
  return runOk('xcrun', ['simctl', 'openurl', state.device, url]);
544
592
  }
@@ -546,12 +594,12 @@ function deepLink(state, url) {
546
594
  function running(state) {
547
595
  reqDevice(state);
548
596
  if (state.platform === 'android') {
549
- const r = runOk('adb', ['-s', state.device, 'shell', 'dumpsys', 'window']);
597
+ const r = adbShell(state.device, 'dumpsys', 'window');
550
598
  if (!r.ok) return r;
551
599
  return { ok: true, out: r.out.split('\n').filter((l) => /mCurrentFocus|mFocusedApp/.test(l)).join('\n') };
552
600
  }
553
601
  const r = runOk('xcrun', ['simctl', 'listapps', state.device]);
554
- return r.ok ? { ok: true, out: r.out.slice(0, 400) } : r;
602
+ return r.ok ? { ok: true, out: stripControls(r.out.slice(0, 400), { keepNewlines: true }) } : r;
555
603
  }
556
604
 
557
605
  export function parseSince(args) {
@@ -572,10 +620,10 @@ function logs(state, args) {
572
620
  const p2 = (x) => String(x).padStart(2, '0');
573
621
  const ts = `${p2(t.getMonth() + 1)}-${p2(t.getDate())} ${p2(t.getHours())}:${p2(t.getMinutes())}:${p2(t.getSeconds())}.000`;
574
622
  const r = runOk('adb', ['-s', state.device, 'logcat', '-d', '-T', ts, errors ? '*:E' : '*:W']);
575
- return r.ok ? { ok: true, out: (r.out || '').split('\n').slice(-400).join('\n') } : r;
623
+ return r.ok ? { ok: true, out: stripControls((r.out || '').split('\n').slice(-400).join('\n'), { keepNewlines: true }) } : r;
576
624
  }
577
625
  const r = runOk('xcrun', ['simctl', 'spawn', state.device, 'log', 'show', '--last', `${since}s`, '--predicate', `processImagePath contains "${state.appId || ''}"`]);
578
- return r.ok ? { ok: true, out: (r.out || '').split('\n').slice(-400).join('\n') } : r;
626
+ return r.ok ? { ok: true, out: stripControls((r.out || '').split('\n').slice(-400).join('\n'), { keepNewlines: true }) } : r;
579
627
  }
580
628
  function logsClear(state) {
581
629
  reqDevice(state);
@@ -598,7 +646,7 @@ function recordStart(state, outPath) {
598
646
  // Record ON the device into a real mp4 container, pull it at record-stop.
599
647
  const devicePath = `/sdcard/_mcli_rec_${process.pid}.mp4`;
600
648
  const r = runOk('adb', ['-s', state.device, 'shell',
601
- `screenrecord --time-limit 180 ${devicePath} </dev/null >/dev/null 2>&1 & echo $!`]);
649
+ `screenrecord --time-limit 180 ${shq(devicePath)} </dev/null >/dev/null 2>&1 & echo $!`]);
602
650
  const devicePid = parseInt((r.out || '').trim().split('\n').pop(), 10);
603
651
  if (!r.ok || !Number.isInteger(devicePid)) throw new CliError('could not start screenrecord: ' + (r.err || r.out));
604
652
  writeFileSync(recPath(), JSON.stringify({ platform: 'android', device: state.device, devicePid, devicePath, outPath, startedAt }));
@@ -616,15 +664,15 @@ function recordStop() {
616
664
  if (!Number.isInteger(rec.devicePid) || !rec.devicePath || !rec.outPath || !rec.device) {
617
665
  throw new CliError(`corrupt recording record — delete ${recPath()} and retry`);
618
666
  }
619
- runOk('adb', ['-s', rec.device, 'shell', 'kill', '-2', String(rec.devicePid)]);
667
+ adbShell(rec.device, 'kill', '-2', String(rec.devicePid));
620
668
  sleep(1500);
621
669
  for (let i = 0; i < 10; i++) { // wait for screenrecord to finalise the file
622
- const alive = runOk('adb', ['-s', rec.device, 'shell', 'kill', '-0', String(rec.devicePid)]);
670
+ const alive = adbShell(rec.device, 'kill', '-0', String(rec.devicePid));
623
671
  if (!alive.ok) break;
624
672
  sleep(500);
625
673
  }
626
674
  const pull = runOk('adb', ['-s', rec.device, 'pull', rec.devicePath, rec.outPath]);
627
- runOk('adb', ['-s', rec.device, 'shell', 'rm', '-f', rec.devicePath]);
675
+ adbShell(rec.device, 'rm', '-f', rec.devicePath);
628
676
  unlinkSync(recPath());
629
677
  return pull.ok ? { ok: true, out: `saved ${rec.outPath}` } : { ok: false, err: pull.err || pull.out };
630
678
  }
@@ -663,7 +711,7 @@ function boot(name) {
663
711
  const r = runOk('adb', ['-s', s, 'emu', 'avd', 'name']);
664
712
  const running = (r.out || '').split('\n')[0].trim();
665
713
  if (running !== name) continue;
666
- const done = runOk('adb', ['-s', s, 'shell', 'getprop', 'sys.boot_completed']);
714
+ const done = adbShell(s, 'getprop', 'sys.boot_completed');
667
715
  if ((done.out || '').trim() === '1') return { platform: 'android', device: s, deviceName: name };
668
716
  }
669
717
  const before = listAdbSerials();
@@ -674,7 +722,7 @@ function boot(name) {
674
722
  while (Date.now() < deadline) {
675
723
  const fresh = listAdbSerials().filter((s) => s.startsWith('emulator-') && !before.includes(s));
676
724
  if (fresh.length) {
677
- const done = runOk('adb', ['-s', fresh[0], 'shell', 'getprop', 'sys.boot_completed']);
725
+ const done = adbShell(fresh[0], 'getprop', 'sys.boot_completed');
678
726
  if ((done.out || '').trim() === '1') { serial = fresh[0]; break; }
679
727
  }
680
728
  sleep(2000);
@@ -798,7 +846,7 @@ export function main(argv = process.argv.slice(2)) {
798
846
  case 'set-app': {
799
847
  reqDevice(state);
800
848
  if (!args[0]) throw new CliError('set-app <appId> required', EXIT.USAGE);
801
- state.appId = args[0];
849
+ state.appId = validateAppId(args[0]);
802
850
  saveState(state);
803
851
  console.log(`appId=${state.appId}`);
804
852
  return;
package/bin/qualiow CHANGED
@@ -43,7 +43,12 @@ esac
43
43
 
44
44
  export CLAUDE_PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-$ROOT}"
45
45
 
46
- VER="$(node -p "try{require('$ROOT/.claude-plugin/plugin.json').version}catch{''}" 2>/dev/null || true)"
47
- [ -z "$VER" ] && VER="latest"
46
+ # Pin to the exact version the plugin ships, and never fall back to `latest`: an unreadable
47
+ # or odd version string means a broken install, not a reason to run whatever npm has newest.
48
+ VER="$(QUALIOW_ROOT="$ROOT" node -p "try{require(process.env.QUALIOW_ROOT+'/.claude-plugin/plugin.json').version}catch{''}" 2>/dev/null || true)"
49
+ if ! printf '%s' "$VER" | grep -Eq '^[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.]+)?$'; then
50
+ echo "qualiow: cannot read a version from $ROOT/.claude-plugin/plugin.json — reinstall the plugin." >&2
51
+ exit 1
52
+ fi
48
53
 
49
54
  exec npx -y -p "qualiow-exploratory-testing@$VER" qualiow "$@"
package/bin/wk-ios CHANGED
@@ -12,7 +12,20 @@
12
12
  # bin/wk-ios --url # just print the page WebSocket URL
13
13
  # bin/wk-ios --stop # stop the background iwdp proxy this script started
14
14
  #
15
+ # EXPOSURE: ios-webkit-debug-proxy (1.9.x) has no bind-address option — it listens on ALL
16
+ # interfaces, unauthenticated, and anyone who can reach WK_IOS_PORT..+101 from the network
17
+ # can evaluate JS in the Simulator's pages (and their logged-in sessions). The proxy stays
18
+ # up between calls so evals stay fast: run `wk-ios --stop` as soon as the session ends, and
19
+ # keep the macOS firewall on or use a trusted network.
20
+ #
15
21
  # ENV: WK_IOS_PORT (default 9221) — iwdp device-list port; pages are served on WK_IOS_PORT+1.
22
+ # WK_PAGE_FILTER — pins the page under test (Safari keeps old tabs inspectable, so without
23
+ # it a stale tab can win). Matched against the PARSED page URL, never as a raw substring:
24
+ # /account path prefix (any host)
25
+ # staging.example.com that host or a subdomain of it (host:port also works)
26
+ # staging.example.com/account exactly that host, path prefix
27
+ # https://staging.example.com/a same scheme and host[:port], path prefix
28
+ # The newest matching page wins; no match is an error.
16
29
  #
17
30
  # REQUIRES: brew install ios-webkit-debug-proxy ; python3 ; Node >= 22.4 ; a booted iOS
18
31
  # Simulator with Safari on a page (bin/mcli set-app com.apple.mobilesafari; bin/mcli open-url <url>).
@@ -21,8 +34,16 @@ set -euo pipefail
21
34
  HERE="$(cd "$(dirname "$0")" && pwd)"
22
35
  PORT="${WK_IOS_PORT:-9221}"
23
36
  PAGE_PORT=$((PORT + 1))
24
- IWDP_LOG="${TMPDIR:-/tmp}/wk-ios-iwdp-$PORT.log"
25
- IWDP_PIDFILE="${TMPDIR:-/tmp}/wk-ios-iwdp-$PORT.pid"
37
+ # Pid/log files live in a private per-user dir, so another local user cannot pre-plant a
38
+ # symlink at a predictable /tmp name and have our `>` follow it.
39
+ RUN_DIR="${TMPDIR:-/tmp}/wk-ios-$(id -u)"
40
+ mkdir -p -m 700 "$RUN_DIR" 2>/dev/null || true
41
+ if [[ -L "$RUN_DIR" || ! -d "$RUN_DIR" || ! -O "$RUN_DIR" ]]; then
42
+ echo "unsafe run dir $RUN_DIR (not a directory owned by you) — remove it or set TMPDIR" >&2; exit 1
43
+ fi
44
+ chmod 700 "$RUN_DIR"
45
+ IWDP_LOG="$RUN_DIR/iwdp-$PORT.log"
46
+ IWDP_PIDFILE="$RUN_DIR/iwdp-$PORT.pid"
26
47
 
27
48
  # Stop only the proxy we started (recorded in our pidfile) — never other users' iwdp.
28
49
  stop_proxy() {
@@ -46,25 +67,58 @@ SOCK="$(lsof -U 2>/dev/null | grep -oE '/private/var/tmp/[^ ]+webinspectord_sim.
46
67
  if ! curl -s "http://localhost:$PORT/json" >/dev/null 2>&1; then
47
68
  ios_webkit_debug_proxy -c "null:$PORT,:$PAGE_PORT-$((PAGE_PORT + 100))" -F -s "unix:$SOCK" > "$IWDP_LOG" 2>&1 &
48
69
  echo $! > "$IWDP_PIDFILE"
70
+ echo "wk-ios: started ios-webkit-debug-proxy on ALL interfaces, ports $PORT-$((PAGE_PORT + 100)), no auth — run 'wk-ios --stop' when done" >&2
49
71
  for _ in $(seq 1 20); do curl -s "http://localhost:$PORT/json" >/dev/null 2>&1 && break; sleep 0.25; done
50
72
  fi
51
73
 
52
74
  # 3) Resolve the frontmost page's WebSocket URL: the LAST page that is not about:blank
53
75
  # (iwdp lists pages in creation order; the newest non-blank one is what the user sees).
76
+ # With WK_PAGE_FILTER set, only pages whose parsed URL matches it are candidates (see the
77
+ # header), and none matching is an error rather than a silent fallback to another tab.
54
78
  # Retry briefly: right after iwdp starts, :$PORT answers before the page list is populated.
55
79
  WS=""
56
80
  for _ in $(seq 1 20); do
57
- WS="$(curl -s "http://localhost:$PAGE_PORT/json" 2>/dev/null | python3 -c 'import sys,json
81
+ WS="$(curl -s "http://localhost:$PAGE_PORT/json" 2>/dev/null | WK_PAGE_FILTER="${WK_PAGE_FILTER:-}" python3 -c 'import sys,json,os
82
+ from urllib.parse import urlsplit
58
83
  d=json.load(sys.stdin)
59
- p=[x for x in d if x.get("url") and x["url"]!="about:blank"] or d
84
+ f=os.environ.get("WK_PAGE_FILTER","")
85
+ def hit(url):
86
+ try:
87
+ u=urlsplit(url); host=(u.hostname or ""); port=u.port
88
+ except ValueError:
89
+ return False
90
+ netloc=host+(":%d"%port if port else "")
91
+ path=u.path or "/"
92
+ if f.startswith("/"):
93
+ return path.startswith(f)
94
+ if "://" in f:
95
+ w=urlsplit(f)
96
+ return u.scheme==w.scheme and netloc==(w.hostname or "")+(":%d"%w.port if w.port else "") and path.startswith(w.path or "/")
97
+ fh,_,fp=f.partition("/")
98
+ fh=fh.lower()
99
+ if fp or ":" in fh:
100
+ ok=(netloc==fh) if ":" in fh else (host==fh)
101
+ return ok and path.startswith("/"+fp)
102
+ return host==fh or host.endswith("."+fh)
103
+ if f:
104
+ p=[x for x in d if hit(x.get("url",""))]
105
+ else:
106
+ p=[x for x in d if x.get("url") and x["url"]!="about:blank"] or d
60
107
  print(p[-1]["webSocketDebuggerUrl"] if p else "")' 2>/dev/null || true)"
61
108
  [[ -n "$WS" ]] && break
62
109
  sleep 0.25
63
110
  done
64
- [[ -n "$WS" ]] || { echo "no inspectable Safari page found on :$PAGE_PORT (open a URL in the sim Safari first)" >&2; exit 1; }
111
+ if [[ -z "$WS" ]]; then
112
+ if [[ -n "${WK_PAGE_FILTER:-}" ]]; then
113
+ echo "no inspectable Safari page matching WK_PAGE_FILTER='$WK_PAGE_FILTER' on :$PAGE_PORT (a /path prefix, a host, host/path or a full URL; unset it to use the newest page)" >&2
114
+ else
115
+ echo "no inspectable Safari page found on :$PAGE_PORT (open a URL in the sim Safari first)" >&2
116
+ fi
117
+ exit 1
118
+ fi
65
119
 
66
120
  if [[ "${1:-}" == "--url" ]]; then echo "$WS"; exit 0; fi
67
- [[ $# -ge 1 ]] || { echo "usage: wk-ios \"<js-expression>\" | --url | --stop" >&2; exit 2; }
121
+ [[ $# -ge 1 ]] || { echo "usage: wk-ios \"<js-expression>\" | --url | --stop (the proxy listens on all interfaces until --stop)" >&2; exit 2; }
68
122
 
69
123
  # 4) Evaluate via the Target-wrapped WebKit protocol bridge.
70
124
  WK_WS="$WS" node "$HERE/wkeval.mjs" "$1"
package/bin/wkeval.mjs CHANGED
@@ -24,6 +24,10 @@ function targetSend(method, params = {}) {
24
24
  });
25
25
  }
26
26
 
27
+ // Page values are untrusted: drop C0/C1 controls (ESC, BEL, CR, ...) so a page cannot
28
+ // drive the terminal; \n and \t survive for multi-line values such as innerText.
29
+ const clean = (s) => String(s).replace(/[\u0000-\u0008\u000B-\u001F\u007F-\u009F]/g, '');
30
+
27
31
  const timeout = setTimeout(() => { console.error('TIMEOUT'); process.exit(3); }, 20000);
28
32
 
29
33
  ws.addEventListener('message', async (ev) => {
@@ -36,8 +40,9 @@ ws.addEventListener('message', async (ev) => {
36
40
  const res = await targetSend('Runtime.evaluate', { expression: wrapped, returnByValue: true, awaitPromise: true });
37
41
  clearTimeout(timeout);
38
42
  const r = res && res.result && res.result.result ? res.result.result : (res && res.result);
39
- if (r && 'value' in r) console.log(typeof r.value === 'object' ? JSON.stringify(r.value) : String(r.value));
40
- else console.log(JSON.stringify(r));
43
+ // JSON.stringify escapes C0 but not C1 (e.g. U+009B, an 8-bit CSI), so clean that too.
44
+ if (r && 'value' in r) console.log(clean(typeof r.value === 'object' ? JSON.stringify(r.value) : r.value));
45
+ else console.log(clean(JSON.stringify(r)));
41
46
  try { ws.close(); } catch { /* ignore */ }
42
47
  process.exit(0);
43
48
  } catch (e) { console.error('EVAL_FAIL', e.message || e); process.exit(5); }