@odori/cli 0.0.4 → 0.0.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@odori/cli",
-  "version": "0.0.4",
+  "version": "0.0.5",
   "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.4"
+    "odori": "0.0.5"
   },
   "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.4"
+    "@odori/registry": "0.0.5"
   },
   "publishConfig": {
     "access": "public"

package/src/cli.ts

@@ -15,6 +15,19 @@ import {testCommand} from "./commands/test";
 
 type Flags = Record<string, string | boolean>;
 
+/**
+ * Flags that are on or off, and therefore never take the next word.
+ *
+ * Without this list `odori add --force title-reveal` reads "force" as the
+ * string "title-reveal": the flag does nothing and the component quietly
+ * vanishes from the list, which is two failures for the price of one and
+ * neither of them says anything. A switch has no value to take.
+ */
+const BOOLEAN_FLAGS = new Set(["force", "dry-run", "json", "no-audio", "no-frame-skip", "no-open", "open", "help", "version"]);
+
+/** Commands that used to exist under another name. */
+const RENAMED: Record<string, string> = {still: "frame"};
+
 export const parseArgs = (argv: string[]): {command: string; positionals: string[]; flags: Flags} => {
   const [command = "help", ...rest] = argv;
   const positionals: string[] = [];
@@ -31,7 +44,7 @@ export const parseArgs = (argv: string[]): {command: string; positionals: string
       }
       const name = token.slice(2);
       const next = rest[index + 1];
-      if (next === undefined || next.startsWith("--")) flags[name] = true;
+      if (BOOLEAN_FLAGS.has(name) || next === undefined || next.startsWith("--")) flags[name] = true;
       else {
         flags[name] = next;
         index += 1;
@@ -86,7 +99,7 @@ const COMMAND_FLAGS: Record<string, string[]> = {
   inspect: ["json", "input"],
   frame: ["at", "output", "input"],
   test: ["json"],
-  export: ["output", "input", "concurrency", "preset", "format", "quality", "scale", "no-frame-skip", "retry"],
+  export: ["output", "input", "concurrency", "preset", "format", "quality", "scale", "no-audio", "no-frame-skip", "retry"],
   jobs: [],
   help: [],
 };
@@ -168,11 +181,12 @@ 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-frame-skip] [--retry <job>]
+             [--no-audio] [--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,
-  0.25 to 2. A retry keeps the settings its job was created with.`,
+  0.25 to 2. --no-audio writes the picture with no sound. A retry keeps the
+  settings its job was created with.`,
   jobs: `odori jobs
   List export jobs and their status.`,
 };
@@ -302,6 +316,7 @@ export const run = async (argv: string[]): Promise<number> => {
           quality: typeof flags.quality === "string" ? flags.quality : undefined,
           scale: numberFlag(flags, "scale"),
           format: typeof flags.format === "string" ? flags.format : undefined,
+          audio: flags["no-audio"] === true ? false : undefined,
           skipUnchangedFrames: flags["no-frame-skip"] === true ? false : undefined,
           retry: typeof flags.retry === "string" ? flags.retry : undefined,
         });
@@ -315,6 +330,13 @@ export const run = async (argv: string[]): Promise<number> => {
         log.info(HELP);
         return 0;
       default: {
+        // A rename is not a typo, and edit distance will never connect the old
+        // name to the new one. Say what happened instead of listing everything.
+        const renamed = RENAMED[command];
+        if (renamed) {
+          log.error(`"odori ${command}" is now "odori ${renamed}".`);
+          return 1;
+        }
         const commands = Object.keys(COMMAND_FLAGS).filter((name) => name !== "help");
         const suggestion = nearest(command, commands);
         log.error(`Unknown command "${command}".${suggestion ? ` Did you mean "odori ${suggestion}"?` : ""}`);

package/src/commands/add.ts

@@ -30,6 +30,10 @@ export const addCommand = async (names: string[], options: {force?: boolean; dry
 
   const queue = [...names.map(normalizeComponentName)];
   const installed: string[] = [];
+  /* Kept so the summary can repeat itself at the end. Installing a library is
+     hundreds of lines of output, and a warning at line 40 is a warning nobody
+     read. */
+  const kept: string[] = [];
 
   while (queue.length > 0) {
     const name = queue.shift()!;
@@ -103,7 +107,8 @@ export const addCommand = async (names: string[], options: {force?: boolean; dry
         const current = hashString(await readFile(destination, "utf8"));
         const recorded = provenance[component.name]?.hashes[name];
         if (current !== recorded) {
-          log.warn(`${relative(config.root, destination)} was modified locally. Keeping your version. Use --force to replace it.`);
+          log.warn(`${relative(config.root, destination)} was modified locally. Keeping your version.`);
+          kept.push(relative(config.root, destination));
           continue;
         }
       }
@@ -147,6 +152,12 @@ export const addCommand = async (names: string[], options: {force?: boolean; dry
     return;
   }
   await writeProvenance(config, provenance);
+
+  if (kept.length > 0) {
+    log.warn(`Kept ${kept.length} locally modified ${kept.length === 1 ? "file" : "files"}:`);
+    for (const file of kept) log.detail(`  ${file}`);
+    log.detail(`Run odori diff to see what upstream changed, or odori add <name> --force to replace them.`);
+  }
   log.detail("Run odori dev to preview the installed component fixtures.");
 };
 

package/src/commands/dev.ts

@@ -174,7 +174,10 @@ export const devCommand = async (options: {port?: number; root?: string; open?:
                 exportDestination(config),
                 `${outputName(video.entry.metadata.id)}${format.extension}`,
               );
-              const record = await createJob(config, manifest, output, {format: format.name, quality, scale});
+              // Frozen with the job: a retry from the CLI has to produce the
+              // same file, silence included.
+              const audio = body.audio !== false;
+              const record = await createJob(config, manifest, output, {format: format.name, quality, scale, audio});
               json(response, 202, record.job);
 
               void runJob(config, origin, record, video).catch((error) => {

package/src/commands/exportVideo.ts

@@ -36,6 +36,7 @@ export const runJob = async (
     quality?: Quality;
     scale?: number;
     format?: VideoFormat;
+    audio?: boolean;
     skipUnchangedFrames?: boolean;
     signal?: AbortSignal;
     onProgress?: (job: ExportJob) => void;
@@ -94,6 +95,7 @@ export const runJob = async (
           quality: options.quality ?? (record.render?.quality as Quality | undefined),
           scale: options.scale ?? record.render?.scale,
           format: options.format ?? (record.render?.format ? resolveFormat(record.render.format, record.output) : undefined),
+          audio: options.audio ?? record.render?.audio,
           skipUnchangedFrames: options.skipUnchangedFrames,
           signal: controller.signal,
           onTimings: (timings) => {
@@ -151,6 +153,8 @@ export const exportCommand = async (
     quality?: string;
     scale?: number;
     format?: string;
+    /** False writes the picture with no audio track. */
+    audio?: boolean;
     skipUnchangedFrames?: boolean;
     retry?: string;
   } = {},
@@ -183,6 +187,7 @@ export const exportCommand = async (
             format: format.name,
             quality,
             scale,
+            audio: options.audio !== false,
             ...(options.preset ? {preset: options.preset} : {}),
           });
         })();
@@ -201,6 +206,7 @@ export const exportCommand = async (
       quality: options.retry && options.quality === undefined ? undefined : quality,
       scale: options.retry && options.scale === undefined ? undefined : scale,
       format: options.retry ? undefined : format,
+      audio: options.audio,
       skipUnchangedFrames: options.skipUnchangedFrames,
       onProgress: (next) => {
         if (next.status === "rendering" || next.status === "encoding") {

package/src/commands/update.ts

@@ -1,5 +1,6 @@
-import {mkdir, readFile, writeFile} from "node:fs/promises";
+import {mkdir, readFile, rm, writeFile} from "node:fs/promises";
 import {existsSync} from "node:fs";
+import {readdir} from "node:fs/promises";
 import {relative, resolve} from "node:path";
 import {hashString} from "odori";
 import {loadConfig, type ResolvedConfig} from "../config";
@@ -28,17 +29,45 @@ export type ComponentStatus = {
   }>;
 };
 
-const provenanceFile = (config: ResolvedConfig) => resolve(config.root, config.outDir, "components.json");
+/**
+ * The record of what was installed, and at which version.
+ *
+ * It sits beside the config and is meant to be committed. It used to live in
+ * `outDir`, which is generated and gitignored, so it did not survive a clone
+ * or a cleared render cache: `odori update` and `odori diff` would report an
+ * empty project while the components sat right there in the tree, and the
+ * suggested fix - run `odori add` - was the one thing that had already been
+ * done. A lockfile is only useful to the next person if it is in the repo.
+ */
+export const LOCKFILE = "odori.lock.json";
+
+const provenanceFile = (config: ResolvedConfig) => resolve(config.root, LOCKFILE);
+
+/** Where it used to live, read once so an existing project keeps its history. */
+const legacyProvenanceFile = (config: ResolvedConfig) =>
+  resolve(config.root, config.outDir, "components.json");
 
 export const readProvenance = async (config: ResolvedConfig): Promise<Provenance> => {
-  const file = provenanceFile(config);
+  const file = existsSync(provenanceFile(config))
+    ? provenanceFile(config)
+    : legacyProvenanceFile(config);
   if (!existsSync(file)) return {};
-  return JSON.parse(await readFile(file, "utf8")) as Provenance;
+  try {
+    return JSON.parse(await readFile(file, "utf8")) as Provenance;
+  } catch {
+    // A truncated or hand-mangled lockfile should cost you the update, not the
+    // command: treat it as unknown and let the next install rewrite it.
+    log.warn(`${relative(config.root, file)} is not readable JSON. Ignoring it.`);
+    return {};
+  }
 };
 
 export const writeProvenance = async (config: ResolvedConfig, provenance: Provenance) => {
-  await mkdir(resolve(config.root, config.outDir), {recursive: true});
+  await mkdir(config.root, {recursive: true});
   await writeFile(provenanceFile(config), `${JSON.stringify(provenance, null, 2)}\n`, "utf8");
+  // Moved, not copied: leaving the old one behind means the next reader has to
+  // guess which of the two is current.
+  await rm(legacyProvenanceFile(config), {force: true});
 };
 
 /**
@@ -109,11 +138,33 @@ const LABELS: Record<ComponentState, string> = {
   missing: "files missing",
 };
 
+/**
+ * What to say when there is nothing to compare against.
+ *
+ * "Run odori add first" is the wrong advice if the components are already on
+ * disk: the missing piece is the lockfile, not the install, and telling
+ * somebody to do the thing they just did is how a tool loses their trust.
+ */
+const explainEmpty = async (config: ResolvedConfig, named: string[]) => {
+  if (named.length > 0) {
+    log.detail(`${named.join(", ")} ${named.length === 1 ? "is" : "are"} not recorded in ${LOCKFILE}.`);
+    return;
+  }
+  const components = resolve(config.root, config.componentsDir);
+  const installed = existsSync(components) ? (await readdir(components)).filter((e) => !e.startsWith(".")) : [];
+  if (installed.length === 0) {
+    log.detail("No registry components are installed yet. Run odori add first.");
+    return;
+  }
+  log.warn(`${installed.length} components are in ${config.componentsDir} but none are recorded in ${LOCKFILE}.`);
+  log.detail("Run odori add <name> to re-record them, or commit the lockfile if a teammate has one.");
+};
+
 export const diffCommand = async (names: string[], options: {full?: boolean} = {}) => {
   const config = await loadConfig(process.cwd());
   const statuses = await componentStatus(config, names.length > 0 ? names : undefined);
   if (statuses.length === 0) {
-    log.detail("No registry components are installed yet. Run odori add first.");
+    await explainEmpty(config, names);
     return;
   }
 
@@ -141,7 +192,7 @@ export const updateCommand = async (names: string[], options: {force?: boolean}
   const config = await loadConfig(process.cwd());
   const statuses = await componentStatus(config, names.length > 0 ? names : undefined);
   if (statuses.length === 0) {
-    log.detail("No registry components are installed yet. Run odori add first.");
+    await explainEmpty(config, names);
     return;
   }
 

package/src/jobs.ts

@@ -5,7 +5,7 @@ import type {ExportJob, RenderManifest} from "odori";
 import type {ResolvedConfig} from "./config";
 
 /** How a job should be encoded, frozen with it so a retry cannot drift. */
-export type JobRender = {format?: string; quality?: string; scale?: number; preset?: string};
+export type JobRender = {format?: string; quality?: string; scale?: number; preset?: string; audio?: boolean};
 
 export type JobRecord = {job: ExportJob; manifest: RenderManifest; output: string; render?: JobRender};