@vosjs/cli 0.42.0 → 0.43.0

package/README.md

@@ -80,7 +80,7 @@ vos plan take --reuse                                   # re-time that cut onto
 
 | Verb     | Flags                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
 | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `record` | `--actions <file>` (or positional) `--url` `--out take` `--strict` `--dry-run` `--allow-wall` `--keep-frames` `--storage-state <file>` `--browser-arg=<switch>`... `--max-duration <s>` `--background <slug\|url\|none>`                                                                                                                                                                                                                                                  |
+| `record` | `--actions <file>` (or positional) `--url` `--out take` `--strict` `--dry-run` `--allow-wall` `--keep-frames` `--storage-state <file>` `--header name=value`... `--browser-arg=<switch>`... `--max-duration <s>` `--background <slug\|url\|none>`                                                                                                                                                                                                                         |
 | `create` | The `record` flags plus the render flags (`--width` `--height` `--fps` `--format` `--parallel` `--draft` `--frame` `--set`), no `--range`. With `--strict` an incomplete recording exits 2 before anything is rendered                                                                                                                                                                                                                                                    |
 | `plan`   | `--fresh` (discard the current plan) `--reuse` `--from <doc.json>` (defaults to `<take>/doc.prev.json`) `--style <doc.json\|take\|vosId>` `--with <doc.json\|take\|vosId>[@end\|@start\|@step:<id>\|@<seconds>]` (a template, repeatable) `--background` `--motion` (re-propose the motion) `--headline` `--kicker` `--launch` `--brand` `--music` `--entrance` `--transitions slide\|fade\|scale\|none` `--end-card on\|none\|<ref>` `--captions` `--clicks` `--release` |
 | `digest` | `--out <take>/digest` `--full 960` `--crop 640` (image long edges, the token budget) `--no-frames` `--transcript <file>` (Whisper-shaped segments merged as `said`) `--style <ref>` (report a reference document's style fields)                                                                                                                                                                                                                                          |
@@ -90,6 +90,19 @@ vos plan take --reuse                                   # re-time that cut onto
 
 **The wall check.** Once the first navigation settles, and before a frame is captured, `record`, `create` and `--dry-run` ask whether the recorder landed where it was sent. A take that met a sign-in instead is refused with exit 4 and a sentence (`asked for /dashboard, landed on /login: no session for app.acme.com`): the asked URL answered 401 or 403, the recorder was sent to an identity provider or a sign-in path, or the page is a sign-in form (one password field, or a one-time-code field) rendered in place. A redirect somewhere else with no sign-in in sight, which is what a site that shows strangers a public page looks like, is refused under `--strict` and in a rehearsal, and said as a warning otherwise. The check runs before a re-record clears anything, so a session that expired since the last take never costs the footage it failed to replace. The way past a wall is a session: `--storage-state <file>`, minted from the test auth the project already has wherever that exists. `--allow-wall` records the page anyway (a video OF a sign-in page is a legitimate take), and the take's `meta.wall` and its digest then say so.
 
+**`setup`: the steps that run before the camera rolls.** A sign-in form, a cookie banner, the "choose your editor" modal, an onboarding tour: things a take must get past and must not show. `actions.json` takes `setup: [...]` beside `steps`, with the verbs `goto`, `click`, `type`, `press`, `wait`. They run after the first navigation and before a frame is captured, as plain actions with no cursor, no frames, no pace and nothing in `meta.steps`; then the recorder opens `url` again and the take begins where the setup left it. A `type` step's `text` may be `{ "env": "DEMO_PASSWORD" }`, read from the shell at run time and never logged or stored (the log names the field, never the value; a literal typed into a password field is refused by `validate`, because `actions.json` is committed and pushed with the take). A selector that never appears fails the take before anything is recorded (exit 2), because a take that begins at a half-finished sign-in is the wall by another name; rehearse the setup with `--dry-run` like everything else. This is rung 2 of the session ladder made scriptable: a local or self-hosted instance with a seeded user, no state file needed.
+
+```json
+"setup": [
+  { "do": "goto", "url": "http://localhost:3000/login" },
+  { "do": "type", "selector": "#email", "text": "demo@acme.test" },
+  { "do": "type", "selector": "#password", "text": { "env": "DEMO_PASSWORD" } },
+  { "do": "press", "key": "Enter", "ms": 800 }
+]
+```
+
+**`--header name=value`**, repeatable: a request header on every request the recording browser makes, the way past a preview deployment protected by a bypass header alone (`--header x-vercel-protection-bypass=$TOKEN`). The rehearsal's `Next:` line carries it.
+
 **What the frame shows.** Getting past a login puts the account's own data in the picture, and asking for a demo account does not hold that line: a person asked to sign in signs in as themselves. So the recorder looks. After the page opens and after every step it reads the text visible in the viewport and reports the KIND of thing it saw and where, never the string: an email address (one on `example.com` or a `.test`, `.example`, `.invalid` or `.localhost` domain is demo data and is not reported), something shaped like an API key or a JWT, a card number that passes the Luhn check, a masked card's visible tail. They land in `meta.exposures[]` (`step`, `kind`, `selector`, `rect`, `seen`), in the `record` and `create` done events, at the end of a rehearsal (before anything is recorded), as warnings in `vos validate <take>`, and in the digest's `take.exposures`. They warn; they do not fail a take, because a product may legitimately show addresses. The `selector` reaches that element and no other, so it can be pasted into a mask.
 
 **`mask`** in `actions.json` hides a selector BEFORE the first frame is captured and keeps it hidden across navigations and re-renders, so the real value is never in a frame, never in the recording, never pushed:

package/dist/{chunk-7RMULTDM.js → chunk-6PJPGBKH.js}

@@ -101,8 +101,137 @@ function createReporter(json) {
   };
 }
 
+// src/plugin/setup.ts
+var VERBS = /* @__PURE__ */ new Set(["wait", "click", "type", "press", "goto"]);
+function validateSetup(value) {
+  const errors = [];
+  if (!Array.isArray(value)) return ["setup must be an array of steps"];
+  value.forEach((raw, i) => {
+    const at2 = `setup[${i}]`;
+    if (typeof raw !== "object" || raw === null) {
+      errors.push(`${at2}: must be an object`);
+      return;
+    }
+    const s = raw;
+    if (typeof s.do !== "string" || !VERBS.has(s.do)) {
+      errors.push(`${at2}: "do" must be one of ${[...VERBS].join(", ")}`);
+      return;
+    }
+    if ((s.do === "click" || s.do === "type") && typeof s.selector !== "string")
+      errors.push(`${at2}: ${s.do} needs a selector`);
+    if (s.do === "wait" && typeof s.ms !== "number")
+      errors.push(`${at2}: wait needs ms`);
+    if (s.do === "press" && typeof s.key !== "string")
+      errors.push(`${at2}: press needs a key`);
+    if (s.do === "goto" && typeof s.url !== "string")
+      errors.push(`${at2}: goto needs a url`);
+    if (s.do === "type") {
+      const t = s.text;
+      const isEnv = typeof t === "object" && t !== null && typeof t.env === "string" && Object.keys(t).length === 1;
+      if (typeof t !== "string" && !isEnv)
+        errors.push(
+          `${at2}: type needs text, a string or { "env": "NAME" } read at run time`
+        );
+      if (typeof t === "string" && /passw|secret|token/i.test(String(s.selector)) && t.length > 0)
+        errors.push(
+          `${at2}: a literal value typed into ${String(s.selector)} would live in actions.json, which is committed and pushed. Use { "env": "NAME" }`
+        );
+    }
+  });
+  return errors;
+}
+function resolveSetupText(t, env = process.env) {
+  if (typeof t === "string") return { value: t, secret: false };
+  const v = env[t.env];
+  if (v === void 0 || v === "")
+    throw new SetupEnvError(
+      `setup: the environment variable ${t.env} is not set, and a type step reads it. Export it in the shell that runs vos record; it is never written to a file`
+    );
+  return { value: v, secret: true };
+}
+async function runSetup(page, steps, opts) {
+  const lines = [];
+  for (const [i, step] of steps.entries()) {
+    const settle = "ms" in step && typeof step.ms === "number" ? step.ms : 150;
+    try {
+      switch (step.do) {
+        case "wait":
+          await opts.sleep(step.ms);
+          lines.push(`setup #${i} wait ${step.ms}ms`);
+          break;
+        case "goto":
+          await page.goto(step.url, { waitUntil: "networkidle", timeout: 45e3 }).catch(() => {
+          });
+          lines.push(`setup #${i} goto ${step.url}`);
+          break;
+        case "press":
+          await page.keyboard.press(step.key);
+          await opts.sleep(settle);
+          lines.push(`setup #${i} press ${step.key}`);
+          break;
+        case "click": {
+          const loc = page.locator(step.selector).first();
+          await loc.waitFor({ state: "visible", timeout: 8e3 });
+          await loc.click();
+          await opts.sleep(settle);
+          lines.push(`setup #${i} click ${step.selector}`);
+          break;
+        }
+        case "type": {
+          const loc = page.locator(step.selector).first();
+          await loc.waitFor({ state: "visible", timeout: 8e3 });
+          const { value, secret } = resolveSetupText(step.text, opts.env);
+          await loc.fill(value);
+          await opts.sleep(settle);
+          lines.push(
+            `setup #${i} type ${secret ? `\${${step.text.env}}` : `${value.length} chars`} into ${step.selector}`
+          );
+          break;
+        }
+      }
+    } catch (e) {
+      if (e instanceof SetupEnvError) throw e;
+      return {
+        ran: i,
+        lines,
+        failed: {
+          step: i,
+          do: step.do,
+          ..."selector" in step ? { selector: step.selector } : {}
+        }
+      };
+    }
+  }
+  return { ran: steps.length, lines };
+}
+var SetupEnvError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "SetupEnvError";
+  }
+};
+var SetupError = class extends Error {
+  constructor(failed2) {
+    super(
+      `setup #${failed2.step} ${failed2.do}${failed2.selector ? ` ${failed2.selector}` : ""}: the selector never appeared, so the take would begin at a half-finished setup. Nothing was recorded. Fix the setup step (rehearse with --dry-run), then record.`
+    );
+    this.failed = failed2;
+    this.name = "SetupError";
+  }
+  failed;
+};
+function parseHeaders(given) {
+  const out = {};
+  for (const h of given ?? []) {
+    const i = h.indexOf("=");
+    if (i <= 0) throw new Error(`--header wants name=value, got "${h}"`);
+    out[h.slice(0, i).trim()] = h.slice(i + 1);
+  }
+  return out;
+}
+
 // src/plugin/actions.ts
-var VERBS = /* @__PURE__ */ new Set([
+var VERBS2 = /* @__PURE__ */ new Set([
   "wait",
   "hover",
   "click",
@@ -129,6 +258,7 @@ function validateActions(value) {
       }
     }
   }
+  if (obj.setup !== void 0) errors.push(...validateSetup(obj.setup));
   if (obj.mask !== void 0) {
     if (!Array.isArray(obj.mask)) {
       errors.push("mask must be an array of { selector, as?, text? }");
@@ -159,8 +289,8 @@ function validateActions(value) {
       return;
     }
     const s = raw;
-    if (typeof s.do !== "string" || !VERBS.has(s.do)) {
-      errors.push(`${at2}: "do" must be one of ${[...VERBS].join(", ")}`);
+    if (typeof s.do !== "string" || !VERBS2.has(s.do)) {
+      errors.push(`${at2}: "do" must be one of ${[...VERBS2].join(", ")}`);
       return;
     }
     if (s.id !== void 0) {
@@ -6994,7 +7124,8 @@ async function recordTake(browser, url, actions, paths, log, opts = {}) {
   const context = await browser.newContext({
     viewport: { width: vw, height: vh },
     deviceScaleFactor: 1,
-    ...opts.storageState ? { storageState: opts.storageState } : {}
+    ...opts.storageState ? { storageState: opts.storageState } : {},
+    ...opts.headers && Object.keys(opts.headers).length ? { extraHTTPHeaders: opts.headers } : {}
   });
   const masks = actions.mask ?? [];
   if (masks.length) await context.addInitScript(maskInitScript(masks));
@@ -7009,12 +7140,26 @@ async function recordTake(browser, url, actions, paths, log, opts = {}) {
   });
   log(`goto ${url}`);
   let navTimeout = false;
-  const response = await page.goto(url, { waitUntil: "networkidle", timeout: 45e3 }).catch(() => {
+  let response = await page.goto(url, { waitUntil: "networkidle", timeout: 45e3 }).catch(() => {
     navTimeout = true;
     log("   (networkidle timeout \u2014 continuing)");
     return null;
   });
   await sleep(800);
+  const setup = actions.setup ?? [];
+  if (setup.length) {
+    log(`setup: ${setup.length} step(s), off camera`);
+    const result = await runSetup(page, setup, { sleep: realSleep });
+    for (const line of result.lines) log(`   ${line}`);
+    if (result.failed) {
+      await context.close().catch(() => {
+      });
+      throw new SetupError(result.failed);
+    }
+    log(`goto ${url} (after setup)`);
+    response = await page.goto(url, { waitUntil: "networkidle", timeout: 45e3 }).catch(() => null);
+    await sleep(800);
+  }
   let wall = null;
   if (opts.onArrival) {
     const seen = await page.evaluate(WALL_PROBE).catch(() => null);
@@ -10518,12 +10663,12 @@ var BOOLEAN_FLAGS5 = /* @__PURE__ */ new Set([
   "dry-run",
   "allow-wall"
 ]);
-var MULTI_FLAGS2 = /* @__PURE__ */ new Set(["set", "override", "browser-arg"]);
+var MULTI_FLAGS2 = /* @__PURE__ */ new Set(["set", "override", "browser-arg", "header"]);
 var HELP = `vos \u2014 record a browser flow, plan effects, render a product video; sync with vos.so
 
 Take pipeline
-  vos create --actions actions.json [--url <url>] [--out take] [out.webm] [--strict] [--allow-wall] [--keep-frames] [--max-duration <s>] [--storage-state <file>] [--browser-arg=<switch>]... [--background <slug|url|none>] [render flags] [--json]
-  vos record --actions actions.json [--url <url>] [--out take] [--strict] [--dry-run] [--allow-wall] [--keep-frames] [--max-duration <s>] [--storage-state <file>] [--browser-arg=<switch>]... [--background <slug|url|none>] [--json]
+  vos create --actions actions.json [--url <url>] [--out take] [out.webm] [--strict] [--allow-wall] [--keep-frames] [--max-duration <s>] [--storage-state <file>] [--header name=value]... [--browser-arg=<switch>]... [--background <slug|url|none>] [render flags] [--json]
+  vos record --actions actions.json [--url <url>] [--out take] [--strict] [--dry-run] [--allow-wall] [--keep-frames] [--max-duration <s>] [--storage-state <file>] [--header name=value]... [--browser-arg=<switch>]... [--background <slug|url|none>] [--json]
   vos plan <take> [--fresh] [--reuse [--from <doc.json>]] [--style <doc.json|vosId>] [--with <doc.json|vosId>[@end|@start|@step:<id>|@<s>]]... [--background <slug|url|none>] [--motion] [--headline "\u2026"] [--kicker "\u2026"] [--launch LAUNCH.md] [--brand BRAND.md] [--music <slug|mood|none>] [--entrance tilt-in|pull-out|rise|fade|slide|none] [--transitions slide|fade|scale|none] [--end-card on|none|<doc.json|vosId>] [--captions none] [--clicks none] [--still <t>] [--release v2.1] [--json]
   vos render <take> [out.webm] [--width] [--height] [--fps] [--format webm|mp4] [--parallel N] [--range a..b] [--draft] [--frame <kind>] [--background <url|slug>] [--set <path=value>]... [--json]
   vos frames <take> [--times 0,25%,50%,75%,100%] [--frame <t>] [--at-zooms] [--at-moments] [--at-still] [--size WxH] [--out dir] [--background <url|slug>] [--set <path=value>]... [--json]
@@ -10816,6 +10961,13 @@ function exposureNote(rec) {
 ${rec.exposures.map((e) => `    - ${exposureLine(e)}`).join("\n")}
   ${EXPOSURE_ADVICE}`;
 }
+function takeHeaders(multi) {
+  try {
+    return parseHeaders(multi.header);
+  } catch (e) {
+    throw new UsageError(e instanceof Error ? e.message : String(e));
+  }
+}
 function takeBrowserArgs(multi) {
   const given = multi["browser-arg"];
   return (given ?? []).filter(Boolean);
@@ -10886,6 +11038,7 @@ async function cmdRecord(argv) {
   const maxDurationSeconds = await maxDuration(flags, r);
   const storageState = takeStorageState(flags);
   const browserArgs = takeBrowserArgs(multi);
+  const headers = takeHeaders(multi);
   if (flags["dry-run"] === true) {
     void flags.strict;
     void flags["keep-frames"];
@@ -10902,6 +11055,7 @@ async function cmdRecord(argv) {
         r.log,
         {
           storageState,
+          headers,
           dryRun: true,
           // A rehearsal is always strict, and it touches no directory.
           onArrival: wallGate(flags, r, { strict: true })
@@ -10917,6 +11071,7 @@ async function cmdRecord(argv) {
       const carried = [
         ...strFlag(flags, "storage-state") ? [`--storage-state ${strFlag(flags, "storage-state")}`] : [],
         ...browserArgs.map((a) => `--browser-arg=${a}`),
+        ...Object.entries(headers).map(([k, v]) => `--header ${k}=${v}`),
         ...flags["allow-wall"] === true ? ["--allow-wall"] : []
       ].join(" ");
       const nextOut = strFlag(flags, "out") ?? "take";
@@ -10958,6 +11113,7 @@ ${lines.join("\n")}
     const rec = await recordTake(browser, url, actions, paths, r.log, {
       maxDurationSeconds,
       storageState,
+      headers,
       onArrival: wallGate(flags, r, {
         strict: flags.strict === true,
         prepare
@@ -11038,6 +11194,7 @@ async function cmdCreate2(argv) {
   const maxDurationSeconds = await maxDuration(flags, r);
   const storageState = takeStorageState(flags);
   const browserArgs = takeBrowserArgs(multi);
+  const headers = takeHeaders(multi);
   const paths = takePaths(outDir);
   const prepare = async () => {
     if (existsSync15(join18(outDir, "meta.json"))) {
@@ -11056,6 +11213,7 @@ async function cmdCreate2(argv) {
     const rec = await recordTake(browser, url, actions, paths, r.log, {
       maxDurationSeconds,
       storageState,
+      headers,
       onArrival: wallGate(flags, r, {
         strict: flags.strict === true,
         prepare
@@ -12196,6 +12354,11 @@ async function run(argv) {
   } catch (e) {
     if (e instanceof UsageError) {
       process.stderr.write(`usage error: ${e.message}
+`);
+      return EXIT_USAGE;
+    }
+    if (e instanceof SetupError || e instanceof SetupEnvError) {
+      process.stderr.write(`${e.message}
 `);
       return EXIT_USAGE;
     }
@@ -12248,4 +12411,4 @@ export {
   verbHelp,
   run
 };
-//# sourceMappingURL=chunk-7RMULTDM.js.map
+//# sourceMappingURL=chunk-6PJPGBKH.js.map