@jami-studio/registry-schema 0.1.0

package/src/index.mjs

@@ -0,0 +1,237 @@
+// @jami-studio/registry-schema
+//
+// Single source of truth for the Studio UI registry contract surface: the
+// registry item, the registryRef handshake, the resolved item graph, and the
+// workspace/theme reference shapes. Schemas are authored as JSON Schema 2020-12
+// and validated with AJV in strict mode so every consumer (the registry
+// generator, the CLI, the Husky pre-commit template validator, the Algolia
+// index sync, and the Jami Harness handshake mirror) checks against the exact
+// same rules.
+
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import Ajv2020 from "ajv/dist/2020.js";
+import Ajv from "ajv";
+import addFormats from "ajv-formats";
+import { findDuplicateJsonObjectKeys, formatDuplicateJsonObjectKeys } from "./json-source.mjs";
+
+const schemaDir = join(dirname(fileURLToPath(import.meta.url)), "schemas");
+
+function loadSchema(file) {
+  const source = readFileSync(join(schemaDir, file), "utf8");
+  const duplicates = findDuplicateJsonObjectKeys(source);
+  if (duplicates.length > 0) {
+    throw new Error(`${file} contains duplicate JSON object keys:\n- ${formatDuplicateJsonObjectKeys(duplicates).join("\n- ")}`);
+  }
+  return JSON.parse(source);
+}
+
+export const registryRefSchema = loadSchema("registry-ref.schema.json");
+export const agentManifestSchema = loadSchema("agent-manifest.schema.json");
+export const registryItemSchema = loadSchema("registry-item.schema.json");
+export const itemGraphSchema = loadSchema("item-graph.schema.json");
+export const workspaceRefSchema = loadSchema("workspace-ref.schema.json");
+export const themeRefSchema = loadSchema("theme-ref.schema.json");
+export const workbenchStateSchema = loadSchema("workbench-state.schema.json");
+export const shadcnRegistryItemSchema = loadSchema("shadcn-registry-item.schema.json");
+
+export const schemas = Object.freeze({
+  registryRef: registryRefSchema,
+  agentManifest: agentManifestSchema,
+  registryItem: registryItemSchema,
+  itemGraph: itemGraphSchema,
+  workspaceRef: workspaceRefSchema,
+  themeRef: themeRefSchema,
+  workbenchState: workbenchStateSchema,
+});
+
+const schemaIds = Object.freeze({
+  registryRef: registryRefSchema.$id,
+  agentManifest: agentManifestSchema.$id,
+  registryItem: registryItemSchema.$id,
+  itemGraph: itemGraphSchema.$id,
+  workspaceRef: workspaceRefSchema.$id,
+  themeRef: themeRefSchema.$id,
+  workbenchState: workbenchStateSchema.$id,
+});
+
+export const agentManifestAllowedComponents = Object.freeze(
+  agentManifestSchema.properties.residentRenderer.properties.allowedComponents.const,
+);
+
+// A fresh strict 2020-12 AJV instance with every contract schema registered, so
+// `$ref`s between them (a registry item embedding a registryRef, a workspaceRef
+// listing installedItems) resolve without per-call wiring.
+export function createAjv(options = {}) {
+  const ajv = new Ajv2020({
+    strict: true,
+    allErrors: true,
+    allowUnionTypes: true,
+    ...options,
+  });
+  addFormats(ajv);
+  ajv.addSchema(registryRefSchema);
+  ajv.addSchema(agentManifestSchema);
+  ajv.addSchema(registryItemSchema);
+  ajv.addSchema(itemGraphSchema);
+  ajv.addSchema(workspaceRefSchema);
+  ajv.addSchema(themeRefSchema);
+  ajv.addSchema(workbenchStateSchema);
+  return ajv;
+}
+
+const ajv = createAjv();
+
+const validators = Object.freeze({
+  registryRef: ajv.getSchema(schemaIds.registryRef),
+  agentManifest: ajv.getSchema(schemaIds.agentManifest),
+  registryItem: ajv.getSchema(schemaIds.registryItem),
+  itemGraph: ajv.getSchema(schemaIds.itemGraph),
+  workspaceRef: ajv.getSchema(schemaIds.workspaceRef),
+  themeRef: ajv.getSchema(schemaIds.themeRef),
+  workbenchState: ajv.getSchema(schemaIds.workbenchState),
+});
+
+export const validateRegistryRef = validators.registryRef;
+export const validateAgentManifest = validators.agentManifest;
+export const validateRegistryItem = validators.registryItem;
+export const validateItemGraph = validators.itemGraph;
+export const validateWorkspaceRef = validators.workspaceRef;
+export const validateThemeRef = validators.themeRef;
+export const validateWorkbenchState = validators.workbenchState;
+
+export const contractNames = Object.freeze(Object.keys(validators));
+
+export function getValidator(name) {
+  const validator = validators[name];
+  if (!validator) {
+    throw new Error(`unknown registry contract "${name}"; expected one of ${contractNames.join(", ")}`);
+  }
+  return validator;
+}
+
+// Format AJV errors into short, deterministic, human-readable lines.
+export function formatErrors(errors) {
+  if (!Array.isArray(errors)) return [];
+  return errors.map((error) => {
+    const where = error.instancePath && error.instancePath.length > 0 ? error.instancePath : "(root)";
+    const extra = error.params?.additionalProperty
+      ? ` (${error.params.additionalProperty})`
+      : error.params?.allowedValues
+        ? ` (allowed: ${error.params.allowedValues.join(", ")})`
+        : "";
+    return `${where} ${error.message}${extra}`;
+  });
+}
+
+// Validate `data` against a named contract. Returns a structured result and
+// never throws on invalid data, so callers can aggregate failures.
+export function validate(name, data) {
+  const validator = getValidator(name);
+  const ok = validator(data) === true;
+  return {
+    ok,
+    errors: ok ? [] : (validator.errors ?? []),
+    messages: ok ? [] : formatErrors(validator.errors ?? []),
+  };
+}
+
+// Validate and throw a descriptive error on failure. Returns `data` on success
+// so it can be used inline.
+export function assertValid(name, data, label = name) {
+  const result = validate(name, data);
+  if (!result.ok) {
+    throw new Error(`${label} failed ${name} validation:\n- ${result.messages.join("\n- ")}`);
+  }
+  return data;
+}
+
+export { findDuplicateJsonObjectKeys, formatDuplicateJsonObjectKeys };
+
+export {
+  WORKSPACE_PART_KINDS,
+  WORKSPACE_PACK_KIND,
+  NON_PART_DEPENDENCY_KINDS,
+  normalizePartType,
+  isPartKind,
+  isPackKind,
+  comparePartKinds,
+  classifyRegistryItem,
+  partKindContract,
+  assertPartKind,
+  partTaxonomyContract,
+  inventoryParts,
+} from "./part-taxonomy.mjs";
+
+// --- shadcn registry-item.json compatibility ---------------------------------
+//
+// The flat `/r/{name}.json` export is consumed by the standard shadcn CLI, so it
+// must validate against the official shadcn `registry-item.json` schema (a vendored
+// draft-07 copy lives in `src/schemas/shadcn-registry-item.schema.json`). The
+// shadcn type enums are narrower than the Jami registry item types, so the export
+// has to map Jami-only types (`registry:app`, `registry:workspace`) onto the
+// shadcn `registry:item` catch-all before it is shadcn-valid.
+
+// `validateSchema: false`: the vendored schema declares the draft-07 `$schema`
+// meta, which AJV's default instance does not carry; we trust the vendored copy
+// and skip meta-schema validation while still evaluating every draft-07 keyword.
+const shadcnAjv = new Ajv({ strict: false, allErrors: true, validateSchema: false });
+addFormats(shadcnAjv);
+export const validateShadcnRegistryItem = shadcnAjv.compile(shadcnRegistryItemSchema);
+
+export const shadcnItemTypes = Object.freeze(
+  new Set(shadcnRegistryItemSchema.properties.type.enum),
+);
+export const shadcnFileTypes = Object.freeze(
+  new Set(shadcnRegistryItemSchema.properties.files.items.properties.type.enum),
+);
+
+const SHADCN_CATCH_ALL_TYPE = "registry:item";
+
+export function toShadcnItemType(type) {
+  return shadcnItemTypes.has(type) ? type : SHADCN_CATCH_ALL_TYPE;
+}
+
+export function toShadcnFileType(type) {
+  return shadcnFileTypes.has(type) ? type : SHADCN_CATCH_ALL_TYPE;
+}
+
+// Coerce a Jami registry output item into a shadcn-standard registry item: map
+// Jami-only item/file types onto the shadcn enums, leaving every other field
+// untouched. The result is what the flat `/r/` export ships.
+export function toShadcnRegistryItem(item) {
+  return {
+    ...item,
+    type: toShadcnItemType(item.type),
+    ...(Array.isArray(item.files)
+      ? { files: item.files.map((file) => ({ ...file, type: toShadcnFileType(file.type) })) }
+      : {}),
+  };
+}
+
+export function validateShadcn(item) {
+  const ok = validateShadcnRegistryItem(item) === true;
+  return {
+    ok,
+    errors: ok ? [] : (validateShadcnRegistryItem.errors ?? []),
+    messages: ok ? [] : formatErrors(validateShadcnRegistryItem.errors ?? []),
+  };
+}
+
+export default {
+  schemas,
+  contractNames,
+  createAjv,
+  getValidator,
+  validate,
+  assertValid,
+  formatErrors,
+  validateAgentManifest,
+  agentManifestAllowedComponents,
+  validateShadcn,
+  validateShadcnRegistryItem,
+  toShadcnRegistryItem,
+  toShadcnItemType,
+  toShadcnFileType,
+};

package/src/json-source.mjs

@@ -0,0 +1,156 @@
+export function findDuplicateJsonObjectKeys(source) {
+  const duplicates = [];
+  const stack = [];
+  let index = 0;
+
+  function skipWhitespace() {
+    while (/\s/.test(source[index] ?? "")) index += 1;
+  }
+
+  function locationAt(offset) {
+    let line = 1;
+    let column = 1;
+    for (let i = 0; i < offset; i += 1) {
+      if (source[i] === "\n") {
+        line += 1;
+        column = 1;
+      } else {
+        column += 1;
+      }
+    }
+    return { line, column };
+  }
+
+  function parseString(start) {
+    let escaped = false;
+    for (let cursor = start + 1; cursor < source.length; cursor += 1) {
+      const char = source[cursor];
+      if (escaped) {
+        escaped = false;
+      } else if (char === "\\") {
+        escaped = true;
+      } else if (char === "\"") {
+        return {
+          value: JSON.parse(source.slice(start, cursor + 1)),
+          end: cursor + 1,
+        };
+      }
+    }
+    throw new SyntaxError("unterminated JSON string");
+  }
+
+  function current() {
+    return stack[stack.length - 1];
+  }
+
+  function markValueComplete() {
+    const parent = current();
+    if (!parent) return;
+    if (parent.type === "object" && parent.expecting === "value") {
+      parent.expecting = "commaOrEnd";
+    } else if (parent.type === "array" && parent.expecting === "valueOrEnd") {
+      parent.expecting = "commaOrEnd";
+    }
+  }
+
+  while (index < source.length) {
+    skipWhitespace();
+    const char = source[index];
+    const context = current();
+    if (!char) break;
+
+    if (char === "{") {
+      if (context?.type === "object" && context.expecting !== "value") {
+        throw new SyntaxError("unexpected object");
+      }
+      if (context?.type === "array" && context.expecting !== "valueOrEnd") {
+        throw new SyntaxError("unexpected object");
+      }
+      stack.push({ type: "object", expecting: "keyOrEnd", keys: new Map() });
+      index += 1;
+      continue;
+    }
+
+    if (char === "[") {
+      if (context?.type === "object" && context.expecting !== "value") {
+        throw new SyntaxError("unexpected array");
+      }
+      if (context?.type === "array" && context.expecting !== "valueOrEnd") {
+        throw new SyntaxError("unexpected array");
+      }
+      stack.push({ type: "array", expecting: "valueOrEnd" });
+      index += 1;
+      continue;
+    }
+
+    if (char === "}") {
+      if (!context || context.type !== "object") throw new SyntaxError("unexpected object close");
+      stack.pop();
+      index += 1;
+      markValueComplete();
+      continue;
+    }
+
+    if (char === "]") {
+      if (!context || context.type !== "array") throw new SyntaxError("unexpected array close");
+      stack.pop();
+      index += 1;
+      markValueComplete();
+      continue;
+    }
+
+    if (char === ",") {
+      if (!context || context.expecting !== "commaOrEnd") throw new SyntaxError("unexpected comma");
+      context.expecting = context.type === "object" ? "keyOrEnd" : "valueOrEnd";
+      index += 1;
+      continue;
+    }
+
+    if (char === ":") {
+      if (!context || context.type !== "object" || context.expecting !== "colon") {
+        throw new SyntaxError("unexpected colon");
+      }
+      context.expecting = "value";
+      index += 1;
+      continue;
+    }
+
+    if (char === "\"") {
+      const stringToken = parseString(index);
+      if (context?.type === "object" && context.expecting === "keyOrEnd") {
+        const firstSeenAt = context.keys.get(stringToken.value);
+        if (firstSeenAt) {
+          duplicates.push({
+            key: stringToken.value,
+            first: firstSeenAt,
+            duplicate: locationAt(index),
+          });
+        } else {
+          context.keys.set(stringToken.value, locationAt(index));
+        }
+        context.expecting = "colon";
+      } else {
+        markValueComplete();
+      }
+      index = stringToken.end;
+      continue;
+    }
+
+    const primitiveMatch = source.slice(index).match(/^-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?|^(?:true|false|null)/);
+    if (!primitiveMatch) {
+      throw new SyntaxError(`unexpected JSON token ${char}`);
+    }
+    index += primitiveMatch[0].length;
+    markValueComplete();
+  }
+
+  if (stack.length > 0) throw new SyntaxError("unterminated JSON value");
+  return duplicates;
+}
+
+export function formatDuplicateJsonObjectKeys(duplicates) {
+  return duplicates.map(
+    ({ key, first, duplicate }) =>
+      `"${key}" first seen at ${first.line}:${first.column}, duplicated at ${duplicate.line}:${duplicate.column}`,
+  );
+}

package/src/part-taxonomy.mjs

@@ -0,0 +1,158 @@
+// Workspace-pack part taxonomy.
+//
+// A workspace pack (a `workspace` registry item) composes five reusable part
+// kinds. This module is the single source of truth for that taxonomy: the kinds,
+// their composition order (foundation-up), the role of each kind, and a pure
+// classifier over registry items. The registry generator, the workspace-evidence
+// generator, the CLI, and the workbench all read the taxonomy from here so the
+// "app / page / block / component / primitive" vocabulary never drifts between
+// surfaces.
+//
+// theme and font registry items are token/asset dependencies a pack pulls in, not
+// composition parts; the workspace item itself is the pack container, not a part.
+
+// Foundation-up order: a primitive composes from tokens, a component from
+// primitives, a block binds one component to workspace state, a page composes
+// blocks, an app composes pages. Index encodes composition depth.
+export const WORKSPACE_PART_KINDS = Object.freeze(["primitive", "component", "block", "page", "app"]);
+
+export const WORKSPACE_PACK_KIND = "workspace";
+
+// Registry item types that are pack dependencies but not composition parts.
+export const NON_PART_DEPENDENCY_KINDS = Object.freeze(["theme", "font"]);
+
+const PART_KIND_INDEX = Object.freeze(
+  Object.fromEntries(WORKSPACE_PART_KINDS.map((kind, index) => [kind, index])),
+);
+
+// Durable contract describing each part kind, what it composes from, and the
+// invariants every part of that kind must hold. `composesFrom: null` marks the
+// foundation (primitives compose from design tokens, which are not parts).
+const PART_TAXONOMY = Object.freeze({
+  primitive: Object.freeze({
+    kind: "primitive",
+    order: PART_KIND_INDEX.primitive,
+    role: "Radix-first resident shadcn primitive; the smallest installable accessible building block.",
+    composesFrom: null,
+    foundation: "design tokens",
+  }),
+  component: Object.freeze({
+    kind: "component",
+    order: PART_KIND_INDEX.component,
+    role: "Resident component composed from primitives with a stable display contract.",
+    composesFrom: "primitive",
+    foundation: null,
+  }),
+  block: Object.freeze({
+    kind: "block",
+    order: PART_KIND_INDEX.block,
+    role: "Titled binding of one component to a workspace state surface (ready/loading/error/empty).",
+    composesFrom: "component",
+    foundation: null,
+  }),
+  page: Object.freeze({
+    kind: "page",
+    order: PART_KIND_INDEX.page,
+    role: "Route surface composing blocks into a labelled, landmarked page.",
+    composesFrom: "block",
+    foundation: null,
+  }),
+  app: Object.freeze({
+    kind: "app",
+    order: PART_KIND_INDEX.app,
+    role: "Full workspace app shell composing pages behind navigation; the installable pack surface.",
+    composesFrom: "page",
+    foundation: null,
+  }),
+});
+
+// The generated/shadcn registry output prefixes Jami types as `registry:<type>`
+// and maps `primitive` onto shadcn's `registry:ui`. Normalize both the authored
+// bare type and the generated output type onto the canonical Jami vocabulary so
+// the classifier works on a source item and its generated output alike.
+const SHADCN_TYPE_ALIASES = Object.freeze({ "registry:ui": "primitive" });
+
+export function normalizePartType(type) {
+  if (typeof type !== "string") return type;
+  if (Object.prototype.hasOwnProperty.call(SHADCN_TYPE_ALIASES, type)) return SHADCN_TYPE_ALIASES[type];
+  if (type.startsWith("registry:")) return type.slice("registry:".length);
+  return type;
+}
+
+export function isPartKind(type) {
+  return Object.prototype.hasOwnProperty.call(PART_KIND_INDEX, normalizePartType(type));
+}
+
+export function isPackKind(type) {
+  return normalizePartType(type) === WORKSPACE_PACK_KIND;
+}
+
+// Stable foundation-up comparator over part kinds (primitive < ... < app).
+// Unknown kinds sort after all known kinds, then by code unit, so callers get a
+// total, locale-independent order without throwing.
+export function comparePartKinds(a, b) {
+  const na = normalizePartType(a);
+  const nb = normalizePartType(b);
+  const ai = isPartKind(na) ? PART_KIND_INDEX[na] : WORKSPACE_PART_KINDS.length;
+  const bi = isPartKind(nb) ? PART_KIND_INDEX[nb] : WORKSPACE_PART_KINDS.length;
+  if (ai !== bi) return ai - bi;
+  return na < nb ? -1 : na > nb ? 1 : 0;
+}
+
+// Pure classifier over a registry item (source or generated output shape). Reads
+// only the `type` field, so it works on both the authored item and the flat
+// shadcn export's pre-mapped Jami type.
+export function classifyRegistryItem(item) {
+  const rawType = item?.type ?? null;
+  const type = normalizePartType(rawType);
+  return {
+    type,
+    rawType,
+    kind: isPartKind(type) ? type : null,
+    isPart: isPartKind(type),
+    isPack: isPackKind(type),
+    isDependency: NON_PART_DEPENDENCY_KINDS.includes(type),
+  };
+}
+
+export function partKindContract(kind) {
+  const contract = PART_TAXONOMY[kind];
+  if (!contract) {
+    throw new Error(`unknown workspace part kind "${kind}"; expected one of ${WORKSPACE_PART_KINDS.join(", ")}`);
+  }
+  return contract;
+}
+
+export function assertPartKind(type, label = "registry item type") {
+  if (!isPartKind(type)) {
+    throw new Error(`${label} "${type}" is not a workspace part kind; expected one of ${WORKSPACE_PART_KINDS.join(", ")}`);
+  }
+  return type;
+}
+
+// The whole taxonomy as a frozen, ordered descriptor — what durable docs and the
+// evidence `index.json` embed so the contract is self-describing on disk.
+export function partTaxonomyContract() {
+  return Object.freeze({
+    schemaVersion: "2026-06-24.workspace-part-taxonomy",
+    packKind: WORKSPACE_PACK_KIND,
+    partKinds: WORKSPACE_PART_KINDS,
+    nonPartDependencyKinds: NON_PART_DEPENDENCY_KINDS,
+    parts: WORKSPACE_PART_KINDS.map((kind) => PART_TAXONOMY[kind]),
+  });
+}
+
+// Group an iterable of registry items into a part inventory keyed by kind, in
+// foundation-up order, with packs and non-part dependencies bucketed separately.
+export function inventoryParts(items) {
+  const parts = Object.fromEntries(WORKSPACE_PART_KINDS.map((kind) => [kind, []]));
+  const packs = [];
+  const dependencies = [];
+  for (const item of items ?? []) {
+    const classified = classifyRegistryItem(item);
+    if (classified.isPart) parts[classified.kind].push(item);
+    else if (classified.isPack) packs.push(item);
+    else if (classified.isDependency) dependencies.push(item);
+  }
+  return { parts, packs, dependencies };
+}