volito 0.1.0 → 0.3.0

package/dist/cli.js

@@ -1,7 +1,31 @@
 #!/usr/bin/env node
 import {
-  ASPECT_NAMES,
+  bundleSpec,
+  isBundleFile,
+  loadBundleFile
+} from "./chunks/chunk-PM3PLI3X.js";
+import {
   AUTHORING_GUIDE,
+  LIBRARY_GUIDE,
+  MOTION_GUIDE,
+  SOUND_GUIDE,
+  findItem,
+  formatIssues,
+  isSpecFile,
+  itemOfSpec,
+  library,
+  loadMedia,
+  loadSpecFile,
+  readStyleArg,
+  readWords,
+  searchItems,
+  specFrom,
+  specJsonSchema,
+  specToOptions,
+  validateSpec
+} from "./chunks/chunk-QA4SEJCZ.js";
+import {
+  ASPECT_NAMES,
   BUILTIN_STYLES,
   CATEGORIES,
   DIRECTIONS,
@@ -9,10 +33,8 @@ import {
   FORMAT_NOTES,
   HITS,
   IDLES,
-  LIBRARY_GUIDE,
   MG_API_REFERENCE,
   MOODS,
-  MOTION_GUIDE,
   MOVES,
   MOVE_NOTES,
   MotionError,
@@ -21,27 +43,25 @@ import {
   SPLITS,
   VIDEO_FORMATS,
   checkItem,
+  describeCues,
   describeItem,
   describeReport,
-  findItem,
-  library,
-  loadMedia,
-  packageVersion,
-  packsDir,
   parseAspect,
   parseMotionArgs,
-  readStyleArg,
-  readWords,
   renderSheet,
+  renderSoundFile,
   renderStill,
-  renderVideo,
-  searchItems
-} from "./chunks/chunk-CFDFWZAC.js";
+  renderVideo
+} from "./chunks/chunk-CUQY6YI3.js";
+import {
+  packageVersion,
+  packsDir
+} from "./chunks/chunk-ZFG3X3DU.js";
 
 // src/cli.ts
 import { availableParallelism } from "node:os";
-import { cpSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
+import { cpSync, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
 import { parseArgs } from "node:util";
 process.env.UV_THREADPOOL_SIZE ??= String(Math.max(4, Math.min(16, availableParallelism())));
 process.stdout.on("error", (e) => {
@@ -52,6 +72,16 @@ var HELP = `Volito ${packageVersion()} \u2014 brand-aware, voice-synced motion g
 Usage: volito <command> [item] [options]
 
 Commands
+  init [--agent a,b] [--dry-run] [--force]        set this project up for Claude Code, Cursor, VS Code or Codex:
+                                                  the MCP server in each agent's config and the Volito skill
+  doctor [--json]                                 what is ready: Node, FFmpeg and its formats, fonts, agents
+  review <item> [--aspect a] [--out dir]          check it, measure its timing and 9:16 safe zones, and write a
+                                                  contact sheet per aspect with a report (review.md)
+  spec <item> [options] [--out g.volito.json]     write the options as a Graphic spec, a file any command takes
+  bundle <spec.json> [--out g.volito]             the spec and every file it uses (DESIGN.md, program, transcript,
+                                                  images) in one file any command takes
+  validate <spec.json> [--strict] [--json]        check a spec against its item before rendering
+  schema                                          the Graphic spec's JSON Schema
   list [--search words] [--category c] [--json]   the graphics in the packs
   info <item> [--json] [--code]                   what an item is and every prop it takes
   styles [--json]                                 the built-in brand styles
@@ -59,6 +89,7 @@ Commands
   render <item> [--out file] [--format f]         render to video (ProRes 4444 .mov by default)
   still <item> [--t seconds] [--out file.png|.svg] one frame
   sheet <item> [--out sheet.png]                  frames across its time in one picture
+  sound <item> [--out track.wav]                  its sound alone, as a WAV, with the cue list
   check <item|file.js> [--aspect a]               run it at every aspect and report problems
   add <item> [--dir ./motion]                     copy an item's source into your project to edit
   new <id> [--dir ./motion]                       start a new item from a template
@@ -66,7 +97,8 @@ Commands
   guide                                           how items and packs are written
   mcp                                             run the MCP server on stdio
 
-An item is "pack/id" (essentials/lower-third), its id alone (lower-third), an item folder, or a .js program.
+An item is "pack/id" (essentials/lower-third), its id alone (lower-third), an item folder, a .js program, or a
+Graphic spec (.json with "volito": 1); options given on the command line win over the spec's.
 
 Options
   --prop name=value      set a prop (repeat it); lists take "a; b; c" or JSON
@@ -88,6 +120,11 @@ Options
   --mood <m>             a choreography: ${MOODS.join(", ")}
   --seed <n>             a new choreography for every number (with or without a mood)
   --speed <x>            every move faster (2) or slower (0.5)
+  --sound                a sound track, synthesised by Volito, muxed into the video (not png/gif): the program's own
+                         sound($) cues, else cues read from its motion \u2014 pops, whooshes, ticks, hits
+  --bed <key>            a pad under it all, in a key: Dm, "F major", C#m
+  --sound-level <x>      the track's level (1)
+  --sound-out <file.wav> also write the track alone (for an editor's timeline, next to a ProRes overlay)
   --packs <dir>          more packs (also VOLITO_PACKS)
   --format <f>           render: ${VIDEO_FORMATS.join(", ")} \xB7 still: png, svg
   --json                 machine-readable output
@@ -122,6 +159,10 @@ var OPTIONS = {
   seed: { type: "string" },
   speed: { type: "string" },
   packs: { type: "string", multiple: true },
+  sound: { type: "boolean" },
+  bed: { type: "string" },
+  "sound-level": { type: "string" },
+  "sound-out": { type: "string" },
   format: { type: "string" },
   out: { type: "string" },
   t: { type: "string" },
@@ -133,6 +174,11 @@ var OPTIONS = {
   pack: { type: "string" },
   json: { type: "boolean" },
   code: { type: "boolean" },
+  agent: { type: "string" },
+  force: { type: "boolean" },
+  "dry-run": { type: "boolean" },
+  "no-skill": { type: "boolean" },
+  strict: { type: "boolean" },
   quiet: { type: "boolean", short: "q" },
   help: { type: "boolean", short: "h" },
   version: { type: "boolean", short: "v" }
@@ -143,6 +189,16 @@ var num = (s, name) => {
   if (!Number.isFinite(n)) throw new MotionError(`--${name} "${s}" is not a number`);
   return n;
 };
+function mergeMotion(base, over) {
+  const out = {};
+  for (const [part, s] of Object.entries(base ?? {})) out[part] = { ...s };
+  for (const [part, s] of Object.entries(over)) out[part] = { ...out[part] ?? {}, ...s };
+  return out;
+}
+function relativeTo(file, path) {
+  const rel = relative(dirname(resolve(file)), resolve(path));
+  return rel.startsWith(".") ? rel : `./${rel}`;
+}
 function pairs(list, flag) {
   return (list ?? []).map((p) => {
     const i = p.indexOf("=");
@@ -150,27 +206,28 @@ function pairs(list, flag) {
     return [p.slice(0, i).trim(), p.slice(i + 1)];
   });
 }
-async function buildOptions(v, item) {
-  let props = {};
+async function buildOptions(v, item, base = {}) {
+  let props = { ...base.props ?? {} };
   if (v.props) {
     const raw = existsSync(resolve(v.props)) ? readFileSync(resolve(v.props), "utf8") : v.props;
     try {
-      props = JSON.parse(raw);
+      props = { ...props, ...JSON.parse(raw) };
     } catch {
       throw new MotionError("--props takes JSON or a JSON file");
     }
   }
   for (const [k, val] of pairs(v.prop, "prop")) props[k] = val;
   for (const [k, val] of pairs(v.image, "image")) props[k] = val;
-  const beats = {};
+  const beats = { ...base.beats ?? {} };
   for (const [k, val] of pairs(v.beat, "beat")) beats[k] = num(val, "beat");
-  const colors = {};
+  const colors = { ...base.colors ?? {} };
   for (const k of ["accent", "accent2", "ink", "paper", "surface", "display", "text", "mono"]) if (v[k]) colors[k] = v[k];
   if (v.mode) {
     if (v.mode !== "dark" && v.mode !== "light") throw new MotionError('--mode is "dark" or "light"');
     colors.mode = v.mode;
   }
   const opts = {
+    ...base,
     props,
     colors,
     ...v.style ? { style: readStyleArg(v.style) } : {},
@@ -181,10 +238,13 @@ async function buildOptions(v, item) {
     ...v.bg ? { background: v.bg } : {},
     ...v.words ? { words: readWords(v.words, num(v.offset, "offset") ?? 0) } : {},
     ...Object.keys(beats).length ? { beats } : {},
-    ...v.motion?.length ? { motion: parseMotionArgs(v.motion) } : {},
+    ...v.motion?.length ? { motion: mergeMotion(base.motion, parseMotionArgs(v.motion)) } : {},
     ...v.mood ? { mood: v.mood } : {},
     ...v.seed !== void 0 ? { seed: num(v.seed, "seed") } : {},
-    ...v.speed ? { speed: num(v.speed, "speed") } : {}
+    ...v.speed ? { speed: num(v.speed, "speed") } : {},
+    ...v.sound || v.bed || v["sound-level"] || v["sound-out"] ? { sound: v["sound-level"] ? { level: num(v["sound-level"], "sound-level") } : true } : {},
+    ...v.bed ? { bed: v.bed } : {},
+    ...v["sound-out"] ? { soundOut: v["sound-out"] } : {}
   };
   opts.media = await loadMedia(item, props);
   return opts;
@@ -222,11 +282,123 @@ async function main(argv) {
   }
   if (rest.length) throw new MotionError(`unexpected "${rest.join(" ")}" \u2014 options start with --`);
   const lib = library(v.packs ?? []);
+  const loaded = target && cmd !== "validate" && cmd !== "bundle" ? isBundleFile(target) ? loadBundleFile(target) : isSpecFile(target) ? loadSpecFile(target) : null : null;
   const need = () => {
     if (!target) throw new MotionError(`${cmd} needs an item (see: volito list)`);
-    return findItem(target, lib);
+    return loaded ? itemOfSpec(loaded, lib) : findItem(target, lib);
   };
+  const optionsFor = (item) => buildOptions(v, item, loaded ? specToOptions(loaded, item) : {});
   switch (cmd) {
+    case "validate": {
+      if (!target) throw new MotionError("validate needs a spec file");
+      let doc;
+      try {
+        doc = JSON.parse(readFileSync(resolve(target), "utf8"));
+      } catch (e) {
+        throw new MotionError(`${target}: ${e.message}`);
+      }
+      const rep = validateSpec(doc, { dir: dirname(resolve(target)), lib });
+      const ok = rep.ok && !(v.strict && rep.warnings.length);
+      if (v.json) process.stdout.write(`${JSON.stringify({ ...rep, ok }, null, 2)}
+`);
+      else {
+        const lines = [ok ? `\u2713 ${target} is a valid spec${rep.item ? ` for ${rep.item}` : ""}` : `\u2717 ${target}`];
+        if (rep.errors.length) lines.push(formatIssues(rep.errors));
+        if (rep.warnings.length) lines.push(formatIssues(rep.warnings, "!"));
+        process.stdout.write(`${lines.join("\n")}
+`);
+      }
+      return ok ? 0 : 1;
+    }
+    case "spec": {
+      const item = need();
+      const base = loaded?.spec;
+      const props = { ...base?.props ?? {} };
+      if (v.props) Object.assign(props, JSON.parse(existsSync(resolve(v.props)) ? readFileSync(resolve(v.props), "utf8") : v.props));
+      for (const [k, val] of [...pairs(v.prop, "prop"), ...pairs(v.image, "image")]) props[k] = val;
+      const colors = { ...base?.colors ?? {} };
+      for (const k of ["accent", "accent2", "ink", "paper", "surface", "mode", "display", "text", "mono"]) if (v[k]) colors[k] = v[k];
+      const beats = { ...base?.beats ?? {} };
+      for (const [k, val] of pairs(v.beat, "beat")) beats[k] = num(val, "beat");
+      const out = v.out ?? `${item.id}.volito.json`;
+      const spec = specFrom({
+        ...base ?? {},
+        ...loaded ? {} : item.pack === "custom" || item.pack === "local" ? { program: relativeTo(out, target) } : { item: item.ref },
+        props,
+        ...v.style ? { style: /\.(md|markdown|txt)$/i.test(v.style) ? relativeTo(out, v.style) : v.style } : {},
+        colors,
+        ...v.aspect ? { aspect: v.aspect } : {},
+        ...v.duration ? { duration: num(v.duration, "duration") } : {},
+        ...v.fps ? { fps: num(v.fps, "fps") } : {},
+        ...v.width ? { width: num(v.width, "width") } : {},
+        ...v.bg ? { background: v.bg } : {},
+        ...v.words ? { words: relativeTo(out, v.words) } : {},
+        ...v.offset ? { offset: num(v.offset, "offset") } : {},
+        beats,
+        ...v.motion?.length ? { motion: mergeMotion(base?.motion, parseMotionArgs(v.motion)) } : {},
+        ...v.mood ? { mood: v.mood } : {},
+        ...v.seed !== void 0 ? { seed: num(v.seed, "seed") } : {},
+        ...v.speed ? { speed: num(v.speed, "speed") } : {},
+        ...v.sound || v.bed || v["sound-level"] ? { sound: v.bed || v["sound-level"] ? { ...v.bed ? { bed: v.bed } : {}, ...v["sound-level"] ? { level: num(v["sound-level"], "sound-level") } : {} } : true } : {},
+        ...v.format ? { render: { ...base?.render ?? {}, format: v.format } } : {}
+      });
+      const rep = validateSpec(spec, { dir: dirname(resolve(out)), lib });
+      if (!rep.ok) throw new MotionError(`that spec would not render:
+${formatIssues(rep.errors)}`);
+      mkdirSync(dirname(resolve(out)), { recursive: true });
+      writeFileSync(resolve(out), `${JSON.stringify(spec, null, 2)}
+`);
+      warn(rep.warnings.map((w) => `${w.path ? `${w.path}: ` : ""}${w.message}`), v.quiet);
+      process.stdout.write(`${resolve(out)}
+  render it with: volito render ${JSON.stringify(out)}
+`);
+      return 0;
+    }
+    case "bundle": {
+      if (!target || !isSpecFile(target)) throw new MotionError('bundle needs a spec file (.json with "volito": 1) \u2014 write one with volito spec');
+      const b = bundleSpec(target, (spec, dir) => {
+        const item = itemOfSpec({ spec, dir }, lib);
+        return Object.entries(item.props).filter(([, p]) => p.type === "image").map(([k]) => k);
+      });
+      const out = resolve(v.out ?? target.replace(/(\.volito)?\.json$/i, "") + ".volito");
+      mkdirSync(dirname(out), { recursive: true });
+      writeFileSync(out, `${JSON.stringify(b)}
+`);
+      const names = Object.keys(b.files);
+      process.stdout.write(`${out}
+  the spec${names.length ? ` and ${names.join(", ")}` : ""} \xB7 ${bytes(statSync(out).size)}
+`);
+      return 0;
+    }
+    case "schema":
+      process.stdout.write(`${JSON.stringify(specJsonSchema(), null, 2)}
+`);
+      return 0;
+    case "init": {
+      const { applyInit, describeInit, parseAgents, planInit } = await import("./chunks/init-JX2BYRKT.js");
+      let agents;
+      try {
+        agents = v.agent ? parseAgents(v.agent) : void 0;
+      } catch (e) {
+        throw new MotionError(e.message);
+      }
+      const plan = planInit(resolve(target ?? "."), { agents, force: v.force, skill: !v["no-skill"] });
+      if (!v["dry-run"]) applyInit(plan.actions);
+      if (v.json) process.stdout.write(`${JSON.stringify({ agents: plan.agents, dryRun: !!v["dry-run"], actions: plan.actions.map(({ kind, agent, detail, ...a }) => ({ kind, agent, detail, path: "path" in a ? a.path : void 0 })) }, null, 2)}
+`);
+      else process.stdout.write(`${describeInit(plan, !!v["dry-run"])}
+`);
+      return 0;
+    }
+    case "doctor": {
+      const { describeDoctor, runDoctor } = await import("./chunks/init-JX2BYRKT.js");
+      const checks = runDoctor(resolve(target ?? "."));
+      if (v.json) process.stdout.write(`${JSON.stringify(checks, null, 2)}
+`);
+      else process.stdout.write(`${describeDoctor(checks)}
+`);
+      return checks.some((c) => !c.ok && (c.name === "Node" || c.name === "Fonts")) ? 1 : 0;
+    }
     case "list": {
       if (v.category && !CATEGORIES.includes(v.category)) throw new MotionError(`--category is one of ${CATEGORIES.join(", ")}`);
       const items = searchItems({ search: v.search ?? target, category: v.category, pack: v.pack }, lib);
@@ -289,20 +461,22 @@ Also: from=${DIRECTIONS.slice(0, 4).join("|")}\u2026 \xB7 distance=px \xB7 blur=
     }
     case "render": {
       const item = need();
-      const opts = await buildOptions(v, item);
-      if (v.format && !VIDEO_FORMATS.includes(v.format)) throw new MotionError(`--format is one of ${VIDEO_FORMATS.join(", ")}`);
-      const r = await renderVideo(item, { ...opts, ...v.format ? { format: v.format } : {}, ...v.out ? { out: v.out } : {}, onProgress: progress(v.quiet) });
+      const opts = await optionsFor(item);
+      const format = v.format ?? loaded?.spec.render?.format;
+      const out = v.out ?? loaded?.spec.render?.out;
+      if (format && !VIDEO_FORMATS.includes(format)) throw new MotionError(`--format is one of ${VIDEO_FORMATS.join(", ")}`);
+      const r = await renderVideo(item, { ...opts, ...format ? { format } : {}, ...out ? { out } : {}, onProgress: progress(v.quiet) });
       warn(r.warnings, v.quiet);
       if (v.json) process.stdout.write(`${JSON.stringify(r, null, 2)}
 `);
       else process.stdout.write(`${r.file}
-  ${r.format} \xB7 ${r.width}\xD7${r.height} \xB7 ${r.fps} fps \xB7 ${r.duration.toFixed(2)} s \xB7 ${r.frames} frames (${r.drawn} drawn)${r.bytes ? ` \xB7 ${bytes(r.bytes)}` : ""} \xB7 ${(r.ms / 1e3).toFixed(1)} s
+  ${r.format} \xB7 ${r.width}\xD7${r.height} \xB7 ${r.fps} fps \xB7 ${r.duration.toFixed(2)} s \xB7 ${r.frames} frames (${r.drawn} drawn)${r.bytes ? ` \xB7 ${bytes(r.bytes)}` : ""}${r.sound ? ` \xB7 sound: ${r.sound.cues.length} cues${r.sound.bed ? ` on a ${r.sound.bed.key} ${r.sound.bed.mode} bed` : ""}${r.sound.file ? ` \u2192 ${r.sound.file}` : ""}` : ""} \xB7 ${(r.ms / 1e3).toFixed(1)} s
 `);
       return 0;
     }
     case "still": {
       const item = need();
-      const opts = await buildOptions(v, item);
+      const opts = await optionsFor(item);
       const format = v.format === "svg" || v.out?.endsWith(".svg") ? "svg" : "png";
       const out = v.out ?? `${item.id}.${format}`;
       const r = await renderStill(item, { ...opts, format, out, ...v.t ? { t: num(v.t, "t") } : {} });
@@ -315,7 +489,7 @@ Also: from=${DIRECTIONS.slice(0, 4).join("|")}\u2026 \xB7 distance=px \xB7 blur=
     }
     case "sheet": {
       const item = need();
-      const opts = await buildOptions(v, item);
+      const opts = await optionsFor(item);
       const times = v.times ? v.times.split(",").map((s) => num(s.trim(), "times")) : void 0;
       const r = await renderSheet(item, { ...opts, ...times ? { times } : {}, ...v.cols ? { cols: num(v.cols, "cols") } : {} });
       const out = resolve(v.out ?? `${item.id}-sheet.png`);
@@ -328,9 +502,20 @@ Also: from=${DIRECTIONS.slice(0, 4).join("|")}\u2026 \xB7 distance=px \xB7 blur=
 `);
       return 0;
     }
+    case "review": {
+      const item = need();
+      const opts = await optionsFor(item);
+      const { describeReview, reviewItem } = await import("./chunks/review-RBH5EUZN.js");
+      const rep = await reviewItem(item, { ...opts, ...v.aspect ? { aspects: [parseAspect(v.aspect)] } : {}, outDir: v.out ?? join("volito-review", item.id) });
+      process.stdout.write(v.json ? `${JSON.stringify(rep, null, 2)}
+` : `${describeReview(rep)}
+  report: ${join(rep.dir, "review.md")}
+`);
+      return rep.ok ? 0 : 1;
+    }
     case "check": {
       const item = need();
-      const opts = await buildOptions(v, item);
+      const opts = await optionsFor(item);
       const rep = await checkItem(item, { ...opts, ...v.aspect ? { aspects: [parseAspect(v.aspect)] } : {} });
       process.stdout.write(v.json ? `${JSON.stringify(rep, null, 2)}
 ` : `${describeReport(rep)}
@@ -355,7 +540,7 @@ Also: from=${DIRECTIONS.slice(0, 4).join("|")}\u2026 \xB7 distance=px \xB7 blur=
       if (!target || !/^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$/.test(target)) throw new MotionError("new needs an id: lowercase words joined by hyphens");
       const dir = resolve(v.dir ?? "motion", target);
       if (existsSync(dir)) throw new MotionError(`${dir} already exists`);
-      cpSync(join(packsDir(), "..", "skill", "template"), dir, { recursive: true });
+      cpSync(join(packsDir(), "..", "templates", "item"), dir, { recursive: true });
       const manifest = JSON.parse(readFileSync(join(dir, "item.json"), "utf8"));
       manifest.id = target;
       manifest.name = target.replace(/-/g, " ").replace(/^./, (c) => c.toUpperCase());
@@ -363,6 +548,19 @@ Also: from=${DIRECTIONS.slice(0, 4).join("|")}\u2026 \xB7 distance=px \xB7 blur=
 `);
       process.stdout.write(`${dir}
   edit item.json and frame.js, then: volito sheet ${JSON.stringify(dir)}
+`);
+      return 0;
+    }
+    case "sound": {
+      const item = need();
+      const opts = await optionsFor(item);
+      const r = await renderSoundFile(item, { ...opts, sound: opts.sound ?? true, out: v.out ?? `${item.id}.wav` });
+      warn(r.warnings, v.quiet);
+      if (v.json) process.stdout.write(`${JSON.stringify({ file: r.file, duration: r.duration, peak: r.peak, bed: r.bed, cues: r.cues }, null, 2)}
+`);
+      else process.stdout.write(`${r.file}
+  ${r.duration.toFixed(2)} s \xB7 ${r.cues.length} cues${r.bed ? ` \xB7 bed ${r.bed.key} ${r.bed.mode}` : ""} \xB7 peak ${r.peak.toFixed(2)}
+${describeCues(r.cues)}
 `);
       return 0;
     }
@@ -370,6 +568,8 @@ Also: from=${DIRECTIONS.slice(0, 4).join("|")}\u2026 \xB7 distance=px \xB7 blur=
       process.stdout.write(`${MG_API_REFERENCE}
 
 ${LIBRARY_GUIDE}
+
+${SOUND_GUIDE}
 `);
       return 0;
     case "guide":