@brandzap/kit-core 0.1.0

package/README.md

@@ -0,0 +1,5 @@
+# @brandzap/kit-core
+
+Shared runtime contract for published BrandZap Brand Kits. It provides schema-v1 manifest and asset validation, immutable resource maps, active-kit reading, and component and asset lookup helpers used by the Kit service and CLI.
+
+This package does not contain publishing credentials or network clients.

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@brandzap/kit-core",
+  "version": "0.1.0",
+  "description": "Shared published Brand Kit schemas, validation, readers, and search helpers.",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/assets.js

@@ -0,0 +1,12 @@
+import { kitSchemaVersion } from "./resource-map.js";
+
+export function createEmptyAssetsDocument() {
+  return {
+    schemaVersion: kitSchemaVersion,
+    assets: []
+  };
+}
+
+export function serializeAssetsDocument(document = createEmptyAssetsDocument()) {
+  return `${JSON.stringify(document, null, 2)}\n`;
+}

package/src/component-search.js

@@ -0,0 +1,71 @@
+export function listComponentSummaries(components = []) {
+  return components.map((component) => ({
+    id: component.id,
+    name: component.name,
+    category: component.category ?? "",
+    group: component.group ?? "",
+    family: component.family ?? "",
+    description: component.description ?? "",
+    tags: Array.isArray(component.tags) ? component.tags : []
+  }));
+}
+
+export function getComponentById(components = [], componentId) {
+  return components.find((component) => component.id === componentId) ?? null;
+}
+
+export function searchComponents(components = [], query = "", limit = 20) {
+  const needle = String(query).trim().toLowerCase();
+  const safeLimit = Math.min(50, Math.max(1, Number(limit) || 20));
+  if (!needle) return listComponentSummaries(components).slice(0, safeLimit);
+  return components
+    .filter((component) => [
+      component.id,
+      component.name,
+      component.category,
+      component.group,
+      component.family,
+      component.description,
+      component.usageGuidance,
+      component.agentNotes,
+      ...(component.tags ?? [])
+    ].join(" ").toLowerCase().includes(needle))
+    .map((component) => listComponentSummaries([component])[0])
+    .slice(0, safeLimit);
+}
+
+export function listAssetSummaries(assetsDocument = { assets: [] }) {
+  return (assetsDocument.assets ?? []).map((asset) => ({
+    id: asset.id,
+    name: asset.name,
+    type: asset.type,
+    mediaType: asset.mediaType,
+    path: asset.path ?? null,
+    description: asset.description ?? "",
+    usageGuidance: asset.usageGuidance ?? "",
+    theme: asset.theme ?? null,
+    preferredFor: asset.preferredFor ?? [],
+    tags: asset.tags ?? []
+  }));
+}
+
+export function getAssetById(assetsDocument = { assets: [] }, assetId) {
+  return (assetsDocument.assets ?? []).find((asset) => asset.id === assetId) ?? null;
+}
+
+export function searchAssets(assetsDocument = { assets: [] }, query = "", limit = 20) {
+  const needle = String(query).trim().toLowerCase();
+  const safeLimit = Math.min(50, Math.max(1, Number(limit) || 20));
+  const assets = assetsDocument.assets ?? [];
+  if (!needle) return listAssetSummaries(assetsDocument).slice(0, safeLimit);
+  return assets.filter((asset) => [
+    asset.id,
+    asset.name,
+    asset.type,
+    asset.description,
+    asset.usageGuidance,
+    ...(asset.tags ?? [])
+  ].join(" ").toLowerCase().includes(needle))
+    .map((asset) => listAssetSummaries({ assets: [asset] })[0])
+    .slice(0, safeLimit);
+}

package/src/index.js

@@ -0,0 +1,6 @@
+export * from "./assets.js";
+export * from "./component-search.js";
+export * from "./kit-reader.js";
+export * from "./manifest.js";
+export * from "./resource-map.js";
+export * from "./schemas.js";

package/src/kit-reader.js

@@ -0,0 +1,51 @@
+import { KitNotFoundError, validateBrandSlug, validateLatestPointer, validateManifest } from "./schemas.js";
+
+export class KitReader {
+  constructor(driver) {
+    this.driver = driver;
+  }
+
+  async resolveActive(brandSlug) {
+    const slug = validateBrandSlug(brandSlug);
+    const pointer = await this.driver.readActivePointer(slug);
+    if (!pointer) throw new KitNotFoundError();
+    validateLatestPointer(pointer);
+    if (pointer.status !== "published" || !pointer.version) throw new KitNotFoundError();
+    const manifestText = await this.driver.readVersionResource(slug, pointer.version, "manifest.json");
+    if (manifestText === null) throw new KitNotFoundError();
+    let manifest;
+    try {
+      manifest = JSON.parse(manifestText);
+    } catch {
+      throw new KitNotFoundError();
+    }
+    validateManifest(manifest, { expectedSlug: slug });
+    if (manifest.version !== pointer.version) throw new KitNotFoundError();
+    return { slug, version: pointer.version, pointer, manifest, manifestText };
+  }
+
+  async readResource(snapshot, resourcePath) {
+    if (resourcePath === "manifest.json") return snapshot.manifestText;
+    const content = await this.driver.readVersionResource(snapshot.slug, snapshot.version, resourcePath);
+    if (content === null) throw new KitNotFoundError("Brand kit resource not found.");
+    return content;
+  }
+
+  async readJsonResource(snapshot, resourcePath) {
+    const content = await this.readResource(snapshot, resourcePath);
+    try {
+      return JSON.parse(content);
+    } catch {
+      throw new KitNotFoundError("Brand kit resource is invalid.");
+    }
+  }
+
+  async readResourceBuffer(snapshot, resourcePath) {
+    if (resourcePath === "manifest.json") return Buffer.from(snapshot.manifestText, "utf8");
+    const content = typeof this.driver.readVersionResourceBuffer === "function"
+      ? await this.driver.readVersionResourceBuffer(snapshot.slug, snapshot.version, resourcePath)
+      : Buffer.from(await this.driver.readVersionResource(snapshot.slug, snapshot.version, resourcePath), "utf8");
+    if (content === null) throw new KitNotFoundError("Brand kit resource not found.");
+    return Buffer.isBuffer(content) ? content : Buffer.from(content, "utf8");
+  }
+}

package/src/manifest.js

@@ -0,0 +1,31 @@
+import { kitSchemaVersion, legacyKitSchemaVersion, legacyManifestResources, manifestResources } from "./resource-map.js";
+import { validateManifest } from "./schemas.js";
+
+export function createPublishedManifest({
+  kitId,
+  publishId,
+  brandId,
+  brandSlug,
+  name,
+  version,
+  publishedAt,
+  baseUrl,
+  contentDigest,
+  schemaVersion = kitSchemaVersion
+}) {
+  const canonicalUrl = `${String(baseUrl).replace(/\/$/, "")}/${brandSlug}`;
+  return validateManifest({
+    schemaVersion,
+    kitId,
+    publishId,
+    brandId,
+    brandSlug,
+    name,
+    version,
+    publishedAt,
+    canonicalUrl,
+    mcpUrl: `${canonicalUrl}/mcp`,
+    contentDigest,
+    resources: schemaVersion === legacyKitSchemaVersion ? legacyManifestResources : manifestResources
+  }, { expectedSlug: brandSlug });
+}

package/src/resource-map.js

@@ -0,0 +1,92 @@
+export const legacyKitSchemaVersion = "1";
+export const kitSchemaVersion = "2";
+
+export const manifestResources = Object.freeze({
+  agentGuide: "./agent.md",
+  tokens: "./tokens.json",
+  components: "./components.json",
+  stylesheet: "./styles.css",
+  brandVoice: "./brand-voice.json",
+  assets: "./assets.json",
+  adapters: Object.freeze({
+    agents: "./adapters/AGENTS.md",
+    claude: "./adapters/CLAUDE.md",
+    cursor: "./adapters/cursor-rules.md"
+  })
+});
+
+export const legacyManifestResources = Object.freeze({
+  agentGuide: "./agent.md",
+  tokens: "./tokens.json",
+  components: "./components.json",
+  stylesheet: "./styles.css",
+  assets: "./assets.json",
+  adapters: Object.freeze({
+    agents: "./adapters/AGENTS.md",
+    claude: "./adapters/CLAUDE.md",
+    cursor: "./adapters/cursor-rules.md"
+  })
+});
+
+export const publishedResourcePaths = Object.freeze([
+  "agent.md",
+  "tokens.json",
+  "components.json",
+  "styles.css",
+  "brand-voice.json",
+  "assets.json",
+  "adapters/AGENTS.md",
+  "adapters/CLAUDE.md",
+  "adapters/cursor-rules.md"
+]);
+
+export const legacyPublishedResourcePaths = Object.freeze([
+  "agent.md",
+  "tokens.json",
+  "components.json",
+  "styles.css",
+  "assets.json",
+  "adapters/AGENTS.md",
+  "adapters/CLAUDE.md",
+  "adapters/cursor-rules.md"
+]);
+
+export const publicResourceRoutes = Object.freeze({
+  "manifest.json": "manifest.json",
+  "agent.md": "agent.md",
+  "tokens.json": "tokens.json",
+  "components.json": "components.json",
+  "styles.css": "styles.css",
+  "brand-voice.json": "brand-voice.json",
+  "assets.json": "assets.json",
+  "adapters/AGENTS.md": "adapters/AGENTS.md",
+  "adapters/CLAUDE.md": "adapters/CLAUDE.md",
+  "adapters/cursor-rules.md": "adapters/cursor-rules.md"
+});
+
+export const contentTypesByPath = Object.freeze({
+  "manifest.json": "application/json; charset=utf-8",
+  "tokens.json": "application/json; charset=utf-8",
+  "components.json": "application/json; charset=utf-8",
+  "assets.json": "application/json; charset=utf-8",
+  "brand-voice.json": "application/json; charset=utf-8",
+  "agent.md": "text/markdown; charset=utf-8",
+  "styles.css": "text/css; charset=utf-8",
+  "adapters/AGENTS.md": "text/markdown; charset=utf-8",
+  "adapters/CLAUDE.md": "text/markdown; charset=utf-8",
+  "adapters/cursor-rules.md": "text/markdown; charset=utf-8"
+});
+
+export function flattenManifestResourcePaths(resources = manifestResources) {
+  return [
+    resources.agentGuide,
+    resources.tokens,
+    resources.components,
+    resources.stylesheet,
+    resources.brandVoice,
+    resources.assets,
+    resources.adapters?.agents,
+    resources.adapters?.claude,
+    resources.adapters?.cursor
+  ];
+}

package/src/schemas.js

@@ -0,0 +1,318 @@
+import { createHash } from "node:crypto";
+import {
+  kitSchemaVersion,
+  legacyKitSchemaVersion,
+  legacyManifestResources,
+  legacyPublishedResourcePaths,
+  manifestResources,
+  publishedResourcePaths
+} from "./resource-map.js";
+
+const slugPattern = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
+const semverPattern = /^1\.0\.(0|[1-9]\d*)$/;
+const uuidPattern = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const reservedSlugs = new Set(["health", "internal", "static", "mcp", "guide"]);
+
+export class KitValidationError extends Error {
+  constructor(message, { statusCode = 400, code = "KIT_VALIDATION_ERROR" } = {}) {
+    super(message);
+    this.name = "KitValidationError";
+    this.statusCode = statusCode;
+    this.code = code;
+  }
+}
+
+export class KitNotFoundError extends Error {
+  constructor(message = "Brand kit not found.") {
+    super(message);
+    this.name = "KitNotFoundError";
+    this.statusCode = 404;
+    this.code = "KIT_NOT_FOUND";
+  }
+}
+
+export function validateBrandSlug(value) {
+  const slug = String(value ?? "").trim();
+  if (!slugPattern.test(slug) || reservedSlugs.has(slug)) {
+    throw new KitValidationError(
+      "Brand slug must be 1-63 lowercase letters, numbers, or internal hyphens and may not be reserved."
+    );
+  }
+  return slug;
+}
+
+export function isPublishedVersion(value) {
+  return semverPattern.test(String(value ?? ""));
+}
+
+export function validatePublishedVersion(value) {
+  const version = String(value ?? "");
+  if (!isPublishedVersion(version)) {
+    throw new KitValidationError("Published version must use the 1.0.x format.");
+  }
+  return version;
+}
+
+export function validateUuid(value, fieldName) {
+  const normalized = String(value ?? "");
+  if (!uuidPattern.test(normalized)) {
+    throw new KitValidationError(`${fieldName} must be a UUID.`);
+  }
+  return normalized;
+}
+
+export function validateAssetsDocument(input) {
+  assertPlainObject(input, "assets.json must contain an object.");
+  if (!isSupportedSchemaVersion(input.schemaVersion) || !Array.isArray(input.assets)) {
+    throw new KitValidationError('assets.json must use schemaVersion "1" or "2" and contain an assets array.');
+  }
+  if ("usageDescription" in input) {
+    requiredString(input.usageDescription, "Assets usageDescription", { allowEmpty: true });
+  }
+  const ids = new Set();
+  const preferredLogoModes = new Set();
+  const allowedTypes = new Set(["logo", "icon", "illustration", "brand-flair", "decorative-graphic", "image", "download", "background"]);
+  for (const asset of input.assets) {
+    assertPlainObject(asset, "Each asset must be an object.");
+    const id = requiredString(asset.id, "Asset id");
+    if (ids.has(id)) throw new KitValidationError(`Duplicate asset id: ${id}.`);
+    ids.add(id);
+    requiredString(asset.name, `Asset ${id} name`);
+    if (!allowedTypes.has(asset.type)) throw new KitValidationError(`Asset ${id} has an unsupported type.`);
+    requiredString(asset.mediaType, `Asset ${id} mediaType`);
+    if (asset.type === "background") {
+      requiredString(asset.cssValue, `Asset ${id} cssValue`);
+    } else {
+      validateRelativeAssetPath(asset.path, id);
+    }
+    if (!Array.isArray(asset.tags) || asset.tags.some((tag) => typeof tag !== "string")) {
+      throw new KitValidationError(`Asset ${id} tags must be an array of strings.`);
+    }
+    requiredString(asset.usageGuidance, `Asset ${id} usageGuidance`, { allowEmpty: true });
+    if (asset.theme !== undefined && !["light", "dark", "both"].includes(asset.theme)) {
+      throw new KitValidationError(`Asset ${id} theme must be light, dark, or both.`);
+    }
+    if (asset.preferredFor !== undefined) {
+      if (asset.type !== "logo" || !Array.isArray(asset.preferredFor)) {
+        throw new KitValidationError(`Asset ${id} preferredFor is supported only for logos and must be an array.`);
+      }
+      if (new Set(asset.preferredFor).size !== asset.preferredFor.length
+        || asset.preferredFor.some((mode) => !["light", "dark"].includes(mode))) {
+        throw new KitValidationError(`Asset ${id} preferredFor must contain unique light and/or dark modes.`);
+      }
+      for (const mode of asset.preferredFor) {
+        if (asset.theme !== "both" && asset.theme !== mode) {
+          throw new KitValidationError(`Asset ${id} cannot be preferred for ${mode} mode when its theme is ${asset.theme}.`);
+        }
+        if (preferredLogoModes.has(mode)) {
+          throw new KitValidationError(`Only one logo may be preferred for ${mode} mode.`);
+        }
+        preferredLogoModes.add(mode);
+      }
+    }
+  }
+  return input;
+}
+
+export function validateManifest(input, { expectedSlug } = {}) {
+  assertPlainObject(input, "manifest.json must contain an object.");
+  if (!isSupportedSchemaVersion(input.schemaVersion)) throw new KitValidationError("Unsupported manifest schemaVersion.");
+  validateUuid(input.kitId, "kitId");
+  validateUuid(input.publishId, "publishId");
+  requiredString(input.brandId, "brandId");
+  const slug = validateBrandSlug(input.brandSlug);
+  if (expectedSlug && slug !== expectedSlug) throw new KitValidationError("Manifest brandSlug does not match the requested kit.");
+  requiredString(input.name, "name");
+  validatePublishedVersion(input.version);
+  validateIsoTimestamp(input.publishedAt, "publishedAt");
+  validateCanonicalUrls(input, slug);
+  validateManifestResources(input.resources, input.schemaVersion);
+  if (input.contentDigest !== undefined && !/^sha256:[0-9a-f]{64}$/.test(input.contentDigest)) {
+    throw new KitValidationError("contentDigest must be a sha256 digest.");
+  }
+  return input;
+}
+
+export function validatePublishEnvelope(input, expectedSlug) {
+  assertPlainObject(input, "Publish request must contain an object.");
+  if (!isSupportedSchemaVersion(input.schemaVersion)) throw new KitValidationError("Unsupported publish schemaVersion.");
+  const publishId = validateUuid(input.publishId, "publishId");
+  const brandId = requiredString(input.brandId, "brandId");
+  const name = requiredString(input.name, "name");
+  const brandSlug = validateBrandSlug(expectedSlug);
+  if (input.visibility !== undefined && !["public", "restricted"].includes(input.visibility)) {
+    throw new KitValidationError("visibility must be public or restricted.");
+  }
+  const remoteKitId = input.remoteKitId ? validateUuid(input.remoteKitId, "remoteKitId") : null;
+  assertPlainObject(input.files, "Publish request files must be an object.");
+  const keys = Object.keys(input.files).sort();
+  const requiredPaths = input.schemaVersion === legacyKitSchemaVersion
+    ? legacyPublishedResourcePaths
+    : publishedResourcePaths;
+  const expectedKeys = [...requiredPaths].sort();
+  if (input.schemaVersion === legacyKitSchemaVersion && JSON.stringify(keys) !== JSON.stringify(expectedKeys)) {
+    throw new KitValidationError(`Publish request must contain exactly: ${expectedKeys.join(", ")}.`);
+  }
+  const missing = expectedKeys.filter((resourcePath) => !keys.includes(resourcePath));
+  if (missing.length) {
+    throw new KitValidationError(`Publish request is missing: ${missing.join(", ")}.`);
+  }
+  const files = {};
+  for (const resourcePath of keys) {
+    if (!requiredPaths.includes(resourcePath) && !isSafePublishedAssetPath(resourcePath)) {
+      throw new KitValidationError(`${resourcePath} is not an allowed published resource path.`);
+    }
+    const content = input.files[resourcePath];
+    if (requiredPaths.includes(resourcePath) && typeof content !== "string") {
+      throw new KitValidationError(`${resourcePath} must be a UTF-8 string.`);
+    }
+    files[resourcePath] = normalizePublishedFile(content, resourcePath);
+  }
+  parseJsonResource(files["tokens.json"], "tokens.json", (value) => assertPlainObject(value, "tokens.json must contain an object."));
+  parseJsonResource(files["components.json"], "components.json", (value) => {
+    if (!Array.isArray(value)) throw new KitValidationError("components.json must contain an array.");
+    const ids = new Set();
+    for (const component of value) {
+      assertPlainObject(component, "Each component must be an object.");
+      const id = requiredString(component.id, "Component id");
+      if (ids.has(id)) throw new KitValidationError(`Duplicate component id: ${id}.`);
+      ids.add(id);
+    }
+  });
+  const assetsDocument = parseJsonResource(files["assets.json"], "assets.json", validateAssetsDocument);
+  if (input.schemaVersion === kitSchemaVersion) {
+    for (const asset of assetsDocument.assets) {
+      if (!asset.path) continue;
+      const resourcePath = asset.path.replace(/^\.\//, "");
+      if (!(resourcePath in files)) {
+        throw new KitValidationError(`Published asset ${asset.id} is missing file ${resourcePath}.`);
+      }
+    }
+  }
+
+  return {
+    schemaVersion: input.schemaVersion,
+    publishId,
+    remoteKitId,
+    brandId,
+    brandSlug,
+    name,
+    visibility: input.visibility === "public" ? "public" : "restricted",
+    files,
+    contentDigest: digestPublishedFiles(files)
+  };
+}
+
+export function digestPublishedFiles(files) {
+  const hash = createHash("sha256");
+  for (const resourcePath of Object.keys(files).sort()) {
+    hash.update(resourcePath);
+    hash.update("\0");
+    hash.update(publishedFileBytes(files[resourcePath]));
+    hash.update("\0");
+  }
+  return `sha256:${hash.digest("hex")}`;
+}
+
+export function validateLatestPointer(input) {
+  assertPlainObject(input, "latest.json must contain an object.");
+  if (!isSupportedSchemaVersion(input.schemaVersion)) throw new KitValidationError("Unsupported latest pointer schemaVersion.");
+  if (input.status !== "published" && input.status !== "unpublished") {
+    throw new KitValidationError("Latest pointer status is invalid.");
+  }
+  if (input.version !== null) validatePublishedVersion(input.version);
+  validateIsoTimestamp(input.activatedAt, "activatedAt");
+  return input;
+}
+
+function validateManifestResources(resources, schemaVersion) {
+  assertPlainObject(resources, "Manifest resources must be an object.");
+  const normalized = JSON.stringify(resources);
+  const expected = schemaVersion === legacyKitSchemaVersion ? legacyManifestResources : manifestResources;
+  if (normalized !== JSON.stringify(expected)) {
+    throw new KitValidationError("Manifest resources do not match the published-kit resource contract.");
+  }
+}
+
+function validateCanonicalUrls(manifest, slug) {
+  let canonicalUrl;
+  let mcpUrl;
+  try {
+    canonicalUrl = new URL(manifest.canonicalUrl);
+    mcpUrl = new URL(manifest.mcpUrl);
+  } catch {
+    throw new KitValidationError("Manifest canonicalUrl and mcpUrl must be valid absolute URLs.");
+  }
+  const canonicalPath = canonicalUrl.pathname.replace(/\/$/, "");
+  if (canonicalPath !== `/${slug}` || canonicalUrl.search || canonicalUrl.hash) {
+    throw new KitValidationError("Manifest canonicalUrl does not match brandSlug.");
+  }
+  if (mcpUrl.origin !== canonicalUrl.origin || mcpUrl.pathname !== `/${slug}/mcp` || mcpUrl.search || mcpUrl.hash) {
+    throw new KitValidationError("Manifest mcpUrl does not match canonicalUrl.");
+  }
+}
+
+function validateRelativeAssetPath(value, id) {
+  const assetPath = requiredString(value, `Asset ${id} path`);
+  if (!assetPath.startsWith("./assets/") || assetPath.includes("..") || assetPath.includes("\\") || assetPath.includes("//")) {
+    throw new KitValidationError(`Asset ${id} path must be a safe version-relative assets path.`);
+  }
+}
+
+function parseJsonResource(content, name, validate) {
+  let parsed;
+  try {
+    parsed = JSON.parse(content);
+  } catch {
+    throw new KitValidationError(`${name} must contain valid JSON.`);
+  }
+  return validate(parsed);
+}
+
+function isSupportedSchemaVersion(value) {
+  return value === legacyKitSchemaVersion || value === kitSchemaVersion;
+}
+
+function isSafePublishedAssetPath(resourcePath) {
+  return typeof resourcePath === "string"
+    && /^assets\/[a-zA-Z0-9][a-zA-Z0-9._/-]*$/.test(resourcePath)
+    && !resourcePath.includes("..")
+    && !resourcePath.includes("//");
+}
+
+function normalizePublishedFile(content, resourcePath) {
+  if (typeof content === "string") return content;
+  assertPlainObject(content, `${resourcePath} must be a UTF-8 string or base64 file descriptor.`);
+  if (content.encoding !== "base64" || typeof content.content !== "string" || !isCanonicalBase64(content.content)) {
+    throw new KitValidationError(`${resourcePath} must use a valid base64 file descriptor.`);
+  }
+  const mediaType = requiredString(content.mediaType, `${resourcePath} mediaType`);
+  if (!["image/png", "image/svg+xml", "application/octet-stream"].includes(mediaType)) {
+    throw new KitValidationError(`${resourcePath} has an unsupported binary media type.`);
+  }
+  return { encoding: "base64", content: content.content, mediaType };
+}
+
+function isCanonicalBase64(value) {
+  if (!/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(value)) return false;
+  return Buffer.from(value, "base64").toString("base64") === value;
+}
+
+function publishedFileBytes(value) {
+  return typeof value === "string" ? Buffer.from(value, "utf8") : Buffer.from(value.content, "base64");
+}
+
+function assertPlainObject(value, message) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new KitValidationError(message);
+}
+
+function requiredString(value, label, { allowEmpty = false } = {}) {
+  if (typeof value !== "string" || (!allowEmpty && !value.trim())) throw new KitValidationError(`${label} is required.`);
+  return value.trim();
+}
+
+function validateIsoTimestamp(value, label) {
+  if (typeof value !== "string" || !value || Number.isNaN(Date.parse(value))) {
+    throw new KitValidationError(`${label} must be an ISO timestamp.`);
+  }
+}