kaloko 0.3.0

package/src/lib/mail.mjs

@@ -0,0 +1,182 @@
+// E-mails of a flow, from wherever the project's stack puts them. Every source returns the same
+// message shape: { id, subject, from, to: [address], date, html, text }.
+//   mailpit — built in (REST API), optional gate auth;
+//   script  — a project module for anything else (letter_opener, Mailosaur, IMAP, the app's own API);
+//   file    — `kaloko mail --file`: a message the agent obtained itself (.eml, .html, .json, .txt).
+import { readFile } from 'node:fs/promises'
+import { extname, resolve } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { secret } from './secrets.mjs'
+import { UserError } from './util.mjs'
+
+const address = (a) => (a?.Address ? (a.Name ? `${a.Name} <${a.Address}>` : a.Address) : '')
+
+/** Mailpit REST client (https://mailpit.axllent.org/docs/api-v1/). */
+export function mailpit (mail) {
+  if (!mail || mail.provider !== 'mailpit' || !mail.url) throw new UserError('Environment has no mail.provider: mailpit with url.')
+  const headers = {}
+  // `auth.basic` (older configs: user_env / password_env next to url), plus any headers of a gate in front of it
+  const basic = mail.auth?.basic || (mail.user_env ? { user_env: mail.user_env, password_env: mail.password_env } : null)
+  if (basic) headers.Authorization = 'Basic ' + Buffer.from(`${secret(basic.user_env, 'mailbox user')}:${secret(basic.password_env, 'mailbox password')}`).toString('base64')
+  for (const [name, spec] of Object.entries(mail.auth?.headers || {})) headers[name] = typeof spec === 'string' ? spec : secret(spec.env, `mailbox header ${name}`)
+  const base = mail.url.replace(/\/$/, '')
+  const get = async (path) => {
+    const res = await fetch(base + path, { headers })
+    if (!res.ok) throw new UserError(`Mailpit ${path} → HTTP ${res.status}${res.status === 401 || res.status === 403 ? ' (check mail.auth)' : ''}`)
+    return res.json()
+  }
+  return {
+    async find ({ to, subject, since, id }) {
+      let hitId = id
+      if (!hitId) {
+        const parts = []
+        if (to) parts.push(`to:"${to}"`)
+        if (subject) parts.push(`subject:"${subject.replace(/"/g, '')}"`)
+        // newest first; only messages received after `since` (the run start by default), with 5 s of clock skew
+        const data = await get(`/api/v1/search?${new URLSearchParams({ query: parts.join(' '), limit: since ? '50' : '1' })}`)
+        const floor = since ? Date.parse(since) - 5000 : null
+        const hit = (data.messages || []).find((x) => floor == null || Date.parse(x.Created || x.Date || 0) >= floor)
+        if (!hit) return null
+        hitId = hit.ID
+      }
+      const m = await get(`/api/v1/message/${encodeURIComponent(hitId)}`)
+      return { id: m.ID, subject: m.Subject || '', from: address(m.From), to: (m.To || []).map((t) => t.Address), date: m.Date, html: m.HTML || null, text: m.Text || null }
+    }
+  }
+}
+
+/**
+ * Project adapter: `mail: { provider: script, script: qa/mail/inbox.mjs, options: {...} }`.
+ * The module's default export is `async ({ to, subject, since, options, root, env }) => message | null`
+ * and returns the newest matching message (see templates/mail/letter-opener.mjs).
+ */
+export function scriptProvider (mail, root, env) {
+  if (!mail.script) throw new UserError('mail.provider: script needs mail.script (a module path relative to kaloko.config.yml).')
+  const file = resolve(root, mail.script)
+  let mod
+  return {
+    async find (query) {
+      mod ||= await import(pathToFileURL(file).href).catch((e) => { throw new UserError(`mail.script ${mail.script}: ${e.message}`) })
+      const fn = typeof mod.default === 'function' ? mod.default : mod.find
+      if (typeof fn !== 'function') throw new UserError(`mail.script ${mail.script} must export a default function.`)
+      const m = await fn({ ...query, options: mail.options || {}, root, env })
+      return m ? normalize(m) : null
+    }
+  }
+}
+
+/** Client for the environment's mailbox. */
+export function mailClient (mail, root = process.cwd(), env = null) {
+  if (!mail || mail.provider === 'none') throw new UserError('This environment has no mailbox (mail.provider). Capture the message with kaloko mail --file, or configure mail in kaloko.config.yml.')
+  if (mail.provider === 'script') return scriptProvider(mail, root, env)
+  return mailpit(mail)
+}
+
+/** Polls until a matching message arrives (mailers run in background jobs). */
+export async function waitForMessage (client, query, { timeoutMs = 60000, intervalMs = 2000 } = {}) {
+  const until = Date.now() + timeoutMs
+  while (true) {
+    const hit = await client.find(query)
+    if (hit) return hit
+    if (Date.now() > until) throw new UserError(`No e-mail matching ${JSON.stringify({ to: query.to, subject: query.subject, ...(query.id ? { id: query.id } : {}) })}${query.since && !query.id ? ` received since ${query.since}` : ''} within ${timeoutMs / 1000} s.${query.since && !query.id ? ' An older message: --since <date>, --any-time or --id <message id>.' : ''}`)
+    await new Promise((r) => setTimeout(r, intervalMs))
+  }
+}
+
+export const recipient = (mail, short) => (mail?.address || '').replace('{run}', short)
+
+const list = (v) => (Array.isArray(v) ? v : v ? String(v).split(/,(?=(?:[^"]*"[^"]*")*[^"]*$)/) : []).map((s) => String(s).trim()).filter(Boolean)
+
+/** Normalizes what an adapter or a JSON file returns (also accepts Mailpit-style capitalized keys). */
+export function normalize (m) {
+  const from = m.from ?? m.From
+  return {
+    id: String(m.id ?? m.ID ?? ''),
+    subject: m.subject ?? m.Subject ?? '',
+    from: typeof from === 'object' && from ? address(from) : from || '',
+    to: list(m.to ?? (m.To || []).map?.((t) => t.Address ?? t)),
+    date: m.date ?? m.Date ?? null,
+    html: m.html ?? m.HTML ?? null,
+    text: m.text ?? m.Text ?? null
+  }
+}
+
+/** A message file the agent obtained itself. */
+export async function readMessageFile (file) {
+  const ext = extname(file).toLowerCase()
+  if (!['.eml', '.msg', '.mbox', '.json', '.html', '.htm', '.txt'].includes(ext)) throw new UserError(`Unknown message file type ${ext || '(none)'}: use .eml, .html, .json or .txt.`)
+  const raw = await readFile(file)
+  if (ext === '.eml' || ext === '.msg' || ext === '.mbox') return parseEml(raw)
+  if (ext === '.json') return normalize(JSON.parse(raw.toString('utf8')))
+  const body = raw.toString('utf8')
+  if (ext === '.html' || ext === '.htm') return { id: '', subject: (body.match(/<title[^>]*>([\s\S]*?)<\/title>/i)?.[1] || '').trim(), from: '', to: [], date: null, html: body, text: null }
+  return { id: '', subject: '', from: '', to: [], date: null, html: null, text: body }
+}
+
+// --- RFC 5322 / MIME, enough for what mailers send: multipart, base64, quoted-printable, charsets ---
+
+const decodeBytes = (bytes, charset = 'utf-8') => {
+  try { return new TextDecoder(charset.toLowerCase().replace(/^(us-ascii|ascii)$/, 'utf-8')).decode(bytes) } catch { return new TextDecoder('utf-8').decode(bytes) }
+}
+const qpBytes = (s, header = false) => {
+  const src = (header ? s.replace(/_/g, ' ') : s).replace(/=\r?\n/g, '')
+  const out = []
+  for (let i = 0; i < src.length; i++) {
+    if (src[i] === '=' && /^[0-9A-Fa-f]{2}$/.test(src.slice(i + 1, i + 3))) { out.push(parseInt(src.slice(i + 1, i + 3), 16)); i += 2 } else out.push(src.charCodeAt(i) & 0xff)
+  }
+  return Buffer.from(out)
+}
+/** RFC 2047 encoded words in headers. */
+export const decodeHeader = (v = '') => v.replace(/=\?([^?]+)\?([BbQq])\?([^?]*)\?=(\s+(?==\?))?/g, (_, cs, enc, text) => decodeBytes(enc.toUpperCase() === 'B' ? Buffer.from(text, 'base64') : qpBytes(text, true), cs))
+
+function splitMessage (bin) {
+  const m = bin.match(/\r?\n\r?\n/)
+  const head = m ? bin.slice(0, m.index) : bin
+  const body = m ? bin.slice(m.index + m[0].length) : ''
+  const headers = {}
+  for (const line of head.replace(/\r?\n[ \t]+/g, ' ').split(/\r?\n/)) {
+    const i = line.indexOf(':')
+    if (i > 0) { const k = line.slice(0, i).trim().toLowerCase(); if (!(k in headers)) headers[k] = line.slice(i + 1).trim() }
+  }
+  return { headers, body }
+}
+const param = (value, name) => value?.match(new RegExp(`${name}\\s*=\\s*(?:"([^"]*)"|([^;\\s]+))`, 'i'))?.slice(1).find(Boolean)
+
+function walkParts ({ headers, body }, found) {
+  const type = (headers['content-type'] || 'text/plain').split(';')[0].trim().toLowerCase()
+  if (type.startsWith('multipart/')) {
+    const boundary = param(headers['content-type'], 'boundary')
+    if (!boundary) return
+    for (const chunk of body.split(`--${boundary}`).slice(1)) {
+      if (chunk.startsWith('--')) break
+      // the line break before a delimiter belongs to the delimiter (RFC 2046)
+      walkParts(splitMessage(chunk.replace(/^\r?\n/, '').replace(/\r?\n$/, '')), found)
+    }
+    return
+  }
+  if (type !== 'text/html' && type !== 'text/plain') return
+  if (/attachment/i.test(headers['content-disposition'] || '')) return
+  const enc = (headers['content-transfer-encoding'] || '').toLowerCase()
+  const bytes = enc === 'base64' ? Buffer.from(body.replace(/\s+/g, ''), 'base64') : enc === 'quoted-printable' ? qpBytes(body) : Buffer.from(body, 'latin1')
+  const key = type === 'text/html' ? 'html' : 'text'
+  found[key] ??= decodeBytes(bytes, param(headers['content-type'], 'charset') || 'utf-8')
+}
+
+/** Parses a raw RFC 5322 message (Buffer or string) into the message shape. */
+export function parseEml (raw) {
+  const bin = Buffer.isBuffer(raw) ? raw.toString('latin1') : Buffer.from(raw, 'utf8').toString('latin1')
+  const top = splitMessage(bin)
+  const found = {}
+  walkParts(top, found)
+  // raw 8-bit header bytes are UTF-8 first; encoded words (ASCII) are decoded after that
+  const h = (k) => decodeHeader(decodeBytes(Buffer.from(top.headers[k] || '', 'latin1')))
+  return {
+    id: (top.headers['message-id'] || '').replace(/[<>]/g, ''),
+    subject: h('subject'),
+    from: h('from'),
+    to: list(h('to')),
+    date: top.headers.date ? new Date(top.headers.date).toISOString() : null,
+    html: found.html ?? null,
+    text: found.text ?? null
+  }
+}

package/src/lib/manifest-core.mjs

@@ -0,0 +1,127 @@
+// Pure assembly of a run manifest's steps and summary: no file system, no Node APIs.
+// Shared by the CLI (build.mjs) and the service, which composes design versions from a draft (#42),
+// so both produce the same verdicts from the same captures.
+
+import { PACK_HELP, packHelp } from './pack-help.mjs'
+
+const RANK = { fail: 4, needs_review: 3, not_evaluated: 2, pass: 1, not_reached: 0 }
+export const worst = (list) => list.reduce((a, b) => (RANK[b] > RANK[a] ? b : a), 'not_reached')
+export const aggregate = (list) => {
+  if (list.every((v) => v === 'not_reached')) return 'not_reached'
+  return worst(list.map((v) => v === 'not_reached' ? 'not_evaluated' : v))
+}
+
+/** Where a criterion lives when it is not a visible element: document head metadata. */
+export function targetOf (c) {
+  const k = c.check
+  if (k.type !== 'deterministic') return null
+  if (k.assert === 'title_matches') return { kind: 'meta', selector: 'title' }
+  if (k.selector && /^\s*(meta|link|title|h[1-6]\b|script\[type=['"]?application\/ld\+json)/i.test(k.selector)) return { kind: 'meta', selector: k.selector }
+  if (k.assert === 'no_console_errors') return { kind: 'console' }
+  return null
+}
+
+/** Node status from criterion verdicts. */
+export function statusOf (verdicts, captured) {
+  if (!captured) return 'skip'
+  if (!verdicts.length) return 'pass'
+  if (verdicts.includes('fail')) return 'fail'
+  if (verdicts.some((v) => v === 'needs_review' || v === 'not_evaluated' || v === 'not_reached')) return 'partial'
+  return 'pass'
+}
+
+/** The capture fields a manifest keeps (the full probe record stays with the capture). */
+export function slimCapture (cap) {
+  return {
+    url: cap.url, size: cap.size, boxes: cap.boxes, captured_at: cap.captured_at,
+    console_errors: cap.console_errors || [], blocked_requests: cap.blocked_requests || [],
+    overflow: cap.overflow || [], meta: cap.meta, mail: cap.mail || null, metadata: cap.metadata || null, ...(cap.view ? { view: cap.view } : {}),
+    ...(cap.http_status ? { http_status: cap.http_status } : {}), ...(cap.platform ? { platform: cap.platform, device: cap.device || null } : {}),
+    ...(cap.design ? { design: cap.design } : {}), ...(cap.capture ? { capture: cap.capture } : {}),
+    ...(cap.criteria_hash ? { criteria_hash: cap.criteria_hash } : {})
+  }
+}
+
+/**
+ * One manifest node from its scenario node and captures.
+ * captures: [{ locale, viewport, cap (capture record or slimCapture), ev (valid evaluation or null),
+ *              files: { png, html, thumb?, eval? }, live? }]
+ */
+export function assembleNode ({ node, pos, locales, viewportNames, captures, attachments = [] }) {
+  const base = { id: node.id, kind: node.kind, title: node.title, path: node.path ?? null, purpose: node.purpose ?? '', col: pos.col, lane: pos.lane }
+  if (node.kind === 'decision') return { ...base, status: null }
+  const applicable = locales.filter((l) => !node.path || typeof node.path === 'string' || (node.path[l] ?? node.path.default))
+  const mine = captures.filter((c) => applicable.includes(c.locale) && viewportNames.includes(c.viewport))
+  const capturesOut = {}
+  const perCriterion = new Map((node.criteria || []).map((c) => [c.id, { id: c.id, text: c.text, type: c.check.type, pack: c.pack || null, ...(c.pack && PACK_HELP[c.id] ? { help: { en: packHelp(c.id, 'en'), cs: packHelp(c.id, 'cs') } } : {}), by_locale: {}, evidence: null, question: c.check.question || null, target: targetOf(c), check: c.check }]))
+  const semanticByKey = {}
+  const metadata = {}
+  for (const c of mine) {
+    const { cap, ev } = c
+    ;(capturesOut[c.locale] ||= {})[c.viewport] = {
+      png: c.files.png, thumb: c.files.thumb || null, html: c.files.html || null, url: cap.url ?? null,
+      ...(cap.platform ? { platform: cap.platform, device: cap.device || null, tree: c.files.tree || null } : {}),
+      ...(cap.http_status ? { http_status: cap.http_status } : {}),
+      ...(cap.capture && (cap.capture.scale !== 1 || cap.capture.format === 'png' || cap.capture.masked || cap.capture.annotations?.length) ? { quality: cap.capture } : {}), size: [cap.size.width, cap.size.height],
+      boxes: cap.boxes, captured_at: cap.captured_at, console_errors: (cap.console_errors || []).length, console: (cap.console_errors || []).slice(0, 20), blocked_list: (cap.blocked_requests || []).slice(0, 20),
+      blocked: (cap.blocked_requests || []).length, overflow: (cap.overflow || []).length, meta: cap.meta,
+      mail: cap.mail || null, eval: ev ? c.files.eval : null,
+      // quick signals from the evaluator (probabilities: purpose met, expected language, looks broken)
+      ...(ev?.signals ? { signals: ev.signals } : {}),
+      ...(c.live ? { live: c.live } : {}),
+      ...(cap.view?.revision ? { view: cap.view } : {})
+    }
+    if (ev?.semantic || ev?.jev) semanticByKey[`${c.locale}|${c.viewport}`] = ev.semantic || ev.jev
+    if (cap.metadata && !metadata[c.locale]) metadata[c.locale] = cap.metadata
+    for (const agg of perCriterion.values()) ((agg.by_locale[c.locale] ||= {})[c.viewport] = { verdict: 'not_evaluated' })
+    for (const r of ev?.criteria || []) {
+      const agg = perCriterion.get(r.id)
+      if (!agg) continue
+      const loc = (agg.by_locale[c.locale] ||= {})
+      const score = r.score ?? r.jev?.noul ?? r.noul ?? null
+      // semantic answers carry the thresholds they were judged by and where they were evaluated (own key or Kaloko)
+      loc[c.viewport] = { verdict: r.verdict, evidence: r.evidence, score, note: r.note ?? null, ...(score != null && ev.thresholds ? { th: [ev.thresholds.fail, ev.thresholds.pass] } : {}), ...(r.type === 'semantic' && ev.semantic?.via ? { via: ev.semantic.via } : {}) }
+      if (r.evidence && (!agg.evidence || r.verdict !== 'pass')) agg.evidence = r.evidence
+    }
+  }
+  const criteria = [...perCriterion.values()].map((agg) => {
+    for (const l of applicable) for (const vp of viewportNames) ((agg.by_locale[l] ||= {})[vp] ||= { verdict: 'not_reached' })
+    const verdicts = applicable.flatMap((l) => viewportNames.map((vp) => agg.by_locale[l][vp].verdict))
+    return { ...agg, verdict: aggregate(verdicts) }
+  })
+  const byLocale = {}
+  for (const l of locales) {
+    const captured = !!capturesOut[l]
+    const vs = criteria.map((c) => aggregate(Object.values(c.by_locale[l] || {}).map((v) => v.verdict)))
+    if (applicable.includes(l) && viewportNames.some((vp) => !capturesOut[l]?.[vp])) vs.push('not_reached')
+    byLocale[l] = statusOf(vs, captured)
+  }
+  const verdicts = criteria.map((c) => c.verdict)
+  if (applicable.some((l) => viewportNames.some((vp) => !capturesOut[l]?.[vp]))) verdicts.push('not_reached')
+  return {
+    ...base,
+    status: statusOf(verdicts, mine.length > 0),
+    by_locale: byLocale,
+    captures: capturesOut,
+    criteria,
+    semantic: semanticByKey,
+    metadata,
+    session: node.session || null,
+    execution: node.execution ? { strategy: node.execution.strategy, instructions: node.execution.instructions } : null,
+    attachments: attachments.map((a) => ({ type: a.kind, title: a.title, file: a.file, locale: a.locale }))
+  }
+}
+
+/** Summary counts of the screens of a manifest. */
+export function summarize (nodes, sessions = null) {
+  const screens = nodes.filter((n) => n.kind !== 'decision')
+  const summary = { pass: 0, partial: 0, fail: 0, skip: 0, criteria: {} }
+  for (const n of screens) summary[n.status]++
+  for (const n of screens) for (const c of n.criteria) summary.criteria[c.verdict] = (summary.criteria[c.verdict] || 0) + 1
+  if (sessions) {
+    summary.by_session = {}
+    for (const key of Object.keys(sessions)) summary.by_session[key] = { pass: 0, partial: 0, fail: 0, skip: 0 }
+    for (const n of screens) if (n.session && summary.by_session[n.session]) summary.by_session[n.session][n.status]++
+  }
+  return summary
+}

package/src/lib/pack-help.mjs

@@ -0,0 +1,55 @@
+// Help for pack criteria (#58 follow-up): a Czech name, why the check matters and how to fix a failure, in
+// English and Czech. The manifest carries it on each pack criterion; the canvas and the walk summary show it.
+
+/** @type {Record<string, { cs: string, why: [string, string], fix: [string, string] }>} id → { cs name, [en, cs] why, [en, cs] fix } */
+export const PACK_HELP = {
+  AC101: { cs: 'Právě jeden nadpis H1', why: ['Search engines and screen readers take the H1 as the name of the page; none or several make it unclear.', 'Vyhledávače i čtečky obrazovky berou H1 jako název stránky; žádný nebo několik ho znejasní.'], fix: ['Keep one <h1> with the page\'s topic; turn other big headings into <h2>.', 'Nechte jeden <h1> s tématem stránky; ostatní velké nadpisy změňte na <h2>.'] },
+  AC102: { cs: 'Titulek má 10 až 70 znaků', why: ['The title is the blue link in search results; too short says nothing, too long gets cut.', 'Titulek je modrý odkaz ve výsledcích hledání; příliš krátký nic neřekne, příliš dlouhý se ořízne.'], fix: ['Write a specific <title> of about 50–60 characters: topic first, brand last.', 'Napište konkrétní <title> kolem 50–60 znaků: nejdřív téma, značka na konec.'] },
+  AC103: { cs: 'Popis stránky má 50 až 160 znaků', why: ['The meta description is the snippet under the link; without it search engines pick random text.', 'Meta popis je úryvek pod odkazem; bez něj vyhledávač vybere náhodný text.'], fix: ['Add <meta name="description"> that says in one or two sentences what the page offers.', 'Doplňte <meta name="description">, který jednou dvěma větami řekne, co stránka nabízí.'] },
+  AC104: { cs: 'Kanonický odkaz je uvedený', why: ['Without a canonical URL, copies of the page (parameters, filters) compete with each other in search.', 'Bez kanonické adresy si kopie stránky (parametry, filtry) konkurují ve vyhledávání.'], fix: ['Add <link rel="canonical" href="…"> with the page\'s preferred address.', 'Doplňte <link rel="canonical" href="…"> s preferovanou adresou stránky.'] },
+  AC105: { cs: 'hreflang pro každý jazyk', why: ['hreflang tells search engines which language version to show to whom.', 'hreflang říká vyhledávačům, kterou jazykovou verzi komu ukázat.'], fix: ['Add <link rel="alternate" hreflang="…"> for every language, including the page itself.', 'Doplňte <link rel="alternate" hreflang="…"> pro každý jazyk včetně stránky samotné.'] },
+  AC106: { cs: 'Open Graph titulek a popis', why: ['Shared links on social networks and chats use Open Graph for their preview.', 'Sdílené odkazy na sítích a v chatech berou náhled z Open Graph.'], fix: ['Add og:title and og:description (and ideally og:image) meta tags.', 'Doplňte meta značky og:title a og:description (ideálně i og:image).'] },
+  AC107: { cs: 'Stránka není vyřazená z indexace', why: ['A noindex robots tag keeps the page out of search results entirely.', 'Značka robots s noindex stránku úplně vyřadí z výsledků hledání.'], fix: ['Remove noindex from <meta name="robots"> on pages that should be found (often left over from staging).', 'Odstraňte noindex z <meta name="robots"> na stránkách, které mají být k nalezení (často zbytek ze stagingu).'] },
+  AC108: { cs: 'Viewport pro telefony', why: ['Without the viewport tag phones show a zoomed-out desktop page.', 'Bez značky viewport ukazují telefony zmenšenou desktopovou stránku.'], fix: ['Add <meta name="viewport" content="width=device-width, initial-scale=1">.', 'Doplňte <meta name="viewport" content="width=device-width, initial-scale=1">.'] },
+  AC109: { cs: 'Atribut lang u html', why: ['Screen readers pick the voice and search engines the language from <html lang>.', 'Čtečky obrazovky podle <html lang> volí hlas a vyhledávače jazyk.'], fix: ['Set <html lang="cs"> (or the page\'s language code).', 'Nastavte <html lang="cs"> (nebo kód jazyka stránky).'] },
+  AC110: { cs: 'Nic nepřetéká do strany', why: ['Content wider than the screen makes phones scroll sideways and breaks the layout.', 'Obsah širší než obrazovka nutí telefony posouvat stránku do strany a rozbíjí rozvržení.'], fix: ['Find the wide element in the evidence; limit it with max-width: 100% or let it wrap.', 'Najděte široký prvek v důkazu; omezte ho max-width: 100% nebo ho nechte zalomit.'] },
+  AC111: { cs: 'V konzoli nejsou chyby', why: ['Console errors often mean a feature silently does not work.', 'Chyby v konzoli často znamenají, že něco tiše nefunguje.'], fix: ['Open the error in the evidence and fix the script, or add the console pack to separate third-party noise.', 'Otevřete chybu v důkazu a opravte skript, nebo přidejte pack console, který oddělí šum cizích skriptů.'] },
+  AC201: { cs: 'Účel stránky je jasný hned na první obrazovce', why: ['Visitors decide within seconds whether they are in the right place.', 'Návštěvník se během pár vteřin rozhodne, jestli je na správném místě.'], fix: ['Make the heading and first sentence say what the page is for and for whom.', 'Ať nadpis a první věta řeknou, k čemu stránka je a pro koho.'] },
+  AC202: { cs: 'Jedna jasná hlavní akce', why: ['Several equally loud buttons make people hesitate; none leaves them without a next step.', 'Několik stejně výrazných tlačítek lidi zdrží; žádné je nechá bez dalšího kroku.'], fix: ['Give one action the primary style; make the others secondary or links.', 'Jedné akci dejte hlavní styl, ostatní udělejte vedlejší nebo jako odkazy.'] },
+  AC203: { cs: 'Formulářová pole mají viditelný popisek', why: ['A placeholder disappears as people type; they forget what the field was.', 'Placeholder při psaní zmizí a lidé zapomenou, co do pole patří.'], fix: ['Add a <label for="…"> (or aria-label) to every visible input.', 'Ke každému viditelnému poli doplňte <label for="…"> (nebo aria-label).'] },
+  AC204: { cs: 'Odkazy a tlačítka říkají, co udělají', why: ['"Click here" or "More" does not say where it leads, especially out of context or to a screen reader.', '„Klikněte zde“ nebo „Více“ neřekne, kam vede, zvlášť mimo kontext nebo ve čtečce.'], fix: ['Name the result: "Download the price list", "Continue to payment".', 'Pojmenujte výsledek: „Stáhnout ceník“, „Pokračovat k platbě“.'] },
+  AC301: { cs: 'Obrázky mají alternativní text', why: ['Without alt text, blind visitors and search engines do not know what an image shows.', 'Bez alt textu nevidomí ani vyhledávače nevědí, co obrázek ukazuje.'], fix: ['Add alt="…" describing the image; decorative images get alt="".', 'Doplňte alt="…" s popisem obrázku; dekorativní obrázky dostanou alt="".'] },
+  AC302: { cs: 'Odkazy a tlačítka mají přístupný název', why: ['An icon button without a name is read as just "button".', 'Tlačítko s ikonou bez názvu čtečka přečte jen jako „tlačítko“.'], fix: ['Add visible text or aria-label to icon-only links and buttons.', 'Odkazům a tlačítkům jen s ikonou doplňte text nebo aria-label.'] },
+  AC303: { cs: 'Formulářová pole mají popisky', why: ['Screen reader users hear only "edit text" for a field without a label.', 'Uživatel čtečky uslyší u pole bez popisku jen „editační pole“.'], fix: ['Connect a <label> to each field (for/id) or use aria-label / aria-labelledby.', 'Ke každému poli připojte <label> (for/id) nebo použijte aria-label / aria-labelledby.'] },
+  AC304: { cs: 'Úrovně nadpisů se nepřeskakují', why: ['People navigate by headings; a jump from H2 to H4 hides the structure.', 'Lidé se pohybují po nadpisech; skok z H2 na H4 zamlží strukturu.'], fix: ['Use heading levels in order; style by CSS, not by picking a smaller level.', 'Používejte úrovně nadpisů postupně; vzhled řešte CSS, ne volbou nižší úrovně.'] },
+  AC305: { cs: 'Text splňuje kontrast WCAG AA', why: ['Low contrast text is hard to read in sunlight and for people with weaker sight.', 'Text s nízkým kontrastem se špatně čte na slunci i lidem se slabším zrakem.'], fix: ['Darken the text or lighten the background to at least 4.5 : 1 (3 : 1 for large text).', 'Ztmavte text nebo zesvětlete pozadí aspoň na 4,5 : 1 (u velkého textu 3 : 1).'] },
+  AC306: { cs: 'Stránka má hlavní oblast (main)', why: ['Screen reader users jump straight to <main> to skip the navigation.', 'Uživatelé čteček skáčou rovnou na <main>, aby přeskočili navigaci.'], fix: ['Wrap the main content in <main> (once per page).', 'Hlavní obsah obalte do <main> (jednou na stránce).'] },
+  AC307: { cs: 'Id prvků jsou jedinečná', why: ['Duplicate ids break labels, anchors and scripts that look elements up by id.', 'Duplicitní id rozbijí popisky, kotvy i skripty, které prvky hledají podle id.'], fix: ['Rename the repeated ids listed in the evidence (often from a copied component).', 'Přejmenujte opakovaná id z důkazu (často z kopírované komponenty).'] },
+  AC401: { cs: 'Největší obsah se vykreslí do 2,5 s', why: ['LCP is how long people wait before the page looks ready; Google uses it for ranking.', 'LCP je doba, než stránka působí hotově; Google ho používá při řazení.'], fix: ['Make the hero image smaller (WebP/AVIF, right size), preload it, and cut render-blocking scripts.', 'Zmenšete hlavní obrázek (WebP/AVIF, správná velikost), přednačtěte ho a omezte blokující skripty.'] },
+  AC402: { cs: 'Rozvržení se při načítání nehýbe (CLS pod 0,1)', why: ['Content that jumps while loading makes people tap the wrong thing.', 'Obsah, který při načítání poskakuje, svádí k ťuknutí vedle.'], fix: ['Give images and embeds width and height, and reserve space for banners and fonts.', 'Dejte obrázkům a vloženým prvkům šířku a výšku a rezervujte místo pro bannery a písma.'] },
+  AC403: { cs: 'Server odpoví do 800 ms', why: ['A slow first byte delays everything else on the page.', 'Pomalý první bajt zdrží všechno ostatní na stránce.'], fix: ['Cache the page (CDN, full-page cache) or speed up the backend work behind it.', 'Stránku kešujte (CDN, cache celé stránky) nebo zrychlete práci backendu za ní.'] },
+  AC404: { cs: 'Stránka má do 3 MB', why: ['Heavy pages are slow and expensive on mobile data.', 'Těžké stránky jsou pomalé a drahé na mobilních datech.'], fix: ['Compress images, drop unused scripts and fonts; the evidence lists the size.', 'Zkomprimujte obrázky, odeberte nepoužité skripty a písma; velikost je v důkazu.'] },
+  AC601: { cs: 'Odpovídá chybovým stavem (4xx/5xx), ne „měkkou“ 200', why: ['A missing page that answers 200 gets indexed as real content and hides broken links from monitoring.', 'Chybějící stránka s odpovědí 200 se zaindexuje jako obsah a skryje rozbité odkazy před monitoringem.'], fix: ['Return 404 (or 410) from the server for missing pages; keep the friendly page as its body.', 'Na chybějící stránky vracejte ze serveru 404 (nebo 410); přívětivou stránku nechte jako obsah.'] },
+  AC602: { cs: 'Odkazuje zpět na úvod', why: ['A dead end loses the visitor.', 'Slepá ulička návštěvníka ztratí.'], fix: ['Add a clear link to the home page.', 'Doplňte zřetelný odkaz na úvodní stránku.'] },
+  AC603: { cs: 'Navigace nebo hledání zůstává dostupné', why: ['People on an error page want to find what they came for.', 'Lidé na chybové stránce chtějí najít, pro co přišli.'], fix: ['Keep the site header with navigation or add a search field.', 'Ponechte hlavičku webu s navigací nebo doplňte vyhledávání.'] },
+  AC604: { cs: 'Žádný výpis chyby, SQL ani ladicí stránka', why: ['Stack traces leak paths, versions and queries that help attackers.', 'Výpisy chyb prozradí cesty, verze a dotazy, které pomáhají útočníkům.'], fix: ['Turn off debug output in production and show a generic error page.', 'Na produkci vypněte ladicí výstup a ukažte obecnou chybovou stránku.'] },
+  AC605: { cs: 'Chybu vysvětlí lidsky a nabídne cestu dál', why: ['A calm explanation keeps people on the site instead of leaving.', 'Klidné vysvětlení udrží lidi na webu, místo aby odešli.'], fix: ['Say what happened without blaming the visitor and offer home, search or popular links.', 'Řekněte, co se stalo, bez obviňování návštěvníka, a nabídněte úvod, hledání nebo oblíbené odkazy.'] },
+  AC606: { cs: 'V konzoli nejsou chyby', why: ['Scripts failing on the error page often break its navigation too.', 'Skripty, které na chybové stránce padají, často rozbijí i její navigaci.'], fix: ['Fix the script error in the evidence.', 'Opravte chybu skriptu z důkazu.'] },
+  AC701: { cs: 'Každý ovládací prvek má přístupný popisek', why: ['VoiceOver and TalkBack read unlabeled controls as "button".', 'VoiceOver a TalkBack přečtou prvek bez popisku jen jako „tlačítko“.'], fix: ['Set contentDescription (Android) or accessibilityLabel (iOS) on icon controls.', 'Nastavte contentDescription (Android) nebo accessibilityLabel (iOS) u prvků s ikonou.'] },
+  AC702: { cs: 'Dotykové plochy aspoň 48 dp / 44 pt', why: ['Small targets are missed, especially by thumbs and older people.', 'Malé plochy se minou, hlavně palcem a u starších lidí.'], fix: ['Enlarge the touch area (padding or a minimum size), not necessarily the icon.', 'Zvětšete dotykovou plochu (odsazením nebo minimální velikostí), ne nutně ikonu.'] },
+  AC703: { cs: 'Žádné oříznuté texty (…)', why: ['Cut text hides prices, names or instructions, often only in longer languages.', 'Oříznutý text skryje ceny, jména nebo pokyny, často jen v delších jazycích.'], fix: ['Let the text wrap or give it room; check the longest language.', 'Nechte text zalomit nebo mu dejte místo; zkontrolujte nejdelší jazyk.'] },
+  AC704: { cs: 'Aplikace nespadla ani nezamrzla', why: ['A crash or an "app not responding" dialog ends the session.', 'Pád nebo hlášení „aplikace nereaguje“ ukončí práci.'], fix: ['Open the crash log for this step (adb logcat, Xcode) and fix the cause.', 'Otevřete záznam pádu u tohoto kroku (adb logcat, Xcode) a opravte příčinu.'] },
+  AC705: { cs: 'Účel obrazovky a další krok jsou jasné', why: ['On a small screen, people need to see at once what to do next.', 'Na malé obrazovce potřebují lidé hned vidět, co dál.'], fix: ['Give the screen a title and one prominent primary action.', 'Dejte obrazovce titulek a jednu výraznou hlavní akci.'] },
+  AC801: { cs: 'Vypadá jako reference designu (rozdíl pod 3 % pixelů)', why: ['Visible differences from the accepted design mean it was built differently than agreed.', 'Viditelné rozdíly od schváleného designu znamenají, že se postavilo jinak, než se domluvilo.'], fix: ['Open the pixel diff and adjust the implementation, not the reference.', 'Otevřete rozdíl v pixelech a upravte implementaci, ne referenci.'] },
+  AC802: { cs: 'Stejná struktura jako reference designu', why: ['Missing headings, actions or fields change what people can do, even if it looks close.', 'Chybějící nadpisy, akce nebo pole mění, co lidé mohou udělat, i když to vypadá podobně.'], fix: ['Add what the evidence lists as missing or remove what was added.', 'Doplňte, co důkaz uvádí jako chybějící, nebo odeberte, co přibylo.'] },
+  AC803: { cs: 'Barvy, písma, velikosti a mezery pocházejí z tokenů', why: ['Raw values drift from the design system and make later changes expensive.', 'Ruční hodnoty se odchylují od design systému a zdražují pozdější změny.'], fix: ['Replace each listed value with the suggested token (CSS variable).', 'Každou uvedenou hodnotu nahraďte navrženým tokenem (CSS proměnnou).'] },
+  AC501: { cs: 'Chyby v konzoli se netýkají toho, co krok přijímá', why: ['Separates real failures from third-party noise (analytics, extensions).', 'Odděluje skutečné chyby od šumu cizích skriptů (analytika, rozšíření).'], fix: ['If the AI says an error matters, fix that script; otherwise it is noise.', 'Pokud AI říká, že chyba vadí, opravte ten skript; jinak je to šum.'] }
+}
+
+/** Help for one pack criterion in a language: { name, why, fix }, or null. */
+export function packHelp (id, lang = 'en') {
+  const h = PACK_HELP[id]
+  if (!h) return null
+  const i = lang === 'cs' ? 1 : 0
+  return { name: lang === 'cs' ? h.cs : null, why: h.why[i], fix: h.fix[i] }
+}

package/src/lib/packs.mjs

@@ -0,0 +1,121 @@
+// Check packs: reusable sets of criteria a node turns on with `packs: [seo, usability]`.
+// Expanded before validation; pack criteria carry `pack` so coverage does not count them as drift.
+
+const det = (assert, extra = {}) => ({ type: 'deterministic', assert, ...extra })
+
+/** @type {Record<string, { base: number, title: string, criteria: (ctx: { locales: string[] }) => Array<{ id: string, text: string, check: object, highlight?: string }> }>} */
+export const PACKS = {
+  seo: {
+    base: 100,
+    title: 'SEO basics: title, description, canonical, hreflang, Open Graph, robots, heading, viewport',
+    criteria: ({ locales }) => [
+      { id: 'AC101', text: 'Exactly one H1', check: det('count', { selector: 'h1', min: 1, max: 1 }) },
+      { id: 'AC102', text: 'Title between 10 and 70 characters', check: det('title_matches', { pattern: '^.{10,70}$' }) },
+      { id: 'AC103', text: 'Meta description between 50 and 160 characters', check: det('meta_matches', { selector: "meta[name='description']", pattern: '^.{50,160}$' }) },
+      { id: 'AC104', text: 'Canonical link present', check: det('exists', { selector: "link[rel='canonical']" }) },
+      ...(locales.length > 1 ? [{ id: 'AC105', text: 'hreflang for every language', check: det('count', { selector: "link[rel='alternate'][hreflang]", min: locales.length }) }] : []),
+      { id: 'AC106', text: 'Open Graph title and description', check: det('count', { selector: "meta[property='og:title'], meta[property='og:description']", min: 2 }) },
+      { id: 'AC107', text: 'Not excluded from indexing', check: det('absent', { selector: "meta[name='robots'][content*='noindex']" }) },
+      { id: 'AC108', text: 'Viewport meta for phones', check: det('exists', { selector: "meta[name='viewport']" }) },
+      { id: 'AC109', text: 'html lang attribute set', check: det('exists', { selector: 'html[lang]' }) },
+      { id: 'AC110', text: 'No horizontal overflow', check: det('no_overflow') },
+      { id: 'AC111', text: 'No console errors', check: det('no_console_errors') }
+    ]
+  },
+  design: {
+    base: 800,
+    title: 'Design reference: pixels, structure and tokens, checked against the accepted design version (#42); combine with a11y for contrast',
+    criteria: () => [
+      { id: 'AC801', text: 'Looks like the design reference (under 3 % of pixels differ)', check: det('design_pixels', { ratio: 0.03 }) },
+      { id: 'AC802', text: 'Same structure as the design reference: headings, landmarks, actions and form fields', check: det('design_structure') },
+      { id: 'AC803', text: 'Colors, fonts, sizes, spacing and radii come from the token set', check: det('uses_tokens') }
+    ]
+  },
+  usability: {
+    base: 200,
+    title: 'Usability: purpose, primary action, forms, feedback',
+    criteria: () => [
+      { id: 'AC201', text: 'The purpose of the page is clear within the first screen', check: { type: 'semantic', question: 'Is the purpose of this page clear from its heading and first paragraph alone?', scope: 'main, body' } },
+      { id: 'AC202', text: 'One clear primary action', check: { type: 'semantic', question: 'Is there exactly one clearly primary call to action on the page?', scope: 'main, body' } },
+      { id: 'AC203', text: 'Form fields have visible labels', check: det('count', { selector: 'input:not([type=hidden]):not([type=submit]):not([aria-label]):not([id])', min: 0, max: 0 }) },
+      { id: 'AC204', text: 'Links and buttons say what they do', check: { type: 'semantic', question: 'Do the link and button texts describe what happens when they are used, rather than generic words like "click here"?', scope: 'main, body' } }
+    ]
+  },
+  a11y: {
+    base: 300,
+    title: 'Accessibility basics (WCAG 2.2 AA subset): alt texts, names, labels, headings, contrast, landmarks, unique ids',
+    criteria: () => [
+      { id: 'AC301', text: 'Images have alternative text', check: det('a11y_images_alt') },
+      { id: 'AC302', text: 'Links and buttons have an accessible name', check: det('a11y_names') },
+      { id: 'AC303', text: 'Form fields have labels', check: det('a11y_labels') },
+      { id: 'AC304', text: 'Heading levels are not skipped', check: det('a11y_headings') },
+      { id: 'AC305', text: 'Text meets WCAG AA contrast', check: det('a11y_contrast') },
+      { id: 'AC306', text: 'The page has a main landmark', check: det('a11y_main') },
+      { id: 'AC307', text: 'Element ids are unique', check: det('a11y_unique_ids') }
+    ]
+  },
+  perf: {
+    base: 400,
+    title: 'Performance from the capture: LCP, CLS, TTFB, page weight (lab values of this walk, not field data)',
+    criteria: () => [
+      { id: 'AC401', text: 'Largest contentful paint within 2.5 s', check: det('perf_lcp', { max: 2500 }) },
+      { id: 'AC402', text: 'Cumulative layout shift below 0.1', check: det('perf_cls', { max: 0.1 }) },
+      { id: 'AC403', text: 'Time to first byte within 800 ms', check: det('perf_ttfb', { max: 800 }) },
+      { id: 'AC404', text: 'Page weight within 3 MB', check: det('perf_weight', { max: 3000 }) }
+    ]
+  },
+  errors: {
+    base: 600,
+    title: 'Error pages (404, 410, 500, maintenance): a real error status, a way forward, no technical leak',
+    criteria: () => [
+      { id: 'AC601', text: 'Answers with an error status (4xx/5xx), not a soft 200', check: det('http_status', { min: 400, max: 599 }) },
+      { id: 'AC602', text: 'Links back to the home page', check: det('link_home') },
+      { id: 'AC603', text: 'Navigation or search stays available', check: det('exists', { selector: "nav a, header a, [role=navigation] a, input[type=search], [role=search]" }) },
+      { id: 'AC604', text: 'No stack trace, SQL error or framework debug page', check: det('text_absent', { pattern: 'Traceback \\(most recent call last\\)|\\bat [\\w.$<>]+ \\([^)]*:\\d+:\\d+\\)|SQLSTATE|Fatal error:|Stack trace:|Whoops, looks like|NoMethodError|ActiveRecord::|RuntimeError at|Exception Value:|Warning: .+ on line \\d+' }) },
+      { id: 'AC605', text: 'Explains the error in plain language and offers a way forward', check: { type: 'semantic', question: 'Does the page tell the visitor in plain language that the page was not found or is unavailable, without blaming them, and offer a way forward such as the home page, search, popular links or contact?', scope: 'main, body' } },
+      { id: 'AC606', text: 'No console errors', check: det('no_console_errors') }
+    ]
+  },
+  app: {
+    base: 700,
+    title: 'Native app screens (Android, iOS, desktop): labelled controls, touch targets, no truncated text, no crash, clear purpose',
+    criteria: () => [
+      { id: 'AC701', text: 'Every control has an accessible label', check: det('app_labels') },
+      { id: 'AC702', text: 'Touch targets at least 48 dp (Android) / 44 pt (iOS)', check: det('app_touch_targets') },
+      { id: 'AC703', text: 'No truncated texts (…)', check: det('app_no_truncation') },
+      { id: 'AC704', text: 'The app did not crash or stop responding', check: det('app_no_crash') },
+      { id: 'AC705', text: 'The purpose of the screen and the next action are clear', check: { type: 'semantic', question: 'Is it clear from this app screen what it is for and what the user should do next, with one obvious primary action?' } }
+    ]
+  },
+  console: {
+    base: 500,
+    title: 'Console errors triaged by the evaluator: relevant to what the step accepts, or unrelated noise',
+    criteria: () => [
+      { id: 'AC501', text: 'Console errors do not touch what the step accepts', check: { type: 'semantic', about: 'console', question: 'Are all of these console errors unrelated to what this step accepts (for example third-party scripts, analytics, browser extensions, CSP reports or favicon requests), so that none of them affects the tested function?' } }
+    ]
+  }
+}
+
+/**
+ * Adds the criteria of each pack listed on a node (`node.packs`) that the node does not already define.
+ * Mutates and returns the scenario; safe to call twice.
+ */
+export function expandPacks (scenario) {
+  if (!scenario || !Array.isArray(scenario.nodes)) return scenario
+  const locales = scenario.locales || ['en']
+  for (const node of scenario.nodes) {
+    if (!Array.isArray(node.packs) || !node.packs.length) continue
+    node.criteria ||= []
+    const have = new Set(node.criteria.map((c) => c.id))
+    for (const name of node.packs) {
+      const pack = PACKS[name]
+      if (!pack) throw new Error(`node "${node.id}": unknown pack "${name}" (known: ${Object.keys(PACKS).join(', ')})`)
+      for (const c of pack.criteria({ locales })) {
+        if (have.has(c.id)) continue
+        node.criteria.push({ ...c, pack: name })
+        have.add(c.id)
+      }
+    }
+  }
+  return scenario
+}

package/src/lib/pr.mjs

@@ -0,0 +1,78 @@
+// `kaloko share --pr`: one comment per scenario on the branch's pull request, updated on later runs.
+// Uses the gh CLI only; never throws — a missing gh or PR is reported and the share stays valid.
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
+
+const exec = promisify(execFile)
+const RANK = { fail: 4, needs_review: 3, not_evaluated: 2, pass: 1, not_reached: 0 }
+const worst = (list) => list.reduce((a, b) => (RANK[b] > RANK[a] ? b : a), 'not_reached')
+const text = (v) => v == null ? '' : typeof v === 'string' ? v : (v.en ?? v.default ?? Object.values(v)[0] ?? '')
+
+export const marker = (scenarioId) => `<!-- qawalk:${scenarioId} -->`
+
+/** Markdown body: canvas link, summary line, verdict, what needs attention with evidence. */
+export function prCommentBody ({ manifest, url, at = new Date() }) {
+  const s = manifest.summary || {}
+  const steps = (manifest.nodes || []).filter((n) => n.kind !== 'decision')
+  const all = steps.flatMap((n) => n.criteria || [])
+  const okCrit = all.filter((c) => c.verdict === 'pass').length
+  const attention = []
+  for (const n of steps) {
+    for (const c of n.criteria || []) {
+      if (c.counts) { // stack step: verdicts per page, counted
+        const bad = Object.entries(c.counts).filter(([v]) => !['pass', 'not_reached', 'not_evaluated'].includes(v)).reduce((k, [, x]) => k + x, 0)
+        if (bad) attention.push(`- ${c.verdict === 'fail' ? '✕' : '!'} **${text(n.title)}** · \`${c.id}\` ${c.text} — _${String(c.verdict).replace('_', ' ')}_ (${bad}/${n.stack?.count ?? '?'} pages; the index on the canvas lists them)`)
+        continue
+      }
+      const cells = Object.entries(c.by_locale || {}).flatMap(([l, vps]) => Object.entries(vps).map(([vp, r]) => ({ l, vp, r })))
+      const bad = cells.filter(({ r }) => r?.verdict && !['pass', 'not_reached'].includes(r.verdict))
+      if (!bad.length) continue
+      const v = worst(bad.map(({ r }) => r.verdict))
+      const where = [...new Set(bad.map(({ l, vp }) => `${l}/${vp}`))].join(', ')
+      const ev = bad.find(({ r }) => r.evidence || r.note)?.r
+      attention.push(`- ${v === 'fail' ? '✕' : '!'} **${text(n.title)}** · \`${c.id}\` ${c.text} — _${v.replace('_', ' ')}_ (${where})${ev ? `\n  \`${String(ev.evidence || ev.note).replace(/\s+/g, ' ').slice(0, 160)}\`` : ''}`)
+    }
+  }
+  const total = steps.length
+  const env = manifest.environment?.name || ''
+  const g = manifest.git || {}
+  const lines = [
+    marker(manifest.scenario.id),
+    `### Kaloko · ${text(manifest.scenario.title)}`,
+    `**${s.pass || 0}/${total} steps passed** · ${okCrit}/${all.length} criteria · ${env}${g.commit ? ` · \`${g.commit}\`` : ''} · [open the canvas](${url})`,
+    '',
+    attention.length ? `**Needs attention (${attention.length})**\n${attention.join('\n')}` : 'All checked criteria passed.',
+    '',
+    `<sub>Run \`${manifest.id}\` · ${at.toISOString().slice(0, 16).replace('T', ' ')} UTC · reviewers accept or return the run on the canvas; \`kaloko feedback\` shows their notes. Updated on every shared run of this scenario.</sub>`
+  ]
+  return lines.join('\n')
+}
+
+/**
+ * Creates or updates the scenario's comment on the current branch's PR.
+ * @returns {{ ok: boolean, action?: 'created'|'updated', url?: string, reason?: string }}
+ */
+export async function upsertPrComment ({ manifest, url, cwd, run = defaultRun }) {
+  const view = await run('gh', ['pr', 'view', '--json', 'number,url,headRepository,headRepositoryOwner'], cwd)
+  if (view == null) return { ok: false, reason: 'gh is not installed, not signed in, or this branch has no pull request' }
+  let pr
+  try { pr = JSON.parse(view) } catch { return { ok: false, reason: 'gh pr view returned no JSON' } }
+  if (!pr.number) return { ok: false, reason: 'this branch has no pull request' }
+  const repo = pr.headRepositoryOwner?.login && pr.headRepository?.name ? `${pr.headRepositoryOwner.login}/${pr.headRepository.name}` : null
+  const body = prCommentBody({ manifest, url })
+  const m = marker(manifest.scenario.id)
+  // find our earlier comment for this scenario
+  const listArgs = ['api', '--paginate', `repos/${repo || '{owner}/{repo}'}/issues/${pr.number}/comments`, '--jq', `.[] | select(.body | contains(${JSON.stringify(m)})) | .id`]
+  const found = (await run('gh', listArgs, cwd)) || ''
+  const existing = found.split(/\s+/).map((x) => x.trim()).filter(Boolean)[0]
+  if (existing) {
+    const r = await run('gh', ['api', '-X', 'PATCH', `repos/${repo || '{owner}/{repo}'}/issues/comments/${existing}`, '-f', `body=${body}`], cwd)
+    return r == null ? { ok: false, reason: 'could not update the existing comment' } : { ok: true, action: 'updated', url: `${pr.url}#issuecomment-${existing}` }
+  }
+  const r = await run('gh', ['pr', 'comment', String(pr.number), '--body', body], cwd)
+  return r == null ? { ok: false, reason: 'could not create the comment' } : { ok: true, action: 'created', url: r.trim() || pr.url }
+}
+
+async function defaultRun (cmd, args, cwd) {
+  try { const { stdout } = await exec(cmd, args, { cwd, timeout: 30000, maxBuffer: 4 * 1024 * 1024 }); return stdout } catch { return null }
+}