@vosjs/cli 0.71.0 → 0.73.0

package/README.md

@@ -15,7 +15,7 @@ npx vos render animation.json out.webm
 
 Deterministic: the preview is the render, and every edit is a data patch to `doc.json`, never a re-record. Rendering is local and free at every resolution up to 4K, no watermark. The workflow skills for agents install with `npx skills add vosjs/skills` (`product-video` records and cuts one video, `vos-cut` cuts an existing recording, `launch-kit` ships the media with a release); `vos setup` runs that for you, and falls back to the copy of the catalog this package ships when skills.sh cannot be reached. A coding agent gets the whole procedure from one line: `Read https://vos.so/agent.md and do what it says.`
 
-Until 0.9 the take pipeline and the vos.so verbs shipped separately as `@vosso/vos-plugin`, and before that as `@vosso/cli` and `@vosso/voila-cli`; those names are deprecated on npm and forward here.
+Until 0.9 the take pipeline and the vos.so verbs shipped separately as `@vosso/vos-plugin`, and before that as `@vosso/cli`; those names are deprecated on npm and forward here.
 
 ## Contents
 
@@ -335,7 +335,7 @@ vos assets ls [--kind <kind>] [--q <text>] [--sort size] | usage | why <id>   #
 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. 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`, `--yes` and `--claimable`. Both take `--wait`. A new vos pushed without `--folder` lands unfiled, at the root of the shelf, and the done line says so.
+`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`, `--yes` and `--claimable`. Both take `--wait`. A new vos pushed without `--folder` lands unfiled, at the root of the shelf, and the done line says so. `--folder` takes a project on your own shelf (its slug or id) or anyone's project by its address, `<handle>/<slug>` as its page on vos.so names it: the server answers where the push lands, CONTINUING that project when the key is its owner's and otherwise STARTING the person's own from it (a private project made once, named after it, with the recipes they may read copied in, never its videos). The push says which.
 
 **A program's files are declared, never typed into a function.** `config.json` names each file it uses in `assets` (`"assets": { "logo": { "ref": "./logo.png", "kind": "image" }, "shots": { "ref": ["./shots/1.png", "./shots/2.png"] } }`) and reads `ctx.assets.logo`, or `"$assets.logo"` in an element, object or font. On disk a `ref` is a path in the config's own directory or below, so `vos render`, `vos still` and `vos preview` serve the file to the page from disk. A path that climbs out of that directory (`../`, an absolute path, a link that points away) is not served and not uploaded, and a config loaded from a URL reads no local file: a program's code runs in a page, and what the page is served the program can send anywhere. `vos push` uploads each local file (content-addressed, so a re-push sends nothing: pictures, SVG, video, sound, `.glb` models, fonts and HDR environments) and what it stores names the hosted file as `asset:<id>`, the one spelling the platform resolves for every render; the config on disk keeps its paths. A file an element names as `src` or a font names as `url` is lifted into the manifest on the way (the element then names `"$assets.<name>"`), and a path in `data` that is a file beside the config is uploaded and rewritten to the hosted file's path, so every place a program can name a file crosses. A file typed inside a function cannot be rewritten: `vos push` says so, with the manifest line to write. `vos fetch --media` brings a program's hosted files home under `assets/` and re-points the manifest at them (`assets/.hosted.json` remembers which hosted file each one is, so a later fetch replaces one that changed); without `--media` the manifest keeps `asset:<id>` and a local render reads each file with your key. `vos check` says when a `"$assets.<name>"` names nothing, when a declared path is not a file, and when a function names a hosted file in code instead of the manifest: a file named only in code does not load on a render of a private program and does not follow a remix. A `--claimable` push carries them too, through the claim's own upload session (below).
 
@@ -369,7 +369,7 @@ vos push /tmp/take --label "$TAG launch" --yes --json       # VOS_API_KEY as a r
 - **`--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.
 - **`create`** is the one-shot verb: record, auto-plan and render in one command and one browser session. The take directory still lands on disk, so the full loop (frames, edit `doc.json`, re-render) stays open afterwards.
 - **`vos validate <thing>`** takes an `actions.json`, a take directory, a program directory (`config.json`, plus its program document when present), or a `kit.json`; exit 1 on any problem.
-- **Environment.** `VOS_ORIGIN` (the platform, and the studio `vos open` opens), `VOS_API_KEY`, `VOS_BROWSER_PATH`, `VOS_CLIENT` (the client string a push self-reports; unset, a push names the coding agent that spawned the CLI, read from its environment the way `@vercel/detect-agent` reads it, e.g. `claude-code vos-cli`, else `vos-cli`). `vos voila <verb>` is still accepted as an alias of `vos <verb>` and says so.
+- **Environment.** `VOS_ORIGIN` (the platform, and the studio `vos open` opens), `VOS_API_KEY`, `VOS_BROWSER_PATH`, `VOS_CLIENT` (the client string a push self-reports; unset, a push names the coding agent that spawned the CLI, read from its environment the way `@vercel/detect-agent` reads it, e.g. `claude-code vos-cli`, else `vos-cli`).
 
 ## Programmatic use
 

package/dist/{chunk-XB5XRE4Q.js → chunk-EYF3WJIC.js}

@@ -2400,7 +2400,7 @@ async function renderChunk(context2, serverBase, chunk, opts, onChunkProgress) {
       bitrate: opts.bitrate ?? 1e7,
       mediabunnyUrl: MEDIABUNNY_URL,
       outName,
-      debug: process.env.VOILA_DEBUG_CHUNKS === "1",
+      debug: process.env.VOS_DEBUG_CHUNKS === "1",
       audioProducerCode: audio?.producerCode,
       audioDataJson: audio ? JSON.stringify(audio.data) : void 0,
       audioDuration: audio?.duration
@@ -3226,7 +3226,7 @@ function parseTranscript(raw) {
 }
 
 // src/plugin/framesTake.ts
-var VIDEO_TOKEN = "__VOILA_CLI_VIDEO__";
+var VIDEO_TOKEN = "__VOS_CLI_VIDEO__";
 function stillSupersample(w, h) {
   return Math.min(3, Math.max(1, Math.ceil(1800 / Math.max(1, w, h))));
 }
@@ -3512,7 +3512,7 @@ import {
   resolveExportSize as resolveExportSize2,
   studioAudioPlan
 } from "@vosjs/studio-core";
-var VIDEO_TOKEN2 = "__VOILA_CLI_VIDEO__";
+var VIDEO_TOKEN2 = "__VOS_CLI_VIDEO__";
 async function renderTake(browser, dir, outFile, opts) {
   const take = await loadTake(dir);
   if (!take.doc) throw new Error(`${dir} has no doc.json \u2014 run plan first`);
@@ -6022,6 +6022,38 @@ function resolveFolder(rows, ref) {
   }
   return hit;
 }
+function projectAddress(ref) {
+  const m = /^@?([A-Za-z0-9_]{1,30})\/([A-Za-z0-9][\w-]{0,99})$/.exec(
+    ref.trim()
+  );
+  return m ? { handle: m[1], slug: m[2].toLowerCase() } : null;
+}
+async function resolvePushFolder(origin, key, ref) {
+  const at2 = projectAddress(ref);
+  if (!at2) {
+    return {
+      id: resolveFolder(await listFolders(origin, key), ref).id,
+      note: null
+    };
+  }
+  const r = await apiJson(
+    origin,
+    `/api/folders/public/${encodeURIComponent(at2.handle)}/${encodeURIComponent(at2.slug)}/push-target`,
+    { method: "POST", key }
+  );
+  if (r.status !== 200 && r.status !== 201) {
+    throw new Error(apiError(`find the project ${at2.handle}/${at2.slug}`, r));
+  }
+  const body = r.body;
+  if (!body.folder) {
+    throw new Error(
+      `find the project ${at2.handle}/${at2.slug}: no project in the answer`
+    );
+  }
+  const source = body.source?.name ?? `${at2.handle}/${at2.slug}`;
+  const note = body.target === "continue" ? `continuing ${source}` : body.created ? `starting your own ${source} (${body.folder.slug}), its ${body.recipes ?? 0} recipe${body.recipes === 1 ? "" : "s"} copied in` : `adding to your own ${source} (${body.folder.slug})`;
+  return { id: body.folder.id, note };
+}
 function printTree(rows) {
   const children = /* @__PURE__ */ new Map();
   for (const f of rows) {
@@ -6404,10 +6436,9 @@ async function pushTake(dir, flags, r) {
         "--folder applies when CREATING a vos \u2014 this take is already pushed; file it with: vos folder move <vosId> --to <folder>"
       );
     }
-    folderId = resolveFolder(
-      await listFolders(ctx.origin, ctx.key),
-      flags.folder
-    ).id;
+    const target = await resolvePushFolder(ctx.origin, ctx.key, flags.folder);
+    folderId = target.id;
+    if (target.note) r.log(target.note);
   }
   if (firstPush && !flags.yes) {
     if (!process.stdin.isTTY) {
@@ -7265,7 +7296,7 @@ async function cmdPushProgram(argv) {
   const target = positionals[0];
   if (!target) {
     throw new UsageError(
-      'vos push <config.json|take> [--vos id] [--title t] [--slug s] [--desc d] [--tags a,b] [--folder <id|slug>] [--remix-of id] [--note n] [--label l] [--base versionId] [--override id]... [--prompt "<the prompt that made it>"] [--claimable [--share]]'
+      'vos push <config.json|take> [--vos id] [--title t] [--slug s] [--desc d] [--tags a,b] [--folder <id|slug|handle/slug>] [--remix-of id] [--note n] [--label l] [--base versionId] [--override id]... [--prompt "<the prompt that made it>"] [--claimable [--share]]'
     );
   }
   const source = resolveConfigPath(target);
@@ -7487,7 +7518,9 @@ ${landedLines(landed2)}` : "")
   const remixOfId = pushTarget.kind === "create" ? pushTarget.remixOfId : void 0;
   const fallbackTitle = state?.title ? `${state.title} remix` : basename3(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;
+  const pushFolder = folderRef ? await resolvePushFolder(origin, key, folderRef) : void 0;
+  const folderId = pushFolder?.id;
+  if (pushFolder?.note) r.log(pushFolder.note);
   const created = await createProgramVos({
     origin,
     key,
@@ -7531,6 +7564,7 @@ ${landedLines(landed2)}` : "")
       title,
       visibility: "private",
       folder: folderRef ?? null,
+      ...pushFolder?.note ? { folderNote: pushFolder.note } : {},
       remixOfId: remixOfId ?? null,
       currentVersionId: created.currentVersionId,
       watchUrl,
@@ -7547,7 +7581,7 @@ ${landedLines(landed2)}` : "")
   watch:  ${watchUrl}
   studio: ${studioUrl}
 ` + (landed ? `${landedLines(landed)}
-` : "") + `  shelf:  ${folderRef ? `in ${folderRef}` : `unfiled, at the root of your shelf (file it: vos folder move ${created.id} --to <slug>)`}
+` : "") + `  shelf:  ${folderRef ? `in ${folderRef}${pushFolder?.note ? ` (${pushFolder.note})` : ""}` : `unfiled, at the root of your shelf (file it: vos folder move ${created.id} --to <slug>)`}
   cover:  ${typeof programDoc?.still === "number" ? `${String(programDoc.still)}s` : "the platform picks an early frame; choose one with --still <seconds>"}
 ` + (prompt ? `  prompt: shown on the watch page
 ` : `  prompt: none shown; show the one that made it: ${promptHint(source, created.id)}
@@ -14328,4 +14362,4 @@ export {
   verbHelp,
   run
 };
-//# sourceMappingURL=chunk-XB5XRE4Q.js.map
+//# sourceMappingURL=chunk-EYF3WJIC.js.map