@odori/cli 0.0.11 → 0.0.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@odori/cli",
-  "version": "0.0.11",
+  "version": "0.0.12",
   "type": "module",
   "description": "The odori command line: discovery, Studio, component installation, stills, tests, and export jobs.",
   "license": "Apache-2.0",
@@ -8,7 +8,10 @@
     "odori": "./bin/odori.mjs"
   },
   "exports": {
-    ".": "./src/index.ts"
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
   },
   "files": [
     "bin",
@@ -16,23 +19,16 @@
     "src",
     "studio"
   ],
-  "scripts": {
-    "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.studio.json",
-    "build": "tsup",
-    "snapshot": "tsx scripts/snapshot.ts",
-    "verify:package": "tsx scripts/verify-package.ts",
-    "prepack": "pnpm snapshot && pnpm build && pnpm verify:package"
-  },
   "dependencies": {
     "@puppeteer/browsers": "3.2.0",
     "@vitejs/plugin-react": "5.1.2",
     "ffmpeg-static": "5.3.0",
-    "odori": "workspace:*",
     "react": "19.2.3",
     "react-dom": "19.2.3",
     "playwright-core": "1.55.0",
     "tsx": "4.20.5",
-    "vite": "7.3.0"
+    "vite": "7.3.0",
+    "odori": "0.0.12"
   },
   "devDependencies": {
     "@types/node": "22.19.0",
@@ -40,15 +36,16 @@
     "@types/react-dom": "19.2.3",
     "tsup": "^8.5.1",
     "typescript": "5.9.3",
-    "@odori/registry": "workspace:*"
+    "@odori/registry": "0.0.12"
   },
   "publishConfig": {
-    "access": "public",
-    "exports": {
-      ".": {
-        "types": "./dist/index.d.ts",
-        "import": "./dist/index.js"
-      }
-    }
+    "access": "public"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.studio.json",
+    "build": "tsup",
+    "snapshot": "tsx scripts/snapshot.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,6 +103,7 @@ 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"],
@@ -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>]
@@ -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;

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/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/graph.ts

@@ -0,0 +1,141 @@
+import {existsSync} from "node:fs";
+import {mkdir, writeFile} from "node:fs/promises";
+import {join, resolve} from "node:path";
+import {resolveEntryLayout} from "odori";
+import {log} from "../log";
+import {writeGenerated} from "../discovery";
+import {checkStructure, type StructureFinding} from "../structure";
+import {createContext} from "./shared";
+
+/**
+ * The whole project as one JSON document: what the filesystem declares,
+ * compiled and answered for. `catalog.json` is what discovery alone can say
+ * about the tree; this is what the tree says once every entry has actually
+ * been loaded — durations, formats, brands, variants, who uses what — plus
+ * every place the filesystem contract is almost met.
+ *
+ * The point is inspectability without execution. An agent, a CI step, or a
+ * teammate's script should be able to ask "what is in this project and is
+ * its shape sound" by reading one file, instead of importing modules or
+ * driving a browser. The videos themselves stay the source of truth; this is
+ * the tree's own testimony, written down where anything can read it.
+ */
+export type GraphArtifact = {
+  sourceHash: string;
+  generatedAt: string;
+  videos: Array<{
+    id: string;
+    title: string;
+    description?: string;
+    file: string;
+    format: {width: number; height: number; fps: number};
+    /** 0 when the composition's scenes decide, which only a browser can total. */
+    durationInFrames: number;
+    seconds: number | null;
+    brand: string;
+    tags: string[];
+    audioVariants: string[];
+    components: string[];
+    prepare: boolean;
+  }>;
+  components: Array<{name: string; file: string; usedBy: string[]}>;
+  brands: Array<{name: string; file: string}>;
+  audio: Array<{name: string; url: string; file: string; bytes: number}>;
+  categories: Array<{path: string; name?: string; order?: number}>;
+  findings: StructureFinding[];
+};
+
+export const buildGraphArtifact = async (root = process.cwd()): Promise<{artifact: GraphArtifact; outDir: string}> => {
+  const {config, graph, videos} = await createContext(root);
+  // The compiled artifacts stay a set: refreshing the graph refreshes the
+  // static imports and the discovery catalog beside it, before the checks
+  // run, so this command never reports a staleness it just repaired.
+  await writeGenerated(config, graph);
+  const findings = await checkStructure(config, graph, videos);
+
+  const slugOf = new Map(graph.videos.map((video) => [video.file, video.slug]));
+  const artifact: GraphArtifact = {
+    sourceHash: graph.sourceHash,
+    generatedAt: new Date().toISOString(),
+    videos: videos.map((video) => {
+      const layout = resolveEntryLayout(video.entry);
+      const slug = slugOf.get(video.file) ?? video.entry.metadata.id;
+      return {
+        id: video.entry.metadata.id,
+        title: video.entry.metadata.title,
+        ...(video.entry.metadata.description ? {description: video.entry.metadata.description} : {}),
+        file: video.relativeFile,
+        format: {width: layout.format.width, height: layout.format.height, fps: layout.format.fps},
+        durationInFrames: video.durationInFrames,
+        seconds: video.durationInFrames ? Number((video.durationInFrames / layout.format.fps).toFixed(2)) : null,
+        brand: layout.brand.name,
+        tags: video.entry.metadata.tags ?? [],
+        audioVariants: Object.keys(video.entry.metadata.audio?.variants ?? {}),
+        components: graph.previews
+          .filter((preview) => preview.usedBy?.includes(slug))
+          .map((preview) => preview.name)
+          .sort(),
+        prepare: existsSync(resolve(video.file, "..", "prepare.ts")),
+      };
+    }),
+    components: graph.previews.map((preview) => ({
+      name: preview.name,
+      file: preview.relativeFile,
+      usedBy: preview.usedBy ?? [],
+    })),
+    brands: graph.brands.map((brand) => ({name: brand.name, file: brand.relativeFile})),
+    audio: graph.audio.map((entry) => ({
+      name: entry.name,
+      url: entry.url,
+      file: entry.relativeFile,
+      bytes: entry.bytes,
+    })),
+    categories: graph.categories,
+    findings,
+  };
+
+  const outDir = resolve(config.root, config.outDir);
+  await mkdir(outDir, {recursive: true});
+  await writeFile(join(outDir, "graph.json"), `${JSON.stringify(artifact, null, 2)}\n`, "utf8");
+  return {artifact, outDir};
+};
+
+export const graphCommand = async (options: {json?: boolean} = {}): Promise<number> => {
+  const {artifact} = await buildGraphArtifact();
+  const errors = artifact.findings.filter((finding) => finding.level === "error");
+
+  if (options.json === true) {
+    log.info(JSON.stringify(artifact, null, 2));
+    return errors.length === 0 ? 0 : 1;
+  }
+
+  log.title(`${artifact.videos.length} video${artifact.videos.length === 1 ? "" : "s"}`);
+  for (const video of artifact.videos) {
+    const duration = video.seconds === null ? "duration from scenes" : `${video.seconds}s`;
+    const extras = [
+      video.audioVariants.length > 0 ? `audio: ${video.audioVariants.join(", ")}` : "",
+      video.components.length > 0 ? `components: ${video.components.join(", ")}` : "",
+      video.prepare ? "prepare.ts" : "",
+    ].filter(Boolean);
+    log.info(`  ${video.id}  ${video.format.width}x${video.format.height}  ${duration}  ${video.brand}`);
+    if (extras.length > 0) log.detail(`    ${extras.join("  ·  ")}`);
+  }
+
+  if (artifact.components.length > 0) {
+    log.title(`${artifact.components.length} component${artifact.components.length === 1 ? "" : "s"}`);
+    for (const component of artifact.components) {
+      log.info(`  ${component.name}${component.usedBy.length > 0 ? `  used by ${component.usedBy.join(", ")}` : ""}`);
+    }
+  }
+  if (artifact.audio.length > 0) log.title(`${artifact.audio.length} audio file${artifact.audio.length === 1 ? "" : "s"}`);
+  for (const entry of artifact.audio) log.info(`  ${entry.url}  ${(entry.bytes / 1024).toFixed(0)} KB`);
+
+  if (artifact.findings.length > 0) log.title("Structure");
+  for (const finding of artifact.findings) {
+    const say = finding.level === "error" ? log.error : log.warn;
+    say(`${finding.file}: ${finding.message}`);
+  }
+
+  log.detail(`Wrote .odori/graph.json (source ${artifact.sourceHash.slice(0, 12)})`);
+  return errors.length === 0 ? 0 : 1;
+};

package/src/commands/test.ts

@@ -2,6 +2,7 @@ import {isOdoriSchema, resolveEntryLayout} from "odori";
 import {log} from "../log";
 import {openRenderPage, readAudio, readTimeline, seekTo} from "../render";
 import {checkAudioWindows, checkInstalledContracts} from "../contracts";
+import {checkStructure} from "../structure";
 import {checkDeterminism} from "../determinism";
 import {createContext, targetFor, withServer} from "./shared";
 import type {LoadedVideo} from "../project";
@@ -309,7 +310,7 @@ const testVideo = async (
 };
 
 export const testCommand = async (id?: string, options: {json?: boolean} = {}) => {
-  const {config, videos} = await createContext();
+  const {config, graph, videos} = await createContext();
   const selected = id ? videos.filter((video) => video.entry.metadata.id === id) : videos;
   if (selected.length === 0) throw new Error(id ? `Unknown video "${id}".` : "No videos discovered.");
 
@@ -318,6 +319,14 @@ export const testCommand = async (id?: string, options: {json?: boolean} = {}) =
   // about the project, not about a frame.
   failures.push(...(await checkInstalledContracts(config, selected)));
 
+  // The filesystem contract next, still before a browser: a referenced sound
+  // with no file behind it fails here as a fact about the tree, instead of
+  // surfacing as unexplained silence in an export. Warnings stay doctor's
+  // business; a test only fails on a promise the project breaks.
+  for (const finding of await checkStructure(config, graph, videos)) {
+    if (finding.level === "error") failures.push({video: finding.file, message: finding.message});
+  }
+
   // So is a wall clock in a composition. It would render fine here and differ
   // on the next machine, which is the failure mode a test is for.
   for (const finding of await checkDeterminism(config)) {