@vosjs/cli 0.59.0 → 0.60.0

package/README.md

@@ -51,7 +51,7 @@ vos logout                          # remove ~/.config/vos/credentials
 vos render  <config.json|url|take> [out]   # config → video; the name picks mp4/webm; a program document's sound is mixed in
 vos still   <config.json|url> [out.webp]   # config → frames: --times 0,1.5,50% in one browser; .png/.jpg re-encoded
 vos info    <config.json|url>              # inspect a config
-vos check   <config.json|url>              # migrate → schema → syntax → compile → determinism and dialect lints, all local
+vos check   <config.json|url>              # migrate → schema → syntax → compile → determinism, dialect and declared-file lints, all local
 vos preview <config.json|url> [--port N]   # serve a local playback page
 vos versions                               # installed @vosjs/* versions
 ```
@@ -334,6 +334,8 @@ vos recipe push <FILE.md> --folder <slug> | --asset <id>   # the one recipe writ
 
 `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 take `--wait`. A new vos pushed without `--folder` lands unfiled, at the root of the shelf, and the done line says so.
 
+**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 beside the config, so `vos render`, `vos still` and `vos preview` serve the file to the page from disk. `vos push` uploads each local file (content-addressed, so a re-push sends nothing) 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. `vos fetch --media` brings a program's hosted files home under `assets/` and re-points the manifest at them; 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 no files, so it is refused when the manifest names local ones.
+
 **Sound is a track, never an element.** A document's added sound lives in `doc.json` (`audio: [{ id, key, name, start, in, out, duration, gain, fadeIn, fadeOut }]`) for a program as for a take: `vos push` uploads each local file its keys name and keys the hosted asset; `vos render` of a program mixes it locally; the studio shows it as a track with gain and fades. An `audio` element embedded in the config is not a track (renders do not mix it, and a `data:` source can push a config past what a claimable push carries); `vos check` says so. `vos asset push score.ogg` uploads a sound on its own and prints the url a key takes; an unfiled sound that no document uses is removed after 7 days, so pass `--folder` or reference it.
 
 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/assetManifest-MM5WGOWG.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+import {
+  hostedLiteralWarnings,
+  localManifestRefs,
+  pullManifest,
+  uploadManifest
+} from "./chunk-PUXY32AP.js";
+import "./chunk-36P5RREC.js";
+export {
+  hostedLiteralWarnings,
+  localManifestRefs,
+  pullManifest,
+  uploadManifest
+};
+//# sourceMappingURL=assetManifest-MM5WGOWG.js.map

package/dist/chunk-36P5RREC.js

@@ -0,0 +1,648 @@
+#!/usr/bin/env node
+
+// src/flagUse.ts
+var given = /* @__PURE__ */ new Set();
+var used = /* @__PURE__ */ new Set();
+function trackFlags(bag) {
+  return new Proxy(bag, {
+    get(target, key, receiver) {
+      if (typeof key === "string") used.add(key);
+      return Reflect.get(target, key, receiver);
+    },
+    has(target, key) {
+      if (typeof key === "string") used.add(key);
+      return Reflect.has(target, key);
+    },
+    // hasOwnProperty.call(flags, name) lands here.
+    getOwnPropertyDescriptor(target, key) {
+      if (typeof key === "string") used.add(key);
+      return Reflect.getOwnPropertyDescriptor(target, key);
+    },
+    // A spread, Object.keys or JSON.stringify hands every flag onward; what
+    // happens to them after that cannot be seen, so they all count as read.
+    ownKeys(target) {
+      for (const key of Reflect.ownKeys(target))
+        if (typeof key === "string") used.add(key);
+      return Reflect.ownKeys(target);
+    }
+  });
+}
+function noteGivenFlag(name) {
+  given.add(name);
+}
+function unusedFlags() {
+  return [...given].filter((name) => !used.has(name) && name !== "help");
+}
+function helpFlagsFor(help, verb) {
+  const out = /* @__PURE__ */ new Set();
+  let inVerb = false;
+  for (const line of help.split("\n")) {
+    const head = /^\s{2}vos\s+(\S+)/.exec(line);
+    if (head) inVerb = head[1] === verb;
+    else if (!/^\s{3,}\S/.test(line)) inVerb = false;
+    if (!inVerb) continue;
+    for (const m of line.matchAll(/--([a-z][a-z0-9-]*)/g)) out.add(m[1]);
+  }
+  return [...out];
+}
+function editDistance(a, b) {
+  const row = Array.from({ length: b.length + 1 }, (_, i) => i);
+  for (let i = 1; i <= a.length; i++) {
+    let prev = row[0];
+    row[0] = i;
+    for (let j = 1; j <= b.length; j++) {
+      const keep = row[j];
+      row[j] = Math.min(
+        row[j] + 1,
+        row[j - 1] + 1,
+        prev + (a[i - 1] === b[j - 1] ? 0 : 1)
+      );
+      prev = keep;
+    }
+  }
+  return row[b.length];
+}
+function nearestFlag(name, candidates) {
+  let best = null;
+  let bestScore = Infinity;
+  for (const c of candidates) {
+    if (c === name) continue;
+    const d = c.includes(name) || name.includes(c) ? 1 : editDistance(name, c);
+    if (d < bestScore) {
+      bestScore = d;
+      best = c;
+    }
+  }
+  return best !== null && bestScore <= Math.max(2, Math.floor(name.length / 3)) ? best : null;
+}
+function unusedFlagsMessage(verb, documented) {
+  const unused = unusedFlags();
+  if (!unused.length) return null;
+  const parts = unused.map((name) => {
+    const near = nearestFlag(name, documented);
+    return `--${name}${near ? ` (did you mean --${near}?)` : ""}`;
+  });
+  const list = documented.length ? ` It reads: ${documented.map((f) => `--${f}`).join(" ")}.` : "";
+  return `vos ${verb} RAN, and ignored ${parts.join(", ")}: ${unused.length > 1 ? "they are" : "it is"} not something this verb reads, so what it printed above was made without ${unused.length > 1 ? "them" : "it"}.${list}`;
+}
+
+// src/args.ts
+var UsageError = class extends Error {
+};
+function parseArgs(argv, booleanFlags) {
+  const positionals = [];
+  const flags = {};
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--") {
+      positionals.push(...argv.slice(i + 1));
+      break;
+    }
+    if (arg.startsWith("--")) {
+      const eq = arg.indexOf("=");
+      if (eq !== -1) {
+        flags[arg.slice(2, eq)] = arg.slice(eq + 1);
+        continue;
+      }
+      const name = arg.slice(2);
+      if (booleanFlags.has(name)) {
+        flags[name] = true;
+        continue;
+      }
+      const next = argv[i + 1];
+      if (next === void 0 || next.startsWith("--")) {
+        throw new UsageError(`--${name} expects a value`);
+      }
+      flags[name] = next;
+      i++;
+      continue;
+    }
+    positionals.push(arg);
+  }
+  for (const name of Object.keys(flags)) noteGivenFlag(name);
+  return { positionals, flags: trackFlags(flags) };
+}
+function numFlag(flags, name, fallback) {
+  const v = flags[name];
+  if (v === void 0) return fallback;
+  const n = Number(v);
+  if (!Number.isFinite(n))
+    throw new UsageError(`--${name} expects a number, got "${String(v)}"`);
+  return n;
+}
+
+// src/programAssets.ts
+import { createHash } from "crypto";
+import { existsSync, mkdirSync, statSync, writeFileSync } from "fs";
+import { tmpdir } from "os";
+import { basename, isAbsolute, join, resolve } from "path";
+var ASSET_ROUTE = "/__assets/";
+var HOSTED_REF = /^(?:asset:|(?:https?:\/\/[^/]+)?\/api\/assets\/)([0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12})(?:\/file(?:\?.*)?)?$/;
+function hostedAssetId(ref) {
+  return HOSTED_REF.exec(ref)?.[1] ?? null;
+}
+function isUrl(ref) {
+  return /^(https?:|data:|blob:)/.test(ref);
+}
+function manifestOf(config) {
+  const assets = config.assets;
+  if (!assets || typeof assets !== "object" || Array.isArray(assets))
+    return null;
+  return Object.keys(assets).length > 0 ? assets : null;
+}
+function manifestRefs(config) {
+  const out = [];
+  for (const [name, decl] of Object.entries(manifestOf(config) ?? {})) {
+    if (Array.isArray(decl.ref)) {
+      decl.ref.forEach((ref, index) => out.push({ name, index, ref }));
+    } else if (typeof decl.ref === "string") {
+      out.push({ name, index: null, ref: decl.ref });
+    }
+  }
+  return out;
+}
+async function fetchHosted(id, opts) {
+  const dir = opts.cacheDir ?? join(tmpdir(), "vos-assets");
+  const file = join(dir, id);
+  if (existsSync(file) && statSync(file).size > 0) return file;
+  if (!opts.origin || !opts.key) {
+    opts.log(
+      `note: asset ${id} is hosted and no credential is set, so the render cannot load it (vos login, or keep the file beside the config and name its path)`
+    );
+    return null;
+  }
+  const res = await fetch(`${opts.origin}/api/assets/${id}/file`, {
+    headers: { authorization: `Bearer ${opts.key}` }
+  });
+  if (!res.ok) {
+    opts.log(
+      `note: asset ${id} could not be read (${res.status}), so the render cannot load it`
+    );
+    return null;
+  }
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(file, new Uint8Array(await res.arrayBuffer()));
+  return file;
+}
+async function programAssets(config, opts) {
+  const refs = manifestRefs(config);
+  if (refs.length === 0) return null;
+  const files = {};
+  const served = /* @__PURE__ */ new Map();
+  const serve = (file) => {
+    const known = served.get(file);
+    if (known) return known;
+    const tag = createHash("sha256").update(file).digest("hex").slice(0, 10);
+    const path = `${ASSET_ROUTE}${tag}/${basename(file)}`;
+    files[path] = file;
+    served.set(file, path);
+    return path;
+  };
+  const reach = async (ref, where) => {
+    if (isUrl(ref)) return ref;
+    const hosted = hostedAssetId(ref);
+    if (hosted) {
+      const file2 = await fetchHosted(hosted, opts);
+      return file2 ? serve(file2) : ref;
+    }
+    const file = isAbsolute(ref) ? ref : resolve(opts.baseDir, ref);
+    if (!existsSync(file) || !statSync(file).isFile()) {
+      opts.log(
+        `note: ${where} names ${ref}, which is not a file beside the config, so the render cannot load it`
+      );
+      return ref;
+    }
+    return serve(file);
+  };
+  const assets = {};
+  for (const { name, index, ref } of refs) {
+    const url = await reach(
+      ref,
+      index === null ? `assets.${name}` : `assets.${name}[${index}]`
+    );
+    if (index === null) assets[name] = url;
+    else {
+      const list = assets[name] ??= [];
+      list[index] = url;
+    }
+  }
+  return { assets, files };
+}
+function missingManifestFiles(config, baseDir) {
+  const out = [];
+  for (const { name, index, ref } of manifestRefs(config)) {
+    if (isUrl(ref) || hostedAssetId(ref)) continue;
+    const file = isAbsolute(ref) ? ref : resolve(baseDir, ref);
+    if (existsSync(file) && statSync(file).isFile()) continue;
+    const where = index === null ? `assets.${name}` : `assets.${name}[${index}]`;
+    out.push(`${where} names ${ref}, which is not a file beside the config`);
+  }
+  return out;
+}
+
+// src/plugin/container.ts
+var OCTET_STREAM = "application/octet-stream";
+var TYPES_BY_EXTENSION = {
+  svg: "image/svg+xml",
+  png: "image/png",
+  jpg: "image/jpeg",
+  jpeg: "image/jpeg",
+  webp: "image/webp",
+  gif: "image/gif",
+  avif: "image/avif",
+  webm: "video/webm",
+  mp4: "video/mp4",
+  mov: "video/quicktime",
+  mp3: "audio/mpeg",
+  wav: "audio/wav",
+  ogg: "audio/ogg",
+  m4a: "audio/mp4",
+  glb: "model/gltf-binary"
+};
+var EXTENSION_BY_TYPE = {
+  "image/jpeg": ".jpg",
+  "video/mp4": ".mp4",
+  "audio/mp4": ".m4a"
+};
+var TAKE_MEDIA_EXTENSIONS = [
+  ".webm",
+  ".mp4",
+  ".mov",
+  ".m4a",
+  ".mp3",
+  ".ogg",
+  ".wav"
+];
+var MEDIA_HEAD_BYTES = 16;
+var ISO_BRANDS = {
+  "qt  ": "video/quicktime",
+  "M4A ": "audio/mp4",
+  "M4B ": "audio/mp4",
+  avif: "image/avif",
+  avis: "image/avif"
+};
+var RIFF_FORMS = {
+  WEBP: "image/webp",
+  WAVE: "audio/wav",
+  "AVI ": "video/x-msvideo"
+};
+function sniffMediaType(head) {
+  const ascii = (at, len) => head.length >= at + len ? String.fromCharCode(...head.subarray(at, at + len)) : "";
+  const startsWith = (...bytes) => bytes.every((b, i) => head[i] === b);
+  if (startsWith(26, 69, 223, 163)) return "video/webm";
+  if (ascii(4, 4) === "ftyp") return ISO_BRANDS[ascii(8, 4)] ?? "video/mp4";
+  if (ascii(0, 4) === "RIFF") return RIFF_FORMS[ascii(8, 4)] ?? null;
+  if (startsWith(137, 80, 78, 71, 13, 10, 26, 10))
+    return "image/png";
+  if (startsWith(255, 216, 255)) return "image/jpeg";
+  if (ascii(0, 4) === "GIF8") return "image/gif";
+  if (ascii(0, 4) === "OggS") return "audio/ogg";
+  if (ascii(0, 3) === "ID3") return "audio/mpeg";
+  if (ascii(0, 4) === "glTF") return "model/gltf-binary";
+  return null;
+}
+function bareType(value) {
+  const type = (value ?? "").split(";")[0].trim().toLowerCase();
+  return !type || type === OCTET_STREAM || type === "binary/octet-stream" ? "" : type;
+}
+function mediaContentType(file) {
+  const ext = (/\.([a-z0-9]+)$/i.exec(file)?.[1] ?? "").toLowerCase();
+  return TYPES_BY_EXTENSION[ext] ?? OCTET_STREAM;
+}
+function extensionFor(contentType) {
+  const type = (contentType ?? "").split(";")[0].trim().toLowerCase();
+  if (EXTENSION_BY_TYPE[type]) return EXTENSION_BY_TYPE[type];
+  const ext = Object.keys(TYPES_BY_EXTENSION).find(
+    (e) => TYPES_BY_EXTENSION[e] === type
+  );
+  return ext ? `.${ext}` : "";
+}
+function resolveMediaType(claims) {
+  const sniffed = claims.head?.length ? sniffMediaType(claims.head) : null;
+  if (sniffed) return { type: sniffed, from: "bytes" };
+  const declared = bareType(claims.declared);
+  if (declared) return { type: declared, from: "declared" };
+  const named = mediaContentType(claims.filename ?? "");
+  if (named !== OCTET_STREAM) return { type: named, from: "filename" };
+  return { type: OCTET_STREAM, from: "unknown" };
+}
+function nameForType(filename, type) {
+  const ext = extensionFor(type);
+  if (!ext) return filename;
+  const current = /\.[a-z0-9]+$/i.exec(filename)?.[0] ?? "";
+  if (current && mediaContentType(`x${current}`) === type) return filename;
+  return `${filename.slice(0, filename.length - current.length)}${ext}`;
+}
+function containerMismatch(filename, head) {
+  const actual = sniffMediaType(head);
+  if (!actual) return null;
+  const claimed = mediaContentType(filename);
+  if (claimed === actual) return null;
+  return `${filename} is ${actual}, not the ${claimed} its name claims \u2014 rename it to ${nameForType(filename, actual)}`;
+}
+
+// src/plugin/args.ts
+function parseArgs2(argv, booleanFlags, multiFlags = /* @__PURE__ */ new Set()) {
+  const positionals = [];
+  const flags = {};
+  const multi = {};
+  const put = (name, value) => {
+    if (multiFlags.has(name)) (multi[name] ??= []).push(value);
+    else flags[name] = value;
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--") {
+      positionals.push(...argv.slice(i + 1));
+      break;
+    }
+    if (arg.startsWith("--")) {
+      const eq = arg.indexOf("=");
+      if (eq !== -1) {
+        put(arg.slice(2, eq), arg.slice(eq + 1));
+        continue;
+      }
+      const name = arg.slice(2);
+      if (booleanFlags.has(name)) {
+        flags[name] = true;
+        continue;
+      }
+      if (i + 1 >= argv.length || argv[i + 1].startsWith("--")) {
+        throw new UsageError(`--${name} expects a value`);
+      }
+      put(name, argv[i + 1]);
+      i++;
+      continue;
+    }
+    positionals.push(arg);
+  }
+  for (const name of Object.keys(flags)) noteGivenFlag(name);
+  for (const name of Object.keys(multi)) noteGivenFlag(name);
+  return { positionals, flags: trackFlags(flags), multi: trackFlags(multi) };
+}
+function numFlag2(flags, name, fallback) {
+  const v = flags[name];
+  if (typeof v !== "string") return fallback;
+  const n = Number(v);
+  if (!Number.isFinite(n))
+    throw new UsageError(`--${name} expects a number, got "${v}"`);
+  return n;
+}
+function strFlag(flags, name) {
+  const v = flags[name];
+  return typeof v === "string" ? v : void 0;
+}
+function hasFlag(flags, name) {
+  return Object.prototype.hasOwnProperty.call(flags, name);
+}
+
+// src/plugin/platform.ts
+import { mkdirSync as mkdirSync2, readFileSync, writeFileSync as writeFileSync2 } from "fs";
+import { homedir } from "os";
+import { join as join2 } from "path";
+
+// src/plugin/hostAgent.ts
+import { existsSync as existsSync2 } from "fs";
+var SLUG = /^[a-z0-9][a-z0-9.-]{0,39}$/;
+var MARKERS = [
+  ["cursor", (e) => !!e.CURSOR_TRACE_ID],
+  [
+    "cursor-cli",
+    (e) => !!e.CURSOR_AGENT || e.CURSOR_EXTENSION_HOST_ROLE === "agent-exec"
+  ],
+  ["gemini-cli", (e) => !!e.GEMINI_CLI],
+  ["codex", (e) => !!(e.CODEX_SANDBOX || e.CODEX_CI || e.CODEX_THREAD_ID)],
+  ["antigravity", (e) => !!e.ANTIGRAVITY_AGENT],
+  ["augment-cli", (e) => !!e.AUGMENT_AGENT],
+  ["opencode", (e) => !!e.OPENCODE_CLIENT],
+  [
+    "claude-code",
+    (e) => !!(e.CLAUDECODE || e.CLAUDE_CODE) && !e.CLAUDE_CODE_IS_COWORK
+  ],
+  ["claude-cowork", (e) => !!(e.CLAUDECODE || e.CLAUDE_CODE)],
+  ["replit", (e) => !!e.REPL_ID],
+  [
+    "github-copilot",
+    (e) => !!(e.COPILOT_MODEL || e.COPILOT_ALLOW_ALL || e.COPILOT_GITHUB_TOKEN)
+  ]
+];
+var DEVIN_LOCAL_PATH = "/opt/.devin";
+function slugFromAiAgent(value) {
+  const head = value.trim().toLowerCase().split("_")[0] ?? "";
+  if (head === "github-copilot-cli") return "github-copilot";
+  return SLUG.test(head) ? head : null;
+}
+function detectHostAgent(env = process.env, exists = existsSync2) {
+  if (env.AI_AGENT) {
+    const slug = slugFromAiAgent(env.AI_AGENT);
+    if (slug) return slug;
+  }
+  for (const [slug, test] of MARKERS) if (test(env)) return slug;
+  try {
+    if (exists(DEVIN_LOCAL_PATH)) return "devin";
+  } catch {
+  }
+  return null;
+}
+
+// src/plugin/platform.ts
+function platformOrigin(flags = {}) {
+  const legacyEnv = process.env.VOS_API_BASE?.trim();
+  const raw = flags.origin ?? flags.api ?? process.env.VOS_ORIGIN?.trim() ?? legacyEnv ?? "https://vos.so";
+  if (!flags.origin && !flags.api && !process.env.VOS_ORIGIN && legacyEnv) {
+    process.stderr.write(
+      "note: VOS_API_BASE is deprecated \u2014 set VOS_ORIGIN (an origin, no /api suffix)\n"
+    );
+  }
+  return raw.replace(/\/+$/, "").replace(/\/api$/, "");
+}
+function parseVosId(input) {
+  if (!/^https?:\/\//.test(input)) {
+    if (/^[A-Za-z0-9_-]+$/.test(input)) return input;
+    throw new UsageError(`"${input}" is not a vos id or URL`);
+  }
+  let url;
+  try {
+    url = new URL(input);
+  } catch {
+    throw new UsageError(`"${input}" is not a valid URL`);
+  }
+  const query = url.searchParams.get("vos");
+  if (query) return query;
+  const path = url.pathname.match(/\/vos\/([A-Za-z0-9_-]+)/);
+  if (path) return path[1];
+  throw new UsageError(
+    `could not find a vos id in ${input} \u2014 expected /vos/{id} or ?vos={id}`
+  );
+}
+function deriveSlug(title) {
+  return title.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 50).replace(/-+$/, "") || "remix";
+}
+var CREDENTIALS_PATH = join2(homedir(), ".config", "vos", "credentials");
+function resolveCredential(explicit) {
+  const flag = explicit?.trim();
+  if (flag) return flag;
+  const env = process.env.VOS_API_KEY?.trim();
+  if (env) return env;
+  try {
+    const first = readFileSync(CREDENTIALS_PATH, "utf8").split("\n")[0].trim();
+    return first || null;
+  } catch {
+    return null;
+  }
+}
+function requireCredential(explicit) {
+  const key = resolveCredential(explicit);
+  if (!key) {
+    throw new Error(
+      "no credential found \u2014 pass --key, set VOS_API_KEY, or run `vos login` (mint a content key at https://vos.so/app/api; a vos_rg_ remix grant works too)"
+    );
+  }
+  return key;
+}
+function writeCredential(key) {
+  mkdirSync2(join2(homedir(), ".config", "vos"), { recursive: true, mode: 448 });
+  writeFileSync2(CREDENTIALS_PATH, `${key.trim()}
+`, { mode: 384 });
+  return CREDENTIALS_PATH;
+}
+function clientId(env = process.env, exists) {
+  const explicit = env.VOS_CLIENT?.trim();
+  if (explicit && explicit.length <= 60 && !/[\r\n]/.test(explicit))
+    return explicit;
+  const host = detectHostAgent(env, exists);
+  return host ? `${host} vos-cli` : "vos-cli";
+}
+async function apiJson(origin, path, init = {}) {
+  const headers = {
+    accept: "application/json",
+    ...init.headers
+  };
+  if (init.key) headers.authorization = `Bearer ${init.key}`;
+  if (init.body !== void 0) headers["content-type"] = "application/json";
+  const reqBody = init.raw !== void 0 ? init.raw : init.body === void 0 ? void 0 : JSON.stringify(init.body);
+  const res = await fetch(`${origin}${path}`, {
+    method: init.method ?? "GET",
+    headers,
+    body: reqBody
+  });
+  let body = {};
+  try {
+    body = await res.json();
+  } catch {
+  }
+  return { status: res.status, body };
+}
+function apiError(what, r) {
+  const detail = typeof r.body.error === "string" ? r.body.error : r.body.details !== void 0 ? JSON.stringify(r.body.details) : "";
+  const hint = r.status === 401 ? " (run `vos login`, or set VOS_API_KEY \u2014 mint a key at https://vos.so/app/api)" : "";
+  return `${what} \u2192 ${r.status}${detail ? `: ${detail}` : ""}${hint}`;
+}
+var SYNC_STATE_NAME = "vos.json";
+function readJsonFile(file) {
+  try {
+    return JSON.parse(readFileSync(file, "utf8"));
+  } catch {
+    return null;
+  }
+}
+function readSyncState(dir) {
+  const own = readJsonFile(join2(dir, SYNC_STATE_NAME));
+  if (own && typeof own.vosId === "string") {
+    return {
+      vosId: own.vosId,
+      versionId: typeof own.versionId === "string" ? own.versionId : null,
+      ...typeof own.pushedAt === "string" ? { pushedAt: own.pushedAt } : {},
+      ...typeof own.title === "string" ? { title: own.title } : {},
+      ...typeof own.slug === "string" ? { slug: own.slug } : {},
+      ...typeof own.remixOfId === "string" ? { remixOfId: own.remixOfId } : {}
+    };
+  }
+  const push = readJsonFile(join2(dir, "push.json"));
+  if (push && typeof push.vosId === "string") {
+    return {
+      vosId: push.vosId,
+      versionId: typeof push.versionId === "string" ? push.versionId : null,
+      ...typeof push.pushedAt === "string" ? { pushedAt: push.pushedAt } : {}
+    };
+  }
+  const meta = readJsonFile(join2(dir, "meta.json"));
+  if (meta && typeof meta.id === "string") {
+    return {
+      vosId: meta.id,
+      versionId: typeof meta.currentVersionId === "string" ? meta.currentVersionId : null,
+      ...typeof meta.title === "string" ? { title: meta.title } : {},
+      ...typeof meta.slug === "string" ? { slug: meta.slug } : {},
+      ...typeof meta.remixOfId === "string" ? { remixOfId: meta.remixOfId } : {}
+    };
+  }
+  return null;
+}
+function writeSyncState(dir, patch) {
+  const merged = {
+    ...readSyncState(dir) ?? { versionId: null },
+    ...patch
+  };
+  writeFileSync2(
+    join2(dir, SYNC_STATE_NAME),
+    `${JSON.stringify(merged, null, 2)}
+`
+  );
+  return merged;
+}
+function formatChanges(changes) {
+  const lines = [];
+  for (const ch of changes) {
+    const label = ch.label ? ` \xB7 ${ch.label}` : "";
+    const who = ch.origin === "studio" ? "human" : ch.origin ?? "unknown";
+    lines.push(
+      `v${String(ch.versionNumber ?? "?")} (${who}${label}): ${ch.summary ?? ""}`
+    );
+    if (ch.note) lines.push(`    note: ${ch.note}`);
+  }
+  return lines;
+}
+function serverWarnings(body, log) {
+  const warnings = Array.isArray(body.warnings) ? body.warnings : [];
+  for (const w of warnings) if (typeof w === "string") log(`warning ${w}`);
+}
+
+export {
+  helpFlagsFor,
+  unusedFlagsMessage,
+  UsageError,
+  parseArgs,
+  numFlag,
+  ASSET_ROUTE,
+  hostedAssetId,
+  manifestRefs,
+  programAssets,
+  missingManifestFiles,
+  TAKE_MEDIA_EXTENSIONS,
+  MEDIA_HEAD_BYTES,
+  sniffMediaType,
+  extensionFor,
+  resolveMediaType,
+  nameForType,
+  containerMismatch,
+  parseArgs2,
+  numFlag2,
+  strFlag,
+  hasFlag,
+  platformOrigin,
+  parseVosId,
+  deriveSlug,
+  CREDENTIALS_PATH,
+  resolveCredential,
+  requireCredential,
+  writeCredential,
+  clientId,
+  apiJson,
+  apiError,
+  SYNC_STATE_NAME,
+  readSyncState,
+  writeSyncState,
+  formatChanges,
+  serverWarnings
+};
+//# sourceMappingURL=chunk-36P5RREC.js.map