@dowel-ui/registry 0.1.0

package/src/build.ts

@@ -0,0 +1,206 @@
+import { readFileSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+import { blockMetas, componentMetas, type ComponentMeta } from "@dowel-ui/react/registry";
+
+import { hashContent } from "./hash";
+import {
+  REGISTRY_VERSION,
+  registryIndexSchema,
+  registryItemSchema,
+  type RegistryFile,
+  type RegistryIndexEntry,
+  type RegistryItem,
+} from "./schema";
+
+/**
+ * Emits the public registry.
+ *
+ * Everything the CLI installs originates here, from the same source files the
+ * library itself builds and tests. There is no second copy of a component to
+ * drift out of sync.
+ */
+
+const here = dirname(fileURLToPath(import.meta.url));
+const uiSrc = join(here, "..", "..", "ui", "src");
+const themesSrc = join(here, "..", "..", "themes", "src");
+const uiPackageJson = JSON.parse(
+  readFileSync(join(here, "..", "..", "ui", "package.json"), "utf8"),
+) as { name: string; version: string };
+
+function read(path: string): string {
+  return readFileSync(path, "utf8");
+}
+
+/**
+ * Turns a meta into a registry item.
+ *
+ * Components and blocks differ only in where their source lives and where it is
+ * installed, so one function covers both rather than two that drift.
+ */
+function buildSourceItem(meta: ComponentMeta): RegistryItem {
+  const isBlock = meta.kind === "block";
+  const sourceDir = join(uiSrc, isBlock ? "blocks" : "components", meta.name);
+  const group = isBlock ? "blocks" : "ui";
+  const fileType = isBlock ? "registry:block" : "registry:ui";
+
+  const files: RegistryFile[] = meta.files.map((file) => {
+    const content = read(join(sourceDir, file));
+    return {
+      path: `${group}/${file}`,
+      type: fileType,
+      content,
+      hash: hashContent(content),
+    };
+  });
+
+  return registryItemSchema.parse({
+    $schema: "./schema/registry-item.json",
+    registryVersion: REGISTRY_VERSION,
+    name: meta.name,
+    type: fileType,
+    title: meta.title,
+    description: meta.description,
+    category: meta.category,
+    status: meta.status,
+    dependencies: meta.dependencies,
+    registryDependencies: meta.registryDependencies,
+    files,
+    a11y: meta.a11y,
+  });
+}
+
+/**
+ * The utilities every component imports.
+ *
+ * Written by `init` rather than by `add`, because a project needs them before
+ * the first component and every component assumes they are present.
+ */
+function buildUtilsItem(): RegistryItem {
+  const files: RegistryFile[] = (["utils.ts", "styles.ts"] as const).map((file) => {
+    const content = read(join(uiSrc, "lib", file));
+    return {
+      path: `lib/${file}`,
+      type: "registry:lib",
+      content,
+      hash: hashContent(content),
+    };
+  });
+
+  return registryItemSchema.parse({
+    registryVersion: REGISTRY_VERSION,
+    name: "utils",
+    type: "registry:lib",
+    title: "Utilities",
+    description:
+      "The cn() class merger and the shared interaction-state fragments every component uses.",
+    category: "foundation",
+    status: "stable",
+    dependencies: ["clsx", "tailwind-merge"],
+    registryDependencies: [],
+    files,
+  });
+}
+
+/**
+ * The design tokens, as CSS to append to the project stylesheet.
+ *
+ * Appended rather than imported from a package: a consumer who cannot edit the
+ * tokens does not really own their design system, which is the whole premise.
+ */
+function buildThemeItem(): RegistryItem {
+  const content = [
+    "/* Design tokens. Safe to edit — this is your copy. */",
+    read(join(themesSrc, "tokens.css")),
+    read(join(themesSrc, "base.css")),
+  ].join("\n\n");
+
+  return registryItemSchema.parse({
+    registryVersion: REGISTRY_VERSION,
+    name: "theme",
+    type: "registry:theme",
+    title: "Theme",
+    description:
+      "Design tokens: colour, radius, typography, elevation and motion, in light and dark.",
+    category: "foundation",
+    status: "stable",
+    dependencies: [],
+    registryDependencies: [],
+    files: [
+      {
+        path: "theme.css",
+        type: "registry:style",
+        content,
+        hash: hashContent(content),
+      },
+    ],
+  });
+}
+
+export function buildRegistry(): RegistryItem[] {
+  return [
+    buildUtilsItem(),
+    buildThemeItem(),
+    ...componentMetas.map(buildSourceItem),
+    ...blockMetas.map(buildSourceItem),
+  ];
+}
+
+export function buildIndex(items: RegistryItem[]) {
+  const entries: RegistryIndexEntry[] = items.map((item) => ({
+    name: item.name,
+    type: item.type,
+    title: item.title,
+    description: item.description,
+    category: item.category,
+    status: item.status,
+    dependencies: item.dependencies,
+    registryDependencies: item.registryDependencies,
+    fileCount: item.files.length,
+  }));
+
+  return registryIndexSchema.parse({
+    $schema: "./schema/registry-index.json",
+    registryVersion: REGISTRY_VERSION,
+    // The package version, not a timestamp: the same source must always produce
+    // byte-identical output, or every build shows as a change.
+    generatedFrom: `${uiPackageJson.name}@${uiPackageJson.version}`,
+    items: entries,
+  });
+}
+
+export function writeRegistry(outDir: string): { items: number; files: number } {
+  const items = buildRegistry();
+  const index = buildIndex(items);
+
+  rmSync(outDir, { recursive: true, force: true });
+  mkdirSync(outDir, { recursive: true });
+
+  writeFileSync(join(outDir, "index.json"), `${JSON.stringify(index, null, 2)}\n`);
+  for (const item of items) {
+    writeFileSync(join(outDir, `${item.name}.json`), `${JSON.stringify(item, null, 2)}\n`);
+  }
+
+  return {
+    items: items.length,
+    files: items.reduce((total, item) => total + item.files.length, 0),
+  };
+}
+
+// Run directly: `tsx src/build.ts [--out <dir>]`
+const invokedDirectly =
+  process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href;
+
+if (invokedDirectly) {
+  const outIndex = process.argv.indexOf("--out");
+  const outDir =
+    outIndex === -1
+      ? join(here, "..", "r")
+      : (process.argv[outIndex + 1] ?? join(here, "..", "r"));
+
+  const result = writeRegistry(outDir);
+  console.log(
+    `Registry written to ${outDir}: ${String(result.items)} items, ${String(result.files)} files.`,
+  );
+}

package/src/hash.ts

@@ -0,0 +1,12 @@
+import { createHash } from "node:crypto";
+
+/**
+ * Content hash used to detect local edits to an installed file.
+ *
+ * Line endings are normalised before hashing so a Windows checkout does not
+ * read as "every file modified", which would make `update` useless there.
+ */
+export function hashContent(content: string): string {
+  const normalised = content.replace(/\r\n/g, "\n");
+  return `sha256:${createHash("sha256").update(normalised, "utf8").digest("hex")}`;
+}

package/src/index.ts

@@ -0,0 +1,16 @@
+export { hashContent } from "./hash";
+export {
+  REGISTRY_VERSION,
+  registryFileSchema,
+  registryFileTypeSchema,
+  registryIndexEntrySchema,
+  registryIndexSchema,
+  registryItemSchema,
+  registryItemTypeSchema,
+  type RegistryFile,
+  type RegistryFileType,
+  type RegistryIndex,
+  type RegistryIndexEntry,
+  type RegistryItem,
+  type RegistryItemType,
+} from "./schema";

package/src/schema.ts

@@ -0,0 +1,106 @@
+import { z } from "zod";
+
+/**
+ * The public registry contract.
+ *
+ * This is the boundary between the library and every consumer's project, so it
+ * is validated on both sides: the build refuses to emit anything that does not
+ * satisfy it, and the CLI refuses to install anything that does not parse. A
+ * registry that serves malformed data breaks builds in someone else's
+ * repository, where it is hardest to diagnose.
+ */
+
+/** Bumped only for a breaking change to the shape below. */
+export const REGISTRY_VERSION = 1;
+
+export const registryFileTypeSchema = z.enum([
+  /** A component. Installed under the `ui` alias. */
+  "registry:ui",
+  /** A shared utility. Installed under the `lib` alias. */
+  "registry:lib",
+  /** A hook. Installed under the `hooks` alias. */
+  "registry:hook",
+  /** A whole page section. Installed under the `blocks` alias. */
+  "registry:block",
+  /** CSS appended to the project stylesheet rather than written as a file. */
+  "registry:style",
+]);
+
+export type RegistryFileType = z.infer<typeof registryFileTypeSchema>;
+
+export const registryItemTypeSchema = z.enum([
+  "registry:ui",
+  "registry:lib",
+  "registry:hook",
+  "registry:theme",
+  "registry:block",
+]);
+
+export type RegistryItemType = z.infer<typeof registryItemTypeSchema>;
+
+export const registryFileSchema = z.object({
+  /**
+   * Logical path within the registry, e.g. `ui/button.tsx`, `lib/utils.ts`.
+   *
+   * The leading segment selects which of the consumer's aliases the file is
+   * written under. The registry deliberately does not know the destination —
+   * that depends on a project layout it has never seen.
+   */
+  path: z.string().min(1),
+  type: registryFileTypeSchema,
+  content: z.string(),
+  /**
+   * `sha256:<hex>` of `content` as published.
+   *
+   * Recorded at install time so `update` can tell an untouched file from one
+   * the user has edited. This cannot be added later: an install that did not
+   * record a hash leaves no way to know what it originally wrote.
+   */
+  hash: z.string().regex(/^sha256:[0-9a-f]{64}$/),
+});
+
+export type RegistryFile = z.infer<typeof registryFileSchema>;
+
+export const registryItemSchema = z.object({
+  $schema: z.string().optional(),
+  registryVersion: z.literal(REGISTRY_VERSION),
+  name: z.string().regex(/^[a-z][a-z0-9-]*$/),
+  type: registryItemTypeSchema,
+  title: z.string().min(1),
+  description: z.string().min(10),
+  category: z.string().min(1),
+  status: z.enum(["stable", "beta", "experimental"]),
+  /** npm packages to install alongside the files. */
+  dependencies: z.array(z.string()),
+  /** Other registry items to install first. */
+  registryDependencies: z.array(z.string()),
+  files: z.array(registryFileSchema).min(1),
+  a11y: z.string().optional(),
+});
+
+export type RegistryItem = z.infer<typeof registryItemSchema>;
+
+export const registryIndexEntrySchema = registryItemSchema
+  .pick({
+    name: true,
+    type: true,
+    title: true,
+    description: true,
+    category: true,
+    status: true,
+    dependencies: true,
+    registryDependencies: true,
+  })
+  .extend({ fileCount: z.number().int().positive() });
+
+export type RegistryIndexEntry = z.infer<typeof registryIndexEntrySchema>;
+
+export const registryIndexSchema = z.object({
+  $schema: z.string().optional(),
+  registryVersion: z.literal(REGISTRY_VERSION),
+  /** Version of the package the registry was generated from. */
+  generatedFrom: z.string().min(1),
+  items: z.array(registryIndexEntrySchema),
+});
+
+export type RegistryIndex = z.infer<typeof registryIndexSchema>;