@odori/cli 0.0.3 → 0.0.5

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

@@ -3,6 +3,7 @@ import {existsSync} from "node:fs";
 import {join, relative, resolve, sep} from "node:path";
 import {hashString} from "odori";
 import type {ResolvedConfig} from "./config";
+import {log} from "./log";
 
 export type DiscoveredVideo = {
   /** Directory-derived id used before the module is loaded. */
@@ -19,6 +20,8 @@ export type DiscoveredPreview = {
   relativeFile: string;
   importPath: string;
   identifier: string;
+  /** Video ids whose composition imports this component. Derived, not declared. */
+  usedBy?: string[];
 };
 
 export type DiscoveredBrandModule = {
@@ -37,11 +40,26 @@ export type DiscoveredAudio = {
   bytes: number;
 };
 
+/**
+ * A directory naming itself, from a `category.json` beside the components it
+ * holds. The path is what the filesystem already says; this is only how that
+ * level should read and where it should sit among its siblings.
+ */
+export type DiscoveredCategory = {
+  /** Directory path under the components directory: `product-ui/forms`. */
+  path: string;
+  /** What to call it. Without one, the directory name is read as words. */
+  name?: string;
+  /** Sort position among siblings. Unset sorts after, alphabetically. */
+  order?: number;
+};
+
 export type ProjectGraph = {
   videos: DiscoveredVideo[];
   previews: DiscoveredPreview[];
   brands: DiscoveredBrandModule[];
   audio: DiscoveredAudio[];
+  categories: DiscoveredCategory[];
   sourceHash: string;
 };
 
@@ -107,7 +125,9 @@ export const discoverProject = async (config: ResolvedConfig): Promise<ProjectGr
   const videos: DiscoveredVideo[] = [];
   const previews: DiscoveredPreview[] = [];
   const brands: DiscoveredBrandModule[] = [];
+  const categories: DiscoveredCategory[] = [];
   const hashParts: string[] = [];
+  const importedBy: Record<string, Set<string>> = {};
   const componentsRoot = resolve(config.root, config.componentsDir);
 
   for (const file of files) {
@@ -119,6 +139,38 @@ export const discoverProject = async (config: ResolvedConfig): Promise<ProjectGr
     }
 
     const base = file.split(sep).pop() ?? "";
+    if (base === "category.json") {
+      // Beside the components it holds, so a label lives with the thing it
+      // labels. A malformed one is reported and skipped: a typo in a display
+      // name must not take the project down.
+      const path = relative(componentsRoot, resolve(file, "..")).split(sep).join("/");
+      if (!path.startsWith("..")) {
+        try {
+          const declared = JSON.parse(contents) as {name?: unknown; order?: unknown};
+          categories.push({
+            path,
+            ...(typeof declared.name === "string" ? {name: declared.name} : {}),
+            ...(typeof declared.order === "number" ? {order: declared.order} : {}),
+          });
+        } catch (error) {
+          log.warn(
+            `${relativeFile} is not valid JSON, so that directory names itself: ${
+              error instanceof Error ? error.message : String(error)
+            }`,
+          );
+        }
+      }
+    }
+
+    if (base === "video.tsx") {
+      // The file is already read for the source hash, so the import graph
+      // costs nothing to take. A component's audience is a fact about the
+      // project rather than something an author should have to restate, and
+      // a restated one goes stale the moment a scene is deleted.
+      for (const match of contents.matchAll(/from\s+["'][^"']*\/components\/([^/"']+)\//g)) {
+        (importedBy[match[1]] ??= new Set()).add(relative(videosRoot, file).replace(/\/?video\.tsx$/, "") || "video");
+      }
+    }
     if (base === "video.tsx") {
       // The path under videos/ is the id, the way a route is a path.
       const slug = relative(videosRoot, file).replace(/\/?video\.tsx$/, "").split(sep).join("/") || "video";
@@ -166,7 +218,12 @@ export const discoverProject = async (config: ResolvedConfig): Promise<ProjectGr
     }
   }
 
-  return {videos, previews, brands, audio, sourceHash: hashString(hashParts.join("|"))};
+  for (const preview of previews) {
+    const users = importedBy[preview.name];
+    if (users) preview.usedBy = [...users].sort();
+  }
+
+  return {videos, previews, brands, audio, categories, sourceHash: hashString(hashParts.join("|"))};
 };
 
 /**
@@ -222,7 +279,11 @@ export const writeGenerated = async (config: ResolvedConfig, graph: ProjectGraph
       {
         sourceHash: graph.sourceHash,
         videos: graph.videos.map((video) => ({slug: video.slug, file: video.relativeFile})),
-        previews: graph.previews.map((preview) => ({name: preview.name, file: preview.relativeFile})),
+        previews: 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})),
       },

package/src/index.ts

@@ -46,7 +46,7 @@ export {clearPrepareCache, prepareCacheKey, readPrepareCache, writePrepareCache}
 export {devCommand} from "./commands/dev";
 export {cancelJob, exportCommand, jobsCommand, runJob, exportQueue} from "./commands/exportVideo";
 export {chunkFrames, planChunks, type ChunkPlan, type FrameChunk} from "./chunks";
-export {stillCommand} from "./commands/still";
+export {frameCommand} from "./commands/frame";
 export {testCommand} from "./commands/test";
 export {listCommand} from "./commands/list";
 export {inspectCommand} from "./commands/inspect";

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};