quicke2e 0.2.0

package/bin/quicke2e.mjs

@@ -0,0 +1,118 @@
+#!/usr/bin/env node
+// quicke2e CLI.
+//   quicke2e discover <baseUrl> [--start /,/admin] [--safe] [--i-own-this-data] [--reset "<cmd>"]
+//                                [--inputs inputs.json] [--storage state.json] [-o quicke2e.map.json]
+//                                [--redact ".css-selector" --redact "/regex/i" ...] [--headed|--headless]
+//   quicke2e run <spec.mjs> [--base url] [--engine jev|local|vercel] [--map quicke2e.map.json]
+//                            [--runs N] [--emit dir] [--trace dir] [--video dir] [--headed|--headless] [--allow-weak] [--only name]
+//   quicke2e check <spec.mjs> [--base url]
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { chromium, runOnce, SNAPSHOT, settle, checkGoal } from "../src/loop.mjs";
+import { discover } from "../src/discover.mjs";
+import { parseRedactArg } from "../src/redact.mjs";
+
+const argv = process.argv.slice(2);
+const cmd = argv.shift();
+const opt = (name, dflt) => { const i = argv.indexOf(name); return i < 0 ? dflt : argv[i + 1]; };
+const flag = (name) => argv.includes(name);
+const FLAGS = new Set(["--safe", "--i-own-this-data", "--headed", "--headless", "--allow-weak", "--json"]);
+const positional = argv.filter((a, i) => !a.startsWith("-") && !(i > 0 && argv[i - 1].startsWith("-") && !FLAGS.has(argv[i - 1])));
+const out = (s = "") => process.stdout.write(s + "\n");
+// Headed when a person runs it (interactive terminal, a display available); headless in CI, with no
+// display, or when the output is piped. --headed / --headless force either.
+const headless = flag("--headless") ? true : flag("--headed") ? false
+  : Boolean(process.env.CI) || !process.stdout.isTTY
+    || (process.platform === "linux" && !process.env.DISPLAY && !process.env.WAYLAND_DISPLAY);
+
+async function loadFlows(file) {
+  const m = await import(pathToFileURL(path.resolve(file)).href);
+  const v = m.default ?? m.flows ?? m.FLOWS;
+  const flows = Array.isArray(v) ? v : [v];
+  const only = opt("--only");
+  return only ? flows.filter((f) => f.name === only) : flows;
+}
+
+// A spec whose assertion already holds on the start page proves nothing (README finding #4).
+async function weak(flow, base, browser) {
+  const ctx = await browser.newContext({ ...(flow.storageState ? { storageState: flow.storageState } : {}) });
+  if (flow.expectSeen?.length) await ctx.addInitScript("window.__jevSeen = [];");
+  const page = await ctx.newPage();
+  try {
+    await page.goto(base.replace(/\/$/, "") + (flow.start || "/"), { waitUntil: "domcontentloaded" });
+    await settle(page);
+    const snap = await page.evaluate(`(${SNAPSHOT})()`);
+    return await checkGoal(page, flow, snap);
+  } finally { await ctx.close(); }
+}
+
+const usage = () => { out(fs.readFileSync(new URL(import.meta.url), "utf8").split("\n").slice(1, 7).map((l) => l.replace(/^\/\/ ?/, "")).join("\n")); process.exit(2); };
+
+if (cmd === "discover") {
+  const base = positional[0]; if (!base) usage();
+  const inputs = opt("--inputs") ? JSON.parse(fs.readFileSync(opt("--inputs"), "utf8")) : {};
+  const dbrowser = await chromium.launch({ headless });
+  const map = await discover({ base, browser: dbrowser, start: (opt("--start", "/")).split(","), mode: flag("--safe") ? "safe" : "full",
+    allowRemote: flag("--i-own-this-data"), reset: opt("--reset"), storageState: opt("--storage"), inputs,
+    maxPages: Number(opt("--max-pages", 40)), log: (m) => out("  " + m),
+    redact: argv.flatMap((a, i) => (a === "--redact" ? [argv[i + 1]] : [])).map(parseRedactArg) });
+  await dbrowser.close();
+  const file = opt("-o", "quicke2e.map.json");
+  fs.writeFileSync(file, JSON.stringify(map, null, 2));
+  out(`\n${map.pages.length} pages, ${map.edges.length} edges, ${map.pages.reduce((n, p) => n + p.forms.length, 0)} forms in ${(map.ms / 1000).toFixed(1)}s -> ${file}`);
+  process.exit(0);
+}
+
+if (cmd === "run" || cmd === "check") {
+  const file = positional[0]; if (!file) usage();
+  const flows = await loadFlows(file);
+  const base = opt("--base", process.env.APP_BASE || "http://localhost:3000");
+  const engine = opt("--engine", "jev");
+  const runs = Number(opt("--runs", 1));
+  const map = opt("--map") ? JSON.parse(fs.readFileSync(opt("--map"), "utf8")) : null;
+  const browser = await chromium.launch({ headless });
+  let failed = 0;
+  const all = [];
+  const { weakSecretKeys } = await import("../src/secret.mjs");
+  for (const flow of flows) {
+    const fbase = flow.base || base;
+    const weakKeys = weakSecretKeys(flow.inputs);
+    if (weakKeys.length) out(`note: ${flow.name}: ${weakKeys.join(", ")} ${weakKeys.length > 1 ? "are" : "is a"} weak secret${weakKeys.length > 1 ? "s" : ""}`
+      + ` (short or a common word). It is kept out of the goal, but the page may echo it to the engine.`);
+    // An app that is not running is the most common first failure: say so in one line, not a stack trace.
+    let isWeak;
+    try { isWeak = await weak(flow, fbase, browser); }
+    catch (e) {
+      out(`UNREACHABLE     ${flow.name}: ${fbase.replace(/\/$/, "")}${flow.start || "/"} (${String(e.message || e).split("\n")[0].replace(/^page\.goto: /, "")}). Is the app running?`);
+      failed++; continue;
+    }
+    if (isWeak) {
+      out(`WEAK_ASSERTION  ${flow.name}: the assertion is already true on ${flow.start || "/"} before any work.`);
+      if (cmd === "check" || !flag("--allow-weak")) { failed++; continue; }
+    } else if (cmd === "check") { out(`ok              ${flow.name}`); continue; }
+    for (let k = 0; k < runs; k++) {
+      const trace = opt("--trace") ? path.join(opt("--trace"), `${flow.name}-${Date.now()}.json`) : undefined;
+      if (trace) fs.mkdirSync(opt("--trace"), { recursive: true });
+      const rec = await runOnce({ flow, engine, browser, base: fbase, trace, ...(map ? { map } : {}),
+        ...(opt("--video") ? { video: opt("--video") } : {}) });
+      all.push(rec);
+      if (!rec.passed) failed++;
+      out(`${rec.passed ? "PASS" : "FAIL"}  ${flow.name.padEnd(28)} ${String(rec.steps.length).padStart(2)} steps  `
+        + `${(rec.wallMs / 1000).toFixed(1).padStart(5)}s  $${rec.cost.toFixed(5)}  ${rec.outcome}`
+        + (rec.route?.pattern ? `  via map -> ${rec.route.pattern}` : "") + (rec.error ? `  ${rec.error}` : ""));
+      if (rec.passed && opt("--emit")) {
+        const { generate } = await import("../codegen/codegen.mjs");
+        fs.mkdirSync(opt("--emit"), { recursive: true });
+        const f = path.join(opt("--emit"), `${flow.name}.spec.ts`);
+        try { fs.writeFileSync(f, generate(rec, flow).code); out(`      emitted ${f}`); }
+        catch (e) { out(`      not emitted: ${e.message}`); }
+      }
+    }
+  }
+  await browser.close();
+  if (flag("--json")) out(JSON.stringify(all));
+  process.exit(failed ? 1 : 0);
+}
+
+usage();

package/codegen/codegen.mjs

@@ -0,0 +1,240 @@
+import { isSecretKey, scrubText } from "../src/secret.mjs";
+// codegen: a PASSED run record -> a deterministic Playwright spec.
+//
+// Why this exists: the decision model runs on MLX, which is Apple Silicon only, so a Linux CI
+// runner cannot load it. Exploring once on a Mac and replaying a plain Playwright spec in CI is
+// the only free path to a merge gate. (README, "A CI merge gate -- not yet".)
+//
+// Three rules, all of them load-bearing:
+//   1. USER-FACING LOCATORS ONLY. getByRole / getByLabel / getByText. Never CSS, never the
+//      data-jev-node stamp -- snapshot.js:105 assigns it per snapshot, so it does not exist at
+//      replay time and a trace's `target` ordinal is meaningless across runs (snapshot.js:58,64).
+//   2. TEXT COMES FROM THE SPEC. The trace records which inputs KEY matched (loop.mjs specKey),
+//      never the value. The spec file reads process.env / INPUTS, so no credential is written
+//      into a trace on disk.
+//   3. THE ASSERTION IS THE TEST. expectUrl/expect/expectState map 1:1 onto real expect() calls;
+//      nothing is invented and nothing is softened.
+
+const IDENT = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+const q = (s) => JSON.stringify(String(s));
+// The snapshot's own role vocabulary -> a real ARIA role Playwright's role engine understands.
+// Identical table to act() in loop.mjs:226-228, on purpose: the spec must resolve the same way
+// the exploratory run did, or it is testing something else.
+const ARIA = { textbox: "textbox", password: "textbox", button: "button", link: "link",
+  option: "option", combobox: "combobox", tab: "tab", checkbox: "checkbox", switch: "switch",
+  radio: "radio", menuitem: "menuitem" };
+
+// ---------------------------------------------------------------- step pruning
+// An exploratory trace wanders. Three classes of junk, and only ONE of them is safe to drop
+// on static grounds:
+//
+//   DROP (mechanical, always safe):
+//     - WAIT           : no target, no label. Playwright auto-waits on every locator action,
+//                        so a WAIT is an artefact of the loop's snapshot cadence, not a step.
+//     - stale:true     : act() threw on all four strategies, so NOTHING happened to the page.
+//                        loop.mjs:317,322 pushes the step and `continue`s without acting.
+//     - noSpecValue / doneRejected / retried : the same shape -- recorded, not performed.
+//     - DONE / BLOCKED : meta choices, never an interaction.
+//
+//   KEEP UNLESS REPLAY SAYS OTHERWISE (the dangerous class):
+//     - a repeated CLICK on the same {op,label} at the same url. It LOOKS redundant. Yesterday's
+//       finding is that such a click was twice the stepping stone the model needed -- e.g. the
+//       first click opens a portal and the second lands in it, or a debounced control needs the
+//       second event. Static analysis cannot tell those apart from a double-fire.
+//       So: prune by REPLAY, not by rule. `prune()` below removes one candidate at a time and
+//       re-runs the generated spec; a step whose removal still passes was not load-bearing.
+export function classify(steps) {
+  const out = [];
+  for (const s of steps) {
+    let drop = null;
+    if (s.op === "WAIT") drop = "WAIT: playwright auto-waits";
+    else if (s.op === "DONE" || s.op === "BLOCKED") drop = `${s.op}: meta choice, no interaction`;
+    else if (s.stale) drop = "stale: act() resolved nothing, the page never changed";
+    else if (s.noSpecValue) drop = "noSpecValue: run aborted here, nothing typed";
+    else if (!s.label) drop = "no label: nothing to build a locator from";
+    else if (s.op === "TYPE_TEXT" && !s.inputKey) drop = "TYPE_TEXT with no inputKey: re-run the trace on a loop.mjs that records it";
+    out.push({ step: s, drop });
+  }
+  // A CLICK whose {op,label,url} repeats an EARLIER kept step is only a *candidate* for pruning.
+  const seen = new Set();
+  for (const o of out) {
+    if (o.drop) continue;
+    const k = `${o.step.op}|${o.step.label}|${o.step.url}`;
+    if (seen.has(k)) o.candidate = "repeat of an earlier identical step -- prune only if replay still passes";
+    seen.add(k);
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------- locators
+//
+// `via` records which rung of act() resolved (loop.mjs:229-241), and it is the ONLY free evidence
+// about the emitted locator. Measured across every saved run in `runs/` (2,751 resolved steps):
+//
+//     node 2738 (99.5%)   role 12 (0.44%)   role~ 1 (0.04%)   text 0
+//
+// So `via` is decisive where it exists and SILENT on 99.5% of steps: the stamped node wins first,
+// so the role rungs are never exercised and nothing is learned about them. Two consequences:
+//   - honour it where it exists. via "role~" means getByRole(..., exact:true) PROVABLY failed at
+//     action time, so emitting exact:true there emits a locator known to match nothing.
+//   - it cannot be the mechanism. For the 99.5% the emitted locator is unverified, which is why
+//     verifyLocators() below re-walks the flow and counts matches per step.
+export const STRATEGY = { exact: "exact", loose: "loose", text: "text" };
+function strategyFor(s) {
+  if (s.locatorStrategy) return s.locatorStrategy;   // measured by verifyLocators(), wins
+  if (s.via === "role~") return STRATEGY.loose;      // exact provably failed at action time
+  if (s.via === "text") return STRATEGY.text;        // both role rungs provably failed
+  return STRATEGY.exact;                             // via "node"/"role": assume, then verify
+}
+export function locator(s, { page = "page", inputs, weakKeys = [] } = {}) {
+  const role = ARIA[s.role];
+  const name = s.label;
+  // SECURITY (audit): a label that echoes a secret spec value is matched by the text before it.
+  // A label may already carry a placeholder (a weak-secret echo scrubbed at the source), or carry a
+  // strong secret that is scrubbed here: either way, match by the text before it.
+  const scrubbed = scrubText(name, inputs, { weakKeys });
+  if (role && (scrubbed !== String(name ?? "") || /<[\w ]+>/.test(String(name ?? "")))) {
+    const prefix = scrubbed.split(/<[^>]+>/)[0].trim();
+    // Never emit an empty name (`/^/` matches every control -- audit FP1). Fail loudly instead.
+    if (!prefix) throw new Error(`cannot emit a stable locator for a ${role}: its accessible name is entirely a secret or redacted value`);
+    return `${page}.getByRole(${q(role)}, { name: new RegExp(${q("^" + escapeRe(prefix))}) })`;
+  }
+  const st = strategyFor(s);
+  // getByLabel is idiomatic for a form field and matches how snapshot.js:41 found the name
+  // (label[for=id]). But accName() also falls back to placeholder, aria-label and the name
+  // attribute (snapshot.js:43-51), which getByLabel cannot see -- measured on login.html,
+  // getByLabel("Email") returns 2 matches and violates strict mode. getByRole is what act()
+  // used, so it is the primary.
+  // FIX (v1, TicketBay D4): a price in the accessible name ("Pay €121.54") breaks the replay on
+  // any price change. Match the stable prefix instead.
+  const priced = /^(.*?\S)\s*(?:[€$£]\s?\d[\d.,]*|\d[\d.,]*\s?[€$£]).*$/.exec(name || "");
+  if (role && priced) return `${page}.getByRole(${q(role)}, { name: new RegExp(${q("^" + escapeRe(priced[1]))}) })`;
+  if (role && st === STRATEGY.exact) return `${page}.getByRole(${q(role)}, { name: ${q(name)}, exact: true })`;
+  // .first() is deliberate here and ONLY here: a loose name is a substring match, so >1 candidate
+  // is expected. Measured on the rename pair, .first() can bind the WRONG control (login.html's
+  // "Email" loosely matches both the login field and the signup form's "Work email"), so this
+  // rung is emitted only when a tighter one was measured to fail.
+  if (role && st === STRATEGY.loose) return `${page}.getByRole(${q(role)}, { name: ${q(name)} }).first()`;
+  return `${page}.getByText(${q(name)}, { exact: true }).filter({ visible: true }).first()`;
+}
+
+function actionLine(s, inputs, weakKeys) {
+  const loc = locator(s, { inputs, weakKeys });
+  if (s.op === "SELECT") return `  await page.getByRole("combobox", { name: ${q(s.control)}, exact: true }).selectOption({ label: ${q(s.option)} });`;
+  // audit: `INPUTS.["discount code"]` is a SyntaxError -- bracket access has no dot.
+  if (s.op === "TYPE_TEXT") return `  await ${loc}.fill(${IDENT.test(s.inputKey) ? `INPUTS.${s.inputKey}` : `INPUTS[${q(s.inputKey)}]`});`;
+  return `  await ${loc}.click();`;
+}
+
+// ---------------------------------------------------------------- assertions
+// Every branch mirrors exactly what the loop checks, so a green spec means the same thing a
+// DONE_VERIFIED meant.
+function assertions(flow, waitMs) {
+  const out = [];
+  // MEASURED (2026-09-22): the first generated create-campaign spec went 20/21 serially and 4/6
+  // under parallel workers, always failing on the terminal toHaveURL. Playwright's default expect
+  // timeout is 5,000 ms; the exploratory run measured 3,251 ms between the last click and
+  // DONE_VERIFIED on an idle app, so a loaded app overruns the default. The exploratory run is the
+  // only honest source for this number -- it is the one thing that watched the app do the work.
+  const t = waitMs ? `, { timeout: ${waitMs} }` : "";
+  if (flow.expectUrl)                                   // loop.mjs:206 new RegExp(...).test(url)
+    out.push(`  await expect(page).toHaveURL(new RegExp(${q(flow.expectUrl)})${t});`);
+  for (const w of flow.expectSeen || [])                // transient text (a toast): poll for it
+    out.push(`  await expect(page.getByText(${q(w)}).first()).toBeVisible(${t ? `{ timeout: ${waitMs} }` : ""});`);
+  for (const w of flow.expect || [])                    // loop.mjs:208-212 innerText substring,
+    out.push(`  await expect(page.locator("body")).toContainText(${q(w)}${t});`);  // both sides normalised
+  for (const w of flow.expectState || []) {             // loop.mjs:192-202 stateOk()
+    const role = ARIA[w.role] || w.role;
+    const loc = `page.getByRole(${q(role)}, { name: ${q(w.name)}, exact: true })`;
+    if (w.value != null) {
+      // snapshot.js:56-72 selectionOf(): a native <select> reports its selected option's label
+      // (readable as the element's value); a <button role=combobox> reports its rendered text.
+      // `tag` on the recorded control says which. Default to text, because that is the Radix
+      // case and the one the substring assertion got wrong (README 2026-09-22).
+      out.push(w.tag === "select" || w.tag === "input"
+        ? `  await expect(${loc}).toHaveValue(new RegExp(${q(escapeRe(w.value))}));`
+        : `  await expect(${loc}).toContainText(${q(w.value)});`);
+    }
+    if (w.checked != null)  out.push(`  await expect(${loc})${w.checked ? "" : ".not"}.toBeChecked();`);
+    if (w.selected != null) out.push(`  await expect(${loc}).toHaveAttribute("aria-selected", ${q(String(w.selected))});`);
+    if (w.expanded != null) out.push(`  await expect(${loc}).toHaveAttribute("aria-expanded", ${q(String(w.expanded))});`);
+  }
+  if (!out.length) out.push(`  // NO ASSERTION IN THE FLOW SPEC -- this spec proves nothing. README finding #4.`);
+  return out;
+}
+const escapeRe = (s) => String(s).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+// ---------------------------------------------------------------- the writer
+export function generate(rec, flow, { title = flow.name, dropCandidates = [] } = {}) {
+  if (!rec.passed) throw new Error(`refusing to generate from a run that did not pass (outcome=${rec.outcome})`);
+  const classified = classify(rec.steps);
+  const kept = [], dropped = [];
+  for (const [i, c] of classified.entries()) {
+    if (c.drop) { dropped.push({ n: c.step.n, op: c.step.op, label: c.step.label, why: c.drop }); continue; }
+    if (dropCandidates.includes(c.step.n)) { dropped.push({ n: c.step.n, op: c.step.op, label: c.step.label, why: "pruned by replay: removing it still passed" }); continue; }
+    kept.push(c);
+  }
+
+  const lines = [];
+  lines.push(`// GENERATED from a passed exploratory run -- do not hand-edit; regenerate.`);
+  lines.push(`// flow: ${flow.name}   engine: ${rec.engine}   outcome: ${rec.outcome}   ${rec.steps.length} steps in ${rec.wallMs} ms`);
+  lines.push(`// Every locator below is an ACCESSIBLE NAME. A rename in the app breaks this spec --`);
+  lines.push(`// that is the intended signal, not a defect. See replay-or-heal.mjs.`);
+  lines.push(`import { test, expect } from "@playwright/test";`);
+  lines.push(``);
+  lines.push(`const BASE = process.env.APP_BASE ?? ${q(rec.base)};`);
+  if (Object.keys(flow.inputs || {}).some(isSecretKey))
+    lines.push(`const missing = (v) => { throw new Error(\`set \${v}: secret spec values are read from the environment only\`); };`);
+  lines.push(`const INPUTS = {`);
+  for (const [k, v] of Object.entries(flow.inputs || {}))
+    // SECURITY (audit): a secret-looking key gets NO literal default -- the spec reads it from the
+    // environment only, so a credential is never written into a generated file.
+    lines.push(isSecretKey(k)
+      ? `  ${IDENT.test(k) ? k : q(k)}: process.env.${envName(flow.name, k)} ?? missing(${q(envName(flow.name, k))}),`
+      : `  ${IDENT.test(k) ? k : q(k)}: process.env.${envName(flow.name, k)} ?? ${q(v)},`);
+  lines.push(`};`);
+  lines.push(``);
+  lines.push(`test(${q(title)}, async ({ page }) => {`);
+  lines.push(`  await page.goto(BASE + ${q(flow.start || "/")});`);
+  // MAP (v1): the run was routed to its target page before the step loop. Replay the same walk.
+  for (const h of rec.route?.hops || []) {
+    if (h.goto) lines.push(`  await page.goto(BASE + ${q(new URL(h.goto).pathname + new URL(h.goto).search)});`);
+    else if (h.ok) lines.push(`  await page.getByRole(${q(h.role)}, { name: ${q(h.label)}, exact: true }).first().click();`);
+  }
+
+  let lastUrl = null;
+  for (const c of kept) {
+    const s = c.step;
+    // A url change between two kept steps is a navigation the exploratory run observed. Asserting
+    // it turns a silent wrong-page click into a named failure at the step that caused it.
+    if (lastUrl !== null && s.url !== lastUrl)
+      lines.push(`  await expect(page).toHaveURL(new RegExp(${q(escapeRe(new URL(s.url).pathname))}));`);
+    lastUrl = s.url;
+    if (c.candidate) lines.push(`  // kept: ${c.candidate}`);
+    lines.push(actionLine(s, flow.inputs, rec.weakEchoed || []));
+  }
+  lines.push(``);
+  lines.push(`  // ---- the assertion. This, not the steps, is the test.`);
+  // Size the terminal wait from what the exploratory run MEASURED between its last action and
+  // DONE_VERIFIED, x3 for headroom, floored at Playwright's own default so we never shorten it.
+  const lastActed = [...rec.steps].reverse().find((s) => s.wallAt != null);
+  const leg = lastActed ? Math.max(0, (rec.tLoopEnd ?? rec.wallMs) - lastActed.wallAt) : 0;
+  for (const a of assertions(flow, Math.max(5000, Math.round(leg * 3 / 500) * 500))) lines.push(a);
+  lines.push(`});`);
+  lines.push(``);
+  // The sidecar: everything needed to RE-EXPLORE this flow when the spec breaks. The spec is
+  // derived; this is the source. Keep them next to each other in the repo.
+  // NB `defaultBase`, NOT `base`. loop.mjs:245 resolves `flow.base || base || $APP_BASE`, so a
+  // `base` key on the flow object OUTRANKS the explicit argument -- which silently sent the heal
+  // re-exploration back to the page the spec was generated from. Measured: the heal loop reported
+  // re-explore ok=true and then emitted a byte-identical spec that failed again.
+  const sidecar = { name: flow.name, start: flow.start, defaultBase: rec.base, maxSteps: flow.maxSteps,
+    inputs: flow.inputs, goal: flow.goal, done: flow.done,
+    expectUrl: flow.expectUrl, expect: flow.expect, expectState: flow.expectState,
+    generatedFrom: { engine: rec.engine, outcome: rec.outcome, wallMs: rec.wallMs, steps: rec.steps.length },
+    locators: kept.map((c) => ({ n: c.step.n, op: c.step.op, role: c.step.role, name: c.step.label })) };
+  return { code: lines.join("\n"), sidecar, kept: kept.map((c) => c.step.n), dropped, classified,
+    measuredLegMs: leg };
+}
+const envName = (flow, k) =>
+  (flow + "_" + k).toUpperCase().replace(/[^A-Z0-9]+/g, "_");

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "quicke2e",
+  "version": "0.2.0",
+  "type": "module",
+  "description": "Plain-English end-to-end browser tests: a small decision model picks each click, your spec supplies every typed value, code decides pass/fail, and a passing run exports a Playwright spec.",
+  "keywords": [
+    "e2e",
+    "end-to-end",
+    "testing",
+    "playwright",
+    "browser-testing",
+    "plain-english",
+    "ai-testing",
+    "decision-model",
+    "jev",
+    "exploratory-testing"
+  ],
+  "homepage": "https://github.com/dmoka/quicke2e#readme",
+  "bugs": {
+    "url": "https://github.com/dmoka/quicke2e/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dmoka/quicke2e.git"
+  },
+  "license": "MIT",
+  "main": "src/loop.mjs",
+  "bin": {
+    "quicke2e": "bin/quicke2e.mjs"
+  },
+  "exports": {
+    ".": "./src/loop.mjs",
+    "./discover": "./src/discover.mjs",
+    "./route": "./src/route.mjs",
+    "./codegen": "./codegen/codegen.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "codegen/codegen.mjs",
+    "skill",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mjs",
+    "fixtures": "node fixtures/run.mjs --checkout ."
+  },
+  "dependencies": {
+    "playwright": "^1.50.0"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.63.0"
+  }
+}

package/skill/quicke2e/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: quicke2e
+description: Invent and run exploratory browser test cases for a web app with quicke2e. Maps the app, reads its source for business rules, writes goal-based specs with deterministic assertions, runs them with the Jev decision model, and reports findings. Use when the user says "quicke2e", "explore my app", "find UI bugs", "write browser test cases", or wants adversarial end-to-end checks without writing selectors.
+---
+
+# quicke2e — invent the cases, let Jev drive, let code judge
+
+Division of labour. Do not blur it:
+- **You (the big model)** invent the cases and write the spec files. Once, offline.
+- **Jev** drives the browser for each spec. Cheap, fast, many times. It only ever picks one of the options the tool offers.
+- **Code** decides pass or fail. Never you, never Jev.
+
+## 1. Map the app
+
+Ask for the base URL if you do not have it. Then:
+
+```bash
+npx quicke2e discover http://localhost:3000 --start / -o quicke2e.map.json
+```
+
+- Full crawl is the default on localhost: it submits forms. Use a throwaway database (`--reset "<cmd>"` to restore seed data).
+- Any other host: use `--safe`, unless the user confirms the data is disposable (`--i-own-this-data`).
+- Read the map: pages, edges, forms, fields, options, and what each form submit led to.
+
+## 2. Read the rules in the source
+
+The map shows WHERE things are. The source shows WHAT MUST BE TRUE. Read, in this order:
+domain/business logic (pricing, limits, windows, permissions, state machines), validation schemas,
+API/route handlers, seed data (real names, codes, dates you can use as inputs), README/PRD.
+List every rule as one line: `rule — file:line`.
+
+## 3. Invent the cases
+
+For each form and each rule, write cases in three kinds:
+1. **Happy path** — the main job of the page works.
+2. **Boundary** — the edge of a rule: last valid day, max quantity, code at its limit.
+3. **Refusal** — the rule must say no: expired window, sold out, wrong code, a started event, a user without the role.
+
+Prefer the cases a scripted suite does not have. Check the existing tests first and say which rules they skip.
+
+## 4. Write the spec
+
+One file, `quicke2e.spec.mjs`, exporting an array:
+
+```js
+export default [
+  {
+    name: "refund-refused-after-start",
+    start: "/orders",
+    maxSteps: 14,
+    inputs: { email: "buyer@example.com" },          // every typed value comes from here
+    goal: "Open the order for the concert that already started and request a refund",
+    done: "The refund request was refused",
+    expectUrl: "/orders/\\d+$",                        // THE ASSERTION
+    expect: ["Refunds close when the event starts"],   // THE ASSERTION
+  },
+];
+```
+
+Rules for the assertion — the assertion IS the test:
+- Assert only what is true AFTER the work: a URL that cannot exist before, text that did not exist before, or a control state via `expectState: [{ role, name, value | checked | selected }]`.
+- `expect` is text a sighted user sees. It ignores form controls (a value the test typed or chose is not a result) and hidden text. To check a chosen option or a field's value, use `expectState`. For a toast that disappears, use `expectSeen`.
+- Never assert a label, a button text, or a word that is on the page anyway.
+- For a refusal, assert the refusal text AND that the success state is absent (use a URL that only the refusal page has, or text only the refusal shows).
+- Field keys in `inputs` must match the field label ("email" matches "Email"). Labels that share a substring ("Email" and "Billing email") get the same value: give such fields distinct keys or avoid the case.
+
+If the page shows sensitive data the engine must not see (recovery codes, saved cards, personal
+data), declare it in the spec: `redact: [".backup-code", "#saved-cards", /recovery code \S+/i]`
+(CSS selectors and text patterns). Nothing is guessed automatically. Secret spec inputs (password,
+api key, card number, token, …) are always kept out.
+
+## 5. Check, then run
+
+```bash
+npx quicke2e check quicke2e.spec.mjs --base http://localhost:3000     # rejects WEAK_ASSERTION specs
+npx quicke2e run quicke2e.spec.mjs --base http://localhost:3000 --map quicke2e.map.json --runs 3
+```
+
+A `WEAK_ASSERTION` means the assertion already holds on the start page: rewrite the assertion, never add `--allow-weak` to make it go away.
+
+## 6. Report
+
+For each failing spec: is it an APP bug (the rule in the source is violated) or a SPEC/TOOL problem (the run never reached the place)? Read the trace (`--trace runs/`) before you decide. The outcome tells you: `DONE_VERIFIED` = pass; `MAX_STEPS`/`MODEL_BLOCKED` = it got lost; a wrong final page with the success text visible = the app broke a rule.
+
+- **Never edit a spec to make it pass.** A red refusal case is the finding.
+- For each app bug: the rule (file:line), the spec name, what happened. Suggest the lowest-level test that would catch it.
+- For a flow that must stay green, emit a Playwright spec from a passing run: `--emit e2e/generated/`.

package/src/discover-pattern.mjs

@@ -0,0 +1,8 @@
+// /events/42/checkout -> /events/:id/checkout. Numeric, uuid-ish and long mixed slugs are ids.
+export function pattern(u) {
+  const url = new URL(u);
+  const segs = url.pathname.split("/").map((s) =>
+    /^\d+$/.test(s) || /^[0-9a-f]{8}-[0-9a-f-]{20,}$/i.test(s) || /^[0-9a-f]{12,}$/i.test(s)
+      || (s.length >= 16 && /\d/.test(s) && /[a-z]/i.test(s)) ? ":id" : s);
+  return segs.join("/") || "/";
+}