@odori/cli 0.0.10 → 0.0.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@odori/cli",
-  "version": "0.0.10",
+  "version": "0.0.12",
   "type": "module",
   "description": "The odori command line: discovery, Studio, component installation, stills, tests, and export jobs.",
   "license": "Apache-2.0",
@@ -28,7 +28,7 @@
     "playwright-core": "1.55.0",
     "tsx": "4.20.5",
     "vite": "7.3.0",
-    "odori": "0.0.10"
+    "odori": "0.0.12"
   },
   "devDependencies": {
     "@types/node": "22.19.0",
@@ -36,7 +36,7 @@
     "@types/react-dom": "19.2.3",
     "tsup": "^8.5.1",
     "typescript": "5.9.3",
-    "@odori/registry": "0.0.9"
+    "@odori/registry": "0.0.12"
   },
   "publishConfig": {
     "access": "public"
@@ -45,6 +45,7 @@
     "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.studio.json",
     "build": "tsup",
     "snapshot": "tsx scripts/snapshot.ts",
-    "verify:package": "tsx scripts/verify-package.ts"
+    "verify:package": "tsx scripts/verify-package.ts",
+    "snapshot:docs": "tsx scripts/docs-snapshot.ts"
   }
 }

package/src/cli.ts

@@ -3,6 +3,7 @@ import {log} from "./log";
 import {addCommand, registryCommand} from "./commands/add";
 import {diffCommand, updateCommand} from "./commands/update";
 import {devCommand} from "./commands/dev";
+import {docsCommand} from "./commands/docs";
 import {doctorCommand} from "./commands/doctor";
 import {installCommand} from "./binaries";
 import {exportCommand, jobsCommand} from "./commands/exportVideo";
@@ -12,8 +13,10 @@ import {inspectCommand} from "./commands/inspect";
 import {listCommand} from "./commands/list";
 import {newCommand} from "./commands/new";
 import {bedCommand} from "./commands/bed";
+import {blocksCommand} from "./commands/blocks";
 import {narrateCommand} from "./commands/narrate";
 import {frameCommand} from "./commands/frame";
+import {graphCommand} from "./commands/graph";
 import {testCommand} from "./commands/test";
 
 type Flags = Record<string, string | boolean>;
@@ -100,12 +103,13 @@ const COMMAND_FLAGS: Record<string, string[]> = {
   diff: ["full"],
   update: ["force"],
   list: [],
+  graph: ["json"],
   inspect: ["json", "input"],
   frame: ["at", "output", "input"],
   bed: ["role", "output", "target", "generate", "provider", "seconds"],
   narrate: ["output", "voice", "role", "provider"],
   test: ["json"],
-  export: ["output", "input", "concurrency", "preset", "format", "quality", "scale", "no-audio", "fast", "no-frame-skip", "retry"],
+  export: ["output", "input", "concurrency", "preset", "format", "quality", "scale", "no-audio", "audio-variant", "fast", "no-frame-skip", "retry"],
   jobs: [],
   help: [],
 };
@@ -184,6 +188,11 @@ const USAGE: Record<string, string> = {
   add: `odori add <components...> [--force] [--dry-run]
   Install editable component source, fetched from the registry and cached.
   --force replaces local edits. --dry-run lists the files and writes nothing.`,
+  blocks: `odori blocks <ls|show|cat|add> [id] [file] [--out <dir>] [--force] [--dry-run] [--json]
+  Whole videos, published like components. ls lists them, show names the files
+  and components one is built from, cat prints one of those files, and add
+  installs the block and everything it imports. --out installs into another
+  directory rather than the one the block was authored in.`,
   registry: `odori registry
   List available registry components and cues.`,
   diff: `odori diff [components] [--full]
@@ -192,6 +201,11 @@ const USAGE: Record<string, string> = {
   Apply upstream component changes.`,
   list: `odori list
   Print discovered video ids and formats.`,
+  graph: `odori graph [--json]
+  Compile the project into .odori/graph.json: every video with its format,
+  duration, brand, tags, audio variants, and components, plus the component
+  catalog, the audio library, and structure findings. --json prints the same
+  document to stdout. Exits non-zero when the structure has errors.`,
   inspect: `odori inspect <id> [--json] [--input <json>]
   Show resolved layout, inputs, scenes, and assets.`,
   frame: `odori frame <id> --at <time> [--output <path>] [--input <json>]
@@ -202,7 +216,7 @@ const USAGE: Record<string, string> = {
   check, for CI.`,
   export: `odori export <id> [--output <path>] [--input <json>] [--concurrency <n>]
              [--preset <name>] [--format <name>] [--quality <tier>] [--scale <n>]
-             [--no-audio] [--fast] [--no-frame-skip] [--retry <job>]
+             [--no-audio] [--audio-variant <name>] [--fast] [--no-frame-skip] [--retry <job>]
   Render and encode a distributable file. --format is mp4, webm, prores, gif,
   or png; without it the output's extension decides, and mp4 is the default.
   --quality is studio, social, or web. --scale multiplies the output size,
@@ -221,14 +235,17 @@ const HELP = `odori - build videos like applications
 Usage
   odori dev [--port 4300]          Discover project resources and start Studio
   odori init                       Add videos/ and odori.config.ts to a project
+  odori docs [page|search <text>]   Read the documentation offline
   odori doctor                     Check everything a render and an encode need
   odori install                    Download the pinned Chrome and FFmpeg
   odori new <name>                 Generate a video.tsx entry
   odori add <components...>        Install editable component source
+  odori blocks <ls|show|add>       Browse and install whole videos
   odori registry                   List available registry components
   odori diff [components]          Compare installed components with upstream
   odori update [components]        Apply upstream component changes
   odori list                       Print discovered video ids and formats
+  odori graph [--json]             Compile the project graph and check its shape
   odori inspect <id> [--json]      Show resolved layout, inputs, scenes, assets
   odori frame <id> --at 4s          Render one deterministic frame to a PNG
   odori test [id] [--json]         Validate contracts and representative frames
@@ -299,6 +316,8 @@ export const run = async (argv: string[]): Promise<number> => {
       case "integrations":
         await integrationsCommand();
         return 0;
+      case "docs":
+        return await docsCommand(positionals, {json: flags.json === true});
       case "doctor":
         return await doctorCommand();
       case "install":
@@ -309,6 +328,14 @@ export const run = async (argv: string[]): Promise<number> => {
       case "add":
         await addCommand(positionals, {force: flags.force === true, dryRun: flags["dry-run"] === true});
         return 0;
+      case "blocks":
+        await blocksCommand(positionals, {
+          out: typeof flags.out === "string" ? flags.out : undefined,
+          force: flags.force === true,
+          dryRun: flags["dry-run"] === true,
+          json: flags.json === true,
+        });
+        return 0;
       case "registry":
         await registryCommand();
         return 0;
@@ -321,6 +348,8 @@ export const run = async (argv: string[]): Promise<number> => {
       case "list":
         await listCommand();
         return 0;
+      case "graph":
+        return await graphCommand({json: flags.json === true});
       case "inspect":
         await inspectCommand(positionals[0] ?? "", {json: flags.json === true, input: parseInput(flags)});
         return 0;
@@ -365,6 +394,7 @@ export const run = async (argv: string[]): Promise<number> => {
           scale: numberFlag(flags, "scale"),
           format: typeof flags.format === "string" ? flags.format : undefined,
           audio: flags["no-audio"] === true ? false : undefined,
+          audioVariant: typeof flags["audio-variant"] === "string" ? flags["audio-variant"] : undefined,
           fast: flags.fast === true,
           skipUnchangedFrames: flags["no-frame-skip"] === true ? false : undefined,
           retry: typeof flags.retry === "string" ? flags.retry : undefined,

package/src/commands/blocks.ts

@@ -0,0 +1,188 @@
+import {existsSync} from "node:fs";
+import {mkdir, writeFile} from "node:fs/promises";
+import {dirname} from "node:path";
+import {loadConfig} from "../config";
+import {log} from "../log";
+import {
+  normalizeComponentName,
+  resolveBlock,
+  resolveBlocks,
+  resolveWithinRoot,
+  verifyBlockIntegrity,
+  type BlockDocument,
+} from "../registry-source";
+import {addCommand} from "./add";
+
+/**
+ * Blocks from the command line.
+ *
+ * `odori add` installs a component and `create odori` scaffolds a project, so
+ * the largest thing the catalog ships was the one thing a reader had to
+ * rebuild by hand: open the page, copy each file, paste it in. `add` closes
+ * that, and the other three exist so running it is not a leap — see what a
+ * block is, read a file, then take it.
+ *
+ * Everything a block install must get right is already solved for components,
+ * so none of it is rewritten here: resolution and its cache, the integrity
+ * hash over the exact bytes, the refusal to write outside the project, and
+ * the component install itself, which `add` performs by calling the same
+ * command a person would.
+ */
+
+/** Where a block's files land, once `--out` has had its say. */
+const rebase = (block: BlockDocument, target: string, out?: string): string => {
+  if (!out) return target;
+  const home = block.entry.slice(0, block.entry.lastIndexOf("/"));
+  // Only the block's own directory moves. A target that somehow sits outside
+  // it keeps its place rather than being silently reparented.
+  if (!target.startsWith(`${home}/`)) return target;
+  return `${out.replace(/\/$/, "")}/${target.slice(home.length + 1)}`;
+};
+
+const findBlock = async (config: Awaited<ReturnType<typeof loadConfig>>, id: string) => {
+  const index = await resolveBlocks(config);
+  const summary = index.items.find((item) => item.id === id);
+  if (!summary) {
+    const names = index.items.map((item) => item.id).join(", ");
+    throw new Error(`No block named ${JSON.stringify(id)}. Available: ${names}`);
+  }
+  return {summary, index};
+};
+
+export const blocksListCommand = async (options: {json?: boolean} = {}) => {
+  const config = await loadConfig(process.cwd());
+  const {items, origin, detail} = await resolveBlocks(config);
+
+  if (options.json) {
+    log.info(JSON.stringify({origin, items}, null, 2));
+    return;
+  }
+
+  if (origin === "cache") log.detail(`blocks: cached copy (offline)`);
+  else log.detail(`blocks: ${detail}`);
+  log.title(`${items.length} block${items.length === 1 ? "" : "s"}`);
+  for (const item of items) {
+    log.info(`  ${item.id}  ${item.title}`);
+    log.detail(`    ${item.format} · ${item.tags.join(", ")}`);
+  }
+  log.detail(`\nodori blocks show <id> for its files, odori blocks add <id> to install one.`);
+};
+
+export const blocksShowCommand = async (id: string, options: {json?: boolean} = {}) => {
+  const config = await loadConfig(process.cwd());
+  const {summary} = await findBlock(config, id);
+
+  if (options.json) {
+    log.info(JSON.stringify(summary, null, 2));
+    return;
+  }
+
+  log.title(`${summary.title}  (${summary.id})`);
+  log.info(`  ${summary.description}`);
+  log.detail(`  ${summary.format} · ${summary.tags.join(", ")}`);
+  log.title("files");
+  for (const file of summary.files) log.info(`  ${file.target}${file.target === summary.entry ? "  (entry)" : ""}`);
+  log.title("components");
+  for (const component of summary.components) log.info(`  ${component}`);
+  log.detail(`\nodori blocks add ${summary.id}`);
+};
+
+export const blocksCatCommand = async (id: string, file: string) => {
+  const config = await loadConfig(process.cwd());
+  await findBlock(config, id);
+  const {block} = await resolveBlock(config, id);
+
+  // A reader types the name they saw, which may be the whole target or just
+  // the file at the end of it.
+  const found =
+    block.files.find((item) => item.target === file) ??
+    block.files.find((item) => item.target.endsWith(`/${file}`));
+  if (!found) {
+    throw new Error(
+      `Block "${id}" has no file ${JSON.stringify(file)}. It ships: ${block.files
+        .map((item) => item.target)
+        .join(", ")}`,
+    );
+  }
+  log.info(found.content);
+};
+
+export const blocksAddCommand = async (
+  id: string,
+  options: {out?: string; force?: boolean; dryRun?: boolean} = {},
+) => {
+  const config = await loadConfig(process.cwd());
+  await findBlock(config, id);
+  const {block, origin} = await resolveBlock(config, id);
+  if (origin === "cache") log.detail("blocks: cached copy (offline)");
+  verifyBlockIntegrity(block);
+
+  const writes = block.files.map((file) => {
+    const target = rebase(block, file.target, options.out);
+    return {target, destination: resolveWithinRoot(config.root, target), content: file.content};
+  });
+
+  // Every refusal is collected before anything is written, so a block never
+  // lands half-installed on the first file that already existed.
+  const clashes = writes.filter((write) => existsSync(write.destination));
+  if (clashes.length > 0 && !options.force) {
+    throw new Error(
+      `These files already exist:\n${clashes.map((write) => `  ${write.target}`).join("\n")}\n` +
+        "Nothing was written. Pass --out to install beside them, or --force to replace them.",
+    );
+  }
+
+  if (options.dryRun) {
+    log.title(`${block.title} would write ${writes.length} file${writes.length === 1 ? "" : "s"}`);
+    for (const write of writes) log.info(`  ${write.target}`);
+    if (block.components.length > 0) log.detail(`  and install ${block.components.join(", ")}`);
+    return;
+  }
+
+  /* The components first: a block's files import them, so a project that
+     stops halfway should be missing the video rather than the parts. */
+  if (block.components.length > 0) {
+    await addCommand(block.components.map(normalizeComponentName), {force: options.force});
+  }
+
+  for (const write of writes) {
+    await mkdir(dirname(write.destination), {recursive: true});
+    await writeFile(write.destination, write.content, "utf8");
+    log.info(`  ${write.target}`);
+  }
+
+  const entry = rebase(block, block.entry, options.out);
+  log.title(`${block.title} installed`);
+  log.detail(`  entry: ${entry}`);
+  /* The id is written inside the entry, not taken from the directory, so a
+     block installed beside itself would be discovered twice under one name.
+     Better said here than found as a duplicate-id error on the next run. */
+  if (options.out) log.detail(`  the video id is set in the entry; change it if this project already has "${block.id}".`);
+  log.detail(`  odori dev, then open the video to watch it.`);
+};
+
+/** The one entry point the CLI dispatches to, so `blocks` reads as one word. */
+export const blocksCommand = async (
+  positionals: string[],
+  flags: {out?: string; force?: boolean; dryRun?: boolean; json?: boolean} = {},
+) => {
+  const [action = "ls", ...rest] = positionals;
+  switch (action) {
+    case "ls":
+    case "list":
+      return blocksListCommand({json: flags.json});
+    case "show":
+      if (!rest[0]) throw new Error("Name a block, for example: odori blocks show launch");
+      return blocksShowCommand(rest[0], {json: flags.json});
+    case "cat":
+      if (!rest[0] || !rest[1]) {
+        throw new Error("Name a block and a file, for example: odori blocks cat launch video.tsx");
+      }
+      return blocksCatCommand(rest[0], rest[1]);
+    case "add":
+      if (!rest[0]) throw new Error("Name a block, for example: odori blocks add launch");
+      return blocksAddCommand(rest[0], {out: flags.out, force: flags.force, dryRun: flags.dryRun});
+    default:
+      throw new Error(`Unknown blocks command ${JSON.stringify(action)}. Try: ls, show, cat, add.`);
+  }
+};

package/src/commands/dev.ts

@@ -165,7 +165,12 @@ export const devCommand = async (options: {port?: number; root?: string; open?:
               const {graph, videos} = await context();
               const video = findVideo(videos, String(body.videoId));
               const input = (body.input ?? {}) as Record<string, unknown>;
-              const compiled = await compileInBrowser(origin, targetFor(video, input), config);
+              const audioVariant = typeof body.audioVariant === "string" ? body.audioVariant : undefined;
+              const compiled = await compileInBrowser(
+                origin,
+                targetFor(video, input, undefined, undefined, undefined, audioVariant),
+                config,
+              );
               const {manifest} = await freezeManifest(
                 {...video, durationInFrames: compiled.durationInFrames},
                 graph,

package/src/commands/docs.ts

@@ -0,0 +1,88 @@
+import {docPages, findDoc, searchDocs} from "../docs";
+import {log} from "../log";
+
+/**
+ * The documentation, in the terminal the agent is already in.
+ *
+ * The pages ship inside this package, so this answers with no network and no
+ * browser: `odori docs` lists what there is, `odori docs <page>` prints one,
+ * and `odori docs search <text>` finds the line that says it. An agent
+ * working in an unfamiliar project can read the framework the same way it
+ * reads the project.
+ */
+export const docsCommand = async (positionals: string[], options: {json?: boolean} = {}) => {
+  const [first, ...rest] = positionals;
+
+  if (first === "search") {
+    const query = rest.join(" ").trim();
+    if (!query) {
+      log.warn("Usage: odori docs search <text>");
+      return 1;
+    }
+    const hits = searchDocs(query);
+    if (options.json) {
+      log.info(JSON.stringify(hits.map(({page, line, text}) => ({slug: page.slug, line, text})), null, 2));
+      return hits.length > 0 ? 0 : 1;
+    }
+    if (hits.length === 0) {
+      log.warn(`No page mentions ${query}.`);
+      return 1;
+    }
+    log.title(`${hits.length} line${hits.length === 1 ? "" : "s"} mentioning ${query}`);
+    for (const hit of hits) {
+      log.info(`  ${hit.page.slug}:${hit.line}`);
+      log.detail(`    ${hit.text}`);
+    }
+    log.detail(`Read one with: odori docs ${hits[0].page.slug}`);
+    return 0;
+  }
+
+  if (!first) {
+    const pages = docPages();
+    if (options.json) {
+      log.info(
+        JSON.stringify(
+          pages.map(({slug, title, description}) => ({slug, title, description})),
+          null,
+          2,
+        ),
+      );
+      return 0;
+    }
+    log.title(`${pages.length} pages`);
+    /* Grouped the way the site files them, because a flat list of eighteen
+       slugs is a list to read rather than a shape to recognise. */
+    const sections = new Map<string, typeof pages>();
+    for (const page of pages) {
+      const key = page.section || "";
+      sections.set(key, [...(sections.get(key) ?? []), page]);
+    }
+    for (const [section, group] of sections) {
+      if (section) log.info(`  ${section}/`);
+      for (const page of group) {
+        const name = section ? page.slug.slice(section.length + 1) : page.slug;
+        log.info(`  ${section ? "  " : ""}${name.padEnd(section ? 20 : 22)}${page.title}`);
+      }
+    }
+    log.detail("Read one with: odori docs <page> · search with: odori docs search <text>");
+    return 0;
+  }
+
+  const page = findDoc(first);
+  if (!page) {
+    log.warn(`No page called ${first}.`);
+    log.detail("List them with: odori docs");
+    return 1;
+  }
+
+  if (options.json) {
+    log.info(JSON.stringify(page, null, 2));
+    return 0;
+  }
+
+  log.title(page.title);
+  if (page.description) log.detail(page.description);
+  log.info("");
+  log.info(page.body);
+  return 0;
+};

package/src/commands/doctor.ts

@@ -4,6 +4,9 @@ import {existsSync} from "node:fs";
 import {createRequire} from "node:module";
 import {relative, resolve} from "node:path";
 import {loadConfig} from "../config";
+import {discoverProject} from "../discovery";
+import {loadVideos} from "../project";
+import {checkStructure} from "../structure";
 import {keySource} from "../keystore";
 import {musicProviders} from "../providers";
 import {CHROME_BUILD, cacheRoot, resolveBrowser, resolveFfmpeg} from "../binaries";
@@ -167,6 +170,41 @@ export const runChecks = async (root: string): Promise<Check[]> => {
     fix: `Add a sibling <name>.preview.tsx with defineComponentPreview so Studio can play it on its own. A component with no fixture only ever renders inside a video.`,
   });
 
+  /**
+   * The filesystem contract, checked the way the graph command checks it. A
+   * file one keystroke away from being an entry, a fixture credited to
+   * nothing, a sound with no file behind it: each is invisible to discovery
+   * by design, which is exactly why doctor has to say it. Loading the videos
+   * can itself fail — a missing export, a colliding id — and that failure is
+   * this check's answer rather than doctor's crash.
+   */
+  if (existsSync(resolve(config.root, config.videosDir))) {
+    try {
+      const graph = await discoverProject(config);
+      const videos = await loadVideos(graph);
+      const findings = await checkStructure(config, graph, videos);
+      const errors = findings.filter((finding) => finding.level === "error");
+      const first = errors[0] ?? findings[0];
+      checks.push({
+        name: "Structure",
+        detail:
+          findings.length === 0
+            ? `${videos.length} video${videos.length === 1 ? "" : "s"}, shape is sound`
+            : `${first.file}: ${first.message}${findings.length > 1 ? ` (and ${findings.length - 1} more)` : ""}`,
+        ok: errors.length === 0,
+        warn: errors.length === 0 && findings.length > 0,
+        fix: 'Run "odori graph" for the full report.',
+      });
+    } catch (error) {
+      checks.push({
+        name: "Structure",
+        detail: error instanceof Error ? error.message : String(error),
+        ok: false,
+        fix: "A video entry failed to load. Open the file the message names.",
+      });
+    }
+  }
+
   // A missing provider key is not a broken project — generation is optional —
   // but doctor is exactly where "why does --generate fail" gets answered.
   for (const provider of Object.values(musicProviders)) {

package/src/commands/exportVideo.ts

@@ -158,6 +158,8 @@ export const exportCommand = async (
     format?: string;
     /** False writes the picture with no audio track. */
     audio?: boolean;
+    /** A declared audio variant to voice this export with. */
+    audioVariant?: string;
     /** True draws on the machine's GPU instead of the reproducible backend. */
     fast?: boolean;
     skipUnchangedFrames?: boolean;
@@ -176,7 +178,21 @@ export const exportCommand = async (
       ? await readJob(config, options.retry)
       : await (async () => {
           const video = findVideo(videos, id);
-          const compiled = await compileInBrowser(server.url, targetFor(video, options.input), config);
+          if (options.audioVariant) {
+            const declared = Object.keys(video.entry.metadata.audio?.variants ?? {});
+            if (!declared.includes(options.audioVariant)) {
+              throw new Error(
+                declared.length
+                  ? `No audio variant named "${options.audioVariant}". Declared: ${declared.join(", ")}.`
+                  : `"${id}" declares no audio variants; drop --audio-variant or add metadata.audio.variants.`,
+              );
+            }
+          }
+          const compiled = await compileInBrowser(
+            server.url,
+            targetFor(video, options.input, undefined, undefined, undefined, options.audioVariant),
+            config,
+          );
           const {manifest} = await freezeManifest(
             {...video, durationInFrames: compiled.durationInFrames},
             graph,
@@ -184,9 +200,12 @@ export const exportCommand = async (
             options.input ?? {},
             {scenes: compiled.scenes, audio: compiled.audio},
           );
+          // The variant names the file, so two voices cannot overwrite each
+          // other's exports.
+          const suffix = options.audioVariant ? `-${options.audioVariant}` : "";
           const output = resolve(
             config.root,
-            options.output ?? `${config.exportDir}/${outputName(id)}${format.extension}`,
+            options.output ?? `${config.exportDir}/${outputName(id)}${suffix}${format.extension}`,
           );
           return createJob(config, manifest, output, {
             format: format.name,