opencode-agent-harness 0.0.0-stage → 0.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 (169) hide show
  1. package/CHANGELOG.md +23 -0
  2. package/LICENSE +21 -0
  3. package/README.md +590 -2
  4. package/bin/agent-harness.js +3059 -0
  5. package/contrib/global-plugins/README.md +49 -0
  6. package/contrib/global-plugins/harness-freshness.ts +355 -0
  7. package/package.json +48 -4
  8. package/templates/.agents/AGENTS.md +204 -0
  9. package/templates/.agents/features/INDEX.md +10 -0
  10. package/templates/.agents/handoffs/README.md +87 -0
  11. package/templates/.agents/memory/dev-loop.md +59 -0
  12. package/templates/.agents/memory/domain-map.md +29 -0
  13. package/templates/.agents/memory/environments.md +35 -0
  14. package/templates/.agents/memory/flow-map.md +23 -0
  15. package/templates/.agents/memory/history.md +7 -0
  16. package/templates/.agents/memory/locations.md +14 -0
  17. package/templates/.agents/memory/model-routing.md +261 -0
  18. package/templates/.agents/memory/orchestration.md +183 -0
  19. package/templates/.agents/memory/owned-files.md +19 -0
  20. package/templates/.agents/memory/product-principles.md +37 -0
  21. package/templates/.agents/memory/quality-parameters.md +37 -0
  22. package/templates/.agents/memory/stack-versions.md +35 -0
  23. package/templates/.agents/memory/test-design-parameters.md +36 -0
  24. package/templates/.agents/nightly.json +17 -0
  25. package/templates/.agents/qa-plans/README.md +70 -0
  26. package/templates/.agents/qa-runs/README.md +21 -0
  27. package/templates/.agents/reviews/README.md +47 -0
  28. package/templates/.agents/rules/00-operating.md +199 -0
  29. package/templates/.agents/skills/data-engineer/SKILL.md +31 -0
  30. package/templates/.agents/skills/devops-engineer/SKILL.md +50 -0
  31. package/templates/.agents/skills/diagnostics-expert/SKILL.md +44 -0
  32. package/templates/.agents/skills/docs/SKILL.md +140 -0
  33. package/templates/.agents/skills/features/SKILL.md +187 -0
  34. package/templates/.agents/skills/frontend-engineer/SKILL.md +81 -0
  35. package/templates/.agents/skills/handoff/SKILL.md +85 -0
  36. package/templates/.agents/skills/mobile-engineer/SKILL.md +101 -0
  37. package/templates/.agents/skills/planner/SKILL.md +112 -0
  38. package/templates/.agents/skills/product-manager/SKILL.md +115 -0
  39. package/templates/.agents/skills/qa-architect/SKILL.md +224 -0
  40. package/templates/.agents/skills/qa-runner/SKILL.md +64 -0
  41. package/templates/.agents/skills/security-engineer/SKILL.md +53 -0
  42. package/templates/.agents/skills/system-architect/SKILL.md +42 -0
  43. package/templates/.agents/skills/ui-designer/SKILL.md +71 -0
  44. package/templates/.github/workflows/ci.yml +148 -0
  45. package/templates/.github/workflows/deploy-uat.yml +95 -0
  46. package/templates/.github/workflows/nightly.yml +83 -0
  47. package/templates/.github/workflows/uat-health.yml +41 -0
  48. package/templates/.husky/pre-push +23 -0
  49. package/templates/.ignore +28 -0
  50. package/templates/.opencode/agents/data-engineer.md +37 -0
  51. package/templates/.opencode/agents/devops-engineer.md +37 -0
  52. package/templates/.opencode/agents/diagnostics-expert.md +37 -0
  53. package/templates/.opencode/agents/docs.md +37 -0
  54. package/templates/.opencode/agents/features.md +21 -0
  55. package/templates/.opencode/agents/frontend-engineer.md +37 -0
  56. package/templates/.opencode/agents/handoff.md +21 -0
  57. package/templates/.opencode/agents/mobile-engineer.md +37 -0
  58. package/templates/.opencode/agents/planner.md +34 -0
  59. package/templates/.opencode/agents/product-manager.md +29 -0
  60. package/templates/.opencode/agents/qa-architect.md +27 -0
  61. package/templates/.opencode/agents/qa-runner.md +17 -0
  62. package/templates/.opencode/agents/security-engineer.md +37 -0
  63. package/templates/.opencode/agents/system-architect.md +37 -0
  64. package/templates/.opencode/agents/ui-designer.md +37 -0
  65. package/templates/.opencode/commands/board.md +15 -0
  66. package/templates/.opencode/commands/checkpoint.md +25 -0
  67. package/templates/.opencode/commands/feature.md +56 -0
  68. package/templates/.opencode/commands/finish.md +36 -0
  69. package/templates/.opencode/commands/next.md +49 -0
  70. package/templates/.opencode/commands/report.md +55 -0
  71. package/templates/.opencode/commands/resume.md +39 -0
  72. package/templates/.opencode/commands/switch-model.md +34 -0
  73. package/templates/.opencode/commands/tidy.md +49 -0
  74. package/templates/.opencode/plugins/backlog-notify.ts +57 -0
  75. package/templates/.opencode/plugins/backlog.ts +272 -0
  76. package/templates/.opencode/plugins/checkpoint.ts +160 -0
  77. package/templates/.opencode/plugins/context-guard.ts +1164 -0
  78. package/templates/.opencode/plugins/diff.ts +85 -0
  79. package/templates/.opencode/plugins/gates.ts +71 -0
  80. package/templates/.opencode/plugins/job-notify.ts +241 -0
  81. package/templates/.opencode/plugins/orient.ts +67 -0
  82. package/templates/.opencode/plugins/session.ts +89 -0
  83. package/templates/.opencode/plugins/wait.ts +101 -0
  84. package/templates/.opencode/plugins/where.ts +70 -0
  85. package/templates/.opencode/skills/bounded-explore/SKILL.md +38 -0
  86. package/templates/.opencode/skills/dev-loop/SKILL.md +87 -0
  87. package/templates/.vercelignore +16 -0
  88. package/templates/AGENTS.md +27 -0
  89. package/templates/BACKLOG.md +95 -0
  90. package/templates/docs/ci-cd-pipeline.md +81 -0
  91. package/templates/docs/gates.md +128 -0
  92. package/templates/docs/mcp-integrations.md +97 -0
  93. package/templates/docs/mobile-testing.md +555 -0
  94. package/templates/docs/nightly-testing.md +106 -0
  95. package/templates/docs/wsl-optimizations.md +290 -0
  96. package/templates/opencode.json +188 -0
  97. package/templates/scripts/agent-report.js +541 -0
  98. package/templates/scripts/agent-search.sh +117 -0
  99. package/templates/scripts/backlog.js +1864 -0
  100. package/templates/scripts/board-service.sh +207 -0
  101. package/templates/scripts/checkpoint.js +290 -0
  102. package/templates/scripts/finalize.js +277 -0
  103. package/templates/scripts/nightly.js +913 -0
  104. package/templates/scripts/orient.js +514 -0
  105. package/templates/scripts/qa/board-client.js +260 -0
  106. package/templates/scripts/qa/board-lib.js +96 -0
  107. package/templates/scripts/qa/board-sync.js +469 -0
  108. package/templates/scripts/qa/capacity-lib.js +916 -0
  109. package/templates/scripts/qa/check-backlog.js +427 -0
  110. package/templates/scripts/qa/check-capacity.js +85 -0
  111. package/templates/scripts/qa/check-ci-policy.js +164 -0
  112. package/templates/scripts/qa/check-concurrency.js +344 -0
  113. package/templates/scripts/qa/check-dispatch-config.js +296 -0
  114. package/templates/scripts/qa/check-docs.js +284 -0
  115. package/templates/scripts/qa/check-integrate.js +98 -0
  116. package/templates/scripts/qa/check-linger.js +160 -0
  117. package/templates/scripts/qa/check-prefix-stability.js +183 -0
  118. package/templates/scripts/qa/check-product.js +177 -0
  119. package/templates/scripts/qa/check-qa-plan.js +378 -0
  120. package/templates/scripts/qa/check-qa-scripts.js +85 -0
  121. package/templates/scripts/qa/check-quality.js +249 -0
  122. package/templates/scripts/qa/check-test-wiring.js +253 -0
  123. package/templates/scripts/qa/ci-triage.js +346 -0
  124. package/templates/scripts/qa/ci-usage-lib.js +185 -0
  125. package/templates/scripts/qa/ci-wait-lib.js +294 -0
  126. package/templates/scripts/qa/command-classifier.js +552 -0
  127. package/templates/scripts/qa/context-guard-core.js +1618 -0
  128. package/templates/scripts/qa/diff.js +174 -0
  129. package/templates/scripts/qa/feature-scaffold.js +224 -0
  130. package/templates/scripts/qa/fixtures/backlog.md +104 -0
  131. package/templates/scripts/qa/governance.js +174 -0
  132. package/templates/scripts/qa/hash-file.js +32 -0
  133. package/templates/scripts/qa/lease-lib.js +263 -0
  134. package/templates/scripts/qa/merge-backlog.js +324 -0
  135. package/templates/scripts/qa/mobile-e2e/analyze-timings.js +300 -0
  136. package/templates/scripts/qa/mobile-e2e/apk-cache.js +420 -0
  137. package/templates/scripts/qa/mobile-e2e/backend-build-cache.js +203 -0
  138. package/templates/scripts/qa/mobile-e2e/boot-emulator.sh +432 -0
  139. package/templates/scripts/qa/mobile-e2e/build-apk.sh +210 -0
  140. package/templates/scripts/qa/mobile-e2e/check-flows.js +453 -0
  141. package/templates/scripts/qa/mobile-e2e/config.yaml +18 -0
  142. package/templates/scripts/qa/mobile-e2e/device-down.sh +88 -0
  143. package/templates/scripts/qa/mobile-e2e/device-up.sh +258 -0
  144. package/templates/scripts/qa/mobile-e2e/ios-simulator-down.sh +72 -0
  145. package/templates/scripts/qa/mobile-e2e/ios-simulator-up.sh +153 -0
  146. package/templates/scripts/qa/mobile-e2e/job-events.js +181 -0
  147. package/templates/scripts/qa/mobile-e2e/prewarm.sh +56 -0
  148. package/templates/scripts/qa/mobile-e2e/run-detached.sh +222 -0
  149. package/templates/scripts/qa/mobile-e2e/run-maestro.js +1543 -0
  150. package/templates/scripts/qa/mobile-e2e/ui-dump.js +327 -0
  151. package/templates/scripts/qa/models.allowlist.txt +32 -0
  152. package/templates/scripts/qa/provider-stats.js +878 -0
  153. package/templates/scripts/qa/run-clean.js +83 -0
  154. package/templates/scripts/qa/run-gates.js +212 -0
  155. package/templates/scripts/qa/run-loop.js +220 -0
  156. package/templates/scripts/qa/session-recon.js +512 -0
  157. package/templates/scripts/qa/store-lib.js +324 -0
  158. package/templates/scripts/qa/tool-lib.js +134 -0
  159. package/templates/scripts/qa/where.js +214 -0
  160. package/templates/scripts/qa/wslconfig-merge.js +157 -0
  161. package/templates/scripts/serve.js +1328 -0
  162. package/templates/scripts/setup-nightly.sh +185 -0
  163. package/templates/scripts/setup-tmpfs.sh +374 -0
  164. package/templates/scripts/ship.js +586 -0
  165. package/templates/scripts/switch-reasoning-model.ps1 +101 -0
  166. package/templates/scripts/switch-reasoning-model.sh +104 -0
  167. package/templates/scripts/wait-for.js +342 -0
  168. package/templates/scripts/wsl-gpu.sh +180 -0
  169. package/templates/scripts/wsl-tune.sh +261 -0
@@ -0,0 +1,453 @@
1
+ #!/usr/bin/env node
2
+ 'use strict';
3
+
4
+ /**
5
+ * F-285 slice 1 — mobile E2E flow-coverage validator (dependency-free).
6
+ *
7
+ * Proves, without a device, adb, Java, Maestro, or any npm dependency, that the
8
+ * journey manifest and its Maestro flows are wired and self-consistent:
9
+ *
10
+ * a. `flows/matrix.yaml` parses (bounded line parser, no YAML dep);
11
+ * b. every journey's flow file exists and is non-empty; every `flows/*.yaml`
12
+ * (excluding `matrix.yaml`) is referenced by some journey (no orphan);
13
+ * c. every flow is structurally well-formed: starts with `appId:`, contains at
14
+ * least one `tapOn`/`assertVisible` command, and uses only known Maestro
15
+ * command verbs at the top level;
16
+ * d. every referenced screen resolves to a file under `mobile/`, and every
17
+ * referenced testID resolves to a static `testID=` occurrence, an allowed
18
+ * dynamic template literal (`testID={`prefix-${expr}`}`) in `mobile/`, or a
19
+ * `prefix-{id}` placeholder selector matching such a template;
20
+ * e. exits 0 with a per-check report, or 1 with the exact violation(s).
21
+ *
22
+ * Usage:
23
+ * node scripts/qa/mobile-e2e/check-flows.js [--root <dir>]
24
+ *
25
+ * `--root` defaults to the repository root and exists so the validator can be
26
+ * pointed at temporary fixture trees by its own negative-case test.
27
+ */
28
+
29
+ const fs = require('fs');
30
+ const path = require('path');
31
+
32
+ const REPO_ROOT = path.resolve(__dirname, '..', '..', '..');
33
+ const FLOWS_SUBPATH = path.join('scripts', 'qa', 'mobile-e2e', 'flows');
34
+
35
+ // Maestro command verbs accepted at the top level of a flow. Keeping this list
36
+ // explicit is the point: an unknown verb is a typo/drift the validator must fail
37
+ // on rather than silently ignore.
38
+ const ALLOWED_VERBS = new Set([
39
+ 'addMedia',
40
+ 'assertNoDefectsWithAI',
41
+ 'assertNotVisible',
42
+ 'assertTrue',
43
+ 'assertVisible',
44
+ 'assertWithAI',
45
+ 'back',
46
+ 'clearKeychain',
47
+ 'clearState',
48
+ 'copyTextFrom',
49
+ 'eraseText',
50
+ 'evalScript',
51
+ 'extendedWaitUntil',
52
+ 'hideKeyboard',
53
+ 'inputText',
54
+ 'killApp',
55
+ 'launchApp',
56
+ 'openLink',
57
+ 'pasteText',
58
+ 'pressKey',
59
+ 'repeat',
60
+ 'runFlow',
61
+ 'scroll',
62
+ 'scrollUntilVisible',
63
+ 'setLocation',
64
+ 'setOrientation',
65
+ 'stopApp',
66
+ 'swipe',
67
+ 'takeScreenshot',
68
+ 'tapOn',
69
+ 'toggleAirplaneMode',
70
+ 'travel',
71
+ 'waitForAnimationToEnd',
72
+ ]);
73
+
74
+ function parseRootArg(argv) {
75
+ for (let i = 0; i < argv.length; i += 1) {
76
+ const arg = argv[i];
77
+ if (arg === '--root' && argv[i + 1]) return path.resolve(argv[i + 1]);
78
+ if (arg.startsWith('--root=')) return path.resolve(arg.slice('--root='.length));
79
+ }
80
+ return REPO_ROOT;
81
+ }
82
+
83
+ /** Split an inline YAML sequence `[a, b, c]` without a YAML dependency. */
84
+ function parseInlineList(raw) {
85
+ const text = String(raw).trim();
86
+ const start = text.indexOf('[');
87
+ const end = text.lastIndexOf(']');
88
+ if (start === -1 || end === -1 || end < start) return [];
89
+ return text
90
+ .slice(start + 1, end)
91
+ .split(',')
92
+ .map((entry) => entry.trim().replace(/^['"]|['"]$/g, ''))
93
+ .filter((entry) => entry.length > 0);
94
+ }
95
+
96
+ /**
97
+ * Bounded, line-oriented parser for the manifest schema documented in
98
+ * `flows/matrix.yaml`. It deliberately understands only the handful of keys the
99
+ * contract defines; anything else is a violation, not a silent skip.
100
+ */
101
+ function parseMatrix(content) {
102
+ const violations = [];
103
+ const journeys = [];
104
+ let seenHeader = false;
105
+ let current = null;
106
+
107
+ const lines = content.split(/\r?\n/);
108
+ lines.forEach((line, index) => {
109
+ const lineNo = index + 1;
110
+ const trimmed = line.trim();
111
+ if (trimmed === '' || trimmed.startsWith('#')) return;
112
+
113
+ if (!seenHeader) {
114
+ if (trimmed !== 'journeys:') {
115
+ violations.push(`matrix.yaml:${lineNo}: expected top-level "journeys:" but found "${trimmed}"`);
116
+ return;
117
+ }
118
+ seenHeader = true;
119
+ return;
120
+ }
121
+
122
+ const itemMatch = trimmed.match(/^-\s+id:\s*(.+)$/);
123
+ if (itemMatch) {
124
+ current = {
125
+ id: itemMatch[1].trim(),
126
+ flow: '',
127
+ entry: '',
128
+ actor: null,
129
+ endsAs: null,
130
+ screens: [],
131
+ testids: [],
132
+ states: [],
133
+ setup: null,
134
+ oracle: null,
135
+ firstLogin: null,
136
+ batchSetup: null,
137
+ line: lineNo,
138
+ };
139
+ journeys.push(current);
140
+ return;
141
+ }
142
+
143
+ const kvMatch = trimmed.match(/^([A-Za-z]+):\s*(.*)$/);
144
+ if (kvMatch) {
145
+ if (!current) {
146
+ violations.push(`matrix.yaml:${lineNo}: "${kvMatch[1]}" appears before any "- id:"`);
147
+ return;
148
+ }
149
+ const [, key, rawValue] = kvMatch;
150
+ if (key === 'flow') current.flow = rawValue.trim();
151
+ else if (key === 'entry') current.entry = rawValue.trim();
152
+ else if (key === 'actor') current.actor = rawValue.trim().replace(/^["']|["']$/g, '');
153
+ else if (key === 'endsAs') current.endsAs = rawValue.trim().replace(/^["']|["']$/g, '');
154
+ else if (key === 'screens') current.screens = parseInlineList(rawValue);
155
+ else if (key === 'testids') current.testids = parseInlineList(rawValue);
156
+ else if (key === 'states') current.states = parseInlineList(rawValue);
157
+ else if (key === 'setup') current.setup = rawValue.trim();
158
+ else if (key === 'oracle') current.oracle = rawValue.trim();
159
+ else if (key === 'firstLogin') current.firstLogin = rawValue.trim();
160
+ else if (key === 'batchSetup') current.batchSetup = rawValue.trim();
161
+ else violations.push(`matrix.yaml:${lineNo}: unknown journey key "${key}"`);
162
+ return;
163
+ }
164
+
165
+ violations.push(`matrix.yaml:${lineNo}: unparseable line "${trimmed}"`);
166
+ });
167
+
168
+ if (!seenHeader) violations.push('matrix.yaml: missing top-level "journeys:" header');
169
+ if (journeys.length === 0) violations.push('matrix.yaml: no journeys declared');
170
+
171
+ journeys.forEach((journey) => {
172
+ if (!journey.id) violations.push(`matrix.yaml:${journey.line}: journey is missing an id`);
173
+ if (!journey.flow) violations.push(`matrix.yaml:${journey.line}: journey "${journey.id}" is missing "flow"`);
174
+ if (!journey.entry) violations.push(`matrix.yaml:${journey.line}: journey "${journey.id}" is missing "entry"`);
175
+ if (journey.screens.length === 0) violations.push(`matrix.yaml:${journey.line}: journey "${journey.id}" declares no screens`);
176
+ if (journey.states.length === 0) violations.push(`matrix.yaml:${journey.line}: journey "${journey.id}" declares no states`);
177
+ // `actor:` is optional (run-maestro defaults to 0502000001); when declared
178
+ // it must be non-empty — it is the phone the shared session signs in as.
179
+ if (journey.actor === '') {
180
+ violations.push(`matrix.yaml:${journey.line}: journey "${journey.id}" declares an empty "actor"`);
181
+ }
182
+ // `endsAs:` is optional; when declared it must name the actor the flow
183
+ // leaves signed in (an empty declaration is meaningless).
184
+ if (journey.endsAs === '') {
185
+ violations.push(`matrix.yaml:${journey.line}: journey "${journey.id}" declares an empty "endsAs"`);
186
+ }
187
+ // `setup:`/`oracle:` are optional; when a journey declares one it must carry
188
+ // the invocation (an empty declaration is a declaration without a step).
189
+ if (journey.setup === '') {
190
+ violations.push(`matrix.yaml:${journey.line}: journey "${journey.id}" declares an empty "setup"`);
191
+ }
192
+ if (journey.oracle === '') {
193
+ violations.push(`matrix.yaml:${journey.line}: journey "${journey.id}" declares an empty "oracle"`);
194
+ }
195
+ // `firstLogin:` is optional; when declared it must be the literal boolean
196
+ // `true`/`false` (the runner only recognises `true`).
197
+ if (journey.firstLogin != null && journey.firstLogin !== '' && !/^(true|false)$/.test(journey.firstLogin)) {
198
+ violations.push(`matrix.yaml:${journey.line}: journey "${journey.id}" has a non-boolean "firstLogin" ("${journey.firstLogin}")`);
199
+ }
200
+ if (journey.firstLogin === '') {
201
+ violations.push(`matrix.yaml:${journey.line}: journey "${journey.id}" declares an empty "firstLogin"`);
202
+ }
203
+ // `batchSetup:` is optional; when declared it must be the literal boolean
204
+ // `true`/`false`. It opts a setup-bearing journey into the setup-batching
205
+ // group (the runner runs its setup before a shared warm invocation).
206
+ if (journey.batchSetup != null && journey.batchSetup !== '' && !/^(true|false)$/.test(journey.batchSetup)) {
207
+ violations.push(
208
+ `matrix.yaml:${journey.line}: journey "${journey.id}" has a non-boolean "batchSetup" ("${journey.batchSetup}")`
209
+ );
210
+ }
211
+ if (journey.batchSetup === '') {
212
+ violations.push(`matrix.yaml:${journey.line}: journey "${journey.id}" declares an empty "batchSetup"`);
213
+ }
214
+ });
215
+
216
+ return { journeys, violations };
217
+ }
218
+
219
+ function readText(file) {
220
+ try {
221
+ return fs.readFileSync(file, 'utf8');
222
+ } catch {
223
+ return null;
224
+ }
225
+ }
226
+
227
+ function walkFiles(dir, predicate, out) {
228
+ let entries;
229
+ try {
230
+ entries = fs.readdirSync(dir, { withFileTypes: true });
231
+ } catch {
232
+ return;
233
+ }
234
+ entries.forEach((entry) => {
235
+ const full = path.join(dir, entry.name);
236
+ if (entry.isDirectory()) {
237
+ if (entry.name === 'node_modules' || entry.name.startsWith('.')) return;
238
+ walkFiles(full, predicate, out);
239
+ } else if (predicate(full)) {
240
+ out.push(full);
241
+ }
242
+ });
243
+ }
244
+
245
+ /**
246
+ * Collect the testIDs declared in `mobile/` source:
247
+ *
248
+ * - static: `testID="x"`, `testID={'x'}`, `testID={`x`}` → exact ids;
249
+ * - dynamic: `testID={`prefix-${expr}`}` → the static prefix up to the first
250
+ * interpolation (`prefix-`), so a flow may reference it either literally
251
+ * (`prefix-…`) or with an `{id}` placeholder (`prefix-{id}`).
252
+ *
253
+ * Dynamic templates that begin with an interpolation (`testID={`${x}-tail`}`)
254
+ * contribute no stable prefix and are ignored — a selector for them cannot be
255
+ * resolved and must be treated as dangling.
256
+ */
257
+ function collectMobileTestIds(mobileDir) {
258
+ const ids = new Set();
259
+ const dynamicPrefixes = new Set();
260
+ const sources = [];
261
+ walkFiles(mobileDir, (file) => /\.(ts|tsx)$/.test(file), sources);
262
+ const staticPattern = /testID=\{?["'`]([^"'`${}]+)["'`]/g;
263
+ const dynamicPattern = /testID=\{\s*`([^`]*?)\$\{/g;
264
+ sources.forEach((file) => {
265
+ const content = readText(file);
266
+ if (content === null) return;
267
+ let match;
268
+ while ((match = staticPattern.exec(content)) !== null) ids.add(match[1]);
269
+ while ((match = dynamicPattern.exec(content)) !== null) {
270
+ const prefix = match[1];
271
+ if (prefix.length > 0) dynamicPrefixes.add(prefix);
272
+ }
273
+ });
274
+ return { ids, dynamicPrefixes };
275
+ }
276
+
277
+ /**
278
+ * Resolve a flow `id:` selector against the declared mobile testIDs.
279
+ *
280
+ * A selector resolves when it is a static id, when it starts with a dynamic
281
+ * template's static prefix (`home-carousel-book-123`), or when it uses the
282
+ * `{id}` placeholder form whose stripped prefix is a dynamic prefix
283
+ * (`home-carousel-book-{id}` → `home-carousel-book-`).
284
+ */
285
+ function resolveMobileTestId(selector, declared) {
286
+ if (declared.ids.has(selector)) return true;
287
+ if (selector.endsWith('{id}')) {
288
+ const stripped = selector.slice(0, -'{id}'.length);
289
+ if (declared.dynamicPrefixes.has(stripped)) return true;
290
+ }
291
+ // Maestro treats an `id:` value as a regex, so a device flow uses `prefix-.*`
292
+ // rather than the literal `prefix-{id}` placeholder. Resolve it the same way:
293
+ // strip the trailing `.*` and require the remaining prefix to be a declared
294
+ // dynamic template prefix.
295
+ if (selector.endsWith('.*')) {
296
+ const stripped = selector.slice(0, -'.*'.length);
297
+ if (declared.dynamicPrefixes.has(stripped)) return true;
298
+ }
299
+ for (const prefix of declared.dynamicPrefixes) {
300
+ if (selector.startsWith(prefix)) return true;
301
+ }
302
+ return false;
303
+ }
304
+
305
+ function validateFlowStructure(flowName, content) {
306
+ const violations = [];
307
+ const lines = content.split(/\r?\n/);
308
+ const significant = [];
309
+ lines.forEach((line, index) => {
310
+ const trimmed = line.trim();
311
+ if (trimmed === '' || trimmed.startsWith('#')) return;
312
+ significant.push({ raw: line, trimmed, lineNo: index + 1 });
313
+ });
314
+
315
+ if (significant.length === 0) {
316
+ violations.push(`${flowName}: flow is empty`);
317
+ return violations;
318
+ }
319
+
320
+ if (!/^appId:\s*\S+/.test(significant[0].trimmed)) {
321
+ violations.push(`${flowName}: first non-comment line must be "appId: <id>" but was "${significant[0].trimmed}"`);
322
+ }
323
+
324
+ const commandLines = significant.filter((entry) => /^(\s*)-\s+([A-Za-z][A-Za-z0-9_]*)/.test(entry.raw));
325
+ if (commandLines.length === 0) {
326
+ violations.push(`${flowName}: no top-level commands found`);
327
+ return violations;
328
+ }
329
+
330
+ const baseIndent = commandLines[0].raw.match(/^(\s*)/)[1].length;
331
+ const verbs = new Set();
332
+ commandLines.forEach((entry) => {
333
+ const indent = entry.raw.match(/^(\s*)/)[1].length;
334
+ if (indent !== baseIndent) return;
335
+ const verb = entry.raw.match(/^\s*-\s+([A-Za-z][A-Za-z0-9_]*)/)[1];
336
+ if (!ALLOWED_VERBS.has(verb)) {
337
+ violations.push(`${flowName}:${entry.lineNo}: unknown top-level command "${verb}"`);
338
+ }
339
+ verbs.add(verb);
340
+ });
341
+
342
+ if (!verbs.has('tapOn') && !verbs.has('assertVisible')) {
343
+ violations.push(`${flowName}: must contain at least one "- tapOn:" or "- assertVisible:" command`);
344
+ }
345
+
346
+ return violations;
347
+ }
348
+
349
+ /**
350
+ * Test-ID references inside a flow (Maestro `id:` selectors). Captures static
351
+ * ids, `{id}` placeholders, and Maestro regex selectors ending in `.*`
352
+ * (`prefix-.*`), which is how a dynamic template id is matched on device.
353
+ */
354
+ function extractFlowTestIds(content) {
355
+ const ids = new Set();
356
+ const pattern = /^\s*id:\s*["']?([A-Za-z0-9_{}.*-]+)["']?\s*$/gm;
357
+ let match;
358
+ while ((match = pattern.exec(content)) !== null) ids.add(match[1]);
359
+ return ids;
360
+ }
361
+
362
+ function validate() {
363
+ const root = parseRootArg(process.argv.slice(2));
364
+ const flowsDir = path.join(root, FLOWS_SUBPATH);
365
+ const mobileDir = path.join(root, 'mobile');
366
+ const matrixFile = path.join(flowsDir, 'matrix.yaml');
367
+ const violations = [];
368
+ const report = [];
369
+
370
+ if (!fs.existsSync(flowsDir)) {
371
+ return { violations: [`flows directory not found: ${path.relative(root, flowsDir) || flowsDir}`], report };
372
+ }
373
+ if (!fs.existsSync(mobileDir)) {
374
+ return { violations: [`mobile directory not found: ${path.relative(root, mobileDir) || mobileDir}`], report };
375
+ }
376
+
377
+ const matrixContent = readText(matrixFile);
378
+ if (matrixContent === null) {
379
+ return { violations: ['flows/matrix.yaml is missing'], report };
380
+ }
381
+ const parsed = parseMatrix(matrixContent);
382
+ violations.push(...parsed.violations);
383
+ report.push(`matrix: ${parsed.journeys.length} journey(s) declared`);
384
+
385
+ const referencedFlows = new Set();
386
+ const mobileTestIds = collectMobileTestIds(mobileDir);
387
+
388
+ parsed.journeys.forEach((journey) => {
389
+ if (!journey.flow) return;
390
+ referencedFlows.add(journey.flow);
391
+ const flowFile = path.join(flowsDir, journey.flow);
392
+ if (!fs.existsSync(flowFile)) {
393
+ violations.push(`journey "${journey.id}": flow file "${journey.flow}" is missing`);
394
+ return;
395
+ }
396
+ const content = readText(flowFile) || '';
397
+ if (content.trim() === '') {
398
+ violations.push(`journey "${journey.id}": flow file "${journey.flow}" is empty`);
399
+ return;
400
+ }
401
+
402
+ violations.push(...validateFlowStructure(journey.flow, content));
403
+
404
+ const flowTestIds = extractFlowTestIds(content);
405
+ const declaredTestIds = new Set([...journey.testids, ...flowTestIds]);
406
+ declaredTestIds.forEach((testId) => {
407
+ if (!resolveMobileTestId(testId, mobileTestIds)) {
408
+ violations.push(`journey "${journey.id}": testID "${testId}" has no static or dynamic testID= in mobile/`);
409
+ }
410
+ });
411
+
412
+ journey.screens.forEach((screen) => {
413
+ const screenFile = path.join(root, screen);
414
+ if (!fs.existsSync(screenFile)) {
415
+ violations.push(`journey "${journey.id}": screen "${screen}" does not resolve under mobile/`);
416
+ }
417
+ });
418
+
419
+ report.push(`journey "${journey.id}": flow ${journey.flow}, ${journey.screens.length} screen(s), ${declaredTestIds.size} testID(s)`);
420
+ });
421
+
422
+ // Orphan check: every flow on disk (except the manifest) must be referenced.
423
+ let flowFiles = [];
424
+ try {
425
+ flowFiles = fs.readdirSync(flowsDir).filter((name) => name.endsWith('.yaml') && name !== 'matrix.yaml');
426
+ } catch {
427
+ flowFiles = [];
428
+ }
429
+ flowFiles.forEach((name) => {
430
+ if (!referencedFlows.has(name)) {
431
+ violations.push(`orphan flow: "${name}" is not referenced by any journey in matrix.yaml`);
432
+ }
433
+ });
434
+ report.push(`flows on disk: ${flowFiles.length}, referenced: ${referencedFlows.size}`);
435
+
436
+ return { violations, report };
437
+ }
438
+
439
+ function main() {
440
+ const { violations, report } = validate();
441
+ report.forEach((line) => console.log(` · ${line}`));
442
+ if (violations.length > 0) {
443
+ console.error(`\nFAIL — ${violations.length} flow-coverage violation(s):`);
444
+ violations.forEach((violation) => console.error(` ✗ ${violation}`));
445
+ process.exit(1);
446
+ }
447
+ console.log('\nPASS — mobile E2E flow coverage is structurally valid.');
448
+ process.exit(0);
449
+ }
450
+
451
+ if (require.main === module) main();
452
+
453
+ module.exports = { parseInlineList, parseMatrix, validate };
@@ -0,0 +1,18 @@
1
+ # F-291 performance — Maestro workspace config.
2
+ #
3
+ # `disableAnimations: true` makes Maestro set the device's window/transition/
4
+ # animator animation scales to 0 for the run (and restores them afterwards).
5
+ # Every command's `waitForAnimationToEnd` settle then returns almost
6
+ # immediately, which is the single biggest per-command cost on the
7
+ # software-rendered WSL2 emulator (run4 measured ~2.5 s/command, ~3.6 s/tap).
8
+ # Assertions, selectors, and coverage are unchanged — only the dead wait time.
9
+ #
10
+ # run-maestro.js passes this file explicitly with `maestro test --config`.
11
+ # Both platforms get `disableAnimations: true`; Maestro applies only the entry
12
+ # for the target device's platform, so keeping the Android block does not affect
13
+ # an iOS run (and vice versa).
14
+ platform:
15
+ android:
16
+ disableAnimations: true
17
+ ios:
18
+ disableAnimations: true
@@ -0,0 +1,88 @@
1
+ #!/usr/bin/env bash
2
+ #
3
+ # mobile E2E — bring the device tier DOWN cleanly: stop the dev server, optionally
4
+ # the emulator, and prune dead `.serve/` records so a stopped emulator is never
5
+ # misreported as live (and its RAM is actually freed).
6
+ #
7
+ # Pairs with `device-up.sh`. The rule is: stop a dev server as soon as its tier
8
+ # passes; reuse an emulator WITHIN a session but stop it at session end. This
9
+ # makes that one command instead of a hand-typed `serve.js stop` per process.
10
+ #
11
+ # Usage:
12
+ # scripts/qa/mobile-e2e/device-down.sh # stop dev server + prune
13
+ # scripts/qa/mobile-e2e/device-down.sh --emulator # also stop the emulator (or iOS Simulator)
14
+ # scripts/qa/mobile-e2e/device-down.sh --all # stop-all heavy tiers
15
+ #
16
+ # Platform: android (default) or ios from `MOBILE_E2E_PLATFORM` / local.json
17
+ # `platform`. On ios the simulator is stopped via ios-simulator-down.sh.
18
+ set -euo pipefail
19
+
20
+ ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../../.." && pwd)"
21
+ cd "$ROOT"
22
+ LOCAL_CONFIG="$ROOT/scripts/qa/mobile-e2e/local.json"
23
+
24
+ DEV_NAME="${MOBILE_E2E_DEV_NAME:-$(node -e "try{const c=require('$LOCAL_CONFIG');process.stdout.write(c.devName||'')}catch(e){}" 2>/dev/null || true)}"
25
+ [ -z "$DEV_NAME" ] && DEV_NAME="app-dev"
26
+
27
+ # Platform selection: env MOBILE_E2E_PLATFORM > local.json `platform` > android.
28
+ # On ios the simulator is stopped via the sibling ios-simulator-down.sh instead
29
+ # of the adb/emulator teardown (which is Android-only).
30
+ PLATFORM="${MOBILE_E2E_PLATFORM:-$(node -e "try{const c=require('$LOCAL_CONFIG');process.stdout.write(c.platform||'')}catch(e){}" 2>/dev/null || true)}"
31
+ case "$PLATFORM" in ios|iOS|IOS) PLATFORM=ios ;; *) PLATFORM=android ;; esac
32
+
33
+ MODE="dev"
34
+ for arg in "$@"; do
35
+ case "$arg" in
36
+ --emulator) MODE="emulator" ;;
37
+ --all) MODE="all" ;;
38
+ -h|--help) sed -n '2,20p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'; exit 0 ;;
39
+ *) echo "unknown argument: $arg" >&2; exit 2 ;;
40
+ esac
41
+ done
42
+
43
+ # Persist a quickboot snapshot before the emulator goes away, so the next
44
+ # device-up boots in seconds. Best-effort: a device that is already gone (or a
45
+ # save the emulator refuses) must never fail the teardown — but the failure is
46
+ # SURFACED (to stderr + `.serve/snapshot-save.log`), because a silent save
47
+ # failure is what made every bring-up cold-boot while the runbook claimed warm
48
+ # booting.
49
+ save_snapshot() {
50
+ [ "${MOBILE_E2E_SNAPSHOT:-1}" = "0" ] && return 0
51
+ local sdk="${ANDROID_HOME:-${ANDROID_SDK_ROOT:-$HOME/android-sdk}}"
52
+ local adb="$sdk/platform-tools/adb"
53
+ local name="${MOBILE_E2E_SNAPSHOT_NAME:-agent-e2e}"
54
+ local log="$ROOT/.serve/snapshot-save.log"
55
+ [ -x "$adb" ] || return 0
56
+ timeout 10 "$adb" get-state >/dev/null 2>&1 || return 0
57
+ echo "device-down: saving quickboot snapshot ($name)"
58
+ mkdir -p "$ROOT/.serve"
59
+ if timeout 120 "$adb" emu avd snapshot save "$name" >"$log" 2>&1; then
60
+ echo "device-down: snapshot saved ($name)"
61
+ else
62
+ echo "device-down: ! snapshot save failed — next device-up will cold boot (see $log)" >&2
63
+ fi
64
+ }
65
+
66
+ if [ "$MODE" = "all" ]; then
67
+ echo "device-down: stop-all + prune"
68
+ if [ "$PLATFORM" = "android" ]; then save_snapshot; fi
69
+ node scripts/serve.js stop-all || true
70
+ if [ "$PLATFORM" = "ios" ]; then bash scripts/qa/mobile-e2e/ios-simulator-down.sh || true; fi
71
+ else
72
+ echo "device-down: stop dev server ($DEV_NAME)"
73
+ node scripts/serve.js stop --name "$DEV_NAME" || true
74
+ if [ "$MODE" = "emulator" ]; then
75
+ if [ "$PLATFORM" = "ios" ]; then
76
+ echo "device-down: stop iOS Simulator"
77
+ bash scripts/qa/mobile-e2e/ios-simulator-down.sh || true
78
+ else
79
+ save_snapshot
80
+ echo "device-down: stop emulator"
81
+ node scripts/serve.js stop --name emulator || true
82
+ node scripts/serve.js stop --name adb-server || true
83
+ fi
84
+ fi
85
+ fi
86
+
87
+ node scripts/serve.js prune --worktrees || true
88
+ node scripts/serve.js list || true