@vosjs/cli 0.38.0 → 0.40.0

package/README.md

@@ -60,6 +60,7 @@ A **take** is a directory: the recording of a scripted browser flow, its exact c
 
 ```bash
 vos create --actions actions.json out.webm --strict     # one shot: record, auto-plan, render
+vos record --actions actions.json --out take --dry-run  # rehearse the script first: which selectors resolve, their rects, in seconds
 vos record --actions actions.json --out take --strict   # drive the page, record it with an exact cursor track, plan the cut
 vos digest take                                         # SEE the recording before cutting: moments, frames, crops (an agent's eyes)
 # … edit take/doc.json (zoom spans, trims, speed, overlays) by hand or by agent …
@@ -79,7 +80,7 @@ vos plan take --reuse                                   # re-time that cut onto
 
 | Verb     | Flags                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
 | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `record` | `--actions <file>` (or positional) `--url` `--out take` `--strict` `--max-duration <s>` `--background <slug\|url\|none>`                                                                                                                                                                                                                                                                                                                                                  |
+| `record` | `--actions <file>` (or positional) `--url` `--out take` `--strict` `--dry-run` `--keep-frames` `--storage-state <file>` `--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)                                                                                                                                                                                                                                          |
@@ -87,6 +88,8 @@ vos plan take --reuse                                   # re-time that cut onto
 | `render` | `--width` `--height` `--fps` `--format webm\|mp4` `--parallel N` (1..16 sessions) `--range a..b` (output seconds; keeps its audio) `--draft` `--frame <kind>` `--background` `--set …`; `out` defaults to `<take>/out.<format>`                                                                                                                                                                                                                                           |
 | `open`   | `--studio http://localhost:6060` `--print` (print the URL, do not launch a browser)                                                                                                                                                                                                                                                                                                                                                                                       |
 
+**Rehearse before you record.** `vos record … --dry-run` runs every step against the real page, in order, because a later selector usually exists only after an earlier click. Nothing is captured and nothing is written: the pointer lands instead of travelling, every pause is cut to a beat, and the take directory beside it keeps its footage, its cut and its script exactly as they were (a real re-record moves `doc.json` aside; a rehearsal does not). Selector lookups keep their whole timeout, so a miss here is a miss in the take. It prints each step with the rect it resolved, in capture px, which are the rects a pin or `vos callout --step` reads, and exits 2 on any miss or a first load that never settled. Add `--dry-run` to the exact command you were about to run; `--storage-state` and `--browser-arg=` apply to it too.
+
 **Digest first.** `vos digest <take>` is how an agent sees a recording without reading the video. It writes `digest/digest.json`: one moment per thing the cursor track says mattered (click clusters, typing sessions, scroll runs, dwells, idle gaps, head, tail, and frame-diff scene changes), each with source and output extents, a normalized `focus` and `rect` you can copy into a zoom span, per-second `activity`, and the planners' `proposed` span ids; plus one footage frame and a crop around the target per moment, and `sheet.png`, the contact sheet. Read the JSON, then the sheet, then a crop only where you must decide. `vos validate` then warns when a zoom does not contain what was clicked under it, and `vos frames --at-moments` renders the composed output at every moment so a still and its footage crop share an id.
 
 **Many media in one take (concat).** `doc.json` may carry `media: [{ id, videoKey, cursor, meta, … }]`, the take's OTHER recordings or uploads, each the `source` shape with an `id`; a segment on one (`{ in, out, media: "m1" }`) plays it, and a zoom, tilt, speed, freeze or cam-move span names the media its source seconds belong to (absent = the primary, `source`). The Video row shows the clips in order, a span is drawn where its media plays, `vos plan` proposes zoom and speed spans on every media from its own cursor track, `vos validate` measures each span against its own media's length, and `vos push` and `vos pull --media` carry every media through the recording door. A media wears its OWN card: `media[].frame` carries the card-owned fields (its placement and size as `inset`, the browser bar, the corner, the shadow, the border, the cover fit and its focus) over the take's frame while it plays; the bar names that media's recorded page, an upload with no page wears none, and the frame-wide fields (the aspect, the padding, the ground, the backdrop, the card's animation) stay the take's. Sound: the primary's tracks play at the primary's moments; another media's own audio is not spliced into the cut yet. **Many cards**: an image or video overlay may show a document media by reference (`key: "media:<id>"`, `media:` alone the primary; its cursor track and recorded page come with it) and wear a card (`frame`: `browserBar`, a `lean` `{rx, ry}` in degrees, `shadow`, `shadowContact`, `shadowColor`, `cursor`), drawn by the card painter on its own plane above the primary card with the media's cursor dot and click rings inside it; a layer without `frame` stays the flat picture. The primary card stays primary: the sequence, the camera and the cut are its.
@@ -214,8 +217,9 @@ Everything that runs on your machine is open source; [vos.so](https://vos.so) is
 vos login [--key <k>] [--label <name>] [--no-browser]   # browser sign-in: a code and a vos.so/cli/auth URL, a human approves, the key stores itself
 vos fetch <vosId|url> [--out <slug>] [--media]         # a program writes config.json + vos.json; a take writes doc.json (+ the recording with --media)
 vos check bright-loop/config.json                      # full local validation
-vos push bright-loop/config.json                       # create a PRIVATE vos (lineage from vos.json or --remix-of)
-vos push bright-loop/config.json --vos <id>            # add a version against your tracked base
+vos push bright-loop/config.json                       # untracked: create a PRIVATE vos. Tracked (vos.json): add a version to it
+vos push bright-loop/config.json --vos <id>            # add a version to a vos this directory does not track
+vos push bright-loop/config.json --remix-of <id>       # create a SEPARATE vos from this config, with that lineage
 vos push bright-loop/config.json --claimable           # no credential: a 72 h claim link instead (programs only)
 vos push take --yes --label "first pass" --note "…"    # host a take: private vos + version history (the recording uploads once)
 vos pull bright-loop [--since <versionId>] [--check]   # what changed on vos.so since your base; syncs config.json (backup kept), or doc.json for a take
@@ -226,7 +230,7 @@ vos asset push <file…> [--folder <slug>] | rename <id> <name.ext>
 vos recipe push <FILE.md> --folder <slug> | --asset <id>   # the one recipe write: create, or replace in place
 ```
 
-`push` is polymorphic by a deterministic sniff, never a flag: a take directory (a `doc.json` carrying `source`) pushes recording and document through the take pipeline; a `config.json` (or a directory holding one) pushes the program, and a `doc.json` beside it that carries `program` (a program document: overlays, objects, audio, speed, tween edits, its own length; `program.config` omitted on disk) rides along, lint-gated. `fetch` and `pull` write a program document back the same way. `pull` takes `--since <versionId>` (walk the changelog from that base instead of the tracked one) and `--check` (print what changed and stop: nothing on disk moves) on both paths. Program pushes take `--vos`, `--title`, `--slug`, `--desc`, `--tags`, `--folder`, `--remix-of`, `--base`, `--label`, `--note`, `--override <id>` (repeatable) and `--claimable`; take pushes take `--title`, `--label`, `--note`, `--folder`, `--override` and `--yes`.
+`push` is polymorphic by a deterministic sniff, never a flag: a take directory (a `doc.json` carrying `source`) pushes recording and document through the take pipeline; a `config.json` (or a directory holding one) pushes the program, and a `doc.json` beside it that carries `program` (a program document: overlays, objects, audio, speed, tween edits, its own length; `program.config` omitted on disk) rides along, lint-gated. `fetch` and `pull` write a program document back the same way. `pull` takes `--since <versionId>` (walk the changelog from that base instead of the tracked one) and `--check` (print what changed and stop: nothing on disk moves) on both paths. A program push LANDS where `vos.json` says: a directory that tracks a vos iterates it, so the fetch, edit, check, push, pull loop needs no flags, and making something separate from the same config is the explicit `--remix-of` door. Program pushes take `--vos`, `--title`, `--slug`, `--desc`, `--tags`, `--folder`, `--remix-of`, `--base`, `--label`, `--note`, `--override <id>` (repeatable) and `--claimable`; take pushes take `--title`, `--label`, `--note`, `--folder`, `--override` and `--yes`.
 
 Both paths share the same base tracking and the same two 409 shapes. `stale_base` replays the platform's typed changelog: run `vos pull`, re-apply, push again. `protected_conflict` lists nodes a human edited in the studio: keep their values, or re-push with `--override <id>` only when the user asked for that exact change. The first push of a take asks before uploading (`--yes` for headless); agents never upload unprompted. The take's duration rides the upload, and the platform refuses a take over the hosted recording cap. Every push should carry `--label` (what changed, one line) and `--note` (why: the user's ask); the version history reads as a conversation, and an unlabelled push is a turn the human cannot read.
 

package/dist/{chunk-LGRNHJ2U.js → chunk-7TDL3N24.js}

@@ -6629,7 +6629,8 @@ function paceLine(r) {
 }
 
 // src/plugin/recorder.ts
-var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+var realSleep = (ms) => new Promise((r) => setTimeout(r, ms));
+var DRY_PAUSE_MS = 120;
 function jpegDims(buf) {
   let i = 2;
   while (i < buf.length - 9) {
@@ -6644,7 +6645,9 @@ function jpegDims(buf) {
   return null;
 }
 async function recordTake(browser, url, actions, paths, log, opts = {}) {
-  const maxSeconds = opts.maxDurationSeconds ?? Infinity;
+  const dry = opts.dryRun === true;
+  const sleep = dry ? (ms) => realSleep(Math.min(ms, DRY_PAUSE_MS)) : realSleep;
+  const maxSeconds = dry ? Infinity : opts.maxDurationSeconds ?? Infinity;
   const vw = actions.viewport?.width ?? 1280;
   const vh = actions.viewport?.height ?? 720;
   const context = await browser.newContext({
@@ -6667,22 +6670,24 @@ async function recordTake(browser, url, actions, paths, log, opts = {}) {
   const frames = [];
   let frameIdx = 0;
   let t0 = 0;
-  cdp.on("Page.screencastFrame", (ev) => {
-    const tsMs = ev.metadata.timestamp ? ev.metadata.timestamp * 1e3 : Date.now();
-    const file = `frame-${String(frameIdx++).padStart(5, "0")}.jpg`;
-    writeFileSync2(join13(paths.framesDir, file), Buffer.from(ev.data, "base64"));
-    frames.push({ file, tMs: Math.max(0, Math.round(tsMs - t0)) });
-    cdp.send("Page.screencastFrameAck", { sessionId: ev.sessionId }).catch(() => {
+  if (!dry)
+    cdp.on("Page.screencastFrame", (ev) => {
+      const tsMs = ev.metadata.timestamp ? ev.metadata.timestamp * 1e3 : Date.now();
+      const file = `frame-${String(frameIdx++).padStart(5, "0")}.jpg`;
+      writeFileSync2(join13(paths.framesDir, file), Buffer.from(ev.data, "base64"));
+      frames.push({ file, tMs: Math.max(0, Math.round(tsMs - t0)) });
+      cdp.send("Page.screencastFrameAck", { sessionId: ev.sessionId }).catch(() => {
+      });
     });
-  });
   t0 = Date.now();
-  await cdp.send("Page.startScreencast", {
-    format: "jpeg",
-    quality: 90,
-    maxWidth: vw,
-    maxHeight: vh,
-    everyNthFrame: 1
-  });
+  if (!dry)
+    await cdp.send("Page.startScreencast", {
+      format: "jpeg",
+      quality: 90,
+      maxWidth: vw,
+      maxHeight: vh,
+      everyNthFrame: 1
+    });
   const events = [];
   const cur = { x: 48, y: 48 };
   const now = () => Date.now() - t0;
@@ -6694,7 +6699,7 @@ async function recordTake(browser, url, actions, paths, log, opts = {}) {
     const dist = Math.hypot(tx - cur.x, ty - cur.y);
     const from = { ...cur };
     await clockMotion(
-      pointerTravelMs(dist),
+      dry ? 0 : pointerTravelMs(dist),
       async (u) => {
         cur.x = from.x + (tx - from.x) * u;
         cur.y = from.y + (ty - from.y) * u;
@@ -6969,12 +6974,14 @@ async function recordTake(browser, url, actions, paths, log, opts = {}) {
       `   WARNING: ${freezePct}% of the take is visually frozen (${freezes.length} freezes, longest ${Math.max(...freezes.map((f) => f.ms))}ms) \u2014 keep motion in frame or trim these spans in doc.json`
     );
   }
-  await writeJson(paths.cursor, events);
-  await writeJson(paths.meta, meta, true);
-  await writeJson(paths.framesIndex, frames);
-  await writeJson(paths.actions, { ...actions, url }, true);
   const pace = paceReport(paces);
-  log(`   ${paceLine(pace)}`);
+  if (!dry) {
+    await writeJson(paths.cursor, events);
+    await writeJson(paths.meta, meta, true);
+    await writeJson(paths.framesIndex, frames);
+    await writeJson(paths.actions, { ...actions, url }, true);
+    log(`   ${paceLine(pace)}`);
+  }
   return {
     events,
     frames,
@@ -7964,6 +7971,21 @@ function takePushRefusal(ask) {
     return `this take tracks vos ${ask.trackedVosId} (its vos.json), not ${ask.vos}. Drop --vos to push there, or remove vos.json to adopt ${ask.vos} instead`;
   return null;
 }
+function programPushTarget(ask) {
+  if (ask.vos) return { kind: "version", vosId: ask.vos, tracked: false };
+  if (ask.remixOf) return { kind: "create", remixOfId: ask.remixOf };
+  const tracked = ask.trackedVosId;
+  if (!tracked) return { kind: "create" };
+  const extra = ask.createOnly ?? [];
+  if (extra.length) {
+    const list = extra.map((f) => `--${f}`).join(", ");
+    return {
+      kind: "refuse",
+      why: `this directory tracks vos ${tracked} (vos.json), so a bare push adds a VERSION to it, and ${list} ${extra.length > 1 ? "apply" : "applies"} only when creating. To make a separate vos from this config: vos push <config.json> --remix-of ${tracked} ${list}. To change the tracked vos's title or slug, edit it on vos.so`
+    };
+  }
+  return { kind: "version", vosId: tracked, tracked: true };
+}
 async function pushTake(dir, flags, r) {
   const take = await loadTake(dir);
   if (!take.doc) {
@@ -8345,12 +8367,12 @@ async function browserLogin(origin, r, opts) {
   r.log(`Sign in at ${verifyUrl}`);
   if (opts.openBrowser) void launchDefaultBrowser(verifyUrl);
   r.log("Waiting for approval\u2026 (Ctrl-C to cancel)");
-  const sleep2 = opts.sleep ?? ((ms) => new Promise((res) => setTimeout(res, ms)));
+  const sleep = opts.sleep ?? ((ms) => new Promise((res) => setTimeout(res, ms)));
   let intervalMs = baseIntervalMs;
   let failures = 0;
   let capNoted = false;
   while (Date.now() < expiresAt) {
-    await sleep2(intervalMs);
+    await sleep(intervalMs);
     let res;
     try {
       res = await apiJson(origin, "/api/cli/login/poll", {
@@ -8652,7 +8674,7 @@ async function cmdPushProgram(argv) {
   const config = pre.config;
   const state = readSyncState(dir);
   const vosFlag = strFlag(flags, "vos");
-  const vosId = vosFlag ? parseVosId(vosFlag) : null;
+  const explicitVosId = vosFlag ? parseVosId(vosFlag) : null;
   const programDoc = await readProgramDoc(dir, config);
   if (programDoc) {
     const lint = lintDoc(programDoc);
@@ -8663,7 +8685,7 @@ async function cmdPushProgram(argv) {
     for (const w of lint.warnings) r.log(`warning doc.json: ${w}`);
   }
   if (flags.claimable === true) {
-    if (vosId) {
+    if (explicitVosId) {
       throw new UsageError(
         "--claimable creates a NEW claimable vos and cannot iterate (--vos). After the human claims it, iterate with their key: vos push --vos <id>"
       );
@@ -8697,6 +8719,15 @@ with their key: vos push ${source} --vos ${String(created2.id ?? "<id>")}`
   const desc = strFlag(flags, "desc");
   const tagsFlag = strFlag(flags, "tags");
   const folderRef = strFlag(flags, "folder");
+  const remixOfFlag = strFlag(flags, "remix-of");
+  const pushTarget = programPushTarget({
+    vos: explicitVosId,
+    remixOf: remixOfFlag,
+    trackedVosId: state?.vosId ?? null,
+    createOnly: ["title", "slug"].filter((f) => strFlag(flags, f))
+  });
+  if (pushTarget.kind === "refuse") throw new UsageError(pushTarget.why);
+  const vosId = pushTarget.kind === "version" ? pushTarget.vosId : null;
   if (vosId && (desc || tagsFlag || folderRef)) {
     throw new UsageError(
       "--desc/--tags/--folder apply when CREATING a vos. On an existing one: vos folder move <id> --to <folder> for filing; edit title/description/tags on vos.so"
@@ -8765,7 +8796,7 @@ with their key: vos push ${source} --vos ${String(created2.id ?? "<id>")}`
     );
     return EXIT_OK;
   }
-  const remixOfId = strFlag(flags, "remix-of") ?? state?.vosId;
+  const remixOfId = pushTarget.kind === "create" ? pushTarget.remixOfId : void 0;
   const fallbackTitle = state?.title ? `${state.title} remix` : basename4(source).replace(/\.json$/i, "") || "vos remix";
   const title = (strFlag(flags, "title") ?? fallbackTitle).slice(0, 100);
   const folderId = folderRef ? resolveFolder(await listFolders(origin, key), folderRef).id : void 0;
@@ -10108,14 +10139,15 @@ var BOOLEAN_FLAGS5 = /* @__PURE__ */ new Set([
   "check",
   "motion",
   "leader",
-  "keep-frames"
+  "keep-frames",
+  "dry-run"
 ]);
 var MULTI_FLAGS2 = /* @__PURE__ */ new Set(["set", "override", "browser-arg"]);
 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] [--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] [--keep-frames] [--max-duration <s>] [--storage-state <file>] [--browser-arg=<switch>]... [--background <slug|url|none>] [--json]
+  vos record --actions actions.json [--url <url>] [--out take] [--strict] [--dry-run] [--keep-frames] [--max-duration <s>] [--storage-state <file>] [--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]
@@ -10445,6 +10477,47 @@ async function cmdRecord(argv) {
   const maxDurationSeconds = await maxDuration(flags, r);
   const storageState = takeStorageState(flags);
   const browserArgs = takeBrowserArgs(multi);
+  if (flags["dry-run"] === true) {
+    void flags.strict;
+    void flags["keep-frames"];
+    const browser2 = await launchBrowser(browserArgs);
+    try {
+      r.log("rehearsing (nothing is captured or written)\u2026");
+      r.event({ event: "phase", phase: "rehearse" });
+      const started = Date.now();
+      const rec = await recordTake(
+        browser2,
+        url,
+        actions,
+        takePaths(outDir),
+        r.log,
+        { storageState, dryRun: true }
+      );
+      const steps = rec.meta.steps ?? [];
+      const lines = steps.map((s) => {
+        const rect = s.rect ? `  rect ${s.rect.x},${s.rect.y} ${s.rect.w}\xD7${s.rect.h}` : "";
+        const what = s.selector ? ` ${s.selector}` : "";
+        return `  ${s.skipped ? "\u2717" : "\u2713"} #${s.step}${s.id ? ` (${s.id})` : ""} ${s.do}${what}${s.skipped ? "  NOT FOUND" : rect}${s.navigated ? "  \u2192 navigated" : ""}`;
+      });
+      const failed2 = rec.skipped.length > 0 || rec.navTimeout;
+      r.done(
+        {
+          dryRun: true,
+          ok: !failed2,
+          seconds: +((Date.now() - started) / 1e3).toFixed(1),
+          steps,
+          skipped: rec.skipped,
+          navTimeout: rec.navTimeout
+        },
+        `${failed2 ? "REHEARSAL FAILED" : "Rehearsal passed"}: ${steps.length - rec.skipped.length}/${steps.length} steps resolved in ${((Date.now() - started) / 1e3).toFixed(1)}s${rec.navTimeout ? " (the first load never reached networkidle)" : ""}
+${lines.join("\n")}
+  ${failed2 ? "Fix the script, rehearse again, then record." : `Rects are capture px (the step rects a pin or a callout reads). Next: vos record --actions ${actionsPath} --out ${outDir} --strict`}`
+      );
+      return failed2 ? EXIT_USAGE : EXIT_OK;
+    } finally {
+      await browser2.close();
+    }
+  }
   if (existsSync15(join18(outDir, "meta.json"))) {
     const { prevDoc, kept } = await prepareReRecord(outDir);
     r.log(
@@ -11691,4 +11764,4 @@ export {
   takeBrowserArgs,
   run
 };
-//# sourceMappingURL=chunk-LGRNHJ2U.js.map
+//# sourceMappingURL=chunk-7TDL3N24.js.map