retake-demos 0.2.2 → 0.4.0

package/dist/describe.js

@@ -25,16 +25,34 @@ import YAML from "yaml";
 import { Manifest } from "./manifest.js";
 import { digest } from "./digest.js";
 export function loadDotenv(root, files = [".env"]) {
+    // One parser for every reader of .env (see env.ts), so a password written
+    // by the window or `retake secret` is typed back exactly as entered.
     for (const name of files) {
-        const f = path.join(root, name);
-        if (!fs.existsSync(f))
+        for (const [k, v] of Object.entries(parseEnvText(root, name)))
+            if (process.env[k] === undefined)
+                process.env[k] = v;
+    }
+}
+function parseEnvText(root, name) {
+    const f = path.join(root, name);
+    if (!fs.existsSync(f))
+        return {};
+    const out = {};
+    for (const raw of fs.readFileSync(f, "utf8").split(/\r?\n/)) {
+        const m = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/.exec(raw);
+        if (!m)
             continue;
-        for (const line of fs.readFileSync(f, "utf8").split("\n")) {
-            const m = /^\s*([A-Z0-9_]+)\s*=\s*(.*)\s*$/.exec(line);
-            if (m && process.env[m[1]] === undefined)
-                process.env[m[1]] = m[2].replace(/^["']|["']$/g, "");
+        const v = m[2].trim();
+        if (v.startsWith('"') && v.endsWith('"')) {
+            try {
+                out[m[1]] = JSON.parse(v);
+                continue;
+            }
+            catch { /* literal */ }
         }
+        out[m[1]] = v.replace(/^(["'])(.*)\1$/, "$2");
     }
+    return out;
 }
 function cliPath(bin) {
     const home = os.homedir();
@@ -293,11 +311,13 @@ export async function proposeEdits(input) {
 // --- drafting ---------------------------------------------------------------
 const SCHEMA_DOC = `
 Manifest YAML fields:
-  name (kebab-case), title, url, preset: post-landscape, waitForSelector (selector present when page is ready),
-  camera: auto, setup: [steps run before recording], steps: [...], outputs: {mp4: true, gif: true, thumbnail: {scene: <label>}}
-  Do NOT set viewport, cursor, chrome, background, fps, crf or captions — the preset handles quality.
+  name (kebab-case), title, url, mode: demo, preset: post-landscape, waitForSelector (selector present when page is ready),
+  camera: static, setup: [steps run before recording], steps: [...], outputs: {mp4: true, gif: true, thumbnail: {scene: <label>}}
+  NEVER set viewport. The preset decides the size and every take at a preset comes out identical; setting viewport makes this demo a different shape from every other one and players letterbox it. Same for cursor, chrome, background, fps, crf and captions — the preset handles all of it.
+  Always set mode: demo — this is a demo, so nothing goes in the frame but the product. Never emit intro or outro cards, music, callouts or voiceover: those belong to mode: launch, which only a person can ask for.
 Steps (each may have pauseAfter ms, waitFor selector, timeout ms):
   {action: scene, label, caption, camera?: static | {focus: selector, zoom: 1.25}}   a named beat; caption is burned in until the next scene (under 60 chars). Set camera: static on every scene unless the thing being shown is genuinely too small to read at full frame — a calm, still demo reads as more real than a zooming one. If the person asked for zooms (or stillness), that wins.
+  {action: select, selector, value}   choose in a <select> — value or the visible label, whichever the page uses
   {action: wait, ms}
   {action: click, selector, zoom: 1.3}   zoom is optional
   {action: type, selector, text, delay: 30}
@@ -307,7 +327,7 @@ Steps (each may have pauseAfter ms, waitFor selector, timeout ms):
   {action: keyboard, key}
   {action: waitFor, selector, timeout: 30000}      wait for something to appear (use after actions that trigger async work)
   {action: evaluate, script}
-Rules: never invent field names or add "?" to keys; 15–35 seconds total; 3–6 scenes; open with a scene; every click uses a selector from the scouted list verbatim (selectors ending in \">> nth=N\" are already disambiguated — keep them exactly); after any action that loads or computes something, waitFor an element that only appears as a result (never one that is already on the page) — if you cannot know it from the scout, use {action: wait, ms: 3000} instead; end with a wait of ~2000ms on the payoff; do not use zoom steps — scenes carry the camera.
+Rules: never invent field names or add "?" to keys; write mode: demo; no cards, music, callouts or voiceover; 15–35 seconds total; 3–6 scenes; open with a scene; every click uses a selector from the scouted list verbatim (selectors ending in \">> nth=N\" are already disambiguated — keep them exactly); after any action that loads or computes something, waitFor an element that only appears as a result (never one that is already on the page) — if you cannot know it from the scout, use {action: wait, ms: 3000} instead; end with a wait of ~2000ms on the payoff; do not use zoom steps — scenes carry the camera; write a caption ONLY where it says something the screen cannot (never narrate a visible click), and hold the payoff in ONE frame rather than moving between tabs or views to show its parts separately.
 `;
 /** The person's standing taste — demos/style.md, written once, read by every
     draft. "No zooms, cursor visible, captions plain" should not need repeating. */

package/dist/dryrun.js

@@ -8,13 +8,74 @@
  */
 import fs from "node:fs";
 import path from "node:path";
-import { runFileOrCommandSeed, resolvePoint, dragPoints } from "./record.js";
+import { applyPageSetup, authState, dragPoints, gateOnApp, resolvePoint, runEvaluateSeed, runFileOrCommandSeed } from "./record.js";
 import { chromium } from "playwright";
 import { expandEnv, resolve } from "./manifest.js";
+async function elInfo(page, selector, timeout) {
+    try {
+        const h = await page.locator(selector).first().elementHandle({ timeout });
+        if (!h)
+            return null;
+        const info = await h.evaluate((el) => {
+            const e = el;
+            return {
+                tag: e.tagName.toLowerCase(),
+                type: (e.type ?? "").toLowerCase(),
+                disabled: !!e.disabled || e.getAttribute("aria-disabled") === "true",
+                readOnly: !!e.readOnly,
+                editable: e.isContentEditable,
+            };
+        });
+        await h.dispose();
+        return info;
+    }
+    catch {
+        return null;
+    }
+}
+/** Does this action make sense on this element? Returns the complaint, or null.
+ *
+ * This is the check that pays for itself: an action that cannot work on the
+ * element it names is knowable before a single frame is recorded, and finding
+ * it out during a take costs the whole take. So the message names the fix, not
+ * just the symptom — a report that says "use `action: select`" ends the
+ * problem, one that says "element is not an <input>" starts an investigation. */
+export function actionFits(action, el) {
+    const NOT_TEXT = new Set(["button", "submit", "reset", "checkbox", "radio", "file", "image", "range", "color"]);
+    const is = (t) => el.tag === t;
+    if (action === "type" || action === "fill") {
+        if (is("select"))
+            return `\`${action}\` cannot be used on a <select> — use \`action: select\` with \`value: "<the option>"\``;
+        if (is("input") && el.type === "file")
+            return `\`${action}\` cannot be used on a file input — use \`action: upload\` with \`file:\``;
+        if (is("input") && NOT_TEXT.has(el.type))
+            return `\`${action}\` cannot be used on <input type="${el.type}"> — it holds no text; \`action: click\` is probably what you mean`;
+        if (!is("input") && !is("textarea") && !el.editable)
+            return `\`${action}\` needs a text field, but this is a <${el.tag}> that is not editable — if it is a custom editor, target the inner element that accepts typing`;
+        if (el.disabled)
+            return `\`${action}\` cannot type into a disabled <${el.tag}> — something earlier has to enable it first`;
+        if (el.readOnly)
+            return `\`${action}\` cannot type into a read-only <${el.tag}>`;
+    }
+    if (action === "select" && !is("select")) {
+        return `\`select\` only works on a real <select>, and this is a <${el.tag}> — for a custom dropdown, \`click\` it and then \`click\` the option`;
+    }
+    if (action === "upload" && !(is("input") && el.type === "file")) {
+        return `\`upload\` needs <input type="file">, and this is a <${el.tag}>${el.type && el.type !== el.tag ? ` type="${el.type}"` : ""}`;
+    }
+    if (action === "click" && el.disabled) {
+        return `this <${el.tag}> is disabled right now — the click would do nothing; wait for whatever enables it (\`action: waitFor\`) before clicking`;
+    }
+    return null;
+}
 export async function dryRun(m, manifestDir, log, opts = {}) {
     const q = resolve(m);
     const lines = [];
     let failures = 0;
+    /** What the page actually laid out at — the width its breakpoints saw. */
+    let layoutWidth = null;
+    // Failure pictures land beside the demo's other output, not in the cwd.
+    const shotDir = path.join(opts.outRoot ?? "outputs", m.name);
     // 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
@@ -28,11 +89,23 @@ export async function dryRun(m, manifestDir, log, opts = {}) {
         log("dry: seeds skipped (--no-seed) — app state may not match what run will see");
     }
     const browser = await chromium.launch({ headless: true });
+    // Start from the same session run would. Without this, a demo behind a
+    // login was dry-run logged OUT — every selector "missing", or worse, a
+    // green dry against a marketing page and a failed take against the app.
+    const auth = authState(m, manifestDir);
+    if (auth.path)
+        log(auth.fresh ? `dry: reusing session ${path.relative(process.cwd(), auth.path)}` : `dry: no fresh session — auth.setup will have to sign in`);
     const context = await browser.newContext({
         viewport: q.viewport,
         colorScheme: m.colorScheme,
         ...(m.reducedMotion ? { reducedMotion: "reduce" } : {}),
+        ...(auth.fresh && auth.path ? { storageState: auth.path } : {}),
     });
+    // Whatever the recorder injects, dry injects — one function, so the two
+    // cannot drift apart again. (Measured, for the record: `html{zoom}` does
+    // NOT move an app's media queries, which is why the layout width reported
+    // below is asked of the page rather than computed as width÷scale.)
+    await applyPageSetup(context, m, q);
     const stubs = new Map();
     const arm = async (d) => {
         const key = `${d.method ?? "ANY"} ${d.url}`;
@@ -56,6 +129,20 @@ export async function dryRun(m, manifestDir, log, opts = {}) {
         // 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(() => { });
+        // `evaluate` seeds write into the page itself — the panel that only
+        // exists once some state is seeded. Dry skipped them, so dry and run were
+        // literally looking at different apps; that was one of three lost takes
+        // in the field report.
+        if (opts.seed !== false) {
+            for (const sd of m.seed)
+                if (sd.kind === "evaluate")
+                    await runEvaluateSeed(page, sd, manifestDir, log);
+        }
+        // The manifest's own readiness gate, with run's wrong-app diagnosis. A dry
+        // run that starts stepping before the app has booted reports selector
+        // failures that are really a race.
+        await gateOnApp(page, m, shotDir);
+        layoutWidth = await page.evaluate(() => document.documentElement.clientWidth).catch(() => null);
         for (const s of [...(m.auth?.setup ?? []), ...m.setup])
             await run(s, true);
         for (const [i, s] of m.steps.entries())
@@ -69,6 +156,16 @@ export async function dryRun(m, manifestDir, log, opts = {}) {
         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 {
+            // Before doing anything: does this action fit the element it names? A
+            // mismatch is the expensive kind of failure — the selector resolves, dry
+            // passes, and the take dies on it minutes into a recording.
+            const sel = step.selector;
+            if (sel && ["type", "fill", "select", "upload", "click"].includes(step.action)) {
+                const el = await elInfo(page, sel, short);
+                const complaint = el && actionFits(step.action, el);
+                if (complaint)
+                    throw new Error(complaint);
+            }
             // 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) => {
@@ -117,7 +214,7 @@ export async function dryRun(m, manifestDir, log, opts = {}) {
                         await page.waitForLoadState("networkidle", { timeout: 8000 }).catch(() => { });
                         break;
                     case "waitFor":
-                        await page.waitForSelector(step.selector, { timeout: Math.min(step.timeout ?? 15000, 15000) });
+                        await page.waitForSelector(step.selector, { state: step.gone ? "hidden" : "visible", 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
@@ -138,6 +235,19 @@ export async function dryRun(m, manifestDir, log, opts = {}) {
                     case "hover":
                         await page.locator(step.selector).first().hover({ timeout: short });
                         break;
+                    case "select": {
+                        // Resolving is not enough: an option that does not exist is the
+                        // whole failure mode, so dry proves the value is selectable.
+                        const sel = page.locator(step.selector).first();
+                        await sel.waitFor({ timeout: short });
+                        try {
+                            await sel.selectOption(step.value, { timeout: short });
+                        }
+                        catch {
+                            await sel.selectOption({ label: step.value }, { timeout: short });
+                        }
+                        break;
+                    }
                     case "scroll":
                         if (step.to)
                             await page.locator(step.to).first().boundingBox({ timeout: short });
@@ -160,6 +270,9 @@ export async function dryRun(m, manifestDir, log, opts = {}) {
                     case "wait":
                         await page.waitForTimeout(isSetup ? step.ms : Math.min(step.ms, 400));
                         break;
+                    case "callout":
+                        await point(step.selector ?? step.at);
+                        break;
                     default: break; // scene, screenshot, zoom, download: nothing to verify
                 }
             if (step.pauseAfter)
@@ -176,6 +289,16 @@ export async function dryRun(m, manifestDir, log, opts = {}) {
                 where = `\n        on ${page.url()} — “${text}”`;
             }
             catch { /* page may be gone */ }
+            // Text alone cannot say "another element is covering the button" or
+            // "the layout is not what you think". A picture can, and dry is the
+            // cheap pass — it should hand over more than run's does, not less.
+            try {
+                const shot = path.join(shotDir, `dry-failed-${String(failures).padStart(2, "0")}.png`);
+                fs.mkdirSync(shotDir, { recursive: true });
+                await page.screenshot({ path: shot, fullPage: true });
+                where += `\n        picture: ${path.relative(process.cwd(), shot)}`;
+            }
+            catch { /* not fatal */ }
             const line = `✗ [${tag}] ${describe(step)} — ${why}${where}`;
             lines.push(line);
             log(line);
@@ -183,8 +306,68 @@ export async function dryRun(m, manifestDir, log, opts = {}) {
     }
     const ok = failures === 0;
     log(ok ? `dry run: all ${m.steps.length} steps resolved` : `dry run: ${failures} step(s) would fail`);
+    // A preset's width is VIDEO pixels: at scale 2 a 1920 preset lays the page
+    // out at 960 CSS px, under most desktop breakpoints, so a responsive app
+    // quietly serves its MOBILE layout and the steps are looking for fields that
+    // are not there. It reads as a pile of broken selectors, and costs a whole
+    // take to work out. Only asked when something actually failed, and only
+    // reported when the wider page proves it.
+    if (!ok) {
+        // Measured, not computed: `zoom` does not move an app's media queries, so
+        // width÷scale is not the number the page's breakpoints saw. Ask the page.
+        const cssWidth = layoutWidth ?? q.viewport.width;
+        if (cssWidth < 1100) {
+            const missing = lines.map((l) => /✗ \[[^\]]+\] \w+ (.+?) —/.exec(l)?.[1]).filter((x) => !!x);
+            const found = await resolvesWiderThan(m, missing, cssWidth, manifestDir);
+            if (found.length) {
+                const note = `⚠ ${found.length} of these selector(s) DO exist when the page is 1280 CSS px wide, but not at ${cssWidth}px.\n` +
+                    `   This take lays the page out at ${cssWidth} CSS px, which is below this app's desktop breakpoint — you are filming its mobile layout.\n` +
+                    `   Fix: give the manifest a wider \`viewport\`, or write the steps against the layout you are actually filming.\n` +
+                    `   Resolved wider: ${found.slice(0, 4).join(", ")}${found.length > 4 ? ` … +${found.length - 4}` : ""}`;
+                lines.push(note);
+                log(note);
+            }
+        }
+    }
     return { ok, lines, failures };
 }
+/** Load the same page at a desktop width and report which of these selectors
+    resolve there. Proof, not a guess: it is only worth telling someone their
+    preset is filming the mobile layout if the wider page really does have the
+    thing they were looking for. */
+async function resolvesWiderThan(m, selectors, narrowPx, manifestDir) {
+    const unique = [...new Set(selectors)].filter((s) => s && !s.startsWith("http"));
+    if (!unique.length || narrowPx >= 1280)
+        return [];
+    const browser = await chromium.launch({ headless: true });
+    try {
+        const ctx = await browser.newContext({ viewport: { width: 1280, height: 900 }, colorScheme: m.colorScheme });
+        const page = await ctx.newPage();
+        for (const d of m.stub) {
+            await ctx.route(d.url, async (route) => {
+                const body = d.json !== undefined ? JSON.stringify(d.json) : d.from ? fs.readFileSync(path.resolve(manifestDir, expandEnv(d.from)), "utf8") : "{}";
+                await route.fulfill({ status: d.status ?? 200, contentType: d.contentType, body });
+            });
+        }
+        await page.goto(expandEnv(m.url), { waitUntil: "domcontentloaded", timeout: 30000 });
+        await page.waitForLoadState("networkidle", { timeout: 6000 }).catch(() => { });
+        const found = [];
+        for (const sel of unique) {
+            try {
+                if (await page.locator(sel).first().isVisible({ timeout: 1500 }))
+                    found.push(sel);
+            }
+            catch { /* still missing */ }
+        }
+        return found;
+    }
+    catch {
+        return [];
+    }
+    finally {
+        await browser.close().catch(() => { });
+    }
+}
 function describe(s) {
     if ("selector" in s && s.selector)
         return `${s.action} ${s.selector}`;

package/dist/env.js

@@ -0,0 +1,76 @@
+/**
+ * The workspace `.env` — where an app's demo-account credentials live.
+ *
+ * Three things write it: the person (by hand, or `retake secret NAME`), the
+ * window (when an agent asks for a secret by name), and Settings. None of
+ * them ever hands a value to a model: the agent learns that `APP_PASSWORD`
+ * is *set*, and references it as `${APP_PASSWORD}` with `secret: true`.
+ */
+import fs from "node:fs";
+import path from "node:path";
+export const SECRET_NAME = /^[A-Z][A-Z0-9_]{1,63}$/;
+/** Parse KEY=value lines (quotes stripped, comments and blanks ignored). */
+export function readEnvFile(root) {
+    const file = path.join(root, ".env");
+    if (!fs.existsSync(file))
+        return {};
+    const out = {};
+    for (const raw of fs.readFileSync(file, "utf8").split(/\r?\n/)) {
+        const m = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/.exec(raw);
+        if (!m)
+            continue;
+        const v = m[2].trim();
+        // Double-quoted values are JSON strings (that is how writeEnvFile writes
+        // anything awkward); single-quoted are literal; bare is bare.
+        if (v.startsWith('"') && v.endsWith('"')) {
+            try {
+                out[m[1]] = JSON.parse(v);
+                continue;
+            }
+            catch { /* fall through */ }
+        }
+        out[m[1]] = v.replace(/^(["'])(.*)\1$/, "$2");
+    }
+    return out;
+}
+/** Set (or, with "", remove) keys in .env, leaving every other line alone.
+    Returns the keys actually written. Also updates process.env so the
+    calling process sees the new values without a restart. */
+export function writeEnvFile(root, set) {
+    const file = path.join(root, ".env");
+    const lines = fs.existsSync(file) ? fs.readFileSync(file, "utf8").split("\n") : [];
+    const written = [];
+    for (const [k, v] of Object.entries(set)) {
+        if (v === undefined)
+            continue;
+        const i = lines.findIndex((l) => l.startsWith(k + "="));
+        // Quote when the value has anything a shell-ish parser would trip on.
+        const line = `${k}=${/[\s#"']/.test(v) ? JSON.stringify(v) : v}`;
+        if (v === "") {
+            if (i >= 0)
+                lines.splice(i, 1);
+            delete process.env[k];
+        }
+        else {
+            if (i >= 0)
+                lines[i] = line;
+            else
+                lines.push(line);
+            process.env[k] = v;
+        }
+        written.push(k);
+    }
+    fs.writeFileSync(file, lines.filter((l, i, a) => l !== "" || i < a.length - 1).join("\n").replace(/\n*$/, "\n"), { mode: 0o600 });
+    // `mode` above only applies to a new file; an existing .env keeps whatever
+    // it had. Credentials went in, so: owner-only, every time.
+    try {
+        fs.chmodSync(file, 0o600);
+    }
+    catch { /* windows */ }
+    return written;
+}
+/** Which of these names are not set (missing or blank) in .env + the environment. */
+export function missingSecrets(root, names) {
+    const file = readEnvFile(root);
+    return names.filter((n) => !(process.env[n]?.trim() || file[n]?.trim()));
+}