kaloko 0.3.0

package/src/lib/apps/tree.mjs

@@ -0,0 +1,222 @@
+// UI trees of native apps (Android, iOS, desktop) in one shape, and the deterministic checks that run on them.
+// A node: { role, name, text, id, value, bounds: { x, y, w, h }, clickable, enabled, focused, checked, children }.
+// Units are logical (dp on Android, points on iOS and macOS) so touch targets compare across devices; `scale` in
+// the capture converts them to screenshot pixels.
+// Formats read: Android uiautomator / Appium Android XML, Appium iOS (XCUIElementType…) XML, idb describe-all JSON,
+// Maestro hierarchy JSON, the macOS accessibility dump of the Kaloko helper, OCR lines, and Kaloko's own tree JSON.
+
+const decode = (s) => String(s ?? '').replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&quot;/g, '"').replace(/&apos;|&#39;/g, "'").replace(/&#10;/g, '\n').replace(/&#(\d+);/g, (_, n) => String.fromCharCode(Number(n))).replace(/&amp;/g, '&')
+const clean = (s) => String(s ?? '').replace(/\s+/g, ' ').trim()
+const bool = (v) => v === true || v === 'true'
+
+/** Minimal XML to { tag, attrs, children } (UI dumps: no text nodes, no namespaces that matter). */
+export function parseXml (xml) {
+  const root = { tag: '#root', attrs: {}, children: [] }
+  const stack = [root]
+  const re = /<(\/?)([A-Za-z_][\w.:-]*)((?:\s+[\w.:-]+\s*=\s*(?:"[^"]*"|'[^']*'))*)\s*(\/?)>|<\?[\s\S]*?\?>|<!--[\s\S]*?-->/g
+  let m
+  while ((m = re.exec(xml))) {
+    if (!m[2]) continue
+    if (m[1]) { if (stack.length > 1) stack.pop(); continue }
+    const attrs = {}
+    for (const a of m[3].matchAll(/([\w.:-]+)\s*=\s*(?:"([^"]*)"|'([^']*)')/g)) attrs[a[1]] = decode(a[2] ?? a[3])
+    const el = { tag: m[2], attrs, children: [] }
+    stack[stack.length - 1].children.push(el)
+    if (!m[4]) stack.push(el)
+  }
+  return root
+}
+
+const ANDROID_ROLES = [[/Button|ImageButton|FloatingActionButton|Chip/, 'button'], [/EditText|TextInput|SearchView/, 'textbox'], [/CheckBox/, 'checkbox'], [/Switch|Toggle/, 'switch'], [/RadioButton/, 'radio'], [/ImageView|Image$/, 'image'], [/TextView|Text$/, 'text'], [/RecyclerView|ListView|ScrollView|LazyColumn/, 'list'], [/WebView/, 'webview'], [/ProgressBar/, 'progressbar'], [/SeekBar|Slider/, 'slider'], [/Spinner/, 'combobox'], [/TabWidget|TabLayout/, 'tablist'], [/Toolbar|ActionBar/, 'toolbar']]
+const roleOfClass = (cls) => { for (const [re, r] of ANDROID_ROLES) if (re.test(cls || '')) return r; return 'group' }
+const IOS_ROLES = { Button: 'button', StaticText: 'text', TextField: 'textbox', SecureTextField: 'textbox', SearchField: 'textbox', TextView: 'textbox', Image: 'image', Switch: 'switch', Slider: 'slider', Cell: 'cell', Table: 'list', CollectionView: 'list', ScrollView: 'list', NavigationBar: 'toolbar', TabBar: 'tablist', Tab: 'tab', Link: 'link', Alert: 'alert', Sheet: 'dialog', Window: 'window', Application: 'application', Other: 'group', Picker: 'combobox', SegmentedControl: 'tablist', ActivityIndicator: 'progressbar', WebView: 'webview', Keyboard: 'keyboard', Key: 'key', Toolbar: 'toolbar', CheckBox: 'checkbox', MenuItem: 'menuitem', Menu: 'menu', PopUpButton: 'combobox', RadioButton: 'radio' }
+const iosRole = (type) => IOS_ROLES[String(type || '').replace(/^(XCUIElementType|AX)/, '')] || String(type || 'group').replace(/^(XCUIElementType|AX)/, '').toLowerCase() || 'group'
+const INTERACTIVE = new Set(['button', 'textbox', 'checkbox', 'switch', 'radio', 'slider', 'combobox', 'link', 'tab', 'cell', 'menuitem', 'key'])
+const boundsOf = (s) => { const m = String(s || '').match(/\[(-?\d+),(-?\d+)\]\[(-?\d+),(-?\d+)\]/); return m ? { x: +m[1], y: +m[2], w: +m[3] - +m[1], h: +m[4] - +m[2] } : null }
+
+function fromAndroid (el, density) {
+  const a = el.attrs
+  const d = density || 1
+  const b = boundsOf(a.bounds)
+  const node = {
+    role: roleOfClass(a.class), name: clean(a['content-desc'] || a.text || ''), text: clean(a.text || ''), id: a['resource-id'] || '',
+    cls: a.class || '', bounds: b ? { x: Math.round(b.x / d), y: Math.round(b.y / d), w: Math.round(b.w / d), h: Math.round(b.h / d) } : null,
+    clickable: bool(a.clickable) || bool(a['long-clickable']) || bool(a.checkable), enabled: a.enabled !== 'false', focused: bool(a.focused), checked: bool(a.checked), password: bool(a.password),
+    children: el.children.map((c) => fromAndroid(c, density))
+  }
+  if (node.clickable && node.role === 'group') node.role = 'button'
+  if (node.role === 'text' && node.clickable) node.role = 'button'
+  return node
+}
+function fromAppiumIos (el) {
+  const a = el.attrs
+  const has = a.x != null && a.width != null
+  const role = iosRole(a.type || el.tag)
+  return {
+    role, name: clean(a.label || a.name || ''), text: clean(a.value || a.label || ''), id: a.name || '', cls: a.type || el.tag,
+    bounds: has ? { x: +a.x, y: +a.y, w: +a.width, h: +a.height } : null,
+    clickable: INTERACTIVE.has(role), enabled: a.enabled !== 'false', focused: bool(a.focused), checked: a.value === '1' && role === 'switch', visible: a.visible !== 'false',
+    children: el.children.map(fromAppiumIos)
+  }
+}
+const idbFrame = (e) => { if (e.frame && typeof e.frame === 'object') return { x: e.frame.x, y: e.frame.y, w: e.frame.width, h: e.frame.height }; const m = String(e.AXFrame || '').match(/\{\{(-?[\d.]+),\s*(-?[\d.]+)\},\s*\{([\d.]+),\s*([\d.]+)\}\}/); return m ? { x: +m[1], y: +m[2], w: +m[3], h: +m[4] } : null }
+function fromIdb (e) {
+  const role = iosRole(e.type || e.role)
+  return { role, name: clean(e.AXLabel || e.title || ''), text: clean(e.AXValue || e.AXLabel || ''), id: e.AXUniqueId || '', cls: e.type || e.role || '', bounds: idbFrame(e), clickable: INTERACTIVE.has(role), enabled: e.enabled !== false, focused: false, children: (e.children || []).map(fromIdb) }
+}
+function fromMaestro (e) {
+  const a = e.attributes || {}
+  const b = boundsOf(a.bounds)
+  const cls = a.class || ''
+  const role = cls ? roleOfClass(cls) : (bool(a.clickable) ? 'button' : a.text ? 'text' : 'group')
+  return { role: bool(a.clickable) && role === 'group' ? 'button' : role, name: clean(a.accessibilityText || a['content-desc'] || a.text || a.hintText || ''), text: clean(a.text || ''), id: a['resource-id'] || a.identifier || '', cls, bounds: b, clickable: bool(a.clickable), enabled: a.enabled !== 'false', focused: bool(a.focused), checked: bool(a.checked), children: (e.children || []).map(fromMaestro) }
+}
+function fromAx (e) {
+  const role = iosRole(e.role)
+  return { role, name: clean(e.title || e.description || e.label || ''), text: clean(e.value ?? e.title ?? ''), id: e.identifier || '', cls: e.role || '', bounds: e.frame ? { x: e.frame.x, y: e.frame.y, w: e.frame.w ?? e.frame.width, h: e.frame.h ?? e.frame.height } : null, clickable: INTERACTIVE.has(role) || (e.actions || []).includes('AXPress'), enabled: e.enabled !== false, focused: !!e.focused, children: (e.children || []).map(fromAx) }
+}
+const fromOwn = (e) => ({ role: e.role || 'group', name: clean(e.name || ''), text: clean(e.text || ''), id: e.id || '', cls: e.cls || '', bounds: e.bounds || null, clickable: !!e.clickable, enabled: e.enabled !== false, focused: !!e.focused, checked: !!e.checked, children: (e.children || []).map(fromOwn) })
+
+/**
+ * Reads any supported dump into { root, format, source }. `density` converts Android pixels to dp.
+ * OCR results ({ ocr: [{ text, x, y, w, h }] }) become a flat tree of text nodes (no roles: only text checks work).
+ */
+export function readTree (input, { density = 1 } = {}) {
+  const text = typeof input === 'string' ? input.trim() : null
+  if (text && text.startsWith('<')) {
+    const doc = parseXml(text)
+    const first = doc.children[0]
+    if (!first) throw new Error('empty UI dump')
+    if (first.tag === 'hierarchy' || first.tag === 'node' || first.children.some((c) => c.tag === 'node') || 'bounds' in (first.children[0]?.attrs || {})) {
+      const root = { role: 'application', name: '', text: '', id: '', bounds: null, clickable: false, enabled: true, children: (first.tag === 'hierarchy' ? first.children : [first]).map((c) => fromAndroid(c, density)) }
+      return { root, format: 'android' }
+    }
+    if (/^XCUIElementType|^AppiumAUT$/.test(first.tag)) {
+      const top = first.tag === 'AppiumAUT' ? first.children : [first]
+      return { root: { role: 'application', name: '', text: '', id: '', bounds: null, clickable: false, enabled: true, children: top.map(fromAppiumIos) }, format: 'ios-appium' }
+    }
+    throw new Error(`unknown XML UI dump <${first.tag}>`)
+  }
+  const data = text ? JSON.parse(text) : input
+  if (data?.schema === 'qawalk.tree.v1') return { root: fromOwn(data.root), format: data.format || 'qawalk' }
+  if (Array.isArray(data?.ocr)) return { root: { role: 'application', name: '', text: '', id: '', bounds: null, clickable: false, enabled: true, children: data.ocr.map((l) => ({ role: 'text', name: clean(l.text), text: clean(l.text), id: '', bounds: { x: l.x, y: l.y, w: l.w, h: l.h }, clickable: false, enabled: true, children: [] })) }, format: 'ocr' }
+  if (data?.ax) return { root: fromAx(data.ax), format: 'macos-ax' }
+  if (Array.isArray(data) && (data[0]?.AXLabel !== undefined || data[0]?.AXFrame !== undefined || data[0]?.type)) return { root: { role: 'application', name: '', text: '', id: '', bounds: null, clickable: false, enabled: true, children: data.map(fromIdb) }, format: 'ios-idb' }
+  if (data?.attributes || data?.children && !data.role) return { root: fromMaestro(data), format: 'maestro' }
+  if (data?.role) return { root: fromOwn(data), format: 'qawalk' }
+  throw new Error('unknown UI dump format')
+}
+
+export const walkTree = (root, fn) => { const visit = (n, depth, parent) => { fn(n, depth, parent); for (const c of n.children || []) visit(c, depth + 1, n) }; visit(root, 0, null) }
+export const flatten = (root) => { const out = []; walkTree(root, (n) => out.push(n)); return out }
+const visible = (n) => n.visible !== false && (!n.bounds || (n.bounds.w > 0 && n.bounds.h > 0))
+
+/**
+ * Selectors for app trees, CSS-like: `button`, `[text="Sign in"]`, `button[name*=close i]`, `[id$=login]`,
+ * `text[text~="^\\d+ Kč$"]` (regex), `*` for any role; alternatives separated by commas.
+ * Attributes: name, text, id, role, cls, value; operators = ^= $= *= ~= (regex); a trailing ` i` ignores case.
+ */
+export function matcher (selector) {
+  const alts = String(selector).split(/,(?=(?:[^"]*"[^"]*")*[^"]*$)/).map((s) => s.trim()).filter(Boolean).map((alt) => {
+    const m = alt.match(/^([a-z*][\w-]*)?((?:\[(?:[^\]"']|"[^"]*"|'[^']*')+\])*)$/i)
+    if (!m) throw new Error(`bad app selector "${alt}"`)
+    const role = m[1] && m[1] !== '*' ? m[1].toLowerCase() : null
+    const conds = [...(m[2] || '').matchAll(/\[\s*([\w-]+)\s*(?:([~^$*]?=)\s*(?:"([^"]*)"|'([^']*)'|([^\]\s]+)))?\s*(i)?\s*\]/g)].map((c) => ({ attr: c[1], op: c[2] || null, value: c[3] ?? c[4] ?? c[5] ?? '', ci: !!c[6] }))
+    return (n) => (!role || n.role === role) && conds.every(({ attr, op, value, ci }) => {
+      let v = attr === 'label' ? n.name : n[attr]
+      if (v == null || v === '') return false
+      if (!op) return true
+      v = String(v)
+      if (op === '~=') return new RegExp(value, ci ? 'iu' : 'u').test(v)
+      const [a, b] = ci ? [v.toLowerCase(), value.toLowerCase()] : [v, value]
+      return op === '=' ? a === b : op === '^=' ? a.startsWith(b) : op === '$=' ? a.endsWith(b) : a.includes(b)
+    })
+  })
+  return (n) => alts.some((f) => f(n))
+}
+export const query = (root, selector) => { const f = matcher(selector); return flatten(root).filter((n) => n !== root && visible(n) && f(n)) }
+
+const label = (n) => `${n.role}${n.name ? ` "${n.name.slice(0, 60)}"` : n.text ? ` "${n.text.slice(0, 60)}"` : ''}${n.id ? ` #${String(n.id).split('/').pop()}` : ''}`
+const textOf = (n) => { const parts = []; walkTree(n, (x) => { const t = x.text || x.name; if (t && !parts.includes(t)) parts.push(t) }); return parts.join('\n') }
+
+/** Readable state for the semantic evaluator: an indented outline of roles and texts (like the web page outline). */
+export function outline (root, maxChars = 90000) {
+  const lines = []
+  walkTree(root, (n, depth) => {
+    if (n === root || !visible(n)) return
+    const t = n.name || n.text
+    if (!t && !n.clickable && n.role === 'group') return
+    lines.push(`${'  '.repeat(Math.min(depth - 1, 12))}${n.role}${t ? `: ${t}` : ''}${n.value ? ` = ${n.value}` : ''}${n.enabled === false ? ' (disabled)' : ''}${n.checked ? ' (checked)' : ''}`)
+  })
+  return lines.join('\n').slice(0, maxChars)
+}
+
+/** Assert names a tree check can answer; the rest are web-only (not evaluated on app captures). */
+export const APP_ASSERTS = new Set(['exists', 'absent', 'count', 'text_matches', 'text_absent', 'attr_equals', 'a11y_names', 'app_touch_targets', 'app_no_truncation', 'app_no_crash', 'app_labels', 'no_console_errors'])
+
+/**
+ * Deterministic checks of a node's criteria on a tree. `ctx`: { platform, crash: string|null, logErrors: string[] }.
+ * Returns { checks: { id: { ok, evidence } }, boxes: { id: [{ x, y, w, h }] } } in logical units.
+ */
+export function treeChecks (criteria, root, ctx = {}) {
+  const checks = {}; const boxes = {}
+  const all = flatten(root).filter((n) => n !== root && visible(n))
+  const interactive = all.filter((n) => n.clickable || INTERACTIVE.has(n.role))
+  const ocr = ctx.format === 'ocr'
+  const box = (id, list) => { const b = list.map((n) => n.bounds).filter(Boolean).slice(0, 20); if (b.length) boxes[id] = b }
+  for (const c of criteria || []) {
+    const ch = c.check
+    if (ch.type !== 'deterministic') continue
+    let ok = null; let evidence = ''
+    try {
+      const re = ch.pattern ? new RegExp(ch.pattern, 'u' + String(ch.flags || '').replace(/[^ims]/g, '')) : null
+      switch (ch.assert) {
+        case 'exists': { const l = query(root, ch.selector); ok = l.length > 0; evidence = l[0] ? label(l[0]) : `no visible ${ch.selector}`; box(c.id, l); break }
+        case 'absent': { const l = query(root, ch.selector); ok = l.length === 0; evidence = l[0] ? label(l[0]) : `no visible ${ch.selector}`; box(c.id, l); break }
+        case 'count': { const l = query(root, ch.selector); ok = l.length >= (ch.min ?? 0) && l.length <= (ch.max ?? Infinity); evidence = `${l.length}× ${ch.selector}`; box(c.id, l); break }
+        case 'text_matches': case 'text_absent': {
+          const scope = ch.selector ? query(root, ch.selector) : [root]
+          const hit = scope.find((n) => re.test(textOf(n)))
+          ok = ch.assert === 'text_matches' ? !!hit : !hit
+          const t = hit ? textOf(hit) : ''
+          const m = hit ? t.match(re) : null
+          evidence = hit ? (m ? `${t.slice(Math.max(0, m.index - 60), m.index)}[${m[0]}]${t.slice(m.index + m[0].length, m.index + m[0].length + 60)}`.replace(/\s+/g, ' ') : label(hit)) : scope[0] ? `/${ch.pattern}/ not found` : `no visible ${ch.selector}`
+          if (hit && hit !== root) box(c.id, [hit])
+          break
+        }
+        case 'attr_equals': { const n = query(root, ch.selector)[0]; if (!n) { ok = false; evidence = `no ${ch.selector}`; break } const v = n[ch.attr === 'label' ? 'name' : ch.attr]; ok = String(v) === String(ch.value); evidence = `${ch.attr}=${v}`; box(c.id, [n]); break }
+        case 'a11y_names': case 'app_labels': {
+          if (ocr) { evidence = 'OCR text only: no roles to check'; break }
+          const bad = interactive.filter((n) => !n.name && !n.text && !(n.children || []).some((k) => k.name || k.text))
+          ok = bad.length === 0; evidence = bad.length ? `${bad.length} control(s) without a label: ${bad.slice(0, 4).map(label).join('; ')}` : `${interactive.length} controls have labels`; box(c.id, bad); break
+        }
+        case 'app_touch_targets': {
+          if (ocr) { evidence = 'OCR text only: no controls to measure'; break }
+          const min = ch.min ?? (ctx.platform === 'android' ? 48 : ctx.platform === 'ios' ? 44 : 24)
+          const small = interactive.filter((n) => n.bounds && n.role !== 'key' && (n.bounds.w < min || n.bounds.h < min) && n.bounds.w > 0)
+          ok = small.length === 0; evidence = small.length ? `${small.length} target(s) below ${min}×${min}: ${small.slice(0, 4).map((n) => `${label(n)} ${n.bounds.w}×${n.bounds.h}`).join('; ')}` : `${interactive.length} targets ≥ ${min}×${min}`; box(c.id, small); break
+        }
+        case 'app_no_truncation': {
+          const cut = all.filter((n) => /(…|\.\.\.)$/.test(n.text || n.name || ''))
+          ok = cut.length === 0; evidence = cut.length ? `${cut.length} truncated text(s): ${cut.slice(0, 4).map((n) => `"${(n.text || n.name).slice(-40)}"`).join('; ')}` : 'no truncated texts'; box(c.id, cut); break
+        }
+        case 'app_no_crash': {
+          const dialog = all.find((n) => /(isn't responding|has stopped|keeps stopping|neodpovídá|byla ukončena|se neustále zastavuje|quit unexpectedly)/i.test(n.text || n.name || ''))
+          ok = !ctx.crash && !dialog; evidence = ctx.crash ? ctx.crash.slice(0, 300) : dialog ? label(dialog) : 'no crash or not-responding dialog'; if (dialog) box(c.id, [dialog]); break
+        }
+        case 'no_console_errors': { if (!ctx.logErrors) { evidence = 'App log was not observed.'; break } ok = ctx.logErrors.length === 0; evidence = ok ? 'no errors in the app log' : ctx.logErrors.slice(0, 3).join(' | '); break }
+        default: evidence = `${ch.assert} is a web check; it does not apply to ${ctx.platform || 'app'} captures`
+      }
+    } catch (error) { ok = false; evidence = `check error: ${error.message}` }
+    checks[c.id] = { ok, evidence }
+  }
+  // highlights for criteria that name an element (semantic criteria with a target selector)
+  for (const c of criteria || []) {
+    if (boxes[c.id] || !c.target) continue
+    try { box(c.id, query(root, c.target)) } catch {}
+  }
+  return { checks, boxes }
+}
+
+/** Serializable tree file (qawalk.tree.v1). */
+export const treeFile = ({ root, format, platform, device, scale, size }) => ({ schema: 'qawalk.tree.v1', format, platform, device, scale, size, root })

package/src/lib/browser-daemon.mjs

@@ -0,0 +1,41 @@
+// Long-lived browser process started by `kaloko browser start`.
+// Holds a persistent Chromium context with CDP, enforces the environment
+// policy and gate on every request and records console errors for captures.
+// Secrets are resolved here from the inherited environment, never passed in argv.
+import { chromium } from 'playwright'
+import { writeJson, appendJsonl } from './util.mjs'
+import { prepareContext, clientCertificates } from './access.mjs'
+
+const opts = JSON.parse(process.argv[2])
+const certs = opts.env ? clientCertificates(opts.env, opts.root) : []
+const context = await chromium.launchPersistentContext(opts.profile, {
+  headless: !opts.headed,
+  channel: opts.channel || undefined,
+  viewport: { width: 1280, height: 800 },
+  ...(certs.length ? { clientCertificates: certs } : {}),
+  args: [`--remote-debugging-port=${opts.port}`]
+})
+
+const log = (entry) => appendJsonl(opts.consoleFile, { ts: new Date().toISOString(), ...entry }).catch(() => {})
+const watch = (page) => {
+  page.on('console', (m) => { if (m.type() === 'error') log({ type: 'console', url: page.url(), text: m.text(), src: m.location()?.url || null }) })
+  page.on('pageerror', (e) => log({ type: 'pageerror', url: page.url(), text: e.message }))
+}
+context.pages().forEach(watch)
+context.on('page', watch)
+
+if (opts.env) await prepareContext(context, opts.env, { log })
+
+await writeJson(opts.stateFile, {
+  pid: process.pid,
+  port: opts.port,
+  cdp: `http://127.0.0.1:${opts.port}`,
+  environment: opts.env?.name || null,
+  readonly: !!opts.env?.readonly,
+  started_at: new Date().toISOString()
+})
+
+const shutdown = async () => { try { await context.close() } finally { process.exit(0) } }
+process.on('SIGTERM', shutdown)
+process.on('SIGINT', shutdown)
+context.on('close', () => process.exit(0))

package/src/lib/browser.mjs

@@ -0,0 +1,161 @@
+import { spawn } from 'node:child_process'
+import { join, resolve, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { readJson } from './util.mjs'
+import { writeFile, rm, mkdir } from 'node:fs/promises'
+import { UserError } from './util.mjs'
+import { gateHeaders, clientCertificates } from './access.mjs'
+
+const here = dirname(fileURLToPath(import.meta.url))
+
+// One shared browser per environment: own profile, state, console log and port,
+// so a production (readonly) run never shares a page or a cookie jar with local work.
+const browserDir = (root, output, envName) => join(resolve(root, output), '.browser', envName || 'default')
+export const browserState = (root, output, envName) => join(browserDir(root, output, envName), 'browser.json')
+export const consoleLog = (root, output, envName) => join(browserDir(root, output, envName), 'console.jsonl')
+const legacyState = (root, output) => join(resolve(root, output), '.browser', 'browser.json')
+
+/** Base port from config plus the environment's position in the config. */
+export function portFor (config, envName) {
+  const index = Math.max(0, Object.keys(config.environments || {}).indexOf(envName))
+  return config.browser.port + index
+}
+
+async function stateFor ({ root, config, env }) {
+  const scoped = await readJson(browserState(root, config.output, env.name), null)
+  if (scoped && await alive(scoped.pid)) return scoped
+  const legacy = await readJson(legacyState(root, config.output), null) // browsers started before per-environment state
+  if (legacy && legacy.environment === env.name && await alive(legacy.pid)) return legacy
+  return null
+}
+
+/** The shared browser must run with the policy of the run's environment. */
+function assertPolicy (state, env) {
+  if (state.environment !== env.name) throw new UserError(`Shared browser runs for environment "${state.environment}", the run is "${env.name}". Start one for it: kaloko browser start`)
+  if (env.readonly && !state.readonly) throw new UserError(`Shared browser for "${env.name}" runs without the readonly policy. Restart it: kaloko browser stop && kaloko browser start`)
+}
+
+async function portBusy (port) {
+  const { createServer } = await import('node:net')
+  return new Promise((done) => {
+    const s = createServer().once('error', () => done(true)).once('listening', () => s.close(() => done(false)))
+    s.listen(port, '127.0.0.1')
+  })
+}
+
+async function alive (pid) {
+  try { process.kill(pid, 0); return true } catch { return false }
+}
+
+/** Starts a detached Chromium with CDP. Agents, scripts and humans share it. */
+export async function startBrowser ({ root, config, env, headed }) {
+  if (!env) throw new UserError('The shared browser belongs to an environment: start a run first (kaloko start) or pass --env <name>.')
+  const existing = await stateFor({ root, config, env })
+  if (existing) { assertPolicy(existing, env); return { ...existing, reused: true } }
+  // fail here with the variable's name rather than in the detached daemon
+  gateHeaders(env); clientCertificates(env, root)
+  const port = portFor(config, env.name)
+  if (await portBusy(port)) throw new UserError(`Port ${port} is in use (another project's browser?). Set a different browser.port in kaloko.config.yml.`)
+  const stateFile = browserState(root, config.output, env.name)
+  const args = JSON.stringify({
+    stateFile,
+    consoleFile: consoleLog(root, config.output, env.name),
+    profile: join(browserDir(root, config.output, env.name), 'profile'),
+    port,
+    channel: config.browser.channel || null,
+    headed: !!headed,
+    root,
+    env
+  })
+  const child = spawn(process.execPath, [join(here, 'browser-daemon.mjs'), args], { detached: true, stdio: 'ignore' })
+  child.unref()
+  for (let i = 0; i < 100; i++) {
+    await new Promise((r) => setTimeout(r, 200))
+    const state = await readJson(stateFile, null)
+    if (state && state.pid === child.pid) return state
+  }
+  throw new UserError('Browser did not start within 20 s. Try "kaloko browser start --headed" to see what happens.')
+}
+
+/** Stops the browser of one environment, or every shared browser of the project. */
+export async function stopBrowser ({ root, config, env = null }) {
+  const states = env ? [await stateFor({ root, config, env })] : await allStates({ root, config })
+  let stopped = 0
+  for (const state of states.filter(Boolean)) { process.kill(state.pid, 'SIGTERM'); stopped++ }
+  return stopped > 0
+}
+
+/** Running shared browsers of the project, one per environment. */
+export async function allStates ({ root, config }) {
+  const names = Object.keys(config.environments || {})
+  const states = []
+  for (const name of names) {
+    const s = await stateFor({ root, config, env: { name } })
+    if (s) states.push(s)
+  }
+  return states
+}
+
+/** Connects over CDP to the environment's shared browser; null when it is not running. */
+export async function connectBrowser ({ root, config, env }) {
+  const state = await stateFor({ root, config, env })
+  if (!state) return null
+  assertPolicy(state, env)
+  const { chromium } = await import('playwright')
+  const browser = await chromium.connectOverCDP(state.cdp)
+  return { browser, context: browser.contexts()[0], state }
+}
+
+/** The page the user or agent is on: focused+visible first, otherwise the last real page. */
+/**
+ * New-visitor session: drops cookies and, for the environment origin, local
+ * and session storage. Used before the first step of a run.
+ */
+export async function resetSession (context, page, baseUrl) {
+  if (baseUrl && typeof baseUrl === 'object') baseUrl = baseUrl.default || Object.values(baseUrl)[0]
+  await context.clearCookies()
+  if (!baseUrl) return
+  try {
+    await page.goto(baseUrl, { waitUntil: 'domcontentloaded' })
+    await page.evaluate(() => { localStorage.clear(); sessionStorage.clear() })
+    await context.clearCookies() // the visit itself may have set some
+  } catch {}
+}
+
+export async function currentPage (context, match) {
+  const pages = context.pages().filter((p) => !p.url().startsWith('devtools://'))
+  if (match) {
+    const hit = pages.find((p) => p.url().includes(match))
+    if (!hit) throw new UserError(`No open page URL contains "${match}". Open pages: ${pages.map((p) => p.url()).join(', ')}`)
+    return hit
+  }
+  for (const p of pages) {
+    try {
+      if (await p.evaluate(() => document.visibilityState === 'visible' && document.hasFocus())) return p
+    } catch {}
+  }
+  const real = pages.filter((p) => p.url() !== 'about:blank')
+  return real[real.length - 1] || pages[pages.length - 1] || context.newPage()
+}
+
+export async function launchEphemeral (config) {
+  const { chromium } = await import('playwright')
+  const browser = await chromium.launch({ headless: true, channel: config.browser.channel || undefined })
+  return browser
+}
+
+/**
+ * One walk at a time on a shared browser (#57): walks share its default context, so one run's session reset signs
+ * the other out and tabs get mixed up. The lock names the run holding it; a dead process or a lock older than six
+ * hours is stale. Returns a release function.
+ */
+export async function acquireWalkLock ({ root, config, env, run }) {
+  const file = join(browserDir(root, config.output, env.name), 'walk.lock')
+  const held = await readJson(file, null)
+  if (held && held.run !== run && held.pid !== process.pid && await alive(held.pid) && Date.now() - Date.parse(held.since) < 6 * 3600e3) {
+    throw new UserError(`Another run (${held.run}, pid ${held.pid}) has been walking on the shared ${env.name} browser since ${held.since}. Walks on one shared browser share its cookies and tabs and sign each other out. Wait for it, or walk this run in its own browser: kaloko walk --ephemeral.`)
+  }
+  await mkdir(dirname(file), { recursive: true })
+  await writeFile(file, JSON.stringify({ run, pid: process.pid, since: new Date().toISOString() }) + '\n')
+  return async () => { const now = await readJson(file, null); if (now?.pid === process.pid && now.run === run) await rm(file, { force: true }) }
+}

package/src/lib/build.mjs

@@ -0,0 +1,149 @@
+import { parsePlan, coverage, flaky } from './coverage.mjs'
+import { readFile, writeFile } from 'node:fs/promises'
+import { join, resolve } from 'node:path'
+import { readJson, writeJson } from './util.mjs'
+import { readCaptures, runPaths, listRuns } from './run.mjs'
+import { latestCaptures, evaluationSource, stepIdOf } from './evaluate.mjs'
+import { fieldsOf, DEFAULT_SEMANTIC_SAMPLE } from './stack.mjs'
+import { layout } from './scenario.mjs'
+import { assembleNode, summarize, statusOf, worst } from './manifest-core.mjs'
+import { packageRoot } from './schema.mjs'
+
+export { targetOf, statusOf } from './manifest-core.mjs'
+
+export async function buildManifest ({ run, scenario, config, root, catalog = [] }) {
+  const meta = run.meta
+  const entries = await readCaptures(run.dir)
+  const captures = latestCaptures(entries)
+  const attachments = entries.filter((e) => e.type === 'attachment')
+  const pos = new Map(layout(scenario).map((p) => [p.id, p]))
+  const locales = meta.scope.locales
+  const viewportNames = Object.keys(meta.scope.viewports)
+  const nodes = []
+  for (const node of scenario.nodes) {
+    if (node.kind === 'stack') { const p = pos.get(node.id); nodes.push(await buildStack({ run, node, base: { id: node.id, kind: node.kind, title: node.title, path: node.path ?? null, purpose: node.purpose ?? '', col: p.col, lane: p.lane }, captures, attachments })); continue }
+    const caps = []
+    // pages of a stack live in its items index; normal steps take their own captures only
+    for (const c of captures.filter((x) => x.node === node.id && !x.item)) {
+      const cap = await readJson(join(run.dir, c.file))
+      const stored = await readJson(runPaths(run.dir).step(c.node, c.locale, c.viewport, 'eval.json'), null)
+      const ev = stored?.source === evaluationSource(node, cap) ? stored : null
+      caps.push({ locale: c.locale, viewport: c.viewport, cap, ev, files: { png: cap.files.png, thumb: cap.files.thumb || null, html: cap.files.html || null, tree: cap.files.tree || null, eval: `steps/${c.node}/${c.locale}/${c.viewport}.eval.json` }, ...(cap.live ? { live: cap.live } : {}) })
+    }
+    nodes.push(assembleNode({ node, pos: pos.get(node.id), locales, viewportNames, captures: caps, attachments: attachments.filter((a) => a.node === node.id) }))
+  }
+  const summary = summarize(nodes, scenario.sessions)
+
+  const allRuns = await listRuns(root, config.output)
+  // flaky: a criterion whose verdict differs from another run of this scenario on the same commit and environment
+  const flakyKeys = flaky({ nodes, git: meta.git, environment: meta.environment }, allRuns.filter((r) => r.scenario?.id === scenario.id && r.id !== meta.id))
+  for (const n of nodes) for (const c of n.criteria || []) if (flakyKeys.has(`${n.id}|${c.id}`)) c.flaky = true
+  if (flakyKeys.size) summary.flaky = flakyKeys.size
+  // coverage against the acceptance plan when the scenario names one
+  let cov = null
+  if (scenario.source) {
+    for (const cand of [resolve(root, scenario.source), resolve(root, meta.scenario_file, '..', scenario.source), resolve(root, meta.scenario_file, '..', '..', scenario.source)]) {
+      try { cov = coverage(scenario, parsePlan(await readFile(cand, 'utf8'))); break } catch {}
+    }
+  }
+  const history = allRuns
+    .filter((r) => r.scenario?.id === scenario.id && r.id !== meta.id)
+    .map((r) => ({ id: r.id, started_at: r.started_at, git: r.git, environment: r.environment, summary: r.summary, statuses: Object.fromEntries(r.nodes.filter((n) => n.status).map((n) => [n.id, n.status])) }))
+    .sort((a, b) => b.started_at.localeCompare(a.started_at))
+
+  return {
+    schema: 'qawalk.run.v1',
+    id: meta.id,
+    org: config.org,
+    scenario: { ...meta.scenario, file: meta.scenario_file },
+    git: meta.git,
+    project: meta.project || null,
+    issue: meta.issue || null,
+    // version of the application under test; `version` is the number of a design version (#42)
+    app_version: meta.app_version ?? meta.version ?? null,
+    environment: meta.environment,
+    executor: meta.executor,
+    started_at: meta.started_at,
+    finished_at: new Date().toISOString(),
+    scope: meta.scope,
+    lanes: scenario.lanes || [],
+    sessions: scenario.sessions || null,
+    nodes,
+    edges: scenario.edges.map((e) => ({ from: e.from, to: e.to, label: e.label || '', kind: e.kind || 'main' })),
+    summary,
+    coverage: cov,
+    history,
+    catalog
+  }
+}
+
+
+/**
+ * A stack step: its pages go to steps/<node>/items.json (qawalk.stack.v1: fields, criteria, and per page the path,
+ * status, index fields, capture files and compact results); the node keeps counts, a visual sample and the path.
+ */
+async function buildStack ({ run, node, base, captures, attachments }) {
+  const paths = runPaths(run.dir)
+  const fields = fieldsOf(node).map((f) => ({ id: f.id, label: f.label || f.id }))
+  const crit = (node.criteria || []).map((c) => ({ id: c.id, text: c.text, type: c.check.type, pack: c.pack || null }))
+  const byItem = new Map()
+  for (const c of captures.filter((x) => x.node === node.id && x.item)) {
+    const cap = await readJson(join(run.dir, c.file))
+    const evPath = paths.step(stepIdOf(c), c.locale, c.viewport, 'eval.json')
+    const stored = await readJson(evPath, null)
+    const ev = stored?.source === evaluationSource(node, cap) ? stored : null
+    let it = byItem.get(c.item)
+    if (!it) { it = { id: c.item, path: cap.item?.path || null, url: cap.url, title: cap.item?.title || cap.fields?.title || cap.metadata?.title || null, fields: cap.fields || {}, captures: {}, results: {}, order: byItem.size }; byItem.set(c.item, it) }
+    ;(it.captures[c.locale] ||= {})[c.viewport] = { png: cap.files.png, thumb: cap.files.thumb || null, html: cap.files.html, url: cap.url, size: cap.size ? [cap.size.width, cap.size.height] : null, boxes: cap.boxes, captured_at: cap.captured_at, console_errors: (cap.console_errors || []).length, console: (cap.console_errors || []).slice(0, 10), overflow: (cap.overflow || []).length, meta: cap.meta, ...(cap.http_status ? { http_status: cap.http_status } : {}), ...(cap.capture?.full_page === false ? { first_screen: true } : {}), eval: ev ? `steps/${stepIdOf(c)}/${c.locale}/${c.viewport}.eval.json` : null }
+    it.results[`${c.locale}|${c.viewport}`] = ev ? Object.fromEntries(ev.criteria.map((r) => [r.id, [r.verdict, r.evidence ? String(r.evidence).slice(0, 200) : null, r.score ?? null]])) : Object.fromEntries(crit.filter((x) => x.type !== 'semantic').map((x) => [x.id, ['not_evaluated', null, null]]))
+    if (!ev) it.stale = true
+  }
+  const items = [...byItem.values()].sort((a, b) => a.order - b.order).map(({ order, ...it }) => {
+    const per = Object.values(it.results)
+    const verdictOf = (id) => worst(per.map((r) => r[id]?.[0]).filter(Boolean))
+    const verdicts = crit.map((c) => verdictOf(c.id)).filter((v) => v !== 'not_reached')
+    const status = statusOf(verdicts, per.length > 0)
+    const by_locale = Object.fromEntries(Object.keys(it.captures).map((l) => [l, statusOf(Object.entries(it.results).filter(([k]) => k.startsWith(`${l}|`)).flatMap(([, r]) => Object.values(r).map((x) => x[0])), true)]))
+    return { ...it, status, by_locale, fails: crit.filter((c) => verdictOf(c.id) === 'fail').map((c) => c.id), review: crit.filter((c) => ['needs_review', 'not_evaluated'].includes(verdictOf(c.id))).map((c) => c.id) }
+  })
+  const summary = { pass: 0, partial: 0, fail: 0, skip: 0 }
+  for (const it of items) summary[it.status]++
+  const criteria = crit.map((c) => {
+    const counts = {}
+    for (const it of items) { const v = worst(Object.values(it.results).map((r) => r[c.id]?.[0]).filter(Boolean)); if (v !== 'not_reached') counts[v] = (counts[v] || 0) + 1 }
+    return { ...c, counts, verdict: counts.fail ? 'fail' : counts.needs_review ? 'needs_review' : counts.not_evaluated ? 'not_evaluated' : counts.pass ? 'pass' : 'not_reached', by_locale: {} }
+  })
+  const semanticSample = node.items?.semantic_sample ?? DEFAULT_SEMANTIC_SAMPLE
+  const file = `steps/${node.id}/items.json`
+  await writeJson(join(run.dir, file), { schema: 'qawalk.stack.v1', node: node.id, fields, criteria: crit, semantic_sample: semanticSample, items })
+  const thumbOf = (it) => { const c = Object.values(it.captures)[0]; const v = c && Object.values(c)[0]; return v ? v.thumb || v.png : null }
+  const sample = [...items.filter((it) => it.status === 'fail'), ...items.filter((it) => it.status !== 'fail')].slice(0, 4).map((it) => ({ id: it.id, title: it.title, path: it.path, status: it.status, thumb: thumbOf(it) }))
+  const status = !items.length ? 'skip' : summary.fail ? 'fail' : summary.partial || summary.skip ? 'partial' : 'pass'
+  const locales = [...new Set(items.flatMap((it) => Object.keys(it.by_locale)))]
+  const by_locale = Object.fromEntries(locales.map((l) => { const s = items.map((it) => it.by_locale[l]).filter(Boolean); return [l, s.includes('fail') ? 'fail' : s.some((x) => x !== 'pass') ? 'partial' : 'pass'] }))
+  const src = node.items || {}
+  return {
+    ...base, status, by_locale, captures: {}, criteria, semantic: {}, metadata: {}, session: node.session || null,
+    execution: node.execution ? { strategy: node.execution.strategy, instructions: node.execution.instructions } : { strategy: 'playwright', instructions: 'Open every page of the stack and capture it.' },
+    attachments: attachments.filter((a) => a.node === node.id).map((a) => ({ type: a.kind, title: a.title, file: a.file, locale: a.locale })),
+    stack: { count: items.length, items: file, summary, fields, sample, semantic_sample: semanticSample, source: ['urls', 'file', 'sitemap', 'crawl', 'script'].find((k) => src[k]) || null, stale: items.filter((it) => it.stale).length }
+  }
+}
+
+export async function writePreview ({ run, manifest }) {
+  const template = await readFile(join(packageRoot, 'viewer', 'index.html'), 'utf8')
+  // the local preview opens from file://, where fetch cannot read files: stack indexes go inline
+  // file:// cannot fetch: stack indexes and app UI trees travel inside the preview
+  const withTrees = async (n) => {
+    if (!Object.values(n.captures || {}).some((vps) => Object.values(vps).some((c) => c?.tree))) return n
+    const captures = {}
+    for (const [l, vps] of Object.entries(n.captures)) { captures[l] = {}; for (const [vp, c] of Object.entries(vps)) captures[l][vp] = c?.tree ? { ...c, tree_inline: await readJson(join(run.dir, c.tree), null) } : c }
+    return { ...n, captures }
+  }
+  const preview = { ...manifest, nodes: await Promise.all(manifest.nodes.map(async (n) => (n.stack ? { ...n, stack: { ...n.stack, items_inline: (await readJson(join(run.dir, n.stack.items), { items: [] })).items } } : withTrees(n)))) }
+  const json = JSON.stringify(preview).replace(/</g, '\\u003c')
+  const html = template.replace('/*__QAWALK_RUN__*/null', () => json)
+  await writeJson(runPaths(run.dir).manifest, manifest)
+  await writeFile(runPaths(run.dir).index, html)
+  return runPaths(run.dir).index
+}