@vosjs/cli 0.41.0 → 0.41.1

package/README.md

@@ -90,7 +90,7 @@ 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.
 
-**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.
+**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, and the `Next:` line it prints carries them, so the command it hands you records what it rehearsed.
 
 **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.
 
@@ -256,6 +256,7 @@ vos push /tmp/take --label "$TAG launch" --yes --json       # VOS_API_KEY as a r
 ## For scripts and agents
 
 - **Output.** Logs on stderr, results on stdout. `--json` turns every verb into NDJSON events ending with `{"event":"done",…}`.
+- **`vos <verb> --help`** prints that verb's usage lines and exits 0 (it used to be a usage error).
 - **Exit codes.** 0 ok, 1 error, 2 usage (including `--strict` failures), 3 no browser found, 4 the recorder met a wall (a sign-in, or under `--strict` a redirect away from the asked page) and nothing was recorded or cleared. `--json` carries the verdict as a `wall` event (`kind`, `level`, `asked`, `landed`, `refused`).
 - **`--strict`** on `record` and `create` (agents: always): a skipped selector, a page that never reaches network idle, or a take that hit `--max-duration` exits 2 and lists `skipped[]` (and `capped`) in the done event. The default is lenient (exit 0, `skipped[]` still reported) for exploratory runs.
 - **`--max-duration <s>`** on `record` and `create` defaults to the hosted recording cap, read live from `GET /api/limits` (2 s, fail-open to 30 min when the origin is unreachable): the capture stops there and the done event says so. Cut the flow rather than raising the cap; the platform refuses a longer take.

package/dist/{chunk-BD4FXBUO.js → chunk-4QVEV3HX.js}

@@ -6687,7 +6687,7 @@ function redirectedAway(asked, landed) {
   if (l.endsWith(a)) return false;
   return true;
 }
-var LADDER = 'Walk the session ladder (mint a session from the test auth the project already has, or pass --storage-state): https://vos.so/llms-full.txt, "Sessions". A take OF this page is --allow-wall.';
+var LADDER = 'This is a missing or expired session, not a script bug. Ways past, cheapest first: mint a session from the test auth the project already has; script the sign-in off camera and save the storage state; or have a person sign in once (npx playwright open --channel chrome --save-storage=<file> <url>). Then pass --storage-state <file>. The ladder: https://vos.so/llms-full.txt, "Sessions". A take OF this page is --allow-wall.';
 function wallVerdict(a) {
   const asked = parse(a.askedUrl);
   const landed = parse(a.landedUrl);
@@ -10675,6 +10675,12 @@ async function cmdRecord(argv) {
         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;
+      const carried = [
+        ...strFlag(flags, "storage-state") ? [`--storage-state ${strFlag(flags, "storage-state")}`] : [],
+        ...browserArgs.map((a) => `--browser-arg=${a}`),
+        ...flags["allow-wall"] === true ? ["--allow-wall"] : []
+      ].join(" ");
+      const nextOut = strFlag(flags, "out") ?? "take";
       r.done(
         {
           dryRun: true,
@@ -10686,7 +10692,7 @@ async function cmdRecord(argv) {
         },
         `${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`}`
+  ${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 ${nextOut}${carried ? ` ${carried}` : ""} --strict`}`
       );
       return failed2 ? EXIT_USAGE : EXIT_OK;
     } finally {
@@ -11842,6 +11848,23 @@ async function cmdPull2(argv) {
   );
   return EXIT_OK;
 }
+function verbHelp(verb) {
+  const lines = HELP.split("\n");
+  const out = [];
+  let taking = false;
+  for (const line of lines) {
+    if (/^ {2}vos /.test(line)) taking = line.startsWith(`  vos ${verb} `);
+    else if (taking && !/^ {3,}\S/.test(line)) taking = false;
+    if (taking) out.push(line);
+  }
+  if (out.length === 0) return `vos ${verb}: no such verb here. Run: vos help
+`;
+  return `${out.join("\n")}
+
+The whole reference, with every flag explained: https://vos.so/llms-full.txt
+Exit codes: 0 ok, 1 error, 2 usage or --strict failure, 3 no browser, 4 the recorder met a sign-in instead of the page.
+`;
+}
 async function run(argv) {
   const [cmd, ...rest] = argv;
   try {
@@ -11849,6 +11872,10 @@ async function run(argv) {
       process.stdout.write(HELP);
       return cmd ? EXIT_OK : EXIT_USAGE;
     }
+    if (rest.includes("--help") || rest.includes("-h")) {
+      process.stdout.write(verbHelp(cmd));
+      return EXIT_OK;
+    }
     switch (cmd) {
       case "create":
         return await cmdCreate2(rest);
@@ -11959,6 +11986,7 @@ export {
   MULTI_FLAGS2 as MULTI_FLAGS,
   HELP,
   takeBrowserArgs,
+  verbHelp,
   run
 };
-//# sourceMappingURL=chunk-BD4FXBUO.js.map
+//# sourceMappingURL=chunk-4QVEV3HX.js.map