retake-demos 0.2.0

package/dist/dryrun.js

@@ -0,0 +1,196 @@
+/**
+ * Dry run — execute a manifest with no camera, and report what would break.
+ *
+ * Recording is the slow part of a take (a demo has to be performed in real
+ * time). Checking that every selector resolves and every wait resolves does
+ * not: it runs as fast as the app responds. So the cheap thing should happen
+ * first, and the camera should only roll on a manifest that already works.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { runFileOrCommandSeed, resolvePoint, dragPoints } from "./record.js";
+import { chromium } from "playwright";
+import { expandEnv, resolve } from "./manifest.js";
+export async function dryRun(m, manifestDir, log, opts = {}) {
+    const q = resolve(m);
+    const lines = [];
+    let failures = 0;
+    // Seeds run here too (file and command kinds — the cheap, out-of-page
+    // ones). Without them dry checks a different app state than run will,
+    // and a selector failure that is really a state difference looks like a
+    // selector failure. --no-seed opts out.
+    const fileSeeds = m.seed.filter((s) => s.kind !== "evaluate");
+    if (opts.seed !== false && fileSeeds.length) {
+        for (const s of fileSeeds)
+            await runFileOrCommandSeed(s, manifestDir, log);
+    }
+    else if (fileSeeds.length) {
+        log("dry: seeds skipped (--no-seed) — app state may not match what run will see");
+    }
+    const browser = await chromium.launch({ headless: true });
+    const context = await browser.newContext({
+        viewport: q.viewport,
+        colorScheme: m.colorScheme,
+        ...(m.reducedMotion ? { reducedMotion: "reduce" } : {}),
+    });
+    const stubs = new Map();
+    const arm = async (d) => {
+        const key = `${d.method ?? "ANY"} ${d.url}`;
+        const fresh = !stubs.has(key);
+        stubs.set(key, d);
+        if (!fresh)
+            return;
+        await context.route(d.url, async (route, request) => {
+            const cur = stubs.get(key);
+            if (cur.method && request.method().toUpperCase() !== cur.method.toUpperCase())
+                return route.fallback();
+            const body = cur.json !== undefined ? JSON.stringify(cur.json) : cur.from ? fs.readFileSync(path.resolve(manifestDir, expandEnv(cur.from)), "utf8") : "{}";
+            await route.fulfill({ status: cur.status ?? 200, contentType: cur.contentType, body });
+        });
+    };
+    const page = await context.newPage();
+    try {
+        for (const d of m.stub)
+            await arm(d);
+        // Document first; idle only if it comes quickly. Busy public sites never
+        // go network-idle, and the manifest's waitForSelector is the real gate.
+        await page.goto(expandEnv(m.url), { waitUntil: "domcontentloaded", timeout: 60000 });
+        await page.waitForLoadState("networkidle", { timeout: 8000 }).catch(() => { });
+        for (const s of [...(m.auth?.setup ?? []), ...m.setup])
+            await run(s, true);
+        for (const [i, s] of m.steps.entries())
+            await run(s, false, i);
+    }
+    finally {
+        await context.close().catch(() => { });
+        await browser.close().catch(() => { });
+    }
+    async function run(step, isSetup, index = -1) {
+        const tag = isSetup ? "setup" : String(index).padStart(3, "0");
+        const short = 8000; // long enough for a click that navigates, short enough to stay fast
+        try {
+            // A point step (click/hover `at`, or a drag) is verified by resolving
+            // its target's rect in the page — the same way the recorder will.
+            const point = async (t) => {
+                if (t && typeof t === "object" && "x" in t)
+                    return t;
+                const sel = typeof t === "string" ? t : t.selector;
+                const until = Date.now() + short;
+                let box = null;
+                while (Date.now() < until) {
+                    const handle = await page.locator(sel).first().elementHandle({ timeout: Math.max(400, until - Date.now()) });
+                    if (handle) {
+                        box = await handle.evaluate((el) => { const r = el.getBoundingClientRect(); return { w: r.width, h: r.height }; });
+                        await handle.dispose();
+                        if (box && (box.w || box.h))
+                            break;
+                    }
+                    await page.waitForTimeout(250);
+                }
+                if (!box)
+                    throw new Error(`no element for point target "${sel}"`);
+                if (!box.w && !box.h)
+                    throw new Error(`point target "${sel}" never got a size (still hidden or collapsed?)`);
+                return resolvePoint(page, t, short);
+            };
+            // Point steps are PERFORMED here, not just resolved: a dry run that skips
+            // the click that opens a panel then reports every later step in that
+            // panel as broken. Drags run compressed — the gesture, not the pacing.
+            if (step.action === "drag") {
+                const f = await point(step.from), t = await point(step.to);
+                await dragPoints(page, f, t, { steps: 6, holdMs: 60, durationMs: 240 });
+                await page.waitForTimeout(400);
+            }
+            else if ((step.action === "click" || step.action === "hover") && step.at) {
+                const pt = await point(step.at);
+                if (step.action === "click") {
+                    await page.mouse.click(pt.x, pt.y);
+                    await page.waitForTimeout(400);
+                }
+                else
+                    await page.mouse.move(pt.x, pt.y);
+            }
+            else
+                switch (step.action) {
+                    case "navigate":
+                        await page.goto(expandEnv(step.url), { waitUntil: "domcontentloaded", timeout: 60000 });
+                        await page.waitForLoadState("networkidle", { timeout: 8000 }).catch(() => { });
+                        break;
+                    case "waitFor":
+                        await page.waitForSelector(step.selector, { timeout: Math.min(step.timeout ?? 15000, 15000) });
+                        break;
+                    // noWaitAfter: a click that submits a form starts a navigation, and
+                    // waiting for the element to settle afterwards reports a false failure
+                    // for a click that actually worked.
+                    case "click":
+                        await page.locator(step.selector).waitFor({ timeout: short }); // strict, like the recorder
+                        await page.locator(step.selector).first().click({ timeout: short, noWaitAfter: true });
+                        await page.waitForLoadState("domcontentloaded", { timeout: 5000 }).catch(() => { });
+                        break;
+                    case "type":
+                        await page.locator(step.selector).waitFor({ timeout: short });
+                        await page.locator(step.selector).fill(expandEnv(step.text), { timeout: short });
+                        break;
+                    case "fill":
+                        await page.locator(step.selector).waitFor({ timeout: short });
+                        await page.locator(step.selector).fill(expandEnv(step.text), { timeout: short });
+                        break;
+                    case "hover":
+                        await page.locator(step.selector).first().hover({ timeout: short });
+                        break;
+                    case "scroll":
+                        if (step.to)
+                            await page.locator(step.to).first().boundingBox({ timeout: short });
+                        break;
+                    case "upload":
+                        await page.locator(step.selector).first().waitFor({ timeout: short });
+                        break;
+                    case "evaluate":
+                        await page.evaluate(step.script);
+                        break;
+                    case "stub":
+                        await arm({ url: step.url, method: step.method, status: step.status ?? 200, json: step.json, from: step.from, contentType: "application/json; charset=utf-8" });
+                        break;
+                    case "keyboard":
+                        await page.keyboard.press(step.key);
+                        break;
+                    // Pacing does not matter in a dry run, so step waits are compressed.
+                    // Setup waits are not: they are usually giving a navigation or a login
+                    // time to finish, and cutting them changes the outcome.
+                    case "wait":
+                        await page.waitForTimeout(isSetup ? step.ms : Math.min(step.ms, 400));
+                        break;
+                    default: break; // scene, screenshot, zoom, download: nothing to verify
+                }
+            if (step.pauseAfter)
+                await page.waitForTimeout(120);
+        }
+        catch (e) {
+            failures++;
+            const why = e.message.split("\n")[0];
+            // What was actually on screen matters more than the timeout message:
+            // most "selector not found" is really "you are on a different page".
+            let where = "";
+            try {
+                const text = (await page.innerText("body")).replace(/\s+/g, " ").trim().slice(0, 110);
+                where = `\n        on ${page.url()} — “${text}”`;
+            }
+            catch { /* page may be gone */ }
+            const line = `✗ [${tag}] ${describe(step)} — ${why}${where}`;
+            lines.push(line);
+            log(line);
+        }
+    }
+    const ok = failures === 0;
+    log(ok ? `dry run: all ${m.steps.length} steps resolved` : `dry run: ${failures} step(s) would fail`);
+    return { ok, lines, failures };
+}
+function describe(s) {
+    if ("selector" in s && s.selector)
+        return `${s.action} ${s.selector}`;
+    if (s.action === "navigate")
+        return `navigate ${s.url}`;
+    if (s.action === "scroll" && s.to)
+        return `scroll to ${s.to}`;
+    return s.action;
+}

package/dist/edits.js

@@ -0,0 +1,229 @@
+/**
+ * Apply structured edits to a manifest file, keeping its comments.
+ *
+ * The model never writes YAML back. It names an edit from a small vocabulary
+ * and Retake makes the change with the document API — so a fix for "slower at
+ * the end" cannot also rewrite the captions, and a person's earlier edits
+ * survive. Each applied edit is described in one plain sentence for the UI.
+ */
+import fs from "node:fs";
+import YAML from "yaml";
+import { Manifest, Step } from "./manifest.js";
+export function applyEdits(file, edits) {
+    const doc = YAML.parseDocument(fs.readFileSync(file, "utf8"));
+    const done = [];
+    const skipped = [];
+    let rerecord = false;
+    const steps = doc.get("steps");
+    const scene = (label) => steps?.items.find((it) => { const n = it; return typeof n.get === "function" && n.get("action") === "scene" && n.get("label") === label; });
+    const step = (i) => { const n = steps?.items[Number(i)]; return n && typeof n.get === "function" ? n : undefined; };
+    const num = (v) => (typeof v === "number" && isFinite(v) ? v : Number(v));
+    for (const e of edits) {
+        try {
+            switch (e.op) {
+                case "set_caption": {
+                    const n = scene(e.scene);
+                    if (!n)
+                        throw new Error(`no scene "${e.scene}"`);
+                    if (e.caption)
+                        n.set("caption", String(e.caption));
+                    else
+                        n.delete("caption");
+                    done.push(`Caption on “${e.scene}” → “${e.caption}”`);
+                    break;
+                }
+                case "set_camera": {
+                    const n = scene(e.scene);
+                    if (!n)
+                        throw new Error(`no scene "${e.scene}"`);
+                    const c = e.camera;
+                    if (c === "static")
+                        n.set("camera", "static");
+                    else if (c === "auto")
+                        n.delete("camera");
+                    else
+                        n.set("camera", { zoom: num(c) });
+                    done.push(`Camera on “${e.scene}” → ${c === "auto" ? "auto" : c === "static" ? "none" : num(c) + "×"}`);
+                    break;
+                }
+                case "set_hold": {
+                    const n = scene(e.scene);
+                    if (!n)
+                        throw new Error(`no scene "${e.scene}"`);
+                    n.set("holdMs", num(e.holdMs));
+                    done.push(`Hold “${e.scene}” for ${(num(e.holdMs) / 1000).toFixed(1)}s`);
+                    break;
+                }
+                case "set_trim": {
+                    const head = num(e.head ?? 0) || 0, tail = num(e.tail ?? 0) || 0;
+                    if (!head && !tail)
+                        doc.delete("trim");
+                    else
+                        doc.set("trim", { head, tail });
+                    done.push(`Trim ${head}s off the start, ${tail}s off the end`);
+                    break;
+                }
+                case "set_format": {
+                    doc.set("preset", String(e.preset));
+                    done.push(`Format → ${e.preset}`);
+                    rerecord = true;
+                    break;
+                }
+                case "set_layout": {
+                    doc.set("layout", String(e.layout));
+                    done.push(`Captions → ${e.layout}`);
+                    break;
+                }
+                case "set_cursor": {
+                    const c = String(e.cursor);
+                    if (c === "none")
+                        doc.set("cursor", false);
+                    else if (c === "touch")
+                        doc.set("cursor", { style: "touch" });
+                    else
+                        doc.delete("cursor");
+                    done.push(`Cursor → ${c}`);
+                    rerecord = true;
+                    break;
+                }
+                case "add_wait": {
+                    const i = Number(e.after);
+                    if (!steps || !steps.items[i])
+                        throw new Error(`no step ${i}`);
+                    steps.items.splice(i + 1, 0, doc.createNode({ action: "wait", ms: num(e.ms) }));
+                    done.push(`Pause ${(num(e.ms) / 1000).toFixed(1)}s after step ${i}`);
+                    rerecord = true;
+                    break;
+                }
+                case "wait_for": {
+                    const i = Number(e.step);
+                    const n = step(i);
+                    if (!n || !steps)
+                        throw new Error(`no step ${i}`);
+                    const node = doc.createNode({ action: "waitFor", selector: String(e.selector), timeout: 30000 });
+                    if (n.get("action") === "wait") {
+                        steps.items.splice(i, 1, node);
+                        done.push(`Step ${i} now waits for ${e.selector} instead of a fixed pause`);
+                    }
+                    else {
+                        steps.items.splice(i + 1, 0, node);
+                        done.push(`Waits for ${e.selector} after step ${i}`);
+                    }
+                    rerecord = true;
+                    break;
+                }
+                case "set_wait": {
+                    const n = step(e.step);
+                    if (!n || n.get("action") !== "wait")
+                        throw new Error(`step ${e.step} is not a wait`);
+                    n.set("ms", num(e.ms));
+                    done.push(`Wait at step ${e.step} → ${(num(e.ms) / 1000).toFixed(1)}s`);
+                    rerecord = true;
+                    break;
+                }
+                case "set_text": {
+                    const n = step(e.step);
+                    if (!n || !["type", "fill"].includes(String(n.get("action"))))
+                        throw new Error(`step ${e.step} does not type`);
+                    n.set("text", String(e.text));
+                    done.push(`Step ${e.step} now types “${e.text}”`);
+                    rerecord = true;
+                    break;
+                }
+                case "replace_selector": {
+                    const n = step(e.step);
+                    if (!n || !n.has("selector"))
+                        throw new Error(`step ${e.step} has no selector`);
+                    n.set("selector", String(e.selector));
+                    done.push(`Step ${e.step} now targets ${e.selector}`);
+                    rerecord = true;
+                    break;
+                }
+                case "delete_step": {
+                    const i = Number(e.step);
+                    if (!steps || !steps.items[i])
+                        throw new Error(`no step ${i}`);
+                    const n = steps.items[i];
+                    const what = typeof n.get === "function" ? `${n.get("action")}${n.has("selector") ? " " + n.get("selector") : ""}` : `step ${i}`;
+                    steps.items.splice(i, 1);
+                    done.push(`Removed ${what}`);
+                    rerecord = true;
+                    break;
+                }
+                // Structural edits. Without these the only way to add a click or a
+                // scene was rewriting the whole file — which an agent under pressure
+                // would rather not do, so it gave up instead (distill-messy, day one).
+                // The new step is checked against the schema before it is allowed in.
+                case "insert_step": {
+                    if (!steps)
+                        throw new Error("manifest has no steps");
+                    const after = Number(e.after);
+                    if (!Number.isInteger(after) || after < -1 || after >= steps.items.length)
+                        throw new Error(`after must be -1 (start) … ${steps.items.length - 1}`);
+                    const parsedStep = Step.safeParse(e.step);
+                    if (!parsedStep.success)
+                        throw new Error("invalid step: " + parsedStep.error.issues.map((i) => `${i.path.join(".") || "step"}: ${i.message}`).join("; "));
+                    steps.items.splice(after + 1, 0, doc.createNode(parsedStep.data));
+                    const st = parsedStep.data;
+                    done.push(`Inserted ${st.action}${st.selector ? " " + st.selector : st.label ? ` "${st.label}"` : ""} as step ${after + 1}`);
+                    rerecord = true;
+                    break;
+                }
+                case "set_step": {
+                    const i = Number(e.step);
+                    if (!steps || !steps.items[i])
+                        throw new Error(`no step ${i}`);
+                    const parsedStep = Step.safeParse(e.value);
+                    if (!parsedStep.success)
+                        throw new Error("invalid step: " + parsedStep.error.issues.map((x) => `${x.path.join(".") || "step"}: ${x.message}`).join("; "));
+                    steps.items.splice(i, 1, doc.createNode(parsedStep.data));
+                    const st = parsedStep.data;
+                    done.push(`Step ${i} is now ${st.action}${st.selector ? " " + st.selector : st.label ? ` "${st.label}"` : ""}`);
+                    rerecord = true;
+                    break;
+                }
+                case "rerecord": {
+                    done.push("Recording again from scratch");
+                    rerecord = true;
+                    break;
+                }
+                default: skipped.push(`unknown edit ${String(e.op)}`);
+            }
+        }
+        catch (err) {
+            skipped.push(`${e.op}: ${err.message}`);
+        }
+    }
+    const yaml = doc.toString();
+    const parsed = Manifest.safeParse(YAML.parse(yaml));
+    if (!parsed.success)
+        throw new Error("edit would make the manifest invalid: " + parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; "));
+    if (done.length)
+        fs.writeFileSync(file, yaml);
+    return { yaml, done, skipped, rerecord };
+}
+/** What the model needs to know about the last take, in plain text with the
+    indexes and labels it must use. Secrets never appear (describe() redacts). */
+export function receiptsFor(take, manifestSteps) {
+    const lines = [];
+    lines.push("Steps (index · action):");
+    manifestSteps.forEach((s, i) => {
+        let desc = s.action;
+        if (s.action === "scene")
+            desc = `scene "${s.label}"${s.caption ? ` — caption “${s.caption}”` : ""}`;
+        else if (s.action === "wait")
+            desc = `wait ${s.ms}ms`;
+        else if (s.selector)
+            desc = `${s.action} ${s.selector}${s.text && !s.secret ? ` “${s.text.slice(0, 40)}”` : ""}`;
+        lines.push(`  ${i}: ${desc}`);
+    });
+    if (take) {
+        lines.push("", `Last take: ${(take.duration - take.trimBefore).toFixed(1)}s, ${take.ok ? "all steps passed" : "some steps FAILED"}${take.partial ? ", partial" : ""}.`);
+        const fails = take.timeline.filter((t) => !t.ok);
+        if (fails.length)
+            lines.push("Failed: " + fails.map((t) => `step ${t.index} (${t.summary}) — ${t.error}`).join("; "));
+        const scenes = take.timeline.filter((t) => t.action === "scene");
+        lines.push("Scene timings: " + scenes.map((s) => `${s.label}@${(s.start - take.trimBefore).toFixed(1)}s`).join(", "));
+    }
+    return lines.join("\n");
+}