@odori/cli 0.0.2

package/src/registry-source.ts

@@ -0,0 +1,269 @@
+import {createHash} from "node:crypto";
+import {existsSync} from "node:fs";
+import {mkdir, readFile, writeFile} from "node:fs/promises";
+import {dirname, resolve} from "node:path";
+import {cacheRoot} from "./binaries";
+import type {ResolvedConfig} from "./config";
+
+/**
+ * Where components come from.
+ *
+ * They used to come from a dependency, which meant a new component required a
+ * new CLI. The registry is the product, so it is fetched from where it is
+ * published and cached beside the pinned binaries — one download per machine,
+ * outside any project.
+ *
+ * Resolution has three steps and reports which one answered, because "why is
+ * this component missing" and "why is this component old" have the same
+ * symptom and different fixes:
+ *
+ *   network → cache → the snapshot built into this package
+ *
+ * The snapshot is the floor. A machine with no network, a locked-down runner,
+ * and a first run behind a proxy all still install something, and `odori test`
+ * never reaches for the network at all.
+ */
+
+/**
+ * The shape of a registry entry, defined here rather than imported.
+ *
+ * `@odori/registry` is a development dependency: it generates the snapshot at
+ * build time and is not installed alongside the published CLI. Importing even
+ * a type from it is fine, but importing a *value* would leave a bare import in
+ * the bundle that no consumer can resolve, so the boundary is drawn at the
+ * package: the CLI describes what it reads, and the generator produces it.
+ */
+export type ComponentContract = {
+  aspectRatios: string[];
+  recommendedDurationInFrames: number;
+  minimumDurationInFrames: number;
+  entranceFrames: number;
+  exitFrames: number;
+  contentLimits: Record<string, number>;
+  reducedMotion: string;
+  requires: {fonts: string[]; audio: string[]};
+  /** Cues only: whether the score is one repeatable phrase. */
+  loops?: boolean;
+};
+
+export type RegistryKind = "component" | "cue";
+
+export type RegistryComponent = {
+  name: string;
+  /** Components render pixels. Cues render samples. Both install as source. */
+  kind?: RegistryKind;
+  /** Present on cues: the brand name it registers, and the factory to call. */
+  cue?: {name: string; export: string};
+  namespaced: string;
+  family: string;
+  description: string;
+  files: string[];
+  registryDependencies: string[];
+  contract: ComponentContract;
+};
+
+/** `@odori/title-reveal` and `title-reveal` name the same component. */
+export const normalizeComponentName = (name: string): string => name.replace(/^@odori\//, "");
+
+export type RegistryOrigin = "network" | "cache" | "bundled";
+
+export type RegistrySource = {
+  items: RegistryComponent[];
+  origin: RegistryOrigin;
+  /** Where it came from, for `odori registry` and for an error message. */
+  detail: string;
+};
+
+/** A published item document, which is shadcn's shape plus our `meta`. */
+type RegistryItemDocument = {
+  name: string;
+  title?: string;
+  description?: string;
+  registryDependencies?: string[];
+  files: Array<{path: string; content: string; target: string}>;
+  meta?: {
+    kind?: string;
+    family?: string;
+    namespaced?: string;
+    contract?: RegistryComponent["contract"];
+    cue?: {name: string; export: string};
+    integrity?: string;
+  };
+};
+
+const DEFAULT_URL = "https://odori.dev/r/v1";
+
+export const registryUrl = (config: ResolvedConfig): string =>
+  (config.registryUrl ?? process.env.ODORI_REGISTRY ?? DEFAULT_URL).replace(/\/$/, "");
+
+/** One directory per origin URL, so two registries never share a cache. */
+const cacheDir = (url: string): string =>
+  resolve(cacheRoot(), "registry", createHash("sha256").update(url).digest("hex").slice(0, 16));
+
+/**
+ * The index, as the CLI's own type.
+ *
+ * A published item is a superset of what a registry row used to be, so the
+ * mapping is mechanical — everything the CLI needs is either at the top level
+ * or in `meta`, which is exactly why `meta` was used rather than a parallel
+ * document.
+ */
+const toComponent = (item: RegistryItemDocument): RegistryComponent => ({
+  name: item.name,
+  namespaced: item.meta?.namespaced ?? `@odori/${item.name}`,
+  kind: (item.meta?.kind as RegistryComponent["kind"]) ?? "component",
+  ...(item.meta?.cue ? {cue: item.meta.cue} : {}),
+  family: item.meta?.family ?? "Uncategorized",
+  description: item.description ?? "",
+  files: item.files.map((file) => file.path.split("/").pop() ?? file.path),
+  registryDependencies: item.registryDependencies ?? [],
+  contract: item.meta?.contract as RegistryComponent["contract"],
+});
+
+/**
+ * The snapshot compiled into this package. Generated; see scripts/snapshot.ts.
+ *
+ * Loaded through `unknown` because TypeScript reads the JSON's literal shape,
+ * which is narrower than the document type it satisfies.
+ */
+const snapshotItems = async (): Promise<RegistryItemDocument[]> => {
+  try {
+    const loaded = (await import("./registry-snapshot.json", {with: {type: "json"}})) as unknown as {
+      default: {items: RegistryItemDocument[]};
+    };
+    return loaded.default.items;
+  } catch {
+    // Committed, and regenerated by `pnpm snapshot`. Reaching this means the
+    // network and the cache both failed too, so say all three rather than
+    // letting a module-resolution stack stand in for the explanation.
+    throw new Error(
+      "No registry available: the network and the cache both failed, and this CLI has no snapshot built into it. " +
+        "Run `pnpm snapshot` in packages/odori-cli, or set registryUrl to a reachable registry.",
+    );
+  }
+};
+
+const bundled = async (): Promise<RegistryComponent[]> => (await snapshotItems()).map(toComponent);
+
+const fetchJson = async (url: string, timeoutMs = 8000): Promise<unknown> => {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const response = await fetch(url, {signal: controller.signal, headers: {accept: "application/json"}});
+    if (!response.ok) throw new Error(`${response.status} ${response.statusText}`);
+    return await response.json();
+  } finally {
+    clearTimeout(timer);
+  }
+};
+
+/**
+ * The registry, from the best source available.
+ *
+ * `allowNetwork` is false for anything that validates a project rather than
+ * changing it. `odori test` must not depend on a connection to tell you
+ * whether your video is correct.
+ */
+export const resolveRegistry = async (
+  config: ResolvedConfig,
+  options: {allowNetwork?: boolean} = {},
+): Promise<RegistrySource> => {
+  const url = registryUrl(config);
+  const cache = resolve(cacheDir(url), "registry.json");
+
+  if (options.allowNetwork !== false) {
+    try {
+      const index = (await fetchJson(`${url}/registry.json`)) as {items: RegistryItemDocument[]};
+      if (!Array.isArray(index.items)) throw new Error("the index has no items array");
+      await mkdir(dirname(cache), {recursive: true});
+      await writeFile(cache, JSON.stringify(index), "utf8");
+      return {items: index.items.map(toComponent), origin: "network", detail: url};
+    } catch {
+      // Fall through. A registry that is unreachable is not an error until
+      // there is also nothing cached and nothing bundled.
+    }
+  }
+
+  if (existsSync(cache)) {
+    try {
+      const index = JSON.parse(await readFile(cache, "utf8")) as {items: RegistryItemDocument[]};
+      return {items: index.items.map(toComponent), origin: "cache", detail: cache};
+    } catch {
+      // A corrupt cache is a cache miss, not a failure.
+    }
+  }
+
+  return {items: await bundled(), origin: "bundled", detail: "the copy built into this CLI"};
+};
+
+/**
+ * One item, with its file contents.
+ *
+ * The index deliberately omits contents — inlining every component's source
+ * would make it a megabyte to answer "what is available" — so installing
+ * fetches the item document, and falls back to the snapshot when it cannot.
+ */
+export const resolveItem = async (
+  config: ResolvedConfig,
+  name: string,
+  options: {allowNetwork?: boolean} = {},
+): Promise<{item: RegistryItemDocument; origin: RegistryOrigin}> => {
+  const url = registryUrl(config);
+  const cache = resolve(cacheDir(url), `${name}.json`);
+
+  if (options.allowNetwork !== false) {
+    try {
+      const item = (await fetchJson(`${url}/${name}.json`)) as RegistryItemDocument;
+      if (item?.name !== name) throw new Error(`the document at ${url}/${name}.json is for "${item?.name}"`);
+      await mkdir(dirname(cache), {recursive: true});
+      await writeFile(cache, JSON.stringify(item), "utf8");
+      return {item, origin: "network"};
+    } catch {
+      // As above: try the disk before giving up.
+    }
+  }
+
+  if (existsSync(cache)) {
+    try {
+      return {item: JSON.parse(await readFile(cache, "utf8")) as RegistryItemDocument, origin: "cache"};
+    } catch {
+      // Corrupt cache, treated as absent.
+    }
+  }
+
+  const item = (await snapshotItems()).find((entry) => entry.name === name);
+  if (!item) throw new Error(`No component named "${name}" in the registry at ${url}, in the cache, or in this CLI.`);
+  return {item, origin: "bundled"};
+};
+
+/**
+ * Recompute the hash the registry published and compare.
+ *
+ * This is what makes fetching source over the network defensible: the bytes
+ * about to be written are the bytes the registry said it was serving. It is
+ * not a signature — a compromised origin can publish a matching hash — but it
+ * catches truncation, a stale proxy, and a corrupted cache, which are the
+ * failures that actually happen.
+ */
+export const verifyIntegrity = (item: RegistryItemDocument): void => {
+  const expected = item.meta?.integrity;
+  if (!expected) return;
+
+  const hash = createHash("sha256");
+  for (const file of [...item.files].sort((left, right) => left.path.localeCompare(right.path))) {
+    hash.update(file.path);
+    hash.update("\0");
+    hash.update(file.content);
+    hash.update("\0");
+  }
+  const actual = `sha256-${hash.digest("base64")}`;
+  if (actual === expected) return;
+
+  throw new Error(
+    `The files for "${item.name}" do not match the hash the registry published.\n` +
+      `  expected ${expected}\n  received ${actual}\n` +
+      "Nothing was written. This is a truncated download, a stale proxy, or a tampered document.",
+  );
+};
+
+export type {RegistryItemDocument};