kaloko 0.4.9 → 0.4.10

package/src/lib/ci.mjs

@@ -0,0 +1,207 @@
+// Packaged CI (#15): `kaloko ci github|gitlab` writes a workflow into the customer's repository that walks the
+// affected scenarios on the pull request's preview deployment and comments on the PR; `kaloko ci preview-url` finds
+// that deployment at run time (Vercel, Netlify, Cloudflare Pages and anything that reports GitHub deployments).
+import { readFile, appendFile } from 'node:fs/promises'
+
+const clean = (u) => (u ? (/^https?:\/\//.test(u) ? u : `https://${u}`).replace(/\/$/, '') : null)
+
+/** Preview URL from variables CI and hosting providers set; { url, source } or null. */
+export function previewFromEnv (vars = process.env, event = null) {
+  if (vars.KALOKO_PREVIEW_URL) return { url: clean(vars.KALOKO_PREVIEW_URL), source: 'KALOKO_PREVIEW_URL' }
+  const ds = event?.deployment_status
+  if (ds && ds.state === 'success' && (ds.environment_url || ds.target_url)) return { url: clean(ds.environment_url || ds.target_url), source: `deployment_status (${ds.environment || event.deployment?.environment || 'deployment'})` }
+  for (const [name, label] of [['VERCEL_BRANCH_URL', 'Vercel'], ['VERCEL_URL', 'Vercel'], ['DEPLOY_PRIME_URL', 'Netlify'], ['DEPLOY_URL', 'Netlify'], ['CF_PAGES_URL', 'Cloudflare Pages'], ['CI_ENVIRONMENT_URL', 'GitLab environment'], ['RENDER_EXTERNAL_URL', 'Render'], ['RAILWAY_PUBLIC_DOMAIN', 'Railway']]) {
+    if (vars[name]) return { url: clean(vars[name]), source: `${name} (${label})` }
+  }
+  return null
+}
+
+async function readEvent (vars) {
+  if (!vars.GITHUB_EVENT_PATH) return null
+  try { return JSON.parse(await readFile(vars.GITHUB_EVENT_PATH, 'utf8')) } catch { return null }
+}
+
+function github (vars, fetchImpl) {
+  const api = (vars.GITHUB_API_URL || 'https://api.github.com').replace(/\/$/, '')
+  const token = vars.GITHUB_TOKEN || vars.GH_TOKEN
+  return async (path) => {
+    const res = await fetchImpl(`${api}${path}`, { headers: { Accept: 'application/vnd.github+json', 'X-GitHub-Api-Version': '2022-11-28', ...(token ? { Authorization: `Bearer ${token}` } : {}) } })
+    if (!res.ok) throw new Error(`GitHub ${path} → HTTP ${res.status}`)
+    return res.json()
+  }
+}
+
+/** The pull request a CI run belongs to: { number, base, head, sha } from the event or, for a deployment, its commit. */
+export async function pullRequestOf ({ vars = process.env, event = undefined, fetchImpl = fetch } = {}) {
+  event = event === undefined ? await readEvent(vars) : event
+  if (vars.KALOKO_PR) return { number: Number(vars.KALOKO_PR), base: vars.KALOKO_BASE?.replace(/^origin\//, '') || null, sha: vars.GITHUB_SHA || null }
+  if (event?.pull_request) return { number: event.pull_request.number, base: event.pull_request.base?.ref || null, head: event.pull_request.head?.ref || null, sha: event.pull_request.head?.sha || null }
+  if (vars.CI_MERGE_REQUEST_IID) return { number: Number(vars.CI_MERGE_REQUEST_IID), base: vars.CI_MERGE_REQUEST_TARGET_BRANCH_NAME || null, head: vars.CI_MERGE_REQUEST_SOURCE_BRANCH_NAME || null, sha: vars.CI_COMMIT_SHA || null }
+  const sha = event?.deployment?.sha || vars.GITHUB_SHA
+  if (sha && vars.GITHUB_REPOSITORY) {
+    try {
+      const pulls = await github(vars, fetchImpl)(`/repos/${vars.GITHUB_REPOSITORY}/commits/${sha}/pulls`)
+      const pr = pulls.find((p) => p.state === 'open') || pulls[0]
+      if (pr) return { number: pr.number, base: pr.base?.ref || null, head: pr.head?.ref || null, sha }
+    } catch {}
+  }
+  return null
+}
+
+/**
+ * The preview deployment of this commit: variables first, then GitHub deployments of the commit (Vercel, Netlify and
+ * Cloudflare Pages report theirs there), polled until one succeeds or `wait` seconds pass. Production is skipped.
+ */
+export async function findPreview ({ vars = process.env, fetchImpl = fetch, wait = 0, sleep = (ms) => new Promise((r) => setTimeout(r, ms)), say = () => {} } = {}) {
+  const event = await readEvent(vars)
+  const direct = previewFromEnv(vars, event)
+  if (direct) return direct
+  const sha = event?.pull_request?.head?.sha || event?.deployment?.sha || vars.GITHUB_SHA
+  if (!sha || !vars.GITHUB_REPOSITORY) return null
+  const gh = github(vars, fetchImpl)
+  const until = Date.now() + wait * 1000
+  for (let round = 0; ; round++) {
+    try {
+      const deployments = await gh(`/repos/${vars.GITHUB_REPOSITORY}/deployments?sha=${sha}&per_page=30`)
+      for (const d of deployments.filter((x) => !/^prod/i.test(x.environment || '') && !x.production_environment)) {
+        const statuses = await gh(`/repos/${vars.GITHUB_REPOSITORY}/deployments/${d.id}/statuses?per_page=10`)
+        const ok = statuses.find((s) => s.state === 'success' && (s.environment_url || s.target_url))
+        if (ok) return { url: clean(ok.environment_url || ok.target_url), source: `GitHub deployment ${d.environment}` }
+      }
+    } catch (e) { if (round === 0) say(`  (GitHub deployments not readable: ${e.message})`) }
+    if (Date.now() >= until) return null
+    if (round === 0) say(`Waiting up to ${wait} s for a preview deployment of ${sha.slice(0, 7)}…`)
+    await sleep(10000)
+  }
+}
+
+/** Lines for $GITHUB_ENV (or a dotenv file): the preview URL, the PR and its base for --affected and share --pr. */
+export function envLines ({ preview, pr }) {
+  return [
+    preview && `KALOKO_PREVIEW_URL=${preview.url}`,
+    pr?.number && `KALOKO_PR=${pr.number}`,
+    pr?.base && `KALOKO_BASE=origin/${pr.base}`,
+    pr?.head && `KALOKO_BRANCH=${pr.head}`
+  ].filter(Boolean)
+}
+
+export const writeEnvFile = (file, lines) => appendFile(file, lines.map((l) => l + '\n').join(''))
+
+const q = (s) => /^[A-Za-z0-9_./-]+$/.test(s) ? s : JSON.stringify(s)
+
+/** How the workflow runs kaloko: through the project's package manager when kaloko is a dependency, else npx. */
+export function runner ({ pm = 'npm', dependency = true, version = 'latest' }) {
+  if (!dependency) return { install: null, kaloko: `npx --yes kaloko@${version}` }
+  return {
+    install: { npm: 'npm ci', pnpm: 'pnpm install --frozen-lockfile', yarn: 'yarn install --frozen-lockfile', bun: 'bun install --frozen-lockfile' }[pm] || 'npm ci',
+    kaloko: { npm: 'npx kaloko', pnpm: 'pnpm exec kaloko', yarn: 'yarn kaloko', bun: 'bunx kaloko' }[pm] || 'npx kaloko'
+  }
+}
+
+/** The loop over scenarios both workflows run: walk what the change reaches, share, comment on the PR. */
+function walkScript ({ scenarios, env, affected, k }) {
+  return [
+    'status=0',
+    `for s in ${scenarios.map(q).join(' ')}; do`,
+    ...(affected ? [`  if ! ${k} affected --scenario "$s" --check; then echo "Nothing in $s is affected; skipped."; continue; fi`] : []),
+    `  ${k} start --scenario "$s" --env ${env}`,
+    `  ${k} walk --ephemeral${affected ? ' --affected' : ''} || status=1`,
+    `  ${k} share --pr || status=1`,
+    'done',
+    'exit $status'
+  ]
+}
+
+/** .github/workflows/kaloko.yml */
+export function githubWorkflow ({ scenarios, env = 'preview', trigger = 'deployment', affected = true, pm = 'npm', dependency = true, version = 'latest', node = 22 }) {
+  const { install, kaloko: k } = runner({ pm, dependency, version })
+  const indent = (lines, n) => lines.map((l) => ' '.repeat(n) + l).join('\n')
+  const on = trigger === 'deployment'
+    ? '  # Vercel, Netlify and Cloudflare Pages report each preview as a GitHub deployment\n  deployment_status:\n  workflow_dispatch:'
+    : '  pull_request:\n  workflow_dispatch:'
+  const guard = trigger === 'deployment'
+    ? "    if: github.event_name != 'deployment_status' || (github.event.deployment_status.state == 'success' && !startsWith(github.event.deployment_status.environment, 'Production') && !startsWith(github.event.deployment_status.environment, 'production'))\n"
+    : ''
+  return `# Kaloko: walk the scenarios this pull request affects on its preview deployment and comment on the PR.
+# Written by kaloko ci github. Secrets: KALOKO_TOKEN (tester role, upload scope; on Enterprise a service account's);
+# TYPESAFE_API_KEY only if semantic criteria should use your own evaluator key.
+name: Kaloko
+on:
+${on}
+concurrency:
+  group: kaloko-\${{ github.event.deployment.sha || github.event.pull_request.head.sha || github.sha }}
+  cancel-in-progress: true
+permissions:
+  contents: read
+  deployments: read
+  pull-requests: write
+jobs:
+  walk:
+${guard}    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    env:
+      KALOKO_TOKEN: \${{ secrets.KALOKO_TOKEN }}
+      TYPESAFE_API_KEY: \${{ secrets.TYPESAFE_API_KEY }}
+      GH_TOKEN: \${{ github.token }}
+      KALOKO_AGENT: github-actions
+      KALOKO_BROWSER_CHANNEL: chromium
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: \${{ github.event.deployment.sha || github.event.pull_request.head.sha || github.sha }}
+          fetch-depth: 0   # walk --affected compares with the pull request's base
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${node}
+${install ? `${['pnpm', 'yarn'].includes(pm) ? '      - run: corepack enable\n' : ''}      - run: ${install}\n` : ''}      - run: ${k} browser install --with-deps   # the Chromium of kaloko's own Playwright
+      - name: Preview deployment
+        # the deployment's URL, the pull request and its base; waits for the preview when it is still building
+        run: ${k} ci preview-url --wait 600 --github-env
+      - name: Walk, share, comment
+        run: |
+${indent(walkScript({ scenarios, env, affected, k }), 10)}
+`
+}
+
+/** kaloko.gitlab-ci.yml, included from .gitlab-ci.yml */
+export function gitlabJob ({ scenarios, env = 'preview', affected = true, pm = 'npm', dependency = true, version = 'latest', playwright = '1.55.0' }) {
+  const { install, kaloko: k } = runner({ pm, dependency, version })
+  const indent = (lines, n) => lines.map((l) => ' '.repeat(n) + l).join('\n')
+  return `# Kaloko: walk the scenarios a merge request affects on its review app and comment on the MR.
+# Written by kaloko ci gitlab. Include it from .gitlab-ci.yml:  include: { local: kaloko.gitlab-ci.yml }
+# CI/CD variables (masked): KALOKO_TOKEN (tester role, upload scope); KALOKO_GITLAB_TOKEN (project access
+# token with the api scope) for the MR comment; TYPESAFE_API_KEY optional.
+kaloko:
+  stage: test        # run it after the job that deploys the review app (needs: [deploy_review])
+  image: mcr.microsoft.com/playwright:v${playwright}-noble
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+  variables:
+    GIT_DEPTH: "0"   # walk --affected compares with the target branch
+    KALOKO_BROWSER_CHANNEL: chromium
+    KALOKO_AGENT: gitlab-ci
+    # KALOKO_PREVIEW_URL: https://$CI_COMMIT_REF_SLUG.review.example.com   # when the review app URL is known
+  script:
+${install ? `${['pnpm', 'yarn'].includes(pm) ? '    - corepack enable\n' : ''}    - ${install}\n` : ''}    - ${k} browser install
+    - export KALOKO_PREVIEW_URL="$(${k} ci preview-url --wait 600)"
+    - git fetch origin "$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"
+    - |
+${indent(walkScript({ scenarios, env, affected, k }), 6)}
+`
+}
+
+/** Adds the preview environment to kaloko.config.yml text (block style); null when it cannot be placed safely. */
+export function addPreviewEnvironment (text, name = 'preview') {
+  if (new RegExp(`^  ${name}:`, 'm').test(text)) return text
+  const m = text.match(/^environments:\s*$/m)
+  if (!m) return null
+  const block = [
+    `  ${name}:                                    # pull request previews (kaloko ci): the URL comes from CI`,
+    '    base_url: ${KALOKO_PREVIEW_URL}',
+    '    # access:                                 # Vercel deployment protection: a bypass for automation',
+    '    #   headers:',
+    '    #     x-vercel-protection-bypass: { env: VERCEL_AUTOMATION_BYPASS_SECRET }'
+  ].join('\n')
+  const at = m.index + m[0].length
+  return text.slice(0, at) + '\n' + block + text.slice(at)
+}

package/src/lib/config.mjs

@@ -48,6 +48,8 @@ export async function loadConfig (start = process.cwd(), explicit) {
   config.output ||= !(await exists(join(dirname(file), 'tmp', 'kaloko'))) && (await exists(join(dirname(file), 'tmp', 'qawalk'))) ? 'tmp/qawalk' : 'tmp/kaloko'
   config.browser ||= {}
   config.browser.port ||= 9333
+  // CI runs the bundled Chromium without a separate config: KALOKO_BROWSER_CHANNEL=chromium (or chrome, msedge)
+  if (process.env.KALOKO_BROWSER_CHANNEL != null) config.browser.channel = ['', 'chromium', 'bundled'].includes(process.env.KALOKO_BROWSER_CHANNEL) ? undefined : process.env.KALOKO_BROWSER_CHANNEL
   return { config, root: dirname(file), file }
 }
 

package/src/lib/evaluate.mjs

@@ -101,8 +101,10 @@ export async function evaluateRun ({ run, scenario, config, root, fetchImpl }) {
       const semantic = outOfSample ? [] : (node.criteria || []).filter((c) => c.check.type === 'semantic' && !(c.check.about === 'console' && !(capture.console_errors || []).length))
       // quick signals ride along on every captured page state (also steps without semantic criteria)
       const signals = settings.signals !== false && !outOfSample && !!capture.state
-      const request = (semantic.length || signals) && current ? buildRequest({ node, capture, criteria: semantic, model: settings.model, signals }) : null
-      work.push({ entry, node, capture, current, outOfSample, request, asks: semantic.length > 0, jev: current ? null : { skipped: 'Capture has no matching criteria fingerprint; capture this step again.' } })
+      // an imported screen without page text (#11) has nothing to ask about: a person decides on the canvas
+      const textless = capture.capture?.source === 'import' && !capture.state
+      const request = (semantic.length || signals) && current && !textless ? buildRequest({ node, capture, criteria: semantic, model: settings.model, signals }) : null
+      work.push({ entry, node, capture, current, outOfSample, request, asks: semantic.length > 0, jev: !current ? { skipped: 'Capture has no matching criteria fingerprint; capture this step again.' } : textless && semantic.length ? { skipped: 'imported screenshot without page text; a person decides on the canvas' } : null })
       if (!current) report.outdated.add(entry.node)
     }
 

package/src/lib/git.mjs

@@ -59,12 +59,16 @@ export async function gitMeta (cwd) {
     out('git', ['rev-parse', 'HEAD'], cwd)
   ])
   let pr = null
-  const json = await out('gh', ['pr', 'view', '--json', 'number,url,state'], cwd)
+  const vars = process.env
+  // CI checks out a detached commit: the branch and pull request come from the environment
+  const ciBranch = vars.KALOKO_BRANCH || vars.GITHUB_HEAD_REF || vars.CI_MERGE_REQUEST_SOURCE_BRANCH_NAME || vars.CI_COMMIT_REF_NAME || null
+  if (vars.GITLAB_CI && vars.CI_MERGE_REQUEST_IID) pr = { number: Number(vars.CI_MERGE_REQUEST_IID), url: `${vars.CI_MERGE_REQUEST_PROJECT_URL || vars.CI_PROJECT_URL}/-/merge_requests/${vars.CI_MERGE_REQUEST_IID}`, state: 'open' }
+  const json = pr ? null : await out('gh', ['pr', 'view', ...(vars.KALOKO_PR ? [String(vars.KALOKO_PR)] : []), '--json', 'number,url,state'], cwd)
   if (json) {
     try {
       const p = JSON.parse(json)
       pr = { number: p.number, url: p.url, state: String(p.state).toLowerCase() }
     } catch {}
   }
-  return { branch, commit, sha, message, author, pr }
+  return { branch: branch === 'HEAD' && ciBranch ? ciBranch : branch, commit, sha, message, author, pr }
 }

package/src/lib/heal.mjs

@@ -0,0 +1,207 @@
+// Self-healing selectors (#13): when a step script waits in vain for a selector, propose a replacement from the page
+// as it is now (role and accessible name, test ids, text), preferring the element the old selector matched in the
+// step's previous capture. The proposal is printed as a patch; `walk --heal` applies it to the script only after the
+// step passed with it. Nothing is ever changed silently.
+import { readFile, writeFile, rm, readdir } from 'node:fs/promises'
+import { join, dirname, basename, relative, resolve } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { readJson } from './util.mjs'
+
+/** The selector a Playwright timeout waited for, or null (only plain locator strings can be patched). */
+export function failedSelector (message) {
+  const text = String(message || '')
+  if (!/Timeout \d+ms exceeded|waiting for/i.test(text) || /strict mode violation/i.test(text)) return null
+  const unq = (s, q) => s.replace(new RegExp(`\\\\${q}`, 'g'), q)
+  let m = text.match(/waiting for locator\('((?:\\'|[^'])+)'\)/)
+  if (m) return unq(m[1], "'")
+  m = text.match(/waiting for locator\("((?:\\"|[^"])+)"\)/)
+  if (m) return unq(m[1], '"')
+  m = text.match(/waiting for selector "((?:\\"|[^"])+)"/)
+  if (m) return unq(m[1], '"')
+  return null
+}
+
+/** Words a selector is made of: ids, classes, attribute values and text, split on punctuation and camelCase. */
+export function tokensOf (selector) {
+  return [...new Set(String(selector)
+    .replace(/([a-z])([A-Z])/g, '$1 $2')
+    .toLowerCase()
+    .split(/[^a-z0-9áčďéěíňóřšťúůýž]+/i)
+    .filter((w) => w.length > 1 && !['text', 'has', 'nth', 'first', 'last', 'visible', 'true', 'role', 'name', 'internal', 'data', 'testid', 'test', 'id', 'qa', 'cy', 'div', 'span'].includes(w)))]
+}
+
+/**
+ * In the page (self-contained, passed to evaluate): interactive and labelled elements with role, accessible name,
+ * test id, id and classes; given an element, that element only.
+ */
+function describeAll (limit) {
+  const TEST = ['data-testid', 'data-test', 'data-qa', 'data-cy', 'data-test-id']
+  const roleOf = (el) => {
+    const r = el.getAttribute('role'); if (r) return r
+    const t = el.tagName.toLowerCase()
+    if (t === 'a' && el.hasAttribute('href')) return 'link'
+    if (t === 'button' || (t === 'input' && ['button', 'submit', 'reset'].includes(el.type))) return 'button'
+    if (t === 'input') return { checkbox: 'checkbox', radio: 'radio', range: 'slider', search: 'searchbox' }[el.type] || 'textbox'
+    if (t === 'textarea') return 'textbox'
+    if (t === 'select') return 'combobox'
+    if (/^h[1-6]$/.test(t)) return 'heading'
+    if (t === 'img') return 'img'
+    return null
+  }
+  const text = (s) => String(s || '').replace(/\s+/g, ' ').trim()
+  const nameOf = (el) => {
+    const l = el.getAttribute('aria-label'); if (l) return text(l)
+    const by = el.getAttribute('aria-labelledby'); if (by) { const t = by.split(/\s+/).map((id) => document.getElementById(id)?.textContent || '').join(' '); if (text(t)) return text(t) }
+    if (el.id) { const lab = document.querySelector(`label[for="${CSS.escape(el.id)}"]`); if (lab) return text(lab.textContent) }
+    const wrap = el.closest('label'); if (wrap && wrap !== el && /^(input|select|textarea)$/i.test(el.tagName)) return text(wrap.textContent)
+    if (/^(input|textarea)$/i.test(el.tagName)) return text(el.getAttribute('placeholder') || el.getAttribute('title') || (['button', 'submit'].includes(el.type) ? el.value : ''))
+    if (el.tagName === 'IMG') return text(el.getAttribute('alt'))
+    return text(el.innerText || el.textContent).slice(0, 80)
+  }
+  const describe = (el) => {
+    const testid = TEST.map((a) => el.getAttribute(a) ? [a, el.getAttribute(a)] : null).find(Boolean) || null
+    const r = el.getBoundingClientRect(); const cs = getComputedStyle(el)
+    return { tag: el.tagName.toLowerCase(), role: roleOf(el), name: nameOf(el), testid, id: el.id || null, classes: [...el.classList].slice(0, 8), visible: r.width > 0 && r.height > 0 && cs.visibility !== 'hidden' && cs.display !== 'none' }
+  }
+  if (typeof limit === 'object' && limit?.nodeType === 1) return describe(limit)
+  const sel = 'a[href], button, input, select, textarea, summary, [role], [aria-label], [data-testid], [data-test], [data-qa], [data-cy], [data-test-id], h1, h2, h3, label'
+  return [...document.querySelectorAll(sel)].slice(0, limit).map(describe).filter((d) => d.visible && (d.name || d.testid || d.id))
+}
+
+/** The element the old selector matched in the previous capture of this step (its HTML), described; null if none. */
+async function previousFingerprint ({ page, selector, root, output, run, node, locale }) {
+  const base = resolve(root, output)
+  let names = []
+  try { names = (await readdir(base, { withFileTypes: true })).filter((e) => e.isDirectory() && e.name !== run.meta.id && !e.name.startsWith('.')).map((e) => e.name).sort().reverse() } catch { return null }
+  for (const name of names.slice(0, 20)) {
+    const meta = await readJson(join(base, name, 'meta.json'), null)
+    if (meta?.scenario?.id !== run.meta.scenario.id) continue
+    let html = null
+    for (const vp of Object.keys(run.meta.scope.viewports || {})) { html = await readFile(join(base, name, 'steps', node.id, locale, `${vp}.html`), 'utf8').catch(() => null); if (html) break }
+    if (!html) continue
+    let scratch = null
+    try {
+      const browser = page.context().browser()
+      scratch = browser ? await browser.newContext({ javaScriptEnabled: false }) : null
+      if (!scratch) return null
+      const p = await scratch.newPage()
+      await p.route('**/*', (r) => r.abort())
+      await p.setContent(html.replace(/<script[\s\S]*?<\/script>/gi, ''), { waitUntil: 'domcontentloaded', timeout: 5000 })
+      const el = p.locator(selector).first()
+      if (!(await el.count().catch(() => 0))) continue
+      const fp = await el.evaluate(describeAll)
+      return { ...fp, run: name }
+    } catch { continue } finally { await scratch?.close().catch(() => {}) }
+  }
+  return null
+}
+
+const q = (s) => JSON.stringify(String(s))
+
+/** Scores a candidate against the fingerprint of the old element and the words of the old selector. */
+export function score (c, { fp, tokens }) {
+  let s = 0; const why = []
+  if (fp) {
+    if (fp.testid && c.testid && fp.testid[1] === c.testid[1]) { s += 6; why.push(`same ${c.testid[0]} "${c.testid[1]}"`) }
+    if (fp.name && c.name && fp.name.toLowerCase() === c.name.toLowerCase()) { s += 4; why.push(`same name "${c.name}"`) }
+    if (fp.role && fp.role === c.role) { s += 2; why.push(`role ${c.role}`) }
+    if (fp.tag === c.tag) s += 1
+    if (fp.id && fp.id === c.id) { s += 3; why.push(`same id ${c.id}`) }
+    const shared = (fp.classes || []).filter((k) => c.classes.includes(k)).length
+    s += Math.min(2, shared)
+  }
+  const hay = [c.id, ...(c.classes || []), c.testid?.[1], c.name, c.role, c.tag].filter(Boolean).join(' ').toLowerCase()
+  const words = tokens.filter((t) => hay.includes(t))
+  if (words.length) { s += words.length * 1.5; why.push(`words ${words.map((w) => `"${w}"`).join(', ')} of the old selector`) }
+  return { score: s, why }
+}
+
+/** Selectors for an element, most stable first: test id, role + name, id, text. */
+export function selectorsFor (c) {
+  const out = []
+  if (c.testid) out.push(`[${c.testid[0]}=${q(c.testid[1])}]`)
+  if (c.role && c.name) out.push(`role=${c.role}[name=${q(c.name)}]`)
+  if (c.id && !/\d{3,}|^[a-f0-9-]{16,}$|^(radix|headlessui|mui|react-aria|:r)/i.test(c.id)) out.push(`#${c.id}`)
+  if (c.name && c.name.length <= 60) out.push(`text=${q(c.name)}`)
+  return out
+}
+
+/**
+ * A replacement for `selector` on the page as it is now: { replacement, why, from } or null.
+ * The replacement matches exactly one element.
+ */
+export async function proposeSelector ({ page, selector, root, output, run, node, locale }) {
+  const fp = await previousFingerprint({ page, selector, root, output, run, node, locale }).catch(() => null)
+  const tokens = tokensOf(selector)
+  let candidates
+  try { candidates = await page.evaluate(describeAll, 1500) } catch { return null }
+  const ranked = candidates.map((c) => ({ c, ...score(c, { fp, tokens }) })).filter((x) => x.score >= (fp ? 4 : 3)).sort((a, b) => b.score - a.score)
+  for (const { c, why } of ranked.slice(0, 8)) {
+    for (const sel of selectorsFor(c)) {
+      if (sel === selector) continue
+      const n = await page.locator(sel).count().catch(() => 0)
+      if (n === 1) return { replacement: sel, why: why.join(', ') || 'closest element', from: fp?.run || null, element: { role: c.role, name: c.name, tag: c.tag } }
+    }
+  }
+  return null
+}
+
+/** Replaces the selector's string literal in a script; { text, diff, count } or null when it is not written literally. */
+export function patchScript (source, selector, replacement, file = 'script.mjs') {
+  const lines = source.split('\n')
+  const out = []; const diff = []; let count = 0
+  for (const [i, line] of lines.entries()) {
+    let next = line
+    for (const quote of ["'", '"', '`']) {
+      const lit = quote + selector.replaceAll('\\', '\\\\').replaceAll(quote, '\\' + quote) + quote
+      if (next.includes(lit)) {
+        const rep = quote + replacement.replaceAll('\\', '\\\\').replaceAll(quote, '\\' + quote) + quote
+        count += next.split(lit).length - 1
+        next = next.replaceAll(lit, rep)
+      }
+    }
+    if (next !== line) diff.push(`@@ -${i + 1} +${i + 1} @@`, `-${line}`, `+${next}`)
+    out.push(next)
+  }
+  if (!count) return null
+  return { text: out.join('\n'), count, diff: [`--- a/${file}`, `+++ b/${file}`, ...diff].join('\n') }
+}
+
+/**
+ * After a failed step: the proposal and, with `apply`, a re-run of the step with the patched script. `rerun(module)`
+ * runs the step with a script module and throws when it fails. Returns { selector, proposal, patch, applied, note }.
+ */
+export async function healStep ({ error, page, scriptFile, root, output, run, node, locale, apply = false, rerun }) {
+  const selector = failedSelector(error?.message)
+  if (!selector) return null
+  const proposal = await proposeSelector({ page, selector, root, output, run, node, locale })
+  if (!proposal) return { selector, proposal: null, note: `no element on the page now resembles ${selector}` }
+  const source = await readFile(scriptFile, 'utf8').catch(() => null)
+  const rel = relative(root, scriptFile)
+  const patch = source ? patchScript(source, selector, proposal.replacement, rel) : null
+  if (!patch) return { selector, proposal, patch: null, note: `${selector} is not written literally in ${rel}; change it by hand` }
+  if (!apply) return { selector, proposal, patch, applied: false }
+  // the patched script runs from a sibling file (its relative imports resolve the same) and replaces the original
+  // only when the step passed with it
+  const trial = join(dirname(scriptFile), `.${basename(scriptFile, '.mjs')}.kaloko-heal-${process.pid}.mjs`)
+  try {
+    await writeFile(trial, patch.text)
+    await rerun(await import(`${pathToFileURL(trial).href}?t=${Date.now()}`))
+    await writeFile(scriptFile, patch.text)
+    return { selector, proposal, patch, applied: true }
+  } catch (e) {
+    return { selector, proposal, patch, applied: false, note: `the step still fails with the proposal (${String(e.message).split('\n')[0]}); ${rel} is unchanged` }
+  } finally { await rm(trial, { force: true }) }
+}
+
+/** Lines for the terminal: what failed, what is proposed and why, and the patch. */
+export function formatHeal (h, { stepArg }) {
+  if (!h) return ''
+  if (!h.proposal) return `  ↳ selector ${h.selector}: ${h.note}`
+  const lines = [`  ↳ selector ${h.selector} not found; proposed ${h.proposal.replacement} (${h.proposal.why}${h.proposal.from ? `; the old selector matched it in run ${h.proposal.from}` : ''})`]
+  if (h.applied) lines.push(`  ↳ healed: the step passed with it, ${h.patch.count} occurrence(s) changed:`)
+  else if (h.note) lines.push(`  ↳ ${h.note}`)
+  if (h.patch) lines.push(h.patch.diff.split('\n').map((l) => `    ${l}`).join('\n'))
+  if (h.patch && !h.applied && !h.note) lines.push(`  ↳ apply it after the step passes: kaloko walk --steps ${stepArg} --heal`)
+  return lines.join('\n')
+}