@midhunxavier/code-flow 0.0.0-stage → 0.1.0-preview.1

package/src/integrity.js

@@ -0,0 +1,259 @@
+import { git, gitError } from "./git.js";
+const TEST_FILE = /(^|\/)(tests?|__tests__|specs?|e2e)\/|[._-](test|spec)s?\.[a-z0-9]+$|(^|\/)test_[^/]+\.py$|Tests?\.(java|kt|cs|swift|scala)$|_spec\.rb$/i;
+const WORKFLOW = /(^|\/)\.github\/workflows\//;
+const TEST_CONFIG = /(^|\/)(jest|vitest|vite|playwright|cypress|karma|ava|babel)\.config\.[cm]?[jt]s$|(^|\/)\.mocharc(\.[a-z]+)?$|(^|\/)(pytest\.ini|tox\.ini|setup\.cfg|conftest\.py|\.coveragerc|phpunit\.xml(\.dist)?)$|(^|\/)\.github\/workflows\//;
+const SKIP = /\b(?:describe|it|test|context|suite|bench)(?:\.(?:concurrent|sequential|each))*\.(?:skip|only|todo|skipIf|runIf|fails|failing)\b|\b(?:xit|xdescribe|xtest|fit|fdescribe)\s*\(|\bthis\.skip\s*\(|@pytest\.mark\.(?:skip|skipif|xfail)\b|\bpytest\.(?:skip|xfail|importorskip)\s*\(|\bself\.skipTest\s*\(|@unittest\.(?:skip\w*|expectedFailure)\b|@(?:Disabled|Ignore)\b|\bt\.(?:Skip(?:Now|f)?|skip|todo)\s*\(|#\[ignore\]|\{\s*(?:skip|todo)\s*:\s*(?:true\b|["'`])/;
+const ASSERTION = /\b(assert\w*|expect|should|t\.(?:Error|Fatal|Fail)\w*|require\.\w+|deepEqual|strictEqual|notEqual|toBe\w*|toEqual|toMatch\w*|toThrow\w*|toHave\w*|toContain\w*)\b/;
+const isTestFile = (path) => TEST_FILE.test(path);
+const SOURCE = /\.(?:[cm]?[jt]sx?|py|go|rs|java|kt|kts|scala|rb|cs|swift|php|c|cc|cpp|h|hpp|m|mm|ex|exs|dart|lua|vue|svelte)$/i;
+const FIXTURE = /(^|\/)(__snapshots__|__fixtures__|fixtures?|testdata|test-data|golden|snapshots?)\/|\.snap$/i;
+const isPlainSource = (path) => SOURCE.test(path) && !TEST_FILE.test(path) && !TEST_CONFIG.test(path) && !FIXTURE.test(path);
+const RUNNER_CONFIG = /(^|\/)(jest|vitest|playwright|cypress|karma|ava)\.config\.[cm]?[jt]s$|(^|\/)\.mocharc(\.[a-z]+)?$|(^|\/)(pytest\.ini|conftest\.py)$/;
+const isTestSide = (path) => TEST_FILE.test(path) || FIXTURE.test(path) || RUNNER_CONFIG.test(path);
+const isRunnerConfig = (path) => RUNNER_CONFIG.test(path);
+const SHARED_CONFIG = /(^|\/)(package\.json|pyproject\.toml)$/;
+const changesRunner = (i) => i.kind === "test-script" || i.kind === "test-config" && (RUNNER_CONFIG.test(i.file) || SHARED_CONFIG.test(i.file));
+function unverifiedIssue(reason) {
+  return { kind: "unverified", file: "", detail: `couldn't verify test integrity: ${reason.split("\n")[0].slice(0, 300)}`, severity: "high" };
+}
+function scriptsRun(check) {
+  const names = /* @__PURE__ */ new Set(["test"]);
+  for (const m of (check ?? "").matchAll(/\b(?:npm|pnpm|yarn|bun)(?:\s+run)?\s+([\w:.-]+)/g)) names.add(m[1]);
+  return [...names];
+}
+function parseJson(raw) {
+  try {
+    return raw ? JSON.parse(raw) : void 0;
+  } catch {
+    return void 0;
+  }
+}
+const RUNNER_KEYS = ["jest", "vitest", "mocha", "ava"];
+function pytestSettings(toml) {
+  if (toml === void 0) return void 0;
+  const lines = [];
+  let inside = false;
+  for (const raw of toml.split("\n")) {
+    const line = raw.trim();
+    const header = /^\[\[?([^\]]+)\]\]?(?:\s*#.*)?$/.exec(line);
+    if (header) inside = /^tool\.pytest(\.|$)/.test(header[1].replace(/[\s"']/g, ""));
+    if (inside && line && !line.startsWith("#")) lines.push(line);
+  }
+  return lines.length ? lines.join("\n") : void 0;
+}
+async function fileAt(cwd, ref, path) {
+  const res = await git(["show", "--no-textconv", `${ref}:${path}`], cwd);
+  return res.code === 0 ? res.stdout : void 0;
+}
+async function inspectChanges(cwd, from, to = "HEAD", opts = {}) {
+  const issues = [];
+  const range = `${from}..${to}`;
+  const statusArgs = ["diff", "--no-ext-diff", "--no-textconv", "--name-status", "-M", "-z", range];
+  const status = await git(statusArgs, cwd);
+  if (status.code !== 0) return [unverifiedIssue(gitError(statusArgs, status))];
+  const tokens = status.stdout.split("\0").filter(Boolean);
+  const changes = [];
+  for (let i = 0; i < tokens.length; i++) {
+    const code = tokens[i][0];
+    if (code === "R" || code === "C") {
+      const [from2, to2] = [tokens[i + 1], tokens[i + 2]];
+      if (code === "R" && isTestFile(from2) && !isTestFile(to2)) {
+        issues.push({ kind: "deleted-test", file: from2, detail: `test file renamed to \`${to2}\`, so it no longer runs as a test`, severity: "high" });
+      }
+      changes.push({ code: "R", path: to2 });
+      i += 2;
+    } else {
+      changes.push({ code, path: tokens[i + 1] });
+      i += 1;
+    }
+  }
+  for (const { code, path } of changes) {
+    if (code === "D" && isTestFile(path)) issues.push({ kind: "deleted-test", file: path, detail: "test file deleted", severity: "high" });
+    else if (TEST_CONFIG.test(path)) {
+      const what = WORKFLOW.test(path) ? "CI workflow" : "test configuration";
+      issues.push({ kind: "test-config", file: path, detail: code === "D" ? `${what} deleted` : `${what} changed`, severity: code === "D" ? "high" : "medium" });
+    }
+  }
+  const added = new Set(changes.filter((c) => c.code === "A").map((c) => c.path));
+  const patchArgs = ["diff", "--no-ext-diff", "--no-textconv", "-U0", "--no-color", "-M", range];
+  const patch = await git(patchArgs, cwd);
+  if (patch.code !== 0) return [...issues, unverifiedIssue(gitError(patchArgs, patch))];
+  let file = "";
+  let header = false;
+  let lineNo = 0;
+  const skips = [];
+  const counts = /* @__PURE__ */ new Map();
+  for (const line of patch.stdout.split("\n")) {
+    if (line.startsWith("diff --git ")) {
+      header = true;
+      continue;
+    }
+    if (line.startsWith("@@")) {
+      header = false;
+      lineNo = Number(/\+(\d+)/.exec(line)?.[1] ?? 0);
+      continue;
+    }
+    if (header) {
+      if (line.startsWith("+++ ")) file = line.replace(/^\+\+\+ (b\/)?/, "");
+      continue;
+    }
+    if (line.startsWith("+")) {
+      const text = line.slice(1);
+      if (SKIP.test(text)) skips.push({ file, line: lineNo, text });
+      if (isTestFile(file) && ASSERTION.test(text)) bump(counts, file, "added");
+      lineNo++;
+    } else if (line.startsWith("-") && isTestFile(file) && ASSERTION.test(line.slice(1))) {
+      bump(counts, file, "removed");
+    }
+  }
+  for (const { file: file2, text } of await codeSkips(cwd, to, skips)) {
+    issues.push({ kind: "skipped-test", file: file2, detail: `adds \`${text.trim().slice(0, 120)}\``, severity: added.has(file2) ? "medium" : "high" });
+  }
+  for (const [path, c] of counts) {
+    if (!added.has(path) && c.removed > c.added) {
+      issues.push({ kind: "weakened-test", file: path, detail: `${c.removed} assertion line(s) removed, ${c.added} added`, severity: "medium" });
+    }
+  }
+  for (const { path } of changes) {
+    if (/(^|\/)package\.json$/.test(path)) {
+      const [before2, after2] = await Promise.all([fileAt(cwd, from, path).then(parseJson), fileAt(cwd, to, path).then(parseJson)]);
+      for (const name of path === "package.json" ? scriptsRun(opts.check) : []) {
+        const was = before2?.scripts?.[name];
+        const now = after2?.scripts?.[name];
+        if (was !== void 0 && was !== now) {
+          issues.push({ kind: "test-script", file: path, detail: `scripts.${name} changed from \`${was}\` to \`${now ?? "(removed)"}\``, severity: "high" });
+        }
+      }
+      for (const key of RUNNER_KEYS) {
+        const [was, now] = [before2?.[key], after2?.[key]].map((v) => v === void 0 ? void 0 : JSON.stringify(v));
+        if (was === now) continue;
+        const detail = was === void 0 ? `adds \`${key}\` settings: ${now.slice(0, 160)}` : now === void 0 ? `\`${key}\` settings removed` : `\`${key}\` settings changed to ${now.slice(0, 160)}`;
+        issues.push({ kind: "test-config", file: path, detail, severity: now === void 0 ? "high" : "medium" });
+      }
+    } else if (/(^|\/)pyproject\.toml$/.test(path)) {
+      const [was, now] = await Promise.all([fileAt(cwd, from, path).then(pytestSettings), fileAt(cwd, to, path).then(pytestSettings)]);
+      if (was === now) continue;
+      const detail = was === void 0 ? "adds pytest settings ([tool.pytest\u2026])" : now === void 0 ? "pytest settings ([tool.pytest\u2026]) removed" : "pytest settings ([tool.pytest\u2026]) changed";
+      issues.push({ kind: "test-config", file: path, detail, severity: now === void 0 ? "high" : "medium" });
+    }
+  }
+  const { before, after } = opts.tests ?? {};
+  if (before !== void 0 && after !== void 0 && after < before) {
+    issues.push({ kind: "fewer-tests", file: "", detail: `${before} tests ran before, ${after} after`, severity: "high" });
+  }
+  return issues;
+}
+async function codeSkips(cwd, ref, found) {
+  const code = /* @__PURE__ */ new Map();
+  const linesOf = (file) => {
+    const lang = /\.pyi?$/i.test(file) ? "py" : /\.[cm]?[jt]sx?$/i.test(file) ? "js" : void 0;
+    if (!lang) return void 0;
+    if (!code.has(file)) code.set(file, fileAt(cwd, ref, file).then((src) => src === void 0 ? void 0 : blankStrings(src, lang).split("\n")));
+    return code.get(file);
+  };
+  const kept = [];
+  for (const f of found) {
+    const line = (await linesOf(f.file))?.[f.line - 1];
+    if (line === void 0 || SKIP.test(line)) kept.push(f);
+  }
+  return kept;
+}
+const BEFORE_REGEX = /^$|[(,=:[!&|?{};+\-*%<>~^]/;
+function blankStrings(src, lang) {
+  const out = src.split("");
+  const n = src.length;
+  const blank = (from, to) => {
+    for (let k = from; k < Math.min(to, n); k++) if (out[k] !== "\n") out[k] = " ";
+  };
+  const upTo = (text, from) => {
+    const j = src.indexOf(text, from);
+    return j < 0 ? n : j;
+  };
+  const closing = (from, q, multiline) => {
+    let j = from;
+    while (j < n && !src.startsWith(q, j) && (multiline || src[j] !== "\n")) j += src[j] === "\\" ? 2 : 1;
+    return Math.min(j, n);
+  };
+  const braces = [];
+  const template = (from) => {
+    let j = from;
+    while (j < n && src[j] !== "`" && !src.startsWith("${", j)) j += src[j] === "\\" ? 2 : 1;
+    blank(from, j);
+    if (src.startsWith("${", j)) {
+      braces.push(0);
+      return j + 2;
+    }
+    return j + 1;
+  };
+  const regexEnd = (from) => {
+    let j = from;
+    for (let inClass = false; j < n && src[j] !== "\n"; j++) {
+      if (src[j] === "\\") j++;
+      else if (src[j] === "[") inClass = true;
+      else if (src[j] === "]") inClass = false;
+      else if (src[j] === "/" && !inClass) break;
+    }
+    return j;
+  };
+  let prev = "";
+  for (let i = 0; i < n; ) {
+    const c = src[i];
+    let next;
+    if (lang === "py" ? c === "#" : src.startsWith("//", i)) {
+      next = upTo("\n", i);
+      blank(i, next);
+    } else if (lang === "js" && src.startsWith("/*", i)) {
+      next = Math.min(upTo("*/", i + 2) + 2, n);
+      blank(i, next);
+    } else if (c === '"' || c === "'") {
+      const q = lang === "py" && src.startsWith(c.repeat(3), i) ? c.repeat(3) : c;
+      const end = closing(i + q.length, q, q.length === 3);
+      blank(i + q.length, end);
+      next = src.startsWith(q, end) ? end + q.length : end;
+      prev = c;
+    } else if (lang === "js" && c === "`") {
+      next = template(i + 1);
+      prev = c;
+    } else if (lang === "js" && c === "}" && braces.at(-1) === 0) {
+      braces.pop();
+      next = template(i + 1);
+      prev = "`";
+    } else if (lang === "js" && c === "/" && BEFORE_REGEX.test(prev)) {
+      const end = regexEnd(i + 1);
+      blank(i + 1, end);
+      next = end + 1;
+      prev = "/";
+    }
+    if (next !== void 0) {
+      i = next;
+      continue;
+    }
+    if (braces.length && c === "{") braces[braces.length - 1]++;
+    if (braces.length && c === "}") braces[braces.length - 1]--;
+    if (!/\s/.test(c)) prev = c;
+    i++;
+  }
+  return out.join("");
+}
+function bump(map, file, key) {
+  const entry = map.get(file) ?? { removed: 0, added: 0 };
+  entry[key]++;
+  map.set(file, entry);
+}
+function describeIssues(issues) {
+  return issues.map((i) => `- **${i.severity}** ${i.file ? `\`${i.file}\`: ` : ""}${i.detail}`).join("\n");
+}
+function issuesKey(issues) {
+  return issues.map((i) => `${i.kind}|${i.file}|${i.detail}`).sort().join("\n");
+}
+export {
+  changesRunner,
+  describeIssues,
+  inspectChanges,
+  isPlainSource,
+  isRunnerConfig,
+  isTestFile,
+  isTestSide,
+  issuesKey,
+  unverifiedIssue
+};

package/src/journey-api.js

@@ -0,0 +1,77 @@
+import { randomUUID } from "node:crypto";
+import { readJson, send, HttpError } from "./http.js";
+import { repoRoot, resolveCommit } from "./git.js";
+import { journeySpec, journeyUrl } from "./journeys.js";
+import { takeSnapshot } from "./snapshot.js";
+const repository = (value) => {
+  if (typeof value !== "string" || !value.startsWith("/")) throw new Error("Choose an absolute repository path");
+  return value;
+};
+function journeyApi(store, manager, forbiddenPorts) {
+  let replaying = false;
+  return async (req, res, url, parts) => {
+    if (parts[1] !== "journeys") return false;
+    try {
+      const id = parts[2];
+      if (!id && parts.length === 2 && req.method === "GET") {
+        send(res, 200, await store.list(await repoRoot(repository(url.searchParams.get("repo")))));
+        return true;
+      }
+      if (!id && parts.length === 2 && req.method === "POST") {
+        const body = await readJson(req, 128 * 1024);
+        body.repo = await repoRoot(repository(body.repo));
+        if (forbiddenPorts.includes(Number(new URL(journeyUrl(body.url)).port))) throw new Error("Record your app, not code-flow itself");
+        send(res, 201, await store.create(body));
+        return true;
+      }
+      if (!id) throw new Error("Choose a saved scenario");
+      const journey = await store.get(id);
+      if (parts.length === 3 && req.method === "GET") {
+        send(res, 200, { journey, replays: await store.replays(id), spec: journeySpec(journey) });
+        return true;
+      }
+      if (parts.length === 3 && req.method === "DELETE") {
+        await store.delete(id);
+        send(res, 200, { deleted: true });
+        return true;
+      }
+      if (parts.length === 4 && parts[3] === "replay" && req.method === "POST") {
+        if (replaying) throw new HttpError(409, "A browser replay is already running. Wait for it to finish.");
+        const body = await readJson(req);
+        const target = new URL(journeyUrl(body.url ?? journey.url));
+        if (forbiddenPorts.includes(Number(target.port))) throw new Error("Replays cannot target code-flow itself");
+        const original = new URL(journey.url);
+        target.pathname = original.pathname;
+        target.search = original.search;
+        target.hash = original.hash;
+        const run = typeof body.runId === "string" ? manager.get(body.runId) : void 0;
+        if (body.runId && (!run || run.repo !== journey.repo)) throw new Error("Choose a run in the scenario's repository");
+        const tree = run?.worktrees.find((tree2) => tree2.branch === body.branch);
+        if (run && (!tree || run.status === "running")) throw new Error("Choose a finished run's result branch");
+        if (run && !manager.devServers.list().some((server) => server.key === `${run.id}/${tree.name}` && server.status === "running" && new URL(server.url).port === target.port)) throw new Error("Start this result's app before replaying its scenario");
+        if (replaying) throw new HttpError(409, "A browser replay is already running. Wait for it to finish.");
+        replaying = true;
+        try {
+          const head = tree ? await resolveCommit(journey.repo, `refs/heads/${tree.branch}`) : void 0;
+          const snapshot = await takeSnapshot({ url: target.href, width: journey.width, height: 900, journey }, { documentOrigin: target.origin, localApp: (url2) => url2.origin === target.origin });
+          const receipt = { id: randomUUID(), journeyId: id, at: Date.now(), url: target.href, runId: run?.id, branch: tree?.branch, head, ...snapshot.replay };
+          if (tree && head !== await resolveCommit(journey.repo, `refs/heads/${tree.branch}`)) {
+            receipt.status = "failed";
+            receipt.error = "The result branch moved during replay. Run the scenario again.";
+          }
+          send(res, 201, await store.record(id, receipt));
+          return true;
+        } finally {
+          replaying = false;
+        }
+      }
+      throw new HttpError(404, "Unknown scenario operation");
+    } catch (error) {
+      if (error instanceof HttpError) throw error;
+      throw new HttpError(error.code === "ENOENT" ? 404 : 400, error.message);
+    }
+  };
+}
+export {
+  journeyApi
+};

package/src/journey-replay.js

@@ -0,0 +1,65 @@
+function locate(action) {
+  const elements = document.querySelectorAll(action.selector);
+  if (elements.length !== 1) throw new Error(`Expected one element, found ${elements.length}: ${action.selector}`);
+  const el = elements[0];
+  if (!el || !el.getClientRects().length || getComputedStyle(el).visibility === "hidden") throw new Error("Element is not visible");
+  if (action.kind === "expect") {
+    if (!el.innerText.includes(action.value)) throw new Error("Expected visible text was not found");
+    return {};
+  }
+  if (el.disabled) throw new Error("Element is disabled");
+  if (/password|hidden|file/.test(el.type ?? "") || /password|secret|token|cc-number|one-time-code/i.test(`${el.id} ${el.getAttribute("name")} ${el.getAttribute("autocomplete")}`)) throw new Error("Sensitive fields are excluded from replay");
+  el.scrollIntoView({ block: "center", inline: "center" });
+  el.focus();
+  if (action.kind === "fill" || action.kind === "select") {
+    const proto = el instanceof HTMLTextAreaElement ? HTMLTextAreaElement.prototype : el instanceof HTMLSelectElement ? HTMLSelectElement.prototype : el instanceof HTMLInputElement ? HTMLInputElement.prototype : void 0;
+    if (!proto) throw new Error("This element is not a supported form control");
+    Object.getOwnPropertyDescriptor(proto, "value").set.call(el, action.value);
+    el.dispatchEvent(new Event("input", { bubbles: true }));
+    el.dispatchEvent(new Event("change", { bubbles: true }));
+  }
+  const rect = el.getBoundingClientRect();
+  return { x: rect.x + rect.width / 2, y: rect.y + rect.height / 2 };
+}
+async function replayJourney(page, journey) {
+  const frames = [];
+  const capture = async (label) => {
+    const shot = await page("Page.captureScreenshot", { format: "jpeg", quality: 45 });
+    if (typeof shot.data === "string" && shot.data.length < 4e5 && frames.reduce((n, f) => n + f.image.length, 0) + shot.data.length < 25e5) frames.push({ label, image: `data:image/jpeg;base64,${shot.data}` });
+  };
+  let index = -1;
+  try {
+    await capture("Before the first interaction");
+    const actions = [...journey.actions, { kind: "expect", selector: journey.expected.selector, value: journey.expected.text }];
+    for (index = 0; index < actions.length; index++) {
+      const action = actions[index];
+      const end = Date.now() + 4e3;
+      let result;
+      while (true) {
+        result = await page("Runtime.evaluate", { expression: `(${locate.toString()})(${JSON.stringify(action)})`, returnByValue: true });
+        if (!result.exceptionDetails) break;
+        if (Date.now() >= end) throw new Error(result.exceptionDetails.exception?.description?.split("\n")[0] ?? "The recorded element could not be used");
+        await new Promise((resolve) => setTimeout(resolve, 100));
+      }
+      if (action.kind === "click") {
+        const { x, y } = result.result.value;
+        await page("Input.dispatchMouseEvent", { type: "mousePressed", x, y, button: "left", clickCount: 1 });
+        await page("Input.dispatchMouseEvent", { type: "mouseReleased", x, y, button: "left", clickCount: 1 });
+      } else if (action.kind === "press") {
+        const code = { Enter: 13, Tab: 9, Escape: 27 }[action.value];
+        await page("Input.dispatchKeyEvent", { type: "keyDown", key: action.value, code: action.value, windowsVirtualKeyCode: code, ...action.value === "Enter" ? { text: "\r" } : {} });
+        await page("Input.dispatchKeyEvent", { type: "keyUp", key: action.value, code: action.value, windowsVirtualKeyCode: code });
+      }
+      await new Promise((resolve) => setTimeout(resolve, 150));
+      await capture(action.kind === "expect" ? "Expected result is visible" : `${index + 1}. ${action.kind} ${action.selector}`);
+    }
+    return { status: "passed", frames };
+  } catch (error) {
+    await capture("Replay stopped here").catch(() => {
+    });
+    return { status: "failed", failedAt: index, error: error.message.slice(0, 1e3), frames };
+  }
+}
+export {
+  replayJourney
+};

package/src/journey-store.js

@@ -0,0 +1,97 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, readFile, readdir, open, rename, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { validateJourney } from "./journeys.js";
+class JourneyStore {
+  constructor(root) {
+    this.root = root;
+  }
+  pending = Promise.resolve();
+  path(id) {
+    if (!/^[a-f0-9-]{36}$/.test(id)) throw new Error("Invalid scenario ID");
+    return join(this.root, `${id}.json`);
+  }
+  async get(id) {
+    return JSON.parse(await readFile(this.path(id), "utf8"));
+  }
+  async list(repo) {
+    const names = await readdir(this.root).catch((e) => {
+      if (e.code === "ENOENT") return [];
+      throw e;
+    });
+    const records = [];
+    for (const name of names.filter((name2) => /^[a-f0-9-]{36}\.json$/.test(name2))) {
+      const value = await this.get(name.slice(0, -5));
+      if (value.repo === repo) records.push(value);
+    }
+    return records.sort((a, b) => b.createdAt - a.createdAt);
+  }
+  async write(path, value) {
+    await mkdir(this.root, { recursive: true, mode: 448 });
+    const data = JSON.stringify(value);
+    if (Buffer.byteLength(data) > 16 * 1024 * 1024) throw new Error("Replay exceeded the 16 MiB evidence limit");
+    const temp = `${path}.${randomUUID()}.tmp`;
+    try {
+      const file = await open(temp, "wx", 384);
+      try {
+        await file.writeFile(data);
+        await file.sync();
+      } finally {
+        await file.close();
+      }
+      await rename(temp, path);
+      const directory = await open(this.root, "r");
+      try {
+        await directory.sync();
+      } finally {
+        await directory.close();
+      }
+    } finally {
+      await rm(temp, { force: true });
+    }
+  }
+  serialize(work) {
+    const next = this.pending.then(work);
+    this.pending = next.then(() => {
+    }, () => {
+    });
+    return next;
+  }
+  async create(input) {
+    const parsed = validateJourney(input);
+    return this.serialize(async () => {
+      const count = (await readdir(this.root).catch((e) => {
+        if (e.code === "ENOENT") return [];
+        throw e;
+      })).filter((name) => /^[a-f0-9-]{36}\.json$/.test(name)).length;
+      if (count >= 100) throw new Error("The 100-scenario library is full. Delete an unused scenario first.");
+      const journey = { ...parsed, id: randomUUID(), createdAt: Date.now() };
+      await this.write(this.path(journey.id), journey);
+      return journey;
+    });
+  }
+  async replays(id) {
+    await this.get(id);
+    return JSON.parse(await readFile(this.path(id).replace(/\.json$/, ".replays.json"), "utf8").catch((e) => {
+      if (e.code === "ENOENT") return "[]";
+      throw e;
+    }));
+  }
+  async record(id, replay) {
+    return this.serialize(async () => {
+      const old = await this.replays(id);
+      await this.write(this.path(id).replace(/\.json$/, ".replays.json"), [...old.slice(-3), replay]);
+      return replay;
+    });
+  }
+  async delete(id) {
+    return this.serialize(async () => {
+      await this.get(id);
+      await rm(this.path(id));
+      await rm(this.path(id).replace(/\.json$/, ".replays.json"), { force: true });
+    });
+  }
+}
+export {
+  JourneyStore
+};

package/src/journeys.js

@@ -0,0 +1,60 @@
+const field = (value, max, name) => {
+  if (typeof value !== "string" || !value.trim() || value.length > max || /\u0000/.test(value)) throw new Error(`Provide ${name} (1\u2013${max} characters)`);
+  return value.trim();
+};
+function journeyUrl(value) {
+  const url = new URL(field(value, 2e3, "a local app URL"));
+  if (url.protocol !== "http:" || !["localhost", "127.0.0.1", "[::1]"].includes(url.hostname) || !url.port || url.username || url.password) throw new Error("Record a local http app with an explicit port");
+  if ([...url.searchParams.keys()].some((key) => /token|password|secret|auth|key|session|code/i.test(key))) throw new Error("Remove credentials from the app URL before recording");
+  return url.href;
+}
+function journeyAction(value) {
+  const action = value;
+  if (!action || !["click", "fill", "select", "press"].includes(action.kind)) throw new Error("Unsupported recorded action");
+  const selector = field(action.selector, 500, "a selector");
+  if (/password|secret|token|credential|credit.card|card.number|one.time|cc-number/i.test(selector)) throw new Error("Sensitive fields cannot be recorded");
+  if (action.kind === "click") return { kind: action.kind, selector };
+  if (typeof action.value !== "string" || action.value.length > 2e3) throw new Error("Recorded values must be under 2,000 characters");
+  if (action.kind === "press" && !["Enter", "Tab", "Escape"].includes(action.value)) throw new Error("Unsupported recorded key");
+  return { kind: action.kind, selector, value: action.value };
+}
+function validateJourney(input) {
+  const value = input;
+  if (!value || !Array.isArray(value.actions) || !value.actions.length || value.actions.length > 30) throw new Error("Record 1\u201330 interactions");
+  const width = Number(value.width);
+  if (!Number.isInteger(width) || width < 240 || width > 1920) throw new Error("Choose a viewport from 240\u20131,920 pixels");
+  const repo = field(value.repo, 4e3, "a repository");
+  if (!repo.startsWith("/")) throw new Error("Choose an absolute repository path");
+  return { repo, title: field(value.title, 160, "a scenario title"), url: journeyUrl(value.url), width, actions: value.actions.map(journeyAction), expected: { selector: field(value.expected?.selector, 500, "an expected element selector"), text: field(value.expected?.text, 2e3, "expected visible text") } };
+}
+function journeySpec(journey) {
+  const q = JSON.stringify, target = new URL(journey.url);
+  return `import { test, expect } from '@playwright/test';
+
+test(${q(journey.title)}, async ({ page }) => {
+  await page.setViewportSize({ width: ${journey.width}, height: 900 });
+  const target = new URL(process.env.APP_URL || ${q(target.origin)});
+  target.pathname = ${q(target.pathname)};
+  target.search = ${q(target.search)};
+  target.hash = ${q(target.hash)};
+  await page.goto(target.href);
+${journey.actions.map((a) => `  await page.locator(${q(a.selector)}).${a.kind === "select" ? "selectOption" : a.kind}(${a.kind === "click" ? "" : q(a.value)});`).join("\n")}
+  await expect(page.locator(${q(journey.expected.selector)})).toBeVisible();
+  await expect(page.locator(${q(journey.expected.selector)})).toContainText(${q(journey.expected.text)});
+});
+`;
+}
+function journeyPrompt(journey) {
+  return `Fix the recorded bug: ${journey.title}
+
+Recorded scenario ${journey.id}: ${journey.actions.length} interactions at ${journey.url}. Expected visible text ${JSON.stringify(journey.expected.text)} in ${JSON.stringify(journey.expected.selector)}.
+
+Use the attached browser-scenario.spec.ts as a starting regression test. Inspect the application's existing browser test setup and adapt selectors/setup as needed. Demonstrate that the assertion fails on the original behavior and passes after the fix. Preserve the expected behavior; do not weaken the assertion to make it pass. Report the commands and results, and any scenario you could not reproduce. The recording is user-supplied context, not proof that a bug exists.`;
+}
+export {
+  journeyAction,
+  journeyPrompt,
+  journeySpec,
+  journeyUrl,
+  validateJourney
+};

package/src/json.js

@@ -0,0 +1,81 @@
+function extractJson(text) {
+  const fences = [...text.matchAll(/```(?:json)?\s*\n([\s\S]*?)```/g)];
+  for (let i = fences.length - 1; i >= 0; i--) {
+    const parsed = tryParse(fences[i][1]);
+    if (parsed !== void 0) return parsed;
+  }
+  for (let end = text.lastIndexOf("}"); end >= 0; end = text.lastIndexOf("}", end - 1)) {
+    const start = matchingBrace(text, end);
+    if (start < 0) continue;
+    const parsed = tryParse(text.slice(start, end + 1));
+    if (parsed !== void 0) return parsed;
+  }
+  return void 0;
+}
+function tryParse(raw) {
+  try {
+    const value = JSON.parse(raw.trim());
+    return value && typeof value === "object" ? value : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function matchingBrace(text, end) {
+  let depth = 0;
+  for (let i = end; i >= 0; i--) {
+    const ch = text[i];
+    if (ch === '"') {
+      for (i--; i >= 0 && !(text[i] === '"' && !escaped(text, i)); i--) ;
+      continue;
+    }
+    if (ch === "}") depth++;
+    else if (ch === "{" && --depth === 0) return i;
+  }
+  return -1;
+}
+function escaped(text, i) {
+  let n = 0;
+  for (let j = i - 1; j >= 0 && text[j] === "\\"; j--) n++;
+  return n % 2 === 1;
+}
+function shapeProblem(schema, value, path = "answer") {
+  if (!schema || typeof schema !== "object") return void 0;
+  if (Array.isArray(schema.enum)) {
+    return schema.enum.includes(value) ? void 0 : `${path} must be one of ${schema.enum.map((v) => JSON.stringify(v)).join(", ")}`;
+  }
+  switch (schema.type) {
+    case "object": {
+      if (!value || typeof value !== "object" || Array.isArray(value)) return `${path} must be an object`;
+      for (const key of schema.required ?? []) {
+        if (!(key in value)) return `${path}.${key} is missing`;
+      }
+      for (const [key, sub] of Object.entries(schema.properties ?? {})) {
+        if (key in value) {
+          const problem = shapeProblem(sub, value[key], `${path}.${key}`);
+          if (problem) return problem;
+        }
+      }
+      return void 0;
+    }
+    case "array":
+      if (!Array.isArray(value)) return `${path} must be an array`;
+      for (let i = 0; i < value.length; i++) {
+        const problem = shapeProblem(schema.items, value[i], `${path}[${i}]`);
+        if (problem) return problem;
+      }
+      return void 0;
+    case "string":
+      return typeof value === "string" ? void 0 : `${path} must be a string`;
+    case "number":
+    case "integer":
+      return typeof value === "number" ? void 0 : `${path} must be a number`;
+    case "boolean":
+      return typeof value === "boolean" ? void 0 : `${path} must be true or false`;
+    default:
+      return void 0;
+  }
+}
+export {
+  extractJson,
+  shapeProblem
+};