pixel-perfect-kit 0.1.0

package/harness/score.js

@@ -0,0 +1,58 @@
+// harness/score.js <name> — score targets/<name>/{live,clone}.json and compare to the
+// previous run, so "is this iteration better?" is a number, not a vibe.
+//
+// Emits a scorecard, appends it to targets/<name>/scores.jsonl, and prints the delta
+// vs the last recorded run (visual fails ↓ = better). Also lists the current failing
+// --visual rows (the fix list) and the strict structural count (document or fix).
+const fs = require("fs"), path = require("path");
+const { diffSnapshots } = require("../tools/pixel-diff.js");
+
+const name = process.argv[2];
+if (!name) { console.error("usage: ppk score <target-name>"); process.exit(1); }
+// targets/ live in the user's current directory (WORK), not inside the installed kit.
+const dir = path.join(process.cwd(), "targets", name);
+const readJson = (f) => {
+  const p = path.join(dir, f);
+  if (!fs.existsSync(p)) { console.error(`missing ${name}/${f} — capture it first (RUNBOOK)`); process.exit(1); }
+  const txt = fs.readFileSync(p, "utf8");
+  if (/^\s*\[BLOCKED/.test(txt)) { console.error(`${name}/${f} holds a "[BLOCKED…]" automation sentinel, not a snapshot — re-capture via the sink/stash path (RUNBOOK).`); process.exit(1); }
+  try { return JSON.parse(txt); } catch (e) { console.error(`${name}/${f} is not valid JSON: ${e.message}. Re-capture it (a truncated/partial paste is the usual cause).`); process.exit(1); }
+};
+
+const live = readJson("live.json"), clone = readJson("clone.json");
+const v = diffSnapshots(live, clone, { visual: true });
+const s = diffSnapshots(live, clone, {});
+const targets = Object.keys(live.elements || {}).length;
+
+const widthMismatch = live.viewport && clone.viewport && live.viewport.width !== clone.viewport.width;
+const score = {
+  ts: new Date().toISOString(),
+  targets,
+  visualComparisons: v.summary.comparisons, visualFails: v.summary.failures, visualOk: v.ok,
+  strictComparisons: s.summary.comparisons, strictFails: s.summary.failures,
+  widthMismatch: !!widthMismatch,
+};
+
+// previous run (last non-empty line of scores.jsonl)
+const logPath = path.join(dir, "scores.jsonl");
+const prevLines = fs.existsSync(logPath) ? fs.readFileSync(logPath, "utf8").trim().split("\n").filter(Boolean) : [];
+const prev = prevLines.length ? JSON.parse(prevLines[prevLines.length - 1]) : null;
+
+const arrow = (cur, was) => was == null ? "" : cur < was ? `  ↓ ${was}→${cur}  better` : cur > was ? `  ↑ ${was}→${cur}  WORSE` : `  = ${cur}  same`;
+
+console.log(`\nscorecard — ${name}  (${targets} targets, width ${clone.viewport && clone.viewport.width})`);
+if (widthMismatch) console.log(`⚠  viewport widths differ (${live.viewport.width} vs ${clone.viewport.width}) — x-positions not comparable. Re-measure both at the same width.`);
+console.log(`  --visual   ${v.ok ? "PASS" : "FAIL"}   fails ${score.visualFails}/${score.visualComparisons}${arrow(score.visualFails, prev && prev.visualFails)}`);
+console.log(`  strict     fails ${score.strictFails}/${score.strictComparisons}${arrow(score.strictFails, prev && prev.strictFails)}   (structural → fix or document)`);
+
+// the fix list — current --visual failures
+const vFails = v.rows.filter((r) => !r.pass);
+if (vFails.length) {
+  console.log(`\n  --visual fix list:`);
+  for (const r of vFails) console.log(`    ${r.target.padEnd(14)} ${String(r.prop).padEnd(20)} live=${r.live}  clone=${r.clone}  Δ=${r.delta}`);
+}
+
+fs.appendFileSync(logPath, JSON.stringify(score) + "\n");
+console.log(`\nrecorded to targets/${name}/scores.jsonl  (${prevLines.length + 1} runs)`);
+if (v.ok) console.log(`✓ --visual green. Next: close coverage (every painted leaf has a target), then read the strict table for colour/underline rows.`);
+process.exit(v.ok ? 0 : 1);

package/harness/serve.js

@@ -0,0 +1,149 @@
+// harness/serve.js <target-name> [port] — static server for one target's clone.
+//
+// Serves targets/<name>/clone/ at / AND the kit's tools/ at /tools/, so the clone
+// page can `fetch('/tools/browser-capture.js')` (single source of truth — no copy to
+// keep in sync). Zero deps. Pair with `node tools/sink.js` to receive snapshots.
+const http = require("http"), fs = require("fs"), path = require("path");
+const MIME = { ".html": "text/html", ".css": "text/css", ".js": "text/javascript", ".mjs": "text/javascript", ".json": "application/json", ".woff2": "font/woff2", ".woff": "font/woff", ".svg": "image/svg+xml", ".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".webp": "image/webp", ".gif": "image/gif" };
+
+// Resolve a request URL to a real file path WITHIN one of the allowed roots, or null.
+// The boundary check uses path.relative (not startsWith), so a sibling prefix like
+// `<clone>-evil` or any `../` traversal is rejected — matching the canonical
+// workspace-boundary guard the kit's diff tools rely on. Pure + exported so it's unit-tested
+// without opening a socket.
+function resolvePath(urlPath, { cloneDir, toolsDir }) {
+  // A malformed percent-encoding ("/%", "/%zz") throws URIError; uncaught inside the request
+  // handler it would kill the whole server mid-session — treat it as unresolvable instead.
+  let u;
+  try { u = decodeURIComponent(urlPath.split("?")[0]); } catch (e) { return null; }
+  if (u === "/") u = "/index.html";
+  const base = u.startsWith("/tools/") ? toolsDir : cloneDir;
+  const rel = u.startsWith("/tools/") ? u.slice(7) : u.slice(1);
+  const fp = path.resolve(base, rel);
+  const within = path.relative(base, fp);
+  if (within.startsWith("..") || path.isAbsolute(within)) return null; // traversal / prefix escape
+  return fp;
+}
+
+// ── LOCAL review mode (/__review) ─────────────────────────────────────────────
+// The no-PingHumans path: the review page renders the latest LOCAL round's spec (same
+// scope-pin/steps/changelog the marketplace test would carry), shows the clone in a
+// same-origin iframe with click-to-pin, and enforces the SAME contract — a verdict
+// button pick is mandatory; comments alone can't pass the gate. The submission is
+// written into human-qa.json where `human-qa.js verify` reads it. Trust model: local
+// verdicts are operator-trusted and recorded as provider:"local" — agents never open
+// or submit this page themselves.
+function latestLocalRound(hq) {
+  const r = (hq && hq.rounds || [])[Math.max(0, (hq.rounds || []).length - 1)];
+  return r && r.provider === "local" ? r : null;
+}
+
+// Pure: apply a review submission to the hq state. Returns {ok, message}.
+function applySubmission(hq, body) {
+  const round = latestLocalRound(hq);
+  if (!round) return { ok: false, message: "no LOCAL round is latest — file one: ppk human <name> file --local" };
+  if (round.raw_response && round.raw_response.n_received) return { ok: false, message: "this round is already answered — file a new round for another review" };
+  if (!body || (body.choice == null && !(body.comments || []).length && !(body.free_text || "").trim())) return { ok: false, message: "empty submission" };
+  const comments = (body.comments || []).filter((c) => c && c.text);
+  const free = comments.length
+    ? `${comments.length} comment(s): ` + comments.map((c) => `<${c.selector || "?"}> — ${c.text}`).join(" | ") + ((body.free_text || "").trim() ? " | " + body.free_text.trim() : "")
+    : (body.free_text || "").trim() || null;
+  round.raw_response = { status: "complete", n_received: 1, n_target: 1, responses: [{ choice: body.choice != null ? body.choice : null, free_text: free }], comments };
+  round.answered_at = new Date().toISOString();
+  return { ok: true, message: `recorded — verdict: ${body.choice != null ? JSON.stringify(body.choice) : "NONE (comments only — the gate will refuse; pick a verdict button)"}` };
+}
+
+function renderReviewPage(hq, name) {
+  const esc = (s) => String(s == null ? "" : s).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+  const round = latestLocalRound(hq);
+  if (!round) return `<!doctype html><meta charset="utf-8"><body style="font:16px system-ui;padding:2rem">No local review round is pending for <b>${esc(name)}</b>.<br>File one: <code>ppk human ${esc(name)} file --local</code></body>`;
+  if (round.raw_response && round.raw_response.n_received) return `<!doctype html><meta charset="utf-8"><body style="font:16px system-ui;padding:2rem">This round is already answered (${esc((round.raw_response.responses[0] || {}).choice || "no verdict")}).<br>File a new round for another review.</body>`;
+  const spec = round.spec || { title: "Review", instructions: "", steps: [], verdict_options: round.approve_verdicts || ["Approve"] };
+  return `<!doctype html><meta charset="utf-8"><title>${esc(spec.title)}</title>
+<body style="margin:0;font:14px/1.45 system-ui;display:grid;grid-template-columns:minmax(340px,28%) 1fr;height:100vh">
+<div style="overflow:auto;padding:16px;border-right:1px solid #ddd;background:#fafafa">
+  <h2 style="margin:0 0 8px;font-size:16px">${esc(spec.title)} <span style="color:#888;font-weight:normal">(local review)</span></h2>
+  <p style="color:#444">${esc(spec.instructions)}</p>
+  <ol style="padding-left:18px;color:#333">${(spec.steps || []).map((s) => `<li style="margin:6px 0">${esc(s.text)}</li>`).join("")}</ol>
+  <p><button id="pin" style="padding:6px 10px">📌 Pin mode: OFF</button> <span style="color:#888">— toggle, then click anything in the clone that looks wrong</span></p>
+  <ul id="pins" style="padding-left:18px"></ul>
+  <p><textarea id="free" placeholder="anything else?" style="width:100%;height:56px"></textarea></p>
+  <p><b>Verdict (required):</b><br>${(spec.verdict_options || []).map((v) => `<label style="display:block;margin:4px 0"><input type="radio" name="v" value="${esc(v)}"> ${esc(v)}</label>`).join("")}</p>
+  <p><button id="go" style="padding:8px 14px;font-weight:600">Submit review</button> <span id="msg" style="color:#c00"></span></p>
+</div>
+<iframe id="clone" src="/" style="border:0;width:100%;height:100%"></iframe>
+<script>
+var pins=[],mode=false;
+var pinBtn=document.getElementById('pin');
+pinBtn.onclick=function(){mode=!mode;pinBtn.textContent='📌 Pin mode: '+(mode?'ON':'OFF')};
+document.getElementById('clone').addEventListener('load',function(){
+  var doc=this.contentDocument;
+  doc.addEventListener('click',function(e){
+    if(!mode)return;e.preventDefault();e.stopPropagation();
+    var el=e.target;
+    var sel=el.id?('#'+el.id):(el.tagName.toLowerCase()+(el.className&&typeof el.className==='string'?'.'+el.className.trim().split(/\\s+/).slice(0,2).join('.'):''));
+    var txt=prompt('What looks wrong here? ('+sel+')');
+    if(txt){pins.push({selector:sel,text:txt});
+      var li=document.createElement('li');li.textContent=sel+' — '+txt;document.getElementById('pins').appendChild(li);}
+  },true);
+});
+document.getElementById('go').onclick=function(){
+  var v=document.querySelector('input[name=v]:checked');
+  if(!v){document.getElementById('msg').textContent='pick a verdict button — comments alone cannot pass the gate';return;}
+  fetch('/__review/submit',{method:'POST',headers:{'content-type':'application/json'},body:JSON.stringify({choice:v.value,free_text:document.getElementById('free').value,comments:pins})})
+    .then(r=>r.json()).then(function(r){document.body.innerHTML='<div style="font:16px system-ui;padding:2rem">'+(r.ok?'✓ recorded. You can close this tab — the agent picks it up via verify.':'❌ '+r.message)+'</div>'});
+};
+</script></body>`;
+}
+
+function serve(name, port) {
+  const PKG = path.resolve(__dirname, "..");   // the installed kit: /tools/* served from here
+  const WORK = process.cwd();                  // the user's dir: targets/<name>/clone lives here
+  const cloneDir = path.join(WORK, "targets", name, "clone");
+  const toolsDir = path.join(PKG, "tools");
+  const hqPath = path.join(WORK, "targets", name, "human-qa.json");
+  const readHq = () => { try { return JSON.parse(fs.readFileSync(hqPath, "utf8")); } catch (e) { return { rounds: [] }; } };
+  if (!fs.existsSync(cloneDir)) { console.error(`no targets/${name}/clone — run: ppk new ${name} <url>`); process.exit(1); }
+  http.createServer((req, res) => {
+    const u = req.url.split("?")[0];
+    if (u === "/__review" && req.method === "GET") {
+      res.writeHead(200, { "content-type": "text/html; charset=utf-8" });
+      res.end(renderReviewPage(readHq(), name));
+      return;
+    }
+    if (u === "/__review/submit" && req.method === "POST") {
+      let body = "";
+      req.on("data", (d) => { body += d; if (body.length > 1e6) req.destroy(); });
+      req.on("end", () => {
+        let parsed = null;
+        try { parsed = JSON.parse(body); } catch (e) {}
+        const hq = readHq();
+        const r = applySubmission(hq, parsed);
+        if (r.ok) fs.writeFileSync(hqPath, JSON.stringify(hq, null, 2) + "\n");
+        console.log(`local review submission: ${r.message}`);
+        res.writeHead(r.ok ? 200 : 400, { "content-type": "application/json" });
+        res.end(JSON.stringify(r));
+      });
+      return;
+    }
+    const fp = resolvePath(req.url, { cloneDir, toolsDir });
+    if (!fp) { res.writeHead(403); res.end("403 forbidden"); return; }
+    fs.readFile(fp, (e, buf) => {
+      if (e) { res.writeHead(404); res.end("404 " + req.url); return; }
+      res.writeHead(200, { "content-type": MIME[path.extname(fp)] || "application/octet-stream", "access-control-allow-origin": "*" });
+      res.end(buf);
+    });
+  }).on("error", (e) => {
+    // self-describing, actionable — never a raw stack for a predictable failure
+    if (e.code === "EADDRINUSE") { console.error(`port ${port} is already in use — pass another: ppk serve ${name} <port>  (e.g. ${port + 1})`); process.exit(1); }
+    console.error(`serve failed: ${e.message}`);
+    process.exit(1);
+  }).listen(port, () => console.log(`serving targets/${name}/clone → http://localhost:${port}   (/tools/* → kit tools)`));
+}
+
+if (require.main === module) {
+  const name = process.argv[2], port = +(process.argv[3] || 8080);
+  if (!name) { console.error("usage: ppk serve <target-name> [port]"); process.exit(1); }
+  serve(name, port);
+}
+module.exports = { resolvePath, serve, applySubmission, renderReviewPage };

package/harness/setup-selftest.js

@@ -0,0 +1,93 @@
+// harness/setup-selftest.js — guards the one-command onboarding (harness/setup.js).
+// Fully offline: setup() takes an injectable io, so every prompt path is driven with
+// scripted answers and a fake probe map; run() calls are recorded, never executed.
+"use strict";
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const { setup, saidYes } = require("./setup.js");
+
+let failed = 0;
+const ok = (cond, msg) => { if (cond) console.log(`  ✓ ${msg}`); else { failed++; console.log(`  ✗ ${msg}`); } };
+
+console.log("setup-selftest — one-command onboarding");
+
+// consent semantics: Enter is yes ONLY on a real terminal; non-TTY silence is never consent
+ok(saidYes("y", false) && saidYes("yes", true) && saidYes("", true), "y / yes / Enter-on-TTY are consent");
+ok(!saidYes("", false) && !saidYes("n", true), "non-TTY silence and 'n' are NOT consent");
+
+function fakeIO({ probes, answers, tty, paths }) {
+  const logs = [], runs = [];
+  let i = 0;
+  return {
+    io: {
+      isTTY: tty !== false,
+      log: (...a) => logs.push(a.join(" ")),
+      run: (cmd, args) => runs.push([cmd, ...args].join(" ")),
+      probe: (cmd) => !!probes[cmd],
+      which: (cmd) => (paths && paths[cmd]) || null,
+      ask: () => Promise.resolve(answers[i++] != null ? answers[i++ - 1] : ""),
+    },
+    logs, runs,
+  };
+}
+
+(async () => {
+  const home = fs.mkdtempSync(path.join(os.tmpdir(), "ppk-setup-"));
+
+  // ── fresh machine (true npx first-run), user consents to everything ──────────
+  // `which ppk` resolves to npx's EPHEMERAL bin — that must NOT count as installed
+  // (found live: the bare probe said "already installed" during the npx run itself)
+  {
+    const { io, logs, runs } = fakeIO({ probes: { brew: true }, answers: ["", "", ""], paths: { ppk: "/Users/x/.npm/_npx/abc123/node_modules/.bin/ppk" } });
+    const r = await setup(io, { home, sourceCheckout: false, resolveToken: () => null, dittoApiKey: false });
+    ok(r.ok, "fresh-machine run completes");
+    ok(runs.includes("npm i -g pixel-perfect-kit"), "npx's ephemeral bin doesn't count as installed — global install prompt fires and runs on consent");
+    ok(runs.includes("brew install cloudflared"), "installs cloudflared via brew on consent");
+    ok(runs.includes("npx cpyany setup"), "runs the PingHumans device login on consent");
+    ok(logs.some((l) => /ditto \(optional fast builder\): connect its MCP/.test(l)), "ditto guidance is MCP/API-key based — never a binary probe (macOS ships /usr/bin/ditto, a guaranteed false positive)");
+    ok(logs.some((l) => /taught your AI agent: .*pixel-perfect-clone/.test(l)), "installs the agent skills");
+    ok(fs.existsSync(path.join(home, ".claude", "skills", "pixel-perfect-clone", "SKILL.md")), "skills really land in the fake HOME");
+    ok(logs.some((l) => /Clone https:\/\/example\.com pixel-perfect/.test(l)) && logs.some((l) => /with ditto/.test(l)), "summary teaches both agent sentences");
+  }
+
+  // ── a real global install IS recognized; a DITTO_API_KEY is reported ─────────
+  {
+    const { io, logs, runs } = fakeIO({ probes: { cloudflared: true }, answers: [], paths: { ppk: "/usr/local/bin/ppk" } });
+    const r = await setup(io, { home, sourceCheckout: false, resolveToken: () => "tok", dittoApiKey: true });
+    ok(r.ok && runs.length === 0 && logs.some((l) => /already installed globally/.test(l)), "a persistent global bin counts as installed (no prompt)");
+    ok(logs.some((l) => /DITTO_API_KEY found/.test(l)), "a configured ditto API key is reported");
+  }
+
+  // ── skip-everything path still ends usable (local review mode) ────────────────
+  {
+    const { io, logs, runs } = fakeIO({ probes: {}, answers: ["n", "n", "n"] });
+    const r = await setup(io, { home: fs.mkdtempSync(path.join(os.tmpdir(), "ppk-setup2-")), sourceCheckout: false, resolveToken: () => null, dittoApiKey: false });
+    ok(r.ok && runs.length === 0, "declining every prompt runs nothing");
+    ok(logs.some((l) => /LOCAL review mode/.test(l)) && logs.some((l) => /file --local/.test(l)), "skip path points at local review mode explicitly");
+  }
+
+  // ── unattended (non-TTY): silence never installs or opens logins ─────────────
+  {
+    const { io, runs } = fakeIO({ probes: { brew: true }, answers: [], tty: false });
+    const r = await setup(io, { home: fs.mkdtempSync(path.join(os.tmpdir(), "ppk-setup3-")), sourceCheckout: false, resolveToken: () => null, dittoApiKey: false });
+    ok(r.ok && runs.length === 0, "non-TTY run never executes installers (silence is not consent)");
+  }
+
+  // ── source checkout + everything already present = pure no-op re-run ─────────
+  {
+    const { io, logs, runs } = fakeIO({ probes: { cloudflared: true }, answers: [] });
+    const r = await setup(io, { home, sourceCheckout: true, resolveToken: () => "tok", dittoApiKey: false });
+    ok(r.ok && runs.length === 0, "idempotent re-run: probes pass, nothing executes");
+    ok(logs.some((l) => /source checkout/.test(l)) && logs.some((l) => /login found/.test(l)), "re-run reports present state (checkout copy, login)");
+    ok(r.steps.includes("skills-present"), "already-installed skills are kept, not overwritten");
+  }
+
+  // ── old node fails fast with the fix ──────────────────────────────────────────
+  // (checkable only via the saidYes/steps contract — setup reads the REAL process
+  // version, so we assert the guard's presence in source rather than simulate it)
+  ok(/needs Node 18\+/.test(fs.readFileSync(path.join(__dirname, "setup.js"), "utf8")), "old-node guard exists with the fix text");
+
+  console.log(failed ? `\n❌ setup-selftest: ${failed} assertion(s) failed.` : "\n✓ setup-selftest: all assertions pass.");
+  process.exit(failed ? 1 : 0);
+})();

package/harness/setup.js

@@ -0,0 +1,158 @@
+// harness/setup.js — `npx pixel-perfect-kit setup` / `ppk setup`: the one-command onboarding.
+//
+// Everything a newcomer needs, in one interactive pass: global install (when run via
+// npx), cloudflared (offered via brew), the PingHumans device login (skippable — LOCAL
+// review mode needs no account), the optional ditto fast-builder check, and the agent
+// skills. Interactive steps CANNOT live in npm postinstall (silenced, breaks CI), which
+// is why this is an explicit command. Idempotent: every step probes before acting, so
+// re-running it is always safe. `ppk doctor` remains the read-only re-check.
+//
+// USAGE:  npx pixel-perfect-kit setup      (first contact — nothing else installed)
+//         ppk setup                        (re-run anytime)
+"use strict";
+
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const readline = require("readline");
+const { spawnSync } = require("child_process");
+
+const PKG = path.resolve(__dirname, "..");
+
+// io is injectable so the selftest can drive every prompt path offline:
+//   probe(cmd,args) -> bool   run(cmd,args) -> void (stdio inherit)
+//   ask(q) -> Promise<string> (lowercased answer; "" = Enter)   isTTY, log
+function defaultIO() {
+  return {
+    isTTY: !!process.stdin.isTTY,
+    log: (...a) => console.log(...a),
+    run: (cmd, args) => spawnSync(cmd, args, { stdio: "inherit" }),
+    probe: (cmd, args) => {
+      try {
+        const r = spawnSync(cmd, args, { stdio: "pipe", timeout: 10_000 });
+        return !r.error && (r.status === 0 || !!((r.stdout && r.stdout.length) || (r.stderr && r.stderr.length)));
+      } catch (e) { return false; }
+    },
+    // Resolve WHERE a command lives, not just whether something answers — found live in
+    // the fresh-machine test: npx injects the ephemeral package's own bin into PATH, so a
+    // bare probe says "ppk already installed" during the one run where the global install
+    // matters most (the npx cache evicts and ppk vanishes).
+    which: (cmd) => {
+      try {
+        const r = spawnSync("sh", ["-c", `command -v ${cmd}`], { stdio: "pipe", timeout: 10_000 });
+        const p = String(r.stdout || "").trim();
+        return r.status === 0 && p ? p : null;
+      } catch (e) { return null; }
+    },
+    ask: (q) =>
+      new Promise((res) => {
+        if (!process.stdin.isTTY) return res("");
+        const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+        rl.question(q, (a) => { rl.close(); res(a.trim().toLowerCase()); });
+      }),
+  };
+}
+
+// An npx-provided bin is EPHEMERAL, not an install (lives in the npx cache).
+const isPersistentInstall = (binPath) => !!binPath && !/[\\/]_npx[\\/]/.test(binPath);
+
+// "yes" = explicit y, or Enter on a real terminal (the [Y/n] default). A non-TTY ""
+// is NOT consent — unattended runs must never install or open logins on their own.
+const saidYes = (answer, isTTY) => answer === "y" || answer === "yes" || (answer === "" && isTTY);
+
+async function setup(io, opts) {
+  const steps = [];
+  io.log("pixel-perfect-kit setup\n─────────────────────────");
+
+  // 1. node — the only hard requirement for anything at all
+  const major = parseInt(process.versions.node, 10);
+  if (major < 18) {
+    io.log(`❌ node ${process.versions.node} — the kit needs Node 18+ (https://nodejs.org). Fix that first, then re-run.`);
+    return { ok: false, steps: ["node-fail"] };
+  }
+  io.log(`✓ node ${process.versions.node}`);
+
+  // 2. ppk on PATH — when run via npx there is no PERSISTENT install yet (npx's own
+  // ephemeral bin must not count, or the prompt never fires in the npx first-run)
+  const ppkPath = io.which("ppk");
+  if (opts.sourceCheckout) {
+    io.log("✓ running from a source checkout — using this copy (skipping global install)");
+    steps.push("global-skip-checkout");
+  } else if (isPersistentInstall(ppkPath)) {
+    io.log("✓ ppk already installed globally");
+    steps.push("global-present");
+  } else if (saidYes(await io.ask("ppk isn't installed globally yet — install now? (npm i -g pixel-perfect-kit) [Y/n] "), io.isTTY)) {
+    io.run("npm", ["i", "-g", "pixel-perfect-kit"]);
+    io.log("✓ installed ppk globally");
+    steps.push("global-installed");
+  } else {
+    io.log("⚠ skipped — the commands below assume `ppk` is on PATH");
+    steps.push("global-skipped");
+  }
+
+  // 3. cloudflared — marketplace review tunnels; LOCAL mode needs none
+  if (io.probe("cloudflared", ["--version"])) {
+    io.log("✓ cloudflared");
+    steps.push("cloudflared-present");
+  } else if (io.probe("brew", ["--version"]) && saidYes(await io.ask("cloudflared not found (public tunnels for marketplace review) — install now? (brew install cloudflared) [Y/n] "), io.isTTY)) {
+    io.run("brew", ["install", "cloudflared"]);
+    steps.push("cloudflared-installed");
+  } else {
+    io.log("⚠ cloudflared not installed — marketplace review needs it; LOCAL review mode works without it.\n  install later: brew install cloudflared  (or developers.cloudflare.com/cloudflared)");
+    steps.push("cloudflared-skipped");
+  }
+
+  // 4. PingHumans login — marketplace reviewers; skippable by design
+  let token = null;
+  try { token = opts.resolveToken(); } catch (e) {}
+  if (token) {
+    io.log("✓ PingHumans login found");
+    steps.push("login-present");
+  } else if (saidYes(await io.ask("PingHumans login (marketplace review rounds, small credits) — log in now? [Y/n] "), io.isTTY)) {
+    io.run("npx", ["cpyany", "setup"]);
+    steps.push("login-run");
+  } else {
+    io.log("⚠ skipped — LOCAL review mode needs no account: your agent files rounds with\n  `ppk human <name> file --local` and you review at http://localhost:8080/__review");
+    steps.push("login-skipped");
+  }
+
+  // 5. ditto — optional fast builder. NOT a binary probe: macOS ships /usr/bin/ditto
+  // (Apple's file copier — a guaranteed false positive), and ditto.site is reached via
+  // its MCP server or REST API (DITTO_API_KEY) anyway, per the ditto-finish skill.
+  if (opts.dittoApiKey) {
+    io.log("✓ DITTO_API_KEY found (ditto fast-builder path available)");
+    steps.push("ditto-key-present");
+  } else {
+    io.log("ℹ ditto (optional fast builder): connect its MCP server in your agent or set DITTO_API_KEY — the full ppk pipeline works without it");
+    steps.push("ditto-unconfigured");
+  }
+
+  // 6. teach the agent — install every skill the kit ships
+  const r = require("./agent-setup.js").install(opts.home, false);
+  io.log(r.ok ? `✓ taught your AI agent: ${r.installed.join(", ")}` : `✓ agent skills already installed (${r.message.split("\n")[0].replace(/^already installed \(|\).*$/g, "")})`);
+  steps.push(r.ok ? "skills-installed" : "skills-present");
+
+  io.log(`
+─────────────────────────
+Done. Open your AI agent and say:
+
+   "Clone https://example.com pixel-perfect."
+or "Clone https://example.com with ditto and polish it."
+
+You'll review the results: pin what looks wrong, pick a verdict button.
+(re-check anytime: ppk doctor)`);
+  return { ok: true, steps };
+}
+
+function main() {
+  const { resolveToken } = require("./human-qa.js");
+  setup(defaultIO(), {
+    home: os.homedir(),
+    sourceCheckout: fs.existsSync(path.join(PKG, ".git")),
+    resolveToken,
+    dittoApiKey: !!process.env.DITTO_API_KEY,
+  }).then((r) => process.exit(r.ok ? 0 : 1));
+}
+
+if (require.main === module) main();
+module.exports = { setup, saidYes };

package/harness/tunnel-selftest.js

@@ -0,0 +1,76 @@
+// harness/tunnel-selftest.js — guards the verified-tunnel tool (harness/tunnel.js).
+// The lesson it locks in: a human test filed against a dead or wrong tunnel burns a whole
+// QA round (hn round 1: "clone unreachable — tunnel died"), so "the tunnel serves the
+// clone" must be a CHECKED fact. Tests the pure halves offline (file:// — socket-free):
+//   - parseTunnelUrl finds the quick-tunnel url in cloudflared's log noise
+//   - verifyServes: byte-identical → ok; different bytes → named mismatch; missing → unreachable
+//   - human-qa file-time integration: no tunnel.json + no --draft → refusal names tunnel.js
+// Run: node harness/tunnel-selftest.js   (regression.js runs it too)
+"use strict";
+
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const { execFileSync } = require("child_process");
+const { pathToFileURL } = require("url");
+const { parseTunnelUrl, verifyServes, looksLikeSink } = require("./tunnel.js");
+
+let failed = 0;
+const check = (label, ok, detail) => {
+  console.log(`${ok ? "✓" : "✗"} ${label}${ok || !detail ? "" : ` — ${detail}`}`);
+  if (!ok) failed++;
+};
+
+// ── parseTunnelUrl ────────────────────────────────────────────────────────────
+const LOG = `2026-07-02T20:00:01Z INF Thank you for trying Cloudflare Tunnel.
+2026-07-02T20:00:02Z INF +--------------------------------------------------------------+
+2026-07-02T20:00:02Z INF |  Your quick Tunnel has been created! Visit it at:             |
+2026-07-02T20:00:02Z INF |  https://engines-pad-firewire-investing.trycloudflare.com     |
+2026-07-02T20:00:02Z INF +--------------------------------------------------------------+`;
+check("parses the quick-tunnel url out of log noise", parseTunnelUrl(LOG) === "https://engines-pad-firewire-investing.trycloudflare.com");
+check("no url in log → null (keeps waiting, no garbage match)", parseTunnelUrl("INF Starting tunnel connection...") === null);
+
+// ── the sink signature (--sink mode verifies delivery through the tunnel by provoking the
+//    sink's distinctive empty-POST reply — not by GET/byte-compare, the sink serves nothing) ──
+check("400 + 'empty body' IS the sink", looksLikeSink(400, "empty body for pxprobe.json — capture returned nothing (the finder/injection likely failed)."));
+check("200 from some other server is NOT the sink", !looksLikeSink(200, "ok"));
+check("a 400 with different text is NOT the sink", !looksLikeSink(400, "Bad Request"));
+
+// ── verifyServes (file:// — offline) ─────────────────────────────────────────
+const work = fs.mkdtempSync(path.join(os.tmpdir(), "ppk-tunnel-"));
+const idx = path.join(work, "index.html");
+fs.writeFileSync(idx, "<html><body>the clone</body></html>");
+const twin = path.join(work, "twin.html");
+fs.writeFileSync(twin, "<html><body>the clone</body></html>");
+const other = path.join(work, "other.html");
+fs.writeFileSync(other, "<html><body>something else entirely</body></html>");
+
+(async () => {
+  const same = await verifyServes(pathToFileURL(twin).href, idx);
+  check("byte-identical content verifies ok (+sha recorded)", same.ok && /^[0-9a-f]{16}$/.test(same.sha256));
+  const diff = await verifyServes(pathToFileURL(other).href, idx);
+  check("different bytes → NOT ok, mismatch is named", !diff.ok && /NOT clone\/index\.html/.test(diff.reason));
+  const dead = await verifyServes(pathToFileURL(path.join(work, "missing.html")).href, idx);
+  check("missing/dead url → NOT ok, reported unreachable", !dead.ok && /unreachable/.test(dead.reason));
+
+  // ── human-qa integration: refusal path names the tunnel tool ───────────────
+  const tdir = path.join(work, "targets", "t1");
+  fs.mkdirSync(path.join(tdir, "clone"), { recursive: true });
+  fs.writeFileSync(path.join(tdir, "target.json"), JSON.stringify({ name: "t1", url: "https://example.com/", width: 1280 }));
+  fs.writeFileSync(path.join(tdir, "clone", "index.html"), "<html></html>");
+  let out = "", status = 0;
+  try { out = execFileSync("node", [path.join(__dirname, "human-qa.js"), "file", "t1"], { cwd: work, stdio: "pipe" }).toString(); }
+  catch (e) { status = e.status; out = (e.stdout || "").toString() + (e.stderr || "").toString(); }
+  check("human-qa file with no tunnel.json and no --draft refuses, pointing at tunnel.js", status === 1 && /tunnel\.js/.test(out));
+
+  // with a recorded tunnel.json pointing at DEAD content, file-time re-verify refuses
+  fs.writeFileSync(path.join(tdir, "tunnel.json"), JSON.stringify({ url: pathToFileURL(path.join(work, "gone.html")).href, port: 8080 }));
+  status = 0; out = "";
+  try { out = execFileSync("node", [path.join(__dirname, "human-qa.js"), "file", "t1"], { cwd: work, stdio: "pipe" }).toString(); }
+  catch (e) { status = e.status; out = (e.stdout || "").toString() + (e.stderr || "").toString(); }
+  check("human-qa file refuses when the recorded tunnel no longer serves (hn round 1)", status === 1 && /refusing to file/.test(out));
+
+  fs.rmSync(work, { recursive: true, force: true });
+  console.log(failed ? `\n❌ tunnel-selftest: ${failed} check(s) failed.` : "\n✓ tunnel-selftest: all checks pass.");
+  process.exit(failed ? 1 : 0);
+})();