wei-wuwei 0.2.1 → 0.3.0

package/CHANGELOG.md

@@ -4,6 +4,10 @@ One section per published version, newest first. `wuwei update` prints the
 sections between the installed version and the new one before it asks;
 `wuwei check` fails when package.json's version has no section here.
 
+## 0.3.0
+
+- wuwei verify on mobile: Maestro on a simulator + wuwei's mock server (#62)
+
 ## 0.2.1
 
 - `wuwei review-collect`: finds the latest Claude Code session that

package/README.md

@@ -73,7 +73,7 @@ node bin/wuwei.js plan-check [stream] # plan-phases step 11's checkable half, be
 node bin/wuwei.js worktree <lens> <sha> # a throwaway worktree no other lens shares (--prune)
 node bin/wuwei.js mutate <f>:<n> --from … --to … --run … --in <wt>  # one mutation: landed, baseline, red count, restored
 node bin/wuwei.js sites <pattern> [--symbol <name>]  # a set derived from the tree, graph and grep both
-node bin/wuwei.js verify [page] [--phase NN]  # every data-bearing page × 500/403/404/empty/pending/failed refetch; --phase: ACCEPTANCE's ## Verify
+node bin/wuwei.js verify [page] [--phase NN]  # every data-bearing page × 500/403/404/empty/pending/failed refetch; --phase: ACCEPTANCE's ## Verify; mobile: Maestro + mock server
 node bin/wuwei.js uninstall          # removes exactly what install wrote, nothing else
 ```
 

package/bin/wuwei.js

@@ -31,9 +31,10 @@
  *                              baseline vs mutated, failing tests, restored, recorded
  *   wuwei sites <pattern> [--symbol <name>]   a set from the tree, with its derivation;
  *                              graph and grep both for a symbol
- *   wuwei verify [<page>…] [--phase NN]  every data-bearing page through its states
- *                              (Playwright, fixtures from .wuwei/verify.json): a matrix of
- *                              shots; --phase runs the pages ACCEPTANCE.md binds to it
+ *   wuwei verify [<page>…] [--phase NN] [--endpoint <text>] [--states 500,404]  every data-bearing page through its states
+ *                              (Playwright on web, Maestro + a mock server on mobile;
+ *                              fixtures from .wuwei/verify.json): a matrix of shots;
+ *                              --phase runs the pages ACCEPTANCE.md binds to it
  *   wuwei plan-check [<stream>]  wuwei-plan-phases step 11's checkable half
  *   wuwei uninstall [<path>]   remove exactly what install wrote
  *   wuwei -v | --version       print the installed version
@@ -48,6 +49,7 @@ import { fileURLToPath } from 'node:url'
 import { createInterface } from 'node:readline/promises'
 import { spawnSync, spawn } from 'node:child_process'
 import { createRequire } from 'node:module'
+import { createServer } from 'node:http'
 import { createHash } from 'node:crypto'
 
 const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..')
@@ -1615,6 +1617,9 @@ const VERIFY_STATES = ['500', '403', '404', 'empty', 'pending', 'refetch-500', '
 const BUSY = '[aria-busy="true"],[role="progressbar"],[data-slot*="skeleton"],[data-loading="true"],.skeleton,[data-skeleton],[class*="skeleton"],.animate-pulse,.animate-spin'
 const SAYS_ERROR = /error|failed|could not|couldn't|unable|try again|retry|錯誤|失敗|無法/i
 const TICKS = /\b\d+\s*(s|sec|secs|seconds?|min|mins|minutes?|h|hours?)\s+ago\b|\d+\s*(秒|分鐘|小時)前|just now|剛剛/i
+const SAYS_NOT_FOUND = /not found|unknown|doesn't exist|does not exist|no longer|找不到|不存在/i
+// a request never answered, the loader still up: the app has no timeout
+const STUCK = cfg => `still loading ${(cfg.pendingStuckMs ?? 30000) / 1000}s on, the request never answered — no timeout, the wait never ends`
 const SAYS_FORBIDDEN = /permission|forbidden|not allowed|denied|access|authori[sz]|權限|無權/i
 
 function loadPlaywright(cwd) {
@@ -1624,7 +1629,7 @@ function loadPlaywright(cwd) {
   return null
 }
 
-const globRe = g => new RegExp('^' + g.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*\*/g, '\u0000').replace(/\*/g, '[^/]*').replace(/\u0000/g, '.*') + '$')
+const globRe = g => new RegExp('^' + g.replace(/[.+?^${}()|[\]\\]/g, '\\$&').replace(/\*\*/g, '\u0000').replace(/\*/g, '[^/]*').replace(/\u0000/g, '.*') + '$')
 
 function fixtureFor(fixtures, method, url) {
   const u = new URL(url)
@@ -1678,13 +1683,28 @@ async function cmdVerify(argv) {
   "pages": [ { "name": "items", "path": "/items", "ready": "text=Items" } ],
   "refetch": "focus", "refetchAfterMs": 600000, "refetchWaitMs": 30000,
   "busy": "[data-slot=skeleton]",            // optional: your loader, beyond the usual ones
-  "errorWaitMs": 60000                       // simulated time client retries may hold the loader
+  "errorWaitMs": 60000,                      // simulated time client retries may hold the loader
+  "pendingStuckMs": 30000,                   // a loader still up this long on an unanswered request is a hang; 0 skips
+  "driftPct": 1, "transientMs": 4000         // live numbers within 1% are the same line; watch a failure 4s for a toast
+}
+a mobile app (Maestro on a simulator; the app built against the mock server):
+{
+  "mobile": { "appId": "com.example.app", "port": 48780,  // iOS → http://localhost:48780, Android emulator → http://10.0.2.2:48780
+              "login": ".maestro/login.yaml",            // optional: run after each launch
+              "device": "<udid>", "maestro": "<path>" }, // optional: which simulator; maestro if not on PATH or in ~/.maestro/bin
+  "fixtures": { … as above … },
+  "pages": [ { "name": "items", "link": "myapp://items", "ready": "Items" } ],   // or "flow": ".maestro/open-items.yaml"
+  "refetchAfterMs": 0,                       // real time in the background: build with staleTime 0, or wait it out
+  "busy": "skeleton|spinner"                 // optional: a regex over ids and labels
 }`)
     process.exit(1)
   }
   const cfg = JSON.parse(readFileSync(cfgPath, 'utf8'))
   const flag = name => { const i = argv.indexOf(name); return i === -1 ? null : argv[i + 1] }
-  const only = argv.filter((a, i) => !a.startsWith('--') && !['--phase', '--stream'].includes(argv[i - 1]))
+  const only = argv.filter((a, i) => !a.startsWith('--') && !['--phase', '--stream', '--endpoint', '--states'].includes(argv[i - 1]))
+  // a narrow run: endpoints whose key contains any --endpoint text, states from --states
+  const endpointFilter = argv.flatMap((a, i) => a === '--endpoint' ? [argv[i + 1]] : [])
+  const stateFilter = flag('--states')?.split(',').map(s => s.trim()).filter(Boolean) ?? null
   // --phase NN: the pages ACCEPTANCE.md binds to that phase — the contract, not memory
   if (flag('--phase')) {
     const sdir = join(dest, '.wuwei', 'streams')
@@ -1699,7 +1719,151 @@ async function cmdVerify(argv) {
     only.push(...want)
   }
   const missing = only.filter(n => !(cfg.pages ?? []).some(pg => pg.name === n))
-  if (missing.length) { console.error(`✗ not in .wuwei/verify.json: ${missing.join(', ')} — add each page (path, ready) and the fixtures it calls, from the API's schema`); process.exit(1) }
+  if (missing.length) { console.error(`✗ not in .wuwei/verify.json: ${missing.join(', ')} — add each page (path or link, ready) and the fixtures it calls, from the API's schema`); process.exit(1) }
+  const sha = quiet('git', ['rev-parse', '--verify', '--quiet', 'HEAD']).stdout?.trim().slice(0, 12) || 'nogit'
+  const outDir = join(dest, '.wuwei-cache', 'verify', sha)
+  const driver = cfg.mobile ? await verifyMobile(cfg, dest, outDir) : await verifyWeb(cfg, dest)
+  const report = []
+  const lines = t => new Set(t.split('\n').map(l => l.trim()).filter(l => l.length > 2))
+  // a live number (an on-chain TVL) moves between any two opens: a line whose
+  // only change is its numbers, each within driftPct (1%), is the same line —
+  // $33,000 → $8,000 is not drift, it is the failure
+  const NUM = /\d[\d,]*(?:\.\d+)?/g
+  const nums = l => (l.match(NUM) ?? []).map(n => Number(n.replace(/,/g, '')))
+  // and a relative time ("updated 2 min ago") is the clock, not the content: it is
+  // taken out of a line, never the whole line with it
+  const unticked = l => l.replace(new RegExp(TICKS.source, 'gi'), '').trim()
+  const drifted = (a, b) => (a = unticked(a), b = unticked(b), a.replace(NUM, '#') === b.replace(NUM, '#')) && nums(a).every((x, i) => {
+    const y = nums(b)[i]; return x === y || Math.abs(x - y) <= Math.max(Math.abs(x), Math.abs(y)) * (cfg.driftPct ?? 1) / 100 })
+  const diff = (before, after) => {
+    const said = [...after].filter(l => !before.has(l)), gone = []
+    for (const l of [...before].filter(l => !after.has(l) && unticked(l))) {
+      const i = said.findIndex(s => drifted(l, s)); if (i === -1) gone.push(l); else said.splice(i, 1)
+    }
+    return { said, gone }
+  }
+  const writeMatrix = ({ page, rows, endpoints, dir }, stopped) => {
+    const md = [`# verify ${page.name} @ ${sha}`, '', `page: \`${page.path ?? page.link ?? page.flow}\` · endpoints: ${endpoints.length} · states: ${VERIFY_STATES.join(', ')}`,
+      ...(stopped ? ['', `**stopped:** ${stopped}`] : []), '',
+      '| endpoint | state | flags | on screen, beyond happy | shot |', '|---|---|---|---|---|',
+      ...rows.map(r => `| ${r.endpoint} | ${r.state} | ${r.flags.length ? r.flags.join('; ') : '—'} | ${(r.note ?? (r.said ?? r.text).split('\n').find(l => l.trim()) ?? '—').slice(0, 60).replace(/\|/g, '\\|')} | ${r.shot} |`)]
+    writeFileSync(join(dir, 'matrix.md'), md.join('\n') + '\n')
+  }
+  // stopped by hand: what ran so far is still a matrix
+  let current = null
+  process.once('SIGINT', () => {
+    if (current) { writeMatrix(current, 'interrupted'); console.log(`\n✗ ${current.page.name}: interrupted after ${current.rows.length} state(s) — ${join(current.dir, 'matrix.md')}`) }
+    process.exit(130)
+  })
+
+  for (const page of (cfg.pages ?? []).filter(pg => !only.length || only.includes(pg.name))) {
+    const dir = join(outDir, page.name)
+    mkdirSync(dir, { recursive: true })
+    const happy = await driver.visit(page, { happy: true })
+    await happy.shot(join(dir, 'happy.png'))
+    writeFileSync(join(dir, 'happy.txt'), happy.text)
+    await happy.close()
+    // a page that never opened makes every state below a picture of the wrong screen
+    const abort = happy.flowError ? `the flow failed — ${happy.flowError}`
+      : page.ready && !happy.ready ? `happy never showed "${page.ready}" — check the link or flow, login and fixtures (happy.png)` : null
+    if (abort) {
+      writeMatrix({ page, rows: [{ endpoint: '—', state: 'happy', flags: ['flow failed'], note: abort.slice(0, 60), shot: 'happy.png', text: '' }], endpoints: [], dir }, abort)
+      report.push({ page: page.name, rows: [], dir, abort }); continue
+    }
+    for (const vp of driver.viewports ?? []) {
+      const narrow = await driver.visit(page, { viewport: vp })
+      await narrow.shot(join(dir, `happy-${vp.width}.png`))
+      await narrow.close()
+    }
+    const endpoints = [...happy.seen.keys()]
+    const happyLines = lines(happy.text)
+    const rows = [{ endpoint: '—', state: 'happy', flags: [...[...happy.unmocked].map(u => `unmocked: ${u}`), ...happy.errors.map(e => `page error: ${e}`)], shot: 'happy.png', text: happy.text }]
+    const served = new Map(happy.seen)
+    current = { page, rows, endpoints, dir }
+    // which endpoints the trigger refetches is the app's query config, not the
+    // failing endpoint's: after one trigger, only those it re-requested run refetch states
+    let triggered = false
+    const refetchable = new Set(), invisible = new Set()
+    // a filter that is a whole key means that key alone; otherwise any key containing it
+    const picked = k => !endpointFilter.length || endpointFilter.some(f => endpoints.includes(f) ? k === f : k.includes(f))
+    pageLoop: for (const key of endpoints.filter(picked)) {
+      for (const state of VERIFY_STATES.filter(s => !stateFilter || stateFilter.includes(s))) {
+        if (state === 'empty' && !emptied(served.get(key)?.json)) continue
+        const refetch = state.match(/^refetch-(\d+)$/)
+        if (refetch && triggered && !refetchable.has(key)) { rows.push({ endpoint: key, state, flags: [], note: `skipped — the trigger re-requested ${refetchable.size ? [...refetchable].join(', ') : 'nothing'}`, shot: '—', text: '' }); continue }
+        const v = refetch ? await driver.visit(page, { refetchFail: { key, status: Number(refetch[1]) } }) : await driver.visit(page, { override: { key, state } })
+        const slug = `${key.replace(/[^\w]+/g, '_').replace(/^_|_$/g, '')}--${state}`
+        await v.shot(join(dir, `${slug}.png`))
+        writeFileSync(join(dir, `${slug}.txt`), v.text)
+        await v.close()
+        if (v.flowError) {
+          rows.push({ endpoint: key, state, flags: ['flow failed'], note: v.flowError.slice(0, 60), shot: `${slug}.png`, text: '' })
+          const abort = `${key} · ${state}: the flow failed — ${v.flowError}`
+          writeMatrix(current, abort); report.push({ page: page.name, rows, dir, abort, written: true }); break pageLoop
+        }
+        if (refetch) { triggered = true; for (const k of v.afterKeys ?? []) refetchable.add(k) }
+        const vLines = lines(v.text)
+        // judged on what the state added to the screen: a nav item saying "Access" is not an answer.
+        // A toast gone by the time the screen settles still said it: glimpsed lines count
+        const d = diff(happyLines, vLines)
+        const known = [...happyLines, ...vLines]
+        const glimpsed = [...(v.glimpsed ?? [])].filter(l => l.length > 2 && unticked(l) && !known.some(k => k === l || drifted(k, l)))
+        // what the screen ended on decides loading; what it said along the way counts as said
+        const said = [...d.said, ...glimpsed].join('\n'), gone = d.gone
+        const loading = v.busy || /loading|載入/i.test(d.said.join('\n'))
+        const flags = v.errors.map(e => `page error: ${e}`)
+        // the screen as happy had it: this page shows nothing of this endpoint — not a missing error
+        const same = !said && !gone.length
+        // shows nothing of it when it fails outright, so a failed refetch of it shows nothing either
+        if (same && refetch && invisible.has(key)) { rows.push({ endpoint: key, state, flags, note: 'no visible effect — this page shows nothing of it', shot: `${slug}.png`, text: v.text, said }); continue }
+        if (same && !refetch) invisible.add(key)
+        if (same && !refetch) { rows.push({ endpoint: key, state, flags: [...flags, ...(v.stuck ? [STUCK(cfg)] : [])], note: 'no visible effect — this page shows nothing of it', shot: `${slug}.png`, text: v.text, said }); continue }
+        if (/^5/.test(state) && loading) flags.push(`still loading ${(cfg.errorWaitMs ?? driver.errorWaitMs) / 1000}s on — client retries outlast the wait; raise "errorWaitMs"`)
+        else if (/^5/.test(state) && !SAYS_ERROR.test(said)) flags.push('no error shown')
+        if (state === '403' && !SAYS_FORBIDDEN.test(said)) flags.push('403 not told as a permission problem')
+        if (state === '404' && v.retry) flags.push('Retry offered on a 404 — it can never succeed')
+        // a 404 that changed the screen — lines gone, or a control greyed out — and says nothing
+        const changed = [...gone, ...d.said.filter(l => l.startsWith('[disabled]'))]
+        if (state === '404' && changed.length && !SAYS_ERROR.test(said) && !SAYS_NOT_FOUND.test(said)) flags.push(`404: ${changed.length} change(s) on screen and nothing says why (${changed.slice(0, 2).join(' / ').slice(0, 60)})`)
+        if (state === '403' && v.retry) flags.push('Retry offered on a 403 — it can never succeed')
+        if (state === 'pending' && !v.busy && !/loading|載入/i.test(v.text)) flags.push('no loading indicator')
+        if (state === 'pending' && v.stuck) flags.push(STUCK(cfg))
+        // a refetch that never happened says nothing about how a failed one looks;
+        // what it did say is the lines it added — a relative time ticking is not an error
+        const told = SAYS_ERROR.test(said) || (state === 'refetch-403' && SAYS_FORBIDDEN.test(said))
+        if (refetch && !v.refetched) flags.push(driver.notRefetched)
+        else if (refetch && !told) flags.push('silent: the failed refetch shows nothing')
+        else if (refetch && gone.length) flags.push(`refetch failure replaced loaded content: ${gone.length} line(s) gone (${gone.slice(0, 2).join(' / ').slice(0, 60)})`)
+        if (state === 'refetch-403' && v.refetched && told && !SAYS_FORBIDDEN.test(said)) flags.push('403 on refetch not told as a permission problem')
+        rows.push({ endpoint: key, state, flags, shot: `${slug}.png`, text: v.text, said })
+      }
+    }
+    current = null
+    if (report.at(-1)?.page === page.name) continue
+    // a failure that reads exactly like no data: the user is told there is nothing, not that it broke
+    for (const e of rows.filter(r => r.state === 'empty' && r.said)) for (const r of rows)
+      if (r.endpoint === e.endpoint && /^\d+$/.test(r.state) && r.said === e.said) r.flags.push(`${r.state} shown as the empty state ("${e.said.split('\n')[0].slice(0, 40)}")`)
+    writeMatrix({ page, rows, endpoints, dir })
+    report.push({ page: page.name, rows, dir })
+  }
+  await driver.done()
+
+  for (const { page, rows, dir, abort } of report) {
+    if (abort) { console.log(`✗ ${page}: stopped after ${rows.length} state(s) — ${abort}${rows.length ? ` · what ran: ${join(dir, 'matrix.md')}` : ''}`); continue }
+    const flagged = rows.filter(r => r.flags.length), quiet = rows.filter(r => r.note && !r.flags.length)
+    console.log(`${page}: ${rows.length} state(s), ${flagged.length} flagged — ${join(dir, 'matrix.md')}`)
+    for (const r of flagged) console.log(`  ${r.endpoint} · ${r.state}: ${r.flags.join('; ')}`)
+    const noEffect = [...new Set(quiet.filter(r => r.note.startsWith('no visible')).map(r => r.endpoint))]
+    if (noEffect.length) console.log(`  no visible effect on this page: ${noEffect.join(', ')}`)
+    const skipped = quiet.filter(r => r.note.startsWith('skipped'))
+    if (skipped.length) console.log(`  ${skipped.length} refetch state(s) skipped — ${skipped[0].note.replace(/^skipped — /, '')}`)
+  }
+  console.log('\nflags are leads, not findings: open the shot, and confirm against the spec what the page should say')
+  if (report.some(r => r.abort)) process.exit(1)
+}
+
+// the web half: Playwright routes the page's own requests to the fixtures
+async function verifyWeb(cfg, dest) {
   const pw = loadPlaywright(dest)
   if (!pw) { console.error('✗ Playwright not found in this project or globally — npm i -D playwright'); process.exit(1) }
   let server = null
@@ -1708,12 +1872,9 @@ async function cmdVerify(argv) {
     if (!(await waitForUrl(cfg.url, cfg.startTimeoutMs ?? 120000))) { console.error(`✗ ${cfg.url} did not come up after \`${cfg.start}\``); try { process.kill(-server.pid) } catch {} ; process.exit(1) }
   } else if (!(await waitForUrl(cfg.url, 5000))) { console.error(`✗ ${cfg.url} is not reachable — start the app, or set "start"`); process.exit(1) }
 
-  const sha = quiet('git', ['rev-parse', 'HEAD']).stdout?.trim().slice(0, 12) || 'nogit'
-  const outDir = join(dest, '.wuwei-cache', 'verify', sha)
   const browser = await pw.chromium.launch()
   const apiRes = [].concat(cfg.api ?? ['**/api/**']).map(globRe)
   const isApi = url => apiRes.some(re => re.test(url) || re.test(new URL(url).pathname))
-  const report = []
 
   // one visit: routes every API call to its fixture, except the endpoint under test
   const visit = async (page, { override, refetchFail, viewport } = {}) => {
@@ -1726,19 +1887,21 @@ async function cmdVerify(argv) {
       }, cfg.auth)
     const p = await ctx.newPage()
     const seen = new Map(), unmocked = new Set(), errors = []
-    let failing = false, refetched = 0
+    let failing = false, refetched = 0, hits = 0
+    const afterKeys = new Set(), glimpsed = new Set()
     p.on('pageerror', e => errors.push(String(e.message ?? e).split('\n')[0]))
     await p.route('**/*', async route => {
       const req = route.request(), url = req.url()
       if (!isApi(url)) return route.continue()
       const fx = fixtureFor(cfg.fixtures, req.method(), url)
       if (!fx) { unmocked.add(`${req.method()} ${new URL(url).pathname}`); return route.fulfill({ status: 501, body: 'unmocked by wuwei verify' }) }
+      if (failing) afterKeys.add(fx.key)
       seen.set(fx.key, fx)
       const hit = override && fx.key === override.key
       if ((hit && override.state === 'pending')) return // never answered: the loading state
-      if (hit && /^\d+$/.test(override.state)) return route.fulfill({ status: Number(override.state), contentType: 'application/json', body: JSON.stringify({ message: `wuwei verify ${override.state}` }) })
+      if (hit && /^\d+$/.test(override.state)) return hits++, route.fulfill({ status: Number(override.state), contentType: 'application/json', body: JSON.stringify({ message: `wuwei verify ${override.state}` }) })
       if (hit && override.state === 'empty') return route.fulfill({ status: 200, contentType: 'application/json', body: JSON.stringify(emptied(fx.json)) })
-      if (refetchFail && fx.key === refetchFail.key && failing) return refetched++, route.fulfill({ status: refetchFail.status, contentType: 'application/json', body: JSON.stringify({ message: `wuwei verify refetch ${refetchFail.status}` }) })
+      if (refetchFail && fx.key === refetchFail.key && failing) return refetched++, hits++, route.fulfill({ status: refetchFail.status, contentType: 'application/json', body: JSON.stringify({ message: `wuwei verify refetch ${refetchFail.status}` }) })
       return route.fulfill({ status: fx.status, contentType: 'application/json', body: JSON.stringify(fx.json) })
     })
     // the page's clock is ours: a fresh cache never refetches on focus (React Query's
@@ -1747,20 +1910,32 @@ async function cmdVerify(argv) {
     await p.clock.install()
     const busyNow = () => p.evaluate(sel => Boolean(document.querySelector(sel)) || /\bloading\b|載入中/i.test(document.body.innerText),
       [BUSY, cfg.busy].filter(Boolean).join(',')).catch(() => false)
-    const settle = async (ms, until) => {
+    // a query with no loader retrying a 5xx is not done either: quiet = 8 simulated
+    // seconds with no new hit on the failing endpoint (React Query backs off 1s, 2s, 4s)
+    let lastHits = -1, quiet = 0
+    const retrying = () => { if (hits !== lastHits) { lastHits = hits; quiet = 0 } else quiet++; return quiet < 8 }
+    // what the screen said along the way: a toast gone before it settles still said it
+    const glimpse = async () => { for (const l of (await p.locator('body').innerText().catch(() => '')).split('\n')) if (l.trim().length > 2) glimpsed.add(l.replace(/[ \t]+/g, ' ').trim()) }
+    const settle = async (ms, until, min = 0) => {
       for (let t = 0; t < ms; t += 1000) {
-        if (until && !(await until())) return
+        if (t >= min && until && !(await until())) return
         await p.clock.runFor(1000)
         // real time for the fetch a timer just fired: networkidle, once reached, never waits again
         await p.waitForTimeout(100)
+        await glimpse()
       }
     }
     await p.goto(new URL(page.path, cfg.url).href, { waitUntil: 'domcontentloaded' })
-    if (override?.state === 'pending') await p.waitForTimeout(cfg.pendingWaitMs ?? 1500)
-    else {
-      if (page.ready) await p.locator(page.ready).first().waitFor({ timeout: 15000 }).catch(() => {})
+    let ready = true, early = null, stuck = false
+    if (override?.state === 'pending') {
+      await p.waitForTimeout(cfg.pendingWaitMs ?? 1500)
+      early = await busyNow()
+      // the loader is right at first; still up long after, with the request never answered, is a hang
+      if (cfg.pendingStuckMs !== 0) { await settle(cfg.pendingStuckMs ?? 30000); stuck = await busyNow() }
+    } else {
+      if (page.ready) ready = await p.locator(page.ready).first().waitFor({ timeout: 15000 }).then(() => true, () => false)
       await p.waitForLoadState('networkidle').catch(() => {})
-      if (override) await settle(cfg.errorWaitMs ?? 60000, busyNow)
+      if (override) await settle(cfg.errorWaitMs ?? 60000, async () => (await busyNow()) || (/^5/.test(override.state) && retrying()), cfg.transientMs ?? 4000)
     }
     if (refetchFail) {
       failing = true
@@ -1770,80 +1945,178 @@ async function cmdVerify(argv) {
       else await p.locator(cfg.refetch).first().click().catch(() => {})
       await settle(cfg.refetchWaitMs ?? 30000)
     }
-    const text = (await p.locator('body').innerText().catch(() => '')).replace(/[ \t]+/g, ' ').trim()
+    // a control that stopped accepting input changed the screen, whatever its text says
+    const disabled = await p.evaluate(() => [...document.querySelectorAll('button:disabled,input:disabled,select:disabled,[aria-disabled="true"]')]
+      .map(e => `[disabled] ${(e.innerText || e.value || e.getAttribute('aria-label') || e.name || e.tagName).trim()}`)).catch(() => [])
+    const text = [(await p.locator('body').innerText().catch(() => '')).replace(/[ \t]+/g, ' ').trim(), ...disabled].join('\n')
     const busy = await p.evaluate(sel => Boolean(document.querySelector(sel)), [BUSY, cfg.busy].filter(Boolean).join(','))
     const retry = await p.getByRole('button', { name: /retry|try again|重試/i }).count()
-    return { p, ctx, text, busy, retry, seen, unmocked, errors, refetched }
+    return { text, busy: early ?? busy, retry, seen, unmocked, errors, refetched, afterKeys, glimpsed, ready, stuck,
+      shot: path => p.screenshot({ path, fullPage: true }), close: () => ctx.close() }
   }
-  const lines = t => new Set(t.split('\n').map(l => l.trim()).filter(l => l.length > 2))
-
-  for (const page of (cfg.pages ?? []).filter(pg => !only.length || only.includes(pg.name))) {
-    const dir = join(outDir, page.name)
-    mkdirSync(dir, { recursive: true })
-    const happy = await visit(page)
-    await happy.p.screenshot({ path: join(dir, 'happy.png'), fullPage: true })
-    writeFileSync(join(dir, 'happy.txt'), happy.text)
-    for (const vp of cfg.viewports ?? [{ width: 390, height: 844 }]) {
-      const narrow = await visit(page, { viewport: vp })
-      await narrow.p.screenshot({ path: join(dir, `happy-${vp.width}.png`), fullPage: true })
-      await narrow.ctx.close()
+  return {
+    visit, viewports: cfg.viewports ?? [{ width: 390, height: 844 }], errorWaitMs: 60000,
+    notRefetched: `not refetched by "${cfg.refetch ?? 'focus'}" ${Math.round((cfg.refetchAfterMs ?? 600000) / 60000)} min on — set "refetch" to what refetches it, or a longer "refetchAfterMs"`,
+    done: async () => { await browser.close(); if (server) try { process.kill(-server.pid) } catch {} },
+  }
+}
+
+// the mobile half: Maestro drives the app on a simulator, and the app is built
+// against wuwei's mock server — a native app has no page.route to take over.
+// No clock either: the background wait is real, so a test build with staleTime 0
+// (or "refetchAfterMs" ≥ staleTime) is what lets a refetch happen at all
+async function verifyMobile(cfg, dest, outDir) {
+  const m = cfg.mobile
+  if (!m.appId) { console.error('✗ verify.json: mobile.appId is required'); process.exit(1) }
+  const unreachable = (cfg.pages ?? []).filter(pg => !pg.link && !pg.flow).map(pg => pg.name)
+  if (unreachable.length) { console.error(`✗ verify.json: ${unreachable.join(', ')} — a mobile page needs "link" (a deep link) or "flow" (a Maestro flow that opens it)`); process.exit(1) }
+  // the installer puts it in ~/.maestro/bin, which a non-interactive shell's PATH often lacks
+  const MAESTRO = m.maestro ?? (!quiet('maestro', ['--version']).error ? 'maestro'
+    : existsSync(join(homedir(), '.maestro', 'bin', 'maestro')) ? join(homedir(), '.maestro', 'bin', 'maestro') : null)
+  if (!MAESTRO) { console.error('✗ maestro not found on PATH or in ~/.maestro/bin — curl -Ls "https://get.maestro.mobile.dev" | bash'); process.exit(1) }
+  // one directory per run: a second run at the same sha must not overwrite the flows an error names
+  const flowsDir = join(outDir, 'flows', new Date().toISOString().replace(/[:.]/g, '-'))
+  mkdirSync(flowsDir, { recursive: true })
+  const sleep = ms => new Promise(r => setTimeout(r, ms))
+  const device = m.device ? ['--device', m.device] : []
+
+  // one scenario at a time: what the next visit's requests get
+  let sc = null
+  const held = []
+  const server = createServer((req, res) => {
+    const reply = (status, json) => { res.writeHead(status, { 'content-type': 'application/json' }); res.end(JSON.stringify(json)) }
+    const fx = fixtureFor(cfg.fixtures, req.method, `http://wuwei.local${req.url}`)
+    if (!sc) return reply(503, { message: 'wuwei verify: no scenario' })
+    if (!fx) { sc.unmocked.add(`${req.method} ${req.url.split('?')[0]}`); return reply(501, { message: 'unmocked by wuwei verify' }) }
+    sc.seen.set(fx.key, fx)
+    if (sc.failing) sc.afterKeys.add(fx.key)
+    const { override, refetchFail } = sc
+    const hit = override && fx.key === override.key
+    if (hit && override.state === 'pending') return held.push(res) // never answered: the loading state
+    if (hit && /^\d+$/.test(override.state)) return sc.hits++, sc.lastHit = Date.now(), reply(Number(override.state), { message: `wuwei verify ${override.state}` })
+    if (hit && override.state === 'empty') return reply(200, emptied(fx.json))
+    if (refetchFail && fx.key === refetchFail.key && sc.failing) return sc.refetched++, sc.lastHit = Date.now(), reply(refetchFail.status, { message: `wuwei verify refetch ${refetchFail.status}` })
+    return reply(fx.status, fx.json)
+  })
+  await new Promise((ok, fail) => server.once('error', fail).listen(m.port ?? 48780, '127.0.0.1', ok))
+    .catch(e => { console.error(`✗ mock server on port ${m.port ?? 48780}: ${e.message}`); process.exit(1) })
+
+  // never spawnSync here: a blocked event loop is a mock server that answers nothing
+  const maestro = args => new Promise(done => {
+    const c = spawn(MAESTRO, [...device, ...args], { stdio: ['ignore', 'pipe', 'pipe'] })
+    let out = '', err = ''
+    c.stdout.on('data', d => { out += d })
+    c.stderr.on('data', d => { err += d })
+    const timer = setTimeout(() => c.kill(), 180000)
+    c.on('close', status => { clearTimeout(timer); done({ status, stdout: out, stderr: err }) })
+    c.on('error', e => { clearTimeout(timer); done({ status: -1, stdout: out, stderr: String(e.message) }) })
+  })
+  // a flow that failed is never a silent pass: its file and the error lines, with
+  // typed text (a login's password) kept out of the report
+  let n = 0
+  const run = async steps => {
+    const file = join(flowsDir, `${String(++n).padStart(3, '0')}.yaml`)
+    writeFileSync(file, `appId: ${m.appId}\n---\n${steps.join('\n')}\n`)
+    const r = await maestro(['test', file])
+    if (r.status === 0) return null
+    // Maestro often prints only a summary; its FAILED line is in the newest ~/.maestro/tests/*/maestro.log
+    const logs = join(homedir(), '.maestro', 'tests')
+    const latest = existsSync(logs) ? readdirSync(logs).map(d => join(logs, d, 'maestro.log')).filter(existsSync).sort((a, b) => statSync(b).mtimeMs - statSync(a).mtimeMs)[0] : null
+    const why = `${r.stderr}\n${r.stdout}\n${latest ? readFileSync(latest, 'utf8').split('\n').slice(-200).join('\n') : ''}`.split('\n')
+      .filter(l => /error|fail|unrecognized|exception|not found/i.test(l) && !/input ?text/i.test(l))
+    return `${file.slice(dest.length + 1)} exited ${r.status}: ${(why.slice(0, 2).join(' / ') || 'no error line').trim().slice(0, 200)}`
+  }
+  const abs = f => resolve(dest, f)
+  const BUSY_RE = new RegExp(['progress|spinner|skeleton|activity.?indicator|loading', m.busy ?? cfg.busy].filter(Boolean).join('|'), 'i')
+  // the screen as text: every node's text (or label) in tree order
+  // the status bar — clock, battery, signal — changes between any two shots
+  const CHROME = /^(\d{1,2}:\d{2}(\s?[AP]M)?|\d{1,3}\s?%|(battery|wi-?fi|signal|cellular|no sim|no signal|no service|searching|lte|5g|4g)\b.*)$/i
+  const capture = async () => {
+    const r = await maestro(['hierarchy'])
+    let tree = null
+    // log lines come before the JSON and after it: the tree is from the first line
+    // that opens an object to the last that closes one
+    try { const o = r.stdout; tree = JSON.parse(o.slice(o.search(/^\{/m), o.lastIndexOf('\n}') + 2)) } catch {}
+    const ids = []
+    // a node's own text, else its label — but a label over children that have text
+    // is their concatenation (an RN accessibility group), so the children speak
+    // and a label whose text the children do not carry (iOS Text nodes often have
+    // none of their own) is kept: the group's label is then the only place the value is
+    const walk = node => {
+      const a = node?.attributes ?? {}
+      ids.push(a['resource-id'] ?? '', a.accessibilityText ?? '', a.class ?? '')
+      const kids = (node?.children ?? []).flatMap(walk)
+      const label = (a.accessibilityText || a.value || '').trim()
+      let rest = label
+      for (const k of kids) rest = rest.replace(k, '')
+      const own = (a.text || (/[\p{L}\p{N}]{2,}/u.test(rest) ? label : '') || '').trim()
+      // a control that stopped accepting input changed the screen, whatever its text says
+      const off = a.enabled === 'false' && (a.clickable === 'true' || a.text || label) ? [`[disabled] ${a.text || label || a['resource-id']}`] : []
+      return [...(own && !CHROME.test(own) ? [own] : []), ...kids, ...off]
     }
-    const endpoints = [...happy.seen.keys()]
-    const happyLines = lines(happy.text)
-    const rows = [{ endpoint: '—', state: 'happy', flags: [...[...happy.unmocked].map(u => `unmocked: ${u}`), ...happy.errors.map(e => `page error: ${e}`)], shot: 'happy.png', text: happy.text }]
-    await happy.ctx.close()
-    const served = new Map(happy.seen)
-    for (const key of endpoints) {
-      for (const state of VERIFY_STATES) {
-        if (state === 'empty' && !emptied(served.get(key)?.json)) continue
-        const refetch = state.match(/^refetch-(\d+)$/)
-        const v = refetch ? await visit(page, { refetchFail: { key, status: Number(refetch[1]) } }) : await visit(page, { override: { key, state } })
-        const slug = `${key.replace(/[^\w]+/g, '_').replace(/^_|_$/g, '')}--${state}`
-        await v.p.screenshot({ path: join(dir, `${slug}.png`), fullPage: true })
-        writeFileSync(join(dir, `${slug}.txt`), v.text)
-        await v.ctx.close()
-        const vLines = lines(v.text)
-        // judged on what the state added to the screen: a nav item saying "Access" is not an answer
-        const said = [...vLines].filter(l => !happyLines.has(l)).join('\n')
-        const loading = v.busy || /loading|載入/i.test(said)
-        const flags = v.errors.map(e => `page error: ${e}`)
-        if (/^5/.test(state) && loading) flags.push(`still loading ${(cfg.errorWaitMs ?? 60000) / 1000}s on — client retries outlast the wait; raise "errorWaitMs"`)
-        else if (/^5/.test(state) && !SAYS_ERROR.test(said)) flags.push('no error shown')
-        if (state === '403' && !SAYS_FORBIDDEN.test(said)) flags.push('403 not told as a permission problem')
-        if (state === '404' && v.retry) flags.push('Retry offered on a 404 — it can never succeed')
-        if (state === '403' && v.retry) flags.push('Retry offered on a 403 — it can never succeed')
-        if (state === 'pending' && !v.busy && !/loading|載入/i.test(v.text)) flags.push('no loading indicator')
-        // a refetch that never happened says nothing about how a failed one looks;
-        // what it did say is the lines it added — a relative time ticking is not an error
-        const gone = [...happyLines].filter(l => !vLines.has(l) && !TICKS.test(l))
-        const told = SAYS_ERROR.test(said) || (state === 'refetch-403' && SAYS_FORBIDDEN.test(said))
-        if (refetch && !v.refetched) flags.push(`not refetched by "${cfg.refetch ?? 'focus'}" ${Math.round((cfg.refetchAfterMs ?? 600000) / 60000)} min on — set "refetch" to what refetches it, or a longer "refetchAfterMs"`)
-        else if (refetch && !told) flags.push('silent: the failed refetch shows nothing')
-        else if (refetch && gone.length) flags.push(`refetch failure replaced loaded content: ${gone.length} line(s) gone (${gone.slice(0, 2).join(' / ').slice(0, 60)})`)
-        if (state === 'refetch-403' && v.refetched && told && !SAYS_FORBIDDEN.test(said)) flags.push('403 on refetch not told as a permission problem')
-        rows.push({ endpoint: key, state, flags, shot: `${slug}.png`, text: v.text, said })
-      }
+    const texts = walk(tree).filter((t, i, all) => all[i - 1] !== t)
+    const text = texts.join('\n')
+    return { text, busy: ids.some(i => i && BUSY_RE.test(i)) || /\bloading\b|載入中/i.test(text), retry: texts.filter(t => /^(retry|try again|重試)$/i.test(t)).length, ok: Boolean(tree) }
+  }
+  // every capture along the way is kept: a toast gone before the screen settles still said it
+  let glimpsed = new Set()
+  const settle = async (ms, until, min = 0) => {
+    const t0 = Date.now()
+    let c = await capture()
+    for (const l of c.text.split('\n')) glimpsed.add(l)
+    while (Date.now() - t0 < ms && (Date.now() - t0 < min || until(c))) {
+      await sleep(1500); c = await capture()
+      for (const l of c.text.split('\n')) glimpsed.add(l)
     }
-    // a failure that reads exactly like no data: the user is told there is nothing, not that it broke
-    for (const e of rows.filter(r => r.state === 'empty' && r.said)) for (const r of rows)
-      if (r.endpoint === e.endpoint && /^\d+$/.test(r.state) && r.said === e.said) r.flags.push(`${r.state} shown as the empty state ("${e.said.split('\n')[0].slice(0, 40)}")`)
-    const md = [`# verify ${page.name} @ ${sha}`, '', `page: \`${page.path}\` · endpoints: ${endpoints.length} · states: ${VERIFY_STATES.join(', ')}`, '',
-      '| endpoint | state | flags | on screen, beyond happy | shot |', '|---|---|---|---|---|',
-      ...rows.map(r => `| ${r.endpoint} | ${r.state} | ${r.flags.length ? r.flags.join('; ') : '—'} | ${((r.said ?? r.text).split('\n').find(l => l.trim()) ?? '—').slice(0, 60).replace(/\|/g, '\\|')} | ${r.shot} |`)]
-    writeFileSync(join(dir, 'matrix.md'), md.join('\n') + '\n')
-    report.push({ page: page.name, rows, dir })
+    return c
   }
-  await browser.close()
-  if (server) try { process.kill(-server.pid) } catch {}
 
-  for (const { page, rows, dir } of report) {
-    const flagged = rows.filter(r => r.flags.length)
-    console.log(`${page}: ${rows.length} state(s), ${flagged.length} flagged — ${join(dir, 'matrix.md')}`)
-    for (const r of flagged) console.log(`  ${r.endpoint} · ${r.state}: ${r.flags.join('; ')}`)
+  const open = page => [
+    `- launchApp:\n    stopApp: true\n    clearState: ${m.clearState === true}`,
+    ...(m.login ? [`- runFlow: ${abs(m.login)}`] : []),
+    ...(page.link ? [`- openLink: ${page.link}`] : page.flow ? [`- runFlow: ${abs(page.flow)}`] : []),
+  ]
+  const visit = async (page, { override, refetchFail, happy } = {}) => {
+    sc = { override, refetchFail, failing: false, refetched: 0, afterKeys: new Set(), hits: 0, lastHit: 0, seen: new Map(), unmocked: new Set() }
+    glimpsed = new Set()
+    // a query with no loader retrying a 5xx is not done: 6s with no new hit is
+    const retrying = () => Date.now() - sc.lastHit < 6000
+    const done = (c, extra = {}) => ({ ...c, seen: sc.seen, unmocked: sc.unmocked, errors: [], refetched: sc.refetched, afterKeys: sc.afterKeys, glimpsed, ...extra,
+      shot: async path => { await run([`- takeScreenshot: ${path.replace(/\.png$/, '')}`]) },
+      // the held request is let go only after the shot, or the shot is of what came next
+      close: async () => { for (const res of held.splice(0)) res.destroy() } })
+    // no extendedWaitUntil: older Maestro rejects its `optional`, and a failed wait
+    // reads like a failed launch. `ready` is polled from the hierarchy instead
+    const opened = await run(open(page))
+    if (opened) return done({ text: '', busy: false, retry: 0, ok: false }, { flowError: opened })
+    let c, ready = true, stuck = false
+    if (happy && page.ready) {
+      c = await settle(15000, x => !x.text.includes(page.ready))
+      ready = c.text.includes(page.ready)
+      if (ready) c = await settle(15000, x => x.busy)
+    } else if (override?.state === 'pending') {
+      await sleep(cfg.pendingWaitMs ?? 3000); c = await capture()
+      // the loader is right at first; still up long after, with the request never answered, is a hang
+      if (c.busy && cfg.pendingStuckMs !== 0) { await sleep(cfg.pendingStuckMs ?? 30000); stuck = (await capture()).busy }
+    } else c = await settle(override ? cfg.errorWaitMs ?? 30000 : 15000, x => x.busy || (/^5/.test(override?.state) && retrying()), override ? cfg.transientMs ?? 4000 : 0)
+    if (refetchFail) {
+      sc.failing = true
+      const bg = await run(['- pressKey: Home'])
+      await sleep(cfg.refetchAfterMs ?? 0)
+      // back to the foreground: React Query hears it only through focusManager wired to AppState
+      const fg = bg ?? await run(['- launchApp:\n    stopApp: false'])
+      if (bg || fg) return done(c, { flowError: bg ?? fg })
+      c = await settle(cfg.refetchWaitMs ?? 30000, x => !sc.refetched || x.busy || retrying())
+    }
+    if (!c.ok) return done(c, { flowError: `no hierarchy from maestro — its output is not JSON (${MAESTRO} hierarchy)` })
+    return done(c, { ready, stuck })
+  }
+  return {
+    visit, errorWaitMs: 30000,
+    notRefetched: `not refetched on returning to the foreground ${Math.round((cfg.refetchAfterMs ?? 0) / 1000)}s on — React Query on RN refetches then only with focusManager wired to AppState, and only a stale query (staleTime; "refetchAfterMs" past it)`,
+    done: async () => { for (const res of held.splice(0)) res.destroy(); await new Promise(r => server.close(r)) },
   }
-  console.log('\nflags are leads, not findings: open the shot, and confirm against the spec what the page should say')
 }
-
 // ── review-collect: the lenses' own record, from Claude Code's transcripts ──
 // Claude Code keeps every subagent's transcript under ~/.claude/projects/<cwd,
 // non-alphanumerics as '-'>/<session>/subagents/agent-<id>.jsonl, its type in

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wei-wuwei",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "為無為，則無不治 — a source-of-truth skills & agents framework that compiles to Claude Code and Codex (Cursor and Gemini CLI planned). Write once, run in every agent, govern without forcing.",
   "type": "module",
   "bin": {

package/skills/wuwei-plan-phases/skill.md

@@ -173,7 +173,8 @@ tags: [planning, workflow]
    red blocks that phase)
    or manual UAT (steps + expected result). **A repo with no e2e harness is
    not a reason for UAT**: the first phase with a bound item adds one
-   (Playwright, which `wuwei verify` runs on too) as its first task.
+   (Playwright on web, Maestro on mobile — what `wuwei verify` runs on) as
+   its first task.
    **`## Verify`** lists each page that shows fetched data — `- <page>:
    <route> · phase: NN`, the phase that builds it; its error, 403, empty,
    loading and failed-refetch states are `wuwei verify`'s, not UAT's. No