@adia-ai/mcp 0.8.37 → 0.8.39

package/factory/vendor/adia-probe.mjs

@@ -0,0 +1,413 @@
+#!/usr/bin/env node
+// adia-probe — the surface-qa browser gate, shipped (factory-audit Wave 2, gh#259).
+//
+// Runs the four-gate probe the surface-qa skill defines (references/
+// verification.md) and emits a VerifyProof: zero console/page errors,
+// non-zero bounding boxes on the named selectors, a deviceScaleFactor:2
+// screenshot — and an explicit HUMAN/MODEL-READS-THE-IMAGE slot, because a
+// probe that screenshots but doesn't read the image has verified nothing.
+// It also records navigation timing as an ADVISORY perf row (REQ-06,
+// gh#1200/gh#1211, realizing ADR-0040's ui-verifier "perf" clause) — a
+// budget observation only; it never flips the verdict, since promoting it
+// to a blocking gate is a later ruling that needs real data first.
+//
+// gh#1259 adds the instrumented AA-contrast slice — the one VerifyProof row
+// QA seats carried as UNMEASURED or hand-computed (the #1246 wave's probes
+// 4/5). It samples rendered foreground/background pairs for visible text
+// nodes (computed sRGB, alpha-composited up to the first opaque ancestor
+// background — the math probe 5 hand-executed), scores each pair against
+// WCAG AA (4.5 normal / 3.0 large text: ≥18pt, or ≥14pt bold), and reports
+// pass/fail per pair with the sampled values. Unlike perf, contrast is a
+// GATE when measured: a failing pair fails the verdict (it is the a11y
+// rubric row's contrast slice, and that row is blocking). When no samples
+// can be captured the row degrades to UNMEASURED, never a silent fail.
+// Pairs whose background chain crosses a background-image before an opaque
+// color are skipped as indeterminate (computed styles can't see pixels of
+// an image) — skipped counts are reported, and those pairs stay the
+// image-reader's judgment.
+//
+// Requires Playwright IN THE CONSUMER APP (a dev dependency it very likely
+// already has; this plugin ships no browser): npm i -D playwright
+//
+// Usage:
+//   node adia-probe.mjs <url> --selector <css> [--selector <css> …]
+//                       [--screenshot probe.png] [--perf-budget-ms 3000] [--json]
+//   node adia-probe.mjs selftest      # gate logic + report shape (no browser)
+//
+// Exit: 0 = mechanized gates pass (verdict "pass-pending-read" — gate 3's
+// image read remains the model's), 1 = a gate failed, 2 = setup error.
+// The perf row is ADVISORY: exceeding perfBudgetMs never changes this exit
+// code or the verdict string — it is reported, not enforced.
+
+import process from 'node:process';
+
+// REQ-06 default budget: generous on purpose (advisory, not a floor) — a
+// number worth reporting against without a real dataset to justify a
+// tighter one yet. Overridable per invocation via --perf-budget-ms.
+const DEFAULT_PERF_BUDGET_MS = 3000;
+
+// ---- WCAG AA contrast math (gh#1259) — pure, browser-free, selftestable ----
+
+// sRGB channel linearization (WCAG 2.x relative-luminance definition).
+export function srgbChannel(c8) {
+  const c = c8 / 255;
+  return c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+}
+
+export function relativeLuminance([r, g, b]) {
+  return 0.2126 * srgbChannel(r) + 0.7152 * srgbChannel(g) + 0.0722 * srgbChannel(b);
+}
+
+export function contrastRatio(fg, bg) {
+  const a = relativeLuminance(fg);
+  const b = relativeLuminance(bg);
+  const [hi, lo] = a >= b ? [a, b] : [b, a];
+  return (hi + 0.05) / (lo + 0.05);
+}
+
+// WCAG "large text": ≥18pt (24px), or ≥14pt (18.66px) bold. AA then asks
+// 3.0 instead of 4.5.
+export function isLargeText(fontSizePx, fontWeight) {
+  return fontSizePx >= 24 || (fontSizePx >= 18.66 && fontWeight >= 700);
+}
+
+// samples: [{ text, element, fg:[r,g,b], bg:[r,g,b], fontSizePx, fontWeight }]
+export function scoreContrastSamples(samples, { skipped = 0 } = {}) {
+  const pairs = samples.map((s) => {
+    const large = isLargeText(s.fontSizePx, s.fontWeight);
+    const required = large ? 3.0 : 4.5;
+    const ratio = Math.round(contrastRatio(s.fg, s.bg) * 100) / 100;
+    return { ...s, large, required, ratio, pass: ratio >= required };
+  });
+  const failing = pairs.filter((p) => !p.pass);
+  return {
+    pass: failing.length === 0,
+    standard: 'WCAG AA — 4.5:1 normal / 3.0:1 large text (≥18pt, or ≥14pt bold)',
+    checked: pairs.length,
+    skippedImageBacked: skipped,
+    failing,
+    pairs,
+  };
+}
+
+export function buildProof({ url, errors, boxes, screenshotPath, navTiming, perfBudgetMs = DEFAULT_PERF_BUDGET_MS, contrastSamples = null, contrastSkipped = 0 }) {
+  const consolePass = errors.length === 0;
+  const boxFailures = Object.entries(boxes)
+    .filter(([, b]) => !b || b.width <= 0 || b.height <= 0)
+    .map(([sel]) => sel);
+  const boxPass = boxFailures.length === 0;
+  // ADVISORY — REQ-06: reports navigation timing against a budget but never
+  // participates in `verdict` below. `navTiming` missing/null means the
+  // caller couldn't measure it (e.g. the selftest's synthetic fixtures);
+  // that is UNMEASURED, not a failure — a VerifyProof still carries the row.
+  const perf = navTiming
+    ? {
+        advisory: true,
+        budgetMs: perfBudgetMs,
+        observed: navTiming,
+        withinBudget: navTiming.loadMs <= perfBudgetMs,
+      }
+    : { advisory: true, budgetMs: perfBudgetMs, observed: null, withinBudget: null, reason: 'UNMEASURED — no navigation timing captured' };
+  // gh#1259 — GATE when measured, UNMEASURED (not failing) when the caller
+  // captured no samples (selftest fixtures, an all-image page, a sampler
+  // crash). This mirrors the perf row's degradation shape but NOT its
+  // advisory nature: a measured failing pair fails the verdict.
+  const contrast = contrastSamples
+    ? scoreContrastSamples(contrastSamples, { skipped: contrastSkipped })
+    : { pass: null, reason: 'UNMEASURED — no text foreground/background pairs sampled' };
+  return {
+    record: 'VerifyProof',
+    url,
+    gates: {
+      consoleErrors: { pass: consolePass, errors },
+      boundingBoxes: { pass: boxPass, failing: boxFailures, boxes },
+      screenshot: { path: screenshotPath, deviceScaleFactor: 2 },
+      imageRead: 'REQUIRED — a screenshot nobody reads verifies nothing; the reader states what the pixels show',
+      perf,
+      contrast,
+    },
+    // perf is deliberately excluded here — advisory means it can never turn
+    // a green gate red (REQ-06's "Advisory means" clause). contrast joins the
+    // verdict only when measured: `pass === false` fails; `null` (UNMEASURED)
+    // does not (gh#1259).
+    verdict: consolePass && boxPass && contrast.pass !== false ? 'pass-pending-read' : 'fail',
+  };
+}
+
+function selftest() {
+  const good = buildProof({
+    url: 'http://x', errors: [], boxes: { 'my-surface': { width: 640, height: 480 } }, screenshotPath: 'p.png',
+    navTiming: { loadMs: 120, domContentLoadedMs: 80 },
+  });
+  const badBox = buildProof({
+    url: 'http://x', errors: [], boxes: { 'my-surface': { width: 0, height: 0 } }, screenshotPath: 'p.png',
+  });
+  const badErr = buildProof({
+    url: 'http://x', errors: ['TypeError: boom'], boxes: { 'my-surface': { width: 1, height: 1 } }, screenshotPath: 'p.png',
+  });
+  // REQ-06: a slow page (over budget) still PASSES the mechanized gates —
+  // advisory means perf never turns a green gate red.
+  const overBudget = buildProof({
+    url: 'http://x', errors: [], boxes: { 'my-surface': { width: 640, height: 480 } }, screenshotPath: 'p.png',
+    navTiming: { loadMs: 9000, domContentLoadedMs: 8000 }, perfBudgetMs: 3000,
+  });
+  const noTiming = buildProof({
+    url: 'http://x', errors: [], boxes: { 'my-surface': { width: 640, height: 480 } }, screenshotPath: 'p.png',
+  });
+  // gh#1259 — contrast fixtures. Positive control: black-on-white text
+  // (ratio 21:1) passes and leaves the verdict green.
+  const goodContrast = buildProof({
+    url: 'http://x', errors: [], boxes: { 'my-surface': { width: 640, height: 480 } }, screenshotPath: 'p.png',
+    contrastSamples: [
+      { text: 'readable body copy', element: 'p', fg: [0, 0, 0], bg: [255, 255, 255], fontSizePx: 16, fontWeight: 400 },
+    ],
+  });
+  // Negative control: #aaa on white (≈2.32:1) — a deliberately-failing
+  // low-contrast pair MUST fail the contrast gate AND flip the verdict.
+  const badContrast = buildProof({
+    url: 'http://x', errors: [], boxes: { 'my-surface': { width: 640, height: 480 } }, screenshotPath: 'p.png',
+    contrastSamples: [
+      { text: 'faint caption', element: 'span', fg: [170, 170, 170], bg: [255, 255, 255], fontSizePx: 16, fontWeight: 400 },
+    ],
+  });
+  // Large-text threshold: #949494 on white (≈3.03:1) fails at 16px normal
+  // (needs 4.5) but passes at 24px (large text, needs 3.0).
+  const borderline = scoreContrastSamples([
+    { text: 'gray at body size', element: 'p', fg: [148, 148, 148], bg: [255, 255, 255], fontSizePx: 16, fontWeight: 400 },
+    { text: 'gray as a heading', element: 'h1', fg: [148, 148, 148], bg: [255, 255, 255], fontSizePx: 24, fontWeight: 400 },
+  ]);
+  const fails = [];
+  const bw = contrastRatio([0, 0, 0], [255, 255, 255]);
+  if (bw < 20.9 || bw > 21.1) fails.push(`black/white ratio ${bw} not ≈21`);
+  if (!isLargeText(24, 400) || !isLargeText(19, 700) || isLargeText(19, 400) || isLargeText(16, 400)) {
+    fails.push('large-text threshold (≥18pt, or ≥14pt bold) mis-scored');
+  }
+  if (goodContrast.verdict !== 'pass-pending-read' || goodContrast.gates.contrast.pass !== true) {
+    fails.push('passing contrast pair did not pass');
+  }
+  if (badContrast.verdict !== 'fail' || badContrast.gates.contrast.pass !== false) {
+    fails.push('NEGATIVE CONTROL: low-contrast pair did not fail the verdict');
+  }
+  if (badContrast.gates.contrast.failing.length !== 1 || badContrast.gates.contrast.failing[0].required !== 4.5
+      || badContrast.gates.contrast.failing[0].ratio >= 4.5) {
+    fails.push('failing pair not reported with sampled ratio + required threshold');
+  }
+  if (borderline.pairs[0].pass !== false || borderline.pairs[1].pass !== true || borderline.pairs[1].required !== 3.0) {
+    fails.push('large-text 3.0 exception not applied per pair');
+  }
+  if (good.gates.contrast.pass !== null || !good.gates.contrast.reason.includes('UNMEASURED')) {
+    fails.push('missing contrast samples did not degrade to UNMEASURED contrast row');
+  }
+  if (good.verdict !== 'pass-pending-read') fails.push('good fixture not pass-pending-read');
+  if (badBox.verdict !== 'fail' || badBox.gates.boundingBoxes.failing[0] !== 'my-surface') fails.push('0x0 box not failed');
+  if (badErr.verdict !== 'fail' || badErr.gates.consoleErrors.pass) fails.push('console error not failed');
+  if (!good.gates.imageRead.includes('REQUIRED')) fails.push('imageRead slot missing');
+  if (!good.gates.perf || good.gates.perf.advisory !== true) fails.push('perf row missing/not advisory');
+  if (good.gates.perf.withinBudget !== true) fails.push('perf row withinBudget mis-scored for a fast fixture');
+  if (overBudget.verdict !== 'pass-pending-read') fails.push('REQ-06 REGRESSION: over-budget perf turned a green gate red');
+  if (overBudget.gates.perf.withinBudget !== false) fails.push('over-budget perf row not flagged withinBudget:false');
+  if (noTiming.gates.perf.observed !== null || !noTiming.gates.perf.reason.includes('UNMEASURED')) {
+    fails.push('missing navTiming did not degrade to UNMEASURED perf row');
+  }
+  if (fails.length) {
+    console.error('selftest FAIL: ' + fails.join(' | '));
+    process.exit(1);
+  }
+  console.log('selftest OK — 8 fixtures, verdicts + imageRead + advisory perf row + AA contrast gate (positive/negative/large-text) correct');
+  process.exit(0);
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  if (argv[0] === 'selftest') selftest();
+  // REQ-06 (gh#1122): help is not a usage error — checked BEFORE url/selector
+  // resolution so -h/--help can never be mistaken for a positional url (a
+  // single-dash flag doesn't start with '--', so it would otherwise fall
+  // through to the `.find` below) and exits 0, not the 2 reserved for a
+  // genuine missing-argument mis-invocation.
+  if (argv.includes('-h') || argv.includes('--help')) {
+    console.log('usage: adia-probe.mjs <url> --selector <css> [--selector <css> …] [--screenshot out.png] [--perf-budget-ms 3000] [--json]');
+    process.exit(0);
+  }
+  const url = argv.find((a) => !a.startsWith('--'));
+  const selectors = argv.flatMap((a, i) => (a === '--selector' ? [argv[i + 1]] : []));
+  const screenshotPath = argv.includes('--screenshot')
+    ? argv[argv.indexOf('--screenshot') + 1] : 'probe.png';
+  // REQ-06: advisory only — an unparsable/absent value falls back to the
+  // default rather than erroring, since this flag never gates anything.
+  const perfBudgetMs = argv.includes('--perf-budget-ms')
+    ? Number(argv[argv.indexOf('--perf-budget-ms') + 1]) || DEFAULT_PERF_BUDGET_MS
+    : DEFAULT_PERF_BUDGET_MS;
+  if (!url || selectors.length === 0) {
+    console.error('usage: adia-probe.mjs <url> --selector <css> [--selector <css> …] [--screenshot out.png] [--perf-budget-ms 3000] [--json]');
+    process.exit(2);
+  }
+
+  // Resolve playwright from the CONSUMER APP (cwd), not from this file's own
+  // location. A bare import('playwright') searches this script's ancestor
+  // directories — correct when the probe runs from inside the app's tree,
+  // wrong when a packed copy lives elsewhere (e.g. @adia-ai/mcp's vendored
+  // copy under an npx cache, PR #1289 review): the app's devDependency would
+  // never be found. Try the bare import first (fast path, zero behavior
+  // change in the plugin's own layout), then fall back to a resolver rooted
+  // at process.cwd().
+  let chromium;
+  try {
+    ({ chromium } = await import('playwright'));
+  } catch {
+    try {
+      const { createRequire } = await import('node:module');
+      const { pathToFileURL } = await import('node:url');
+      const path = await import('node:path');
+      const req = createRequire(path.join(process.cwd(), 'package.json'));
+      ({ chromium } = await import(pathToFileURL(req.resolve('playwright')).href));
+    } catch {
+      console.error('adia-probe: playwright not installed in this app — npm i -D playwright');
+      process.exit(2);
+    }
+  }
+
+  const browser = await chromium.launch();
+  // deviceScaleFactor must be set at CONTEXT creation — scale:'device' on a
+  // default context captures at 1x (the defect this script replaced).
+  const context = await browser.newContext({ deviceScaleFactor: 2 });
+  const page = await context.newPage();
+  const errors = [];
+  page.on('console', (m) => m.type() === 'error' && errors.push(m.text()));
+  page.on('pageerror', (e) => errors.push(String(e)));
+  await page.goto(url, { waitUntil: 'networkidle' });
+
+  const boxes = {};
+  for (const sel of selectors) {
+    boxes[sel] = await page.locator(sel).first().boundingBox().catch(() => null);
+  }
+  // REQ-06 — Navigation Timing Level 2 (the non-deprecated API); `null` on
+  // a page that hasn't finished loading or a substrate that doesn't expose
+  // it, which `buildProof` degrades to an UNMEASURED (not failing) perf row.
+  const navTiming = await page.evaluate(() => {
+    const [entry] = performance.getEntriesByType('navigation');
+    if (!entry) return null;
+    return {
+      loadMs: Math.round(entry.loadEventEnd - entry.startTime),
+      domContentLoadedMs: Math.round(entry.domContentLoadedEventEnd - entry.startTime),
+      responseMs: Math.round(entry.responseEnd - entry.startTime),
+    };
+  }).catch(() => null);
+  // gh#1259 — sample rendered fg/bg pairs for visible text nodes. The
+  // evaluate callback is self-contained (it serializes into the page; module
+  // scope is unreachable there): it collects RAW sampled values only, and the
+  // WCAG scoring runs in Node via the exported, selftested functions above.
+  // Composite backgrounds: walk up to the first opaque ancestor
+  // background-color, alpha-compositing translucent layers (over white, the
+  // document default). A background-image anywhere in that chain makes the
+  // pair indeterminate from computed styles — skipped and counted, never
+  // guessed. Deduped by (fg, bg, size, weight) and capped, so the report
+  // stays bounded on long pages.
+  const sampled = await page.evaluate(() => {
+    const parse = (s) => {
+      const m = /rgba?\(([^)]+)\)/.exec(s || '');
+      if (!m) return null;
+      const [r, g, b, a = 1] = m[1].split(',').map(Number);
+      return { rgb: [r, g, b], a };
+    };
+    const over = (fg, a, bg) => fg.map((c, i) => Math.round(c * a + bg[i] * (1 - a)));
+    const bgFor = (el) => {
+      const layers = [];
+      for (let n = el; n && n.nodeType === 1; n = n.parentElement || (n.getRootNode && n.getRootNode().host) || null) {
+        const cs = getComputedStyle(n);
+        if (cs.backgroundImage && cs.backgroundImage !== 'none') return null; // indeterminate — pixels, not computed styles
+        const c = parse(cs.backgroundColor);
+        if (c && c.a > 0) {
+          layers.push(c);
+          if (c.a >= 1) break;
+        }
+      }
+      let bg = [255, 255, 255];
+      for (let i = layers.length - 1; i >= 0; i--) bg = over(layers[i].rgb, layers[i].a, bg);
+      return bg;
+    };
+    const samples = [];
+    let skipped = 0;
+    const seen = new Set();
+    const walker = document.createTreeWalker(document.body, NodeFilter.SHOW_TEXT);
+    let node;
+    while ((node = walker.nextNode()) && samples.length < 120) {
+      const text = node.textContent.trim();
+      if (!text) continue;
+      const el = node.parentElement;
+      if (!el || ['SCRIPT', 'STYLE', 'NOSCRIPT', 'TEMPLATE'].includes(el.tagName)) continue;
+      const cs = getComputedStyle(el);
+      if (cs.display === 'none' || cs.visibility === 'hidden' || Number(cs.opacity) === 0) continue;
+      const rect = el.getBoundingClientRect();
+      if (rect.width <= 0 || rect.height <= 0) continue;
+      const fgc = parse(cs.color);
+      if (!fgc) continue;
+      const bg = bgFor(el);
+      if (!bg) { skipped += 1; continue; }
+      const fg = fgc.a >= 1 ? fgc.rgb.map(Math.round) : over(fgc.rgb, fgc.a, bg);
+      const fontSizePx = parseFloat(cs.fontSize) || 16;
+      const fontWeight = cs.fontWeight === 'bold' ? 700 : Number(cs.fontWeight) || 400;
+      const key = `${fg.join()}|${bg.join()}|${fontSizePx}|${fontWeight}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      samples.push({
+        text: text.slice(0, 40),
+        element: el.tagName.toLowerCase() + (el.id ? `#${el.id}` : ''),
+        fg, bg, fontSizePx, fontWeight,
+      });
+    }
+    return { samples, skipped };
+  }).catch(() => null);
+  await page.screenshot({ path: screenshotPath, scale: 'device', fullPage: true });
+  await browser.close();
+
+  const proof = buildProof({
+    url, errors, boxes, screenshotPath, navTiming, perfBudgetMs,
+    contrastSamples: sampled && sampled.samples.length ? sampled.samples : null,
+    contrastSkipped: sampled ? sampled.skipped : 0,
+  });
+  if (process.argv.includes('--json')) {
+    console.log(JSON.stringify(proof, null, 1));
+  } else {
+    const perfNote = proof.gates.perf.observed
+      ? `perf(advisory):${proof.gates.perf.observed.loadMs}ms/${proof.gates.perf.budgetMs}ms budget`
+      : 'perf(advisory):UNMEASURED';
+    const c = proof.gates.contrast;
+    const contrastNote = c.pass === null
+      ? 'contrast:UNMEASURED'
+      : `contrast:${c.pass ? 'pass' : 'FAIL'} ${c.checked - c.failing.length}/${c.checked} pairs${c.skippedImageBacked ? ` (+${c.skippedImageBacked} image-backed skipped)` : ''}`;
+    console.log(`[adia-probe] ${proof.verdict} — errors:${errors.length} boxes:${selectors.length - proof.gates.boundingBoxes.failing.length}/${selectors.length} shot:${screenshotPath} ${perfNote} ${contrastNote}`);
+    if (proof.verdict === 'fail') {
+      for (const e of errors) console.log(`  console: ${e}`);
+      for (const s of proof.gates.boundingBoxes.failing) console.log(`  0×0/missing: ${s}`);
+      if (c.pass === false) {
+        for (const p of c.failing) {
+          console.log(`  contrast: ${p.ratio}:1 < ${p.required}:1 — ${p.element} "${p.text}" fg rgb(${p.fg.join(',')}) on bg rgb(${p.bg.join(',')}) @ ${p.fontSizePx}px w${p.fontWeight}${p.large ? ' (large)' : ''}`);
+        }
+      }
+    }
+    if (proof.gates.perf.observed && !proof.gates.perf.withinBudget) {
+      console.log(`  NOTE: perf row over advisory budget (${proof.gates.perf.observed.loadMs}ms > ${proof.gates.perf.budgetMs}ms) — advisory only, does not fail this gate.`);
+    }
+    console.log(`  NEXT: read ${screenshotPath} — the proof is incomplete until the pixels are described.`);
+  }
+  process.exit(proof.verdict === 'fail' ? 1 : 0);
+}
+
+// Entry guard (PR #1289 review): this module exports pure contrast helpers
+// (srgbChannel … buildProof) for tests and other tooling — an unguarded
+// top-level main() would launch the CLI (and its process.exit(2) usage path)
+// on ANY import. Canonical-path compare via realpathSync on both sides, the
+// repo's standing rule, because skill invocation paths are symlinks
+// (adia-contract-check.mjs carries the same guard).
+const isMain = await (async () => {
+  if (!process.argv[1]) return false;
+  try {
+    const { realpathSync } = await import('node:fs');
+    const { fileURLToPath } = await import('node:url');
+    return realpathSync(fileURLToPath(import.meta.url)) === realpathSync(process.argv[1]);
+  } catch {
+    return false;
+  }
+})();
+if (isMain) await main();