@thebes/cadmus 0.2.1 → 0.3.0

package/dist/cms/index.d.cts

@@ -1,2 +1,2 @@
-import { A as CollectionAccess, B as RelationshipFieldConfig, C as relationshipJoinTables, D as CadmeaPlugin, E as BaseFieldConfig, F as GroupFieldConfig, G as flattenDoc, H as SelectFieldConfig, I as JsonFieldConfig, K as flattenFields, L as JsonValue, M as CollectionHooks, N as DateFieldConfig, O as CheckboxFieldConfig, P as FieldConfig, R as NumberFieldConfig, S as extractSearchText, T as ArrayFieldConfig, U as TextFieldConfig, V as RichTextFieldConfig, W as UploadFieldConfig, _ as cmsConfigToSchema, a as generateSchemaSource, b as collectionToTable, c as CmsRegistry, d as can, f as createLocalApi, g as defineCollection, h as defineCmsConfig, i as deliverWebhookMessage, j as CollectionConfig, k as CmsConfig, l as LocalApi, m as getRegisteredApi, n as WebhookMessage, o as CollectionMeta, p as createVersionedLocalApi, q as nestDoc, r as createWebhookHook, s as getCollectionsMeta, t as WebhookConfig, u as VersionedLocalApi, v as collectionSearchTableName, w as AccessFn, x as collectionVersionsTable, y as collectionSearchTableSQL, z as RelationshipDepth } from "../index-BUrCSGVb.cjs";
-export { AccessFn, ArrayFieldConfig, BaseFieldConfig, CadmeaPlugin, CheckboxFieldConfig, CmsConfig, CmsRegistry, CollectionAccess, CollectionConfig, CollectionHooks, CollectionMeta, DateFieldConfig, FieldConfig, GroupFieldConfig, JsonFieldConfig, JsonValue, LocalApi, NumberFieldConfig, RelationshipDepth, RelationshipFieldConfig, RichTextFieldConfig, SelectFieldConfig, TextFieldConfig, UploadFieldConfig, VersionedLocalApi, WebhookConfig, WebhookMessage, can, cmsConfigToSchema, collectionSearchTableName, collectionSearchTableSQL, collectionToTable, collectionVersionsTable, createLocalApi, createVersionedLocalApi, createWebhookHook, defineCmsConfig, defineCollection, deliverWebhookMessage, extractSearchText, flattenDoc, flattenFields, generateSchemaSource, getCollectionsMeta, getRegisteredApi, nestDoc, relationshipJoinTables };
+import { $ as ValidationSeverity, A as CollectionConfig, B as RichTextFieldConfig, C as ArrayFieldConfig, D as CmsConfig, Dt as StringBlockRenderer, E as CheckboxFieldConfig, Et as PortableBlockLike, F as JsonFieldConfig, G as flattenFields, H as TextFieldConfig, I as JsonValue, J as CustomValidatorResult, K as nestDoc, L as NumberFieldConfig, M as DateFieldConfig, N as FieldConfig, O as CollectionAccess, Ot as createBlockRegistry, P as GroupFieldConfig, Q as ValidationFieldContext, R as RelationshipDepth, S as AccessFn, T as CadmeaPlugin, Tt as BlockRegistry, U as UploadFieldConfig, V as SelectFieldConfig, W as flattenDoc, X as ValidateDocumentOptions, Y as Rule, Z as ValidationBuilder, _ as collectionSearchTableSQL, a as BuildStudioStructureOptions, at as LocalApi, b as extractSearchText, c as StudioStructureItem, ct as createLocalApi, d as CollectionMeta, et as assertValid, f as getCollectionsMeta, g as collectionSearchTableName, h as cmsConfigToSchema, i as deliverWebhookMessage, it as CmsRegistry, j as CollectionHooks, k as CollectionAdminConfig, kt as renderBlocksToString, l as buildStudioStructure, lt as createVersionedLocalApi, m as defineCollection, n as WebhookMessage, nt as rule, o as DEFAULT_STUDIO_GROUP, ot as VersionedLocalApi, p as defineCmsConfig, q as CustomValidator, r as createWebhookHook, rt as validateDocument, s as StudioStructureGroup, st as can, t as WebhookConfig, tt as defineField, u as generateSchemaSource, ut as getRegisteredApi, v as collectionToTable, w as BaseFieldConfig, x as relationshipJoinTables, y as collectionVersionsTable, z as RelationshipFieldConfig } from "../index-BRZrCTsN.cjs";
+export { AccessFn, ArrayFieldConfig, BaseFieldConfig, BlockRegistry, BuildStudioStructureOptions, CadmeaPlugin, CheckboxFieldConfig, CmsConfig, CmsRegistry, CollectionAccess, CollectionAdminConfig, CollectionConfig, CollectionHooks, CollectionMeta, CustomValidator, CustomValidatorResult, DEFAULT_STUDIO_GROUP, DateFieldConfig, FieldConfig, GroupFieldConfig, JsonFieldConfig, JsonValue, LocalApi, NumberFieldConfig, PortableBlockLike, RelationshipDepth, RelationshipFieldConfig, RichTextFieldConfig, Rule, SelectFieldConfig, StringBlockRenderer, StudioStructureGroup, StudioStructureItem, TextFieldConfig, UploadFieldConfig, ValidateDocumentOptions, ValidationBuilder, ValidationFieldContext, ValidationSeverity, VersionedLocalApi, WebhookConfig, WebhookMessage, assertValid, buildStudioStructure, can, cmsConfigToSchema, collectionSearchTableName, collectionSearchTableSQL, collectionToTable, collectionVersionsTable, createBlockRegistry, createLocalApi, createVersionedLocalApi, createWebhookHook, defineCmsConfig, defineCollection, defineField, deliverWebhookMessage, extractSearchText, flattenDoc, flattenFields, generateSchemaSource, getCollectionsMeta, getRegisteredApi, nestDoc, relationshipJoinTables, renderBlocksToString, rule, validateDocument };

package/dist/cms/index.d.ts

@@ -1,2 +1,2 @@
-import { A as CollectionAccess, B as RelationshipFieldConfig, C as relationshipJoinTables, D as CadmeaPlugin, E as BaseFieldConfig, F as GroupFieldConfig, G as flattenDoc, H as SelectFieldConfig, I as JsonFieldConfig, K as flattenFields, L as JsonValue, M as CollectionHooks, N as DateFieldConfig, O as CheckboxFieldConfig, P as FieldConfig, R as NumberFieldConfig, S as extractSearchText, T as ArrayFieldConfig, U as TextFieldConfig, V as RichTextFieldConfig, W as UploadFieldConfig, _ as cmsConfigToSchema, a as generateSchemaSource, b as collectionToTable, c as CmsRegistry, d as can, f as createLocalApi, g as defineCollection, h as defineCmsConfig, i as deliverWebhookMessage, j as CollectionConfig, k as CmsConfig, l as LocalApi, m as getRegisteredApi, n as WebhookMessage, o as CollectionMeta, p as createVersionedLocalApi, q as nestDoc, r as createWebhookHook, s as getCollectionsMeta, t as WebhookConfig, u as VersionedLocalApi, v as collectionSearchTableName, w as AccessFn, x as collectionVersionsTable, y as collectionSearchTableSQL, z as RelationshipDepth } from "../index-BUrCSGVb.js";
-export { AccessFn, ArrayFieldConfig, BaseFieldConfig, CadmeaPlugin, CheckboxFieldConfig, CmsConfig, CmsRegistry, CollectionAccess, CollectionConfig, CollectionHooks, CollectionMeta, DateFieldConfig, FieldConfig, GroupFieldConfig, JsonFieldConfig, JsonValue, LocalApi, NumberFieldConfig, RelationshipDepth, RelationshipFieldConfig, RichTextFieldConfig, SelectFieldConfig, TextFieldConfig, UploadFieldConfig, VersionedLocalApi, WebhookConfig, WebhookMessage, can, cmsConfigToSchema, collectionSearchTableName, collectionSearchTableSQL, collectionToTable, collectionVersionsTable, createLocalApi, createVersionedLocalApi, createWebhookHook, defineCmsConfig, defineCollection, deliverWebhookMessage, extractSearchText, flattenDoc, flattenFields, generateSchemaSource, getCollectionsMeta, getRegisteredApi, nestDoc, relationshipJoinTables };
+import { $ as ValidationSeverity, A as CollectionConfig, B as RichTextFieldConfig, C as ArrayFieldConfig, D as CmsConfig, Dt as StringBlockRenderer, E as CheckboxFieldConfig, Et as PortableBlockLike, F as JsonFieldConfig, G as flattenFields, H as TextFieldConfig, I as JsonValue, J as CustomValidatorResult, K as nestDoc, L as NumberFieldConfig, M as DateFieldConfig, N as FieldConfig, O as CollectionAccess, Ot as createBlockRegistry, P as GroupFieldConfig, Q as ValidationFieldContext, R as RelationshipDepth, S as AccessFn, T as CadmeaPlugin, Tt as BlockRegistry, U as UploadFieldConfig, V as SelectFieldConfig, W as flattenDoc, X as ValidateDocumentOptions, Y as Rule, Z as ValidationBuilder, _ as collectionSearchTableSQL, a as BuildStudioStructureOptions, at as LocalApi, b as extractSearchText, c as StudioStructureItem, ct as createLocalApi, d as CollectionMeta, et as assertValid, f as getCollectionsMeta, g as collectionSearchTableName, h as cmsConfigToSchema, i as deliverWebhookMessage, it as CmsRegistry, j as CollectionHooks, k as CollectionAdminConfig, kt as renderBlocksToString, l as buildStudioStructure, lt as createVersionedLocalApi, m as defineCollection, n as WebhookMessage, nt as rule, o as DEFAULT_STUDIO_GROUP, ot as VersionedLocalApi, p as defineCmsConfig, q as CustomValidator, r as createWebhookHook, rt as validateDocument, s as StudioStructureGroup, st as can, t as WebhookConfig, tt as defineField, u as generateSchemaSource, ut as getRegisteredApi, v as collectionToTable, w as BaseFieldConfig, x as relationshipJoinTables, y as collectionVersionsTable, z as RelationshipFieldConfig } from "../index-BRZrCTsN.js";
+export { AccessFn, ArrayFieldConfig, BaseFieldConfig, BlockRegistry, BuildStudioStructureOptions, CadmeaPlugin, CheckboxFieldConfig, CmsConfig, CmsRegistry, CollectionAccess, CollectionAdminConfig, CollectionConfig, CollectionHooks, CollectionMeta, CustomValidator, CustomValidatorResult, DEFAULT_STUDIO_GROUP, DateFieldConfig, FieldConfig, GroupFieldConfig, JsonFieldConfig, JsonValue, LocalApi, NumberFieldConfig, PortableBlockLike, RelationshipDepth, RelationshipFieldConfig, RichTextFieldConfig, Rule, SelectFieldConfig, StringBlockRenderer, StudioStructureGroup, StudioStructureItem, TextFieldConfig, UploadFieldConfig, ValidateDocumentOptions, ValidationBuilder, ValidationFieldContext, ValidationSeverity, VersionedLocalApi, WebhookConfig, WebhookMessage, assertValid, buildStudioStructure, can, cmsConfigToSchema, collectionSearchTableName, collectionSearchTableSQL, collectionToTable, collectionVersionsTable, createBlockRegistry, createLocalApi, createVersionedLocalApi, createWebhookHook, defineCmsConfig, defineCollection, defineField, deliverWebhookMessage, extractSearchText, flattenDoc, flattenFields, generateSchemaSource, getCollectionsMeta, getRegisteredApi, nestDoc, relationshipJoinTables, renderBlocksToString, rule, validateDocument };

package/dist/cms/index.js

@@ -1,7 +1,64 @@
-import { a as CadmusCmsError, l as CadmusQueueError, t as CadmusAccessDeniedError } from "../errors-mZIqZJO4.js";
+import { a as CadmusCmsError, l as CadmusQueueError, p as CadmusValidationError, t as CadmusAccessDeniedError } from "../errors-C8SqkFjl.js";
 import { enqueue } from "../queues/index.js";
 import { integer, real, sqliteTable, text } from "drizzle-orm/sqlite-core";
-import { count, desc, eq, inArray, sql } from "drizzle-orm";
+import { and, count, desc, eq, inArray, ne, sql } from "drizzle-orm";
+//#region src/cms/blocks.ts
+/**
+* Create a block renderer registry. Seed it with an initial `type → renderer`
+* map and/or an `options.fallback` for unknown types.
+*
+* ```ts
+* const registry = createBlockRegistry<StringBlockRenderer>({
+*   divider: () => "<hr>",
+* });
+* registry.register("hero", (b) => `<h1>${b.heading}</h1>`);
+* renderBlocksToString(blocks, registry);
+* ```
+*/
+function createBlockRegistry(initial = {}, options = {}) {
+	const renderers = new Map(Object.entries(initial));
+	let fallback = options.fallback;
+	const registry = {
+		register(type, renderer) {
+			renderers.set(type, renderer);
+			return registry;
+		},
+		registerMany(map) {
+			for (const [type, renderer] of Object.entries(map)) renderers.set(type, renderer);
+			return registry;
+		},
+		get(type) {
+			return renderers.get(type);
+		},
+		has(type) {
+			return renderers.has(type);
+		},
+		types() {
+			return [...renderers.keys()];
+		},
+		setFallback(renderer) {
+			fallback = renderer;
+			return registry;
+		},
+		resolve(type) {
+			return renderers.get(type) ?? fallback;
+		}
+	};
+	return registry;
+}
+/**
+* Render an array of blocks to a single HTML string via a registry of
+* {@link StringBlockRenderer}s. Blocks whose type resolves to no renderer
+* (and no fallback) contribute the empty string — the same forgiving
+* behavior the old hand-rolled `switch` had for unknown types.
+*/
+function renderBlocksToString(blocks, registry) {
+	return blocks.map((block) => {
+		const renderer = registry.resolve(block.type);
+		return renderer ? renderer(block) : "";
+	}).join("");
+}
+//#endregion
 //#region src/cms/types.ts
 /**
 * Expands every `group` field in `fields` into its flattened equivalents
@@ -249,6 +306,289 @@ function defineCmsConfig(config) {
 	return resolved;
 }
 //#endregion
+//#region src/cms/validation.ts
+const EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+const SLUG_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+/**
+* Immutable, chainable rule builder — the value a field's `validation`
+* function receives and returns. Build a `Rule` with the module-level
+* {@link rule} factory, or accept the one passed to your `validation`
+* callback.
+*/
+var Rule = class Rule {
+	checks;
+	constructor(checks = []) {
+		this.checks = checks;
+	}
+	add(check) {
+		return new Rule([...this.checks, check]);
+	}
+	/** Override the message of the most recently added check. */
+	error(message) {
+		return this.withLast({
+			message,
+			severity: "error"
+		});
+	}
+	/**
+	* Demote the most recently added check to a warning (non-blocking),
+	* optionally with a message. Sanity's `Rule.warning()` analogue.
+	*/
+	warning(message) {
+		return this.withLast({
+			severity: "warning",
+			...message ? { message } : {}
+		});
+	}
+	withLast(patch) {
+		if (this.checks.length === 0) return this;
+		const next = this.checks.slice();
+		next[next.length - 1] = {
+			...next[next.length - 1],
+			...patch
+		};
+		return new Rule(next);
+	}
+	required() {
+		return this.add({ kind: "required" });
+	}
+	/** Minimum string length / array length / numeric value. */
+	min(n) {
+		return this.add({
+			kind: "min",
+			n
+		});
+	}
+	/** Maximum string length / array length / numeric value. */
+	max(n) {
+		return this.add({
+			kind: "max",
+			n
+		});
+	}
+	/** Exact string/array length. */
+	length(n) {
+		return this.add({
+			kind: "length",
+			n
+		});
+	}
+	regex(re, label = "match the required format") {
+		return this.add({
+			kind: "regex",
+			re,
+			label
+		});
+	}
+	email() {
+		return this.add({
+			kind: "regex",
+			re: EMAIL_RE,
+			label: "be a valid email"
+		});
+	}
+	/** Lowercase kebab-case slug format. Pair with `.unique()` for slugs. */
+	slug() {
+		return this.add({
+			kind: "regex",
+			re: SLUG_RE,
+			label: "be a lowercase, hyphen-separated slug"
+		});
+	}
+	integer() {
+		return this.add({ kind: "integer" });
+	}
+	positive() {
+		return this.add({ kind: "positive" });
+	}
+	/**
+	* Value must be unique across the collection (DB-backed; skipped in a
+	* pure client-side pass). A first-class rule rather than the hand-rolled
+	* column `unique` flag, so the failure is a clear field message instead of
+	* a raw UNIQUE-constraint write error.
+	*/
+	unique() {
+		return this.add({ kind: "unique" });
+	}
+	/**
+	* For a `relationship` field: the referenced id must exist in the related
+	* collection (DB-backed; skipped client-side).
+	*/
+	reference() {
+		return this.add({ kind: "reference" });
+	}
+	custom(fn) {
+		return this.add({
+			kind: "custom",
+			fn
+		});
+	}
+	/** Internal: the accumulated checks, read by {@link validateDocument}. */
+	toChecks() {
+		return this.checks;
+	}
+};
+/** Fresh, empty rule — the root of a chain. */
+function rule() {
+	return new Rule();
+}
+/**
+* Identity helper mirroring Sanity's `defineField` — returns the field
+* config unchanged but gives editors autocomplete and a single, greppable
+* call site for field definitions. Optional: a plain object literal is still
+* a valid field.
+*/
+function defineField(field) {
+	return field;
+}
+function resolveChecks(field) {
+	if (!field.validation) return [];
+	const built = field.validation(new Rule());
+	return (Array.isArray(built) ? built : [built]).flatMap((r) => r.toChecks());
+}
+function isEmpty(value) {
+	return value === void 0 || value === null || typeof value === "string" && value.length === 0;
+}
+function sizeOf(value) {
+	if (typeof value === "string") return {
+		size: value.length,
+		unit: "character"
+	};
+	if (Array.isArray(value)) return {
+		size: value.length,
+		unit: "item"
+	};
+	if (typeof value === "number") return {
+		size: value,
+		unit: ""
+	};
+	return null;
+}
+/**
+* Evaluate every field's validation rules against `doc`, returning all
+* violations (both errors and warnings). `doc` is the nested document; field
+* values are read from its flattened form so group subfields validate too.
+*/
+async function validateDocument(config, doc, options) {
+	const flatFields = flattenFields(config.fields);
+	const flatDoc = flattenDocShallow(config, doc);
+	const violations = [];
+	for (const [path, field] of Object.entries(flatFields)) {
+		if (options.onlyFields && !options.onlyFields.has(path)) continue;
+		const checks = resolveChecks(field);
+		if (checks.length === 0) continue;
+		const value = flatDoc[path];
+		const ctx = {
+			document: doc,
+			path,
+			operation: options.operation,
+			...options.id !== void 0 ? { id: options.id } : {}
+		};
+		for (const check of checks) {
+			const violation = await evaluateCheck(check, value, field, ctx, options);
+			if (violation) violations.push(violation);
+		}
+	}
+	return violations;
+}
+function flattenDocShallow(config, doc) {
+	return Object.values(config.fields).some((f) => f.type === "group") ? flattenDoc(config.fields, doc) : doc;
+}
+async function evaluateCheck(check, value, field, ctx, options) {
+	const fail = (defaultMessage) => ({
+		path: ctx.path,
+		message: check.message ?? `${ctx.path} must ${defaultMessage}`,
+		severity: check.severity ?? "error"
+	});
+	switch (check.kind) {
+		case "required": return isEmpty(value) ? fail("not be empty") : null;
+		case "min": {
+			if (isEmpty(value)) return null;
+			const s = sizeOf(value);
+			if (s && s.size < check.n) return fail(s.unit ? `have at least ${check.n} ${s.unit}${check.n === 1 ? "" : "s"}` : `be at least ${check.n}`);
+			return null;
+		}
+		case "max": {
+			if (isEmpty(value)) return null;
+			const s = sizeOf(value);
+			if (s && s.size > check.n) return fail(s.unit ? `have at most ${check.n} ${s.unit}${check.n === 1 ? "" : "s"}` : `be at most ${check.n}`);
+			return null;
+		}
+		case "length": {
+			if (isEmpty(value)) return null;
+			const s = sizeOf(value);
+			if (s?.unit && s.size !== check.n) return fail(`be exactly ${check.n} ${s.unit}${check.n === 1 ? "" : "s"}`);
+			return null;
+		}
+		case "regex":
+			if (isEmpty(value)) return null;
+			if (typeof value !== "string" || !check.re.test(value)) return fail(check.label);
+			return null;
+		case "integer":
+			if (isEmpty(value)) return null;
+			return typeof value === "number" && Number.isInteger(value) ? null : fail("be an integer");
+		case "positive":
+			if (isEmpty(value)) return null;
+			return typeof value === "number" && value > 0 ? null : fail("be a positive number");
+		case "unique": return evaluateUnique(value, ctx, options, check);
+		case "reference": return evaluateReference(value, field, ctx, options, check);
+		case "custom": {
+			const result = await check.fn(value, ctx);
+			if (result === true || result === void 0) return null;
+			if (result === false) return fail("be valid");
+			if (typeof result === "string") return {
+				path: ctx.path,
+				message: result,
+				severity: check.severity ?? "error"
+			};
+			return {
+				path: ctx.path,
+				message: result.message,
+				severity: result.severity ?? check.severity ?? "error"
+			};
+		}
+	}
+}
+async function evaluateUnique(value, ctx, options, check) {
+	if (isEmpty(value) || !options.db || !options.table) return null;
+	const column = options.table[ctx.path];
+	if (!column) return null;
+	const where = ctx.id !== void 0 ? and(eq(column, value), ne(options.table.id, ctx.id)) : eq(column, value);
+	if ((await options.db.select({ id: options.table.id }).from(options.table).where(where).limit(1)).length > 0) return {
+		path: ctx.path,
+		message: check.message ?? `${ctx.path} "${String(value)}" is already taken`,
+		severity: check.severity ?? "error"
+	};
+	return null;
+}
+async function evaluateReference(value, field, ctx, options, check) {
+	if (isEmpty(value) || !options.db || !options.registry) return null;
+	if (field.type !== "relationship") return null;
+	const target = options.registry.tables[field.relationTo];
+	if (!target) return null;
+	if ((await options.db.select({ id: target.id }).from(target).where(eq(target.id, value)).limit(1)).length === 0) return {
+		path: ctx.path,
+		message: check.message ?? `${ctx.path} references a "${field.relationTo}" that does not exist`,
+		severity: check.severity ?? "error"
+	};
+	return null;
+}
+/**
+* Run {@link validateDocument} and throw {@link CadmusValidationError} if any
+* `"error"`-severity violations are found. Warnings are returned (never
+* thrown) so a caller can still surface them. The thrown error's message is
+* a readable, joined summary of every blocking violation.
+*/
+async function assertValid(config, doc, options) {
+	const violations = await validateDocument(config, doc, options);
+	const errors = violations.filter((v) => v.severity === "error");
+	if (errors.length > 0) {
+		const summary = errors.map((v) => v.message).join("; ");
+		throw new CadmusValidationError(`Validation failed for collection "${config.slug}": ${summary}`, violations);
+	}
+	return violations;
+}
+//#endregion
 //#region src/cms/localApi.ts
 function validateRequiredFields(config, input) {
 	for (const [key, field] of Object.entries(flattenFields(config.fields))) {
@@ -429,9 +769,16 @@ function createLocalApi(db, table, config, registry) {
 		},
 		async create(context, input) {
 			await checkAccess(config, "create", context);
-			const flatData = toFlatDoc(await runBeforeChange(config, input));
+			const data = await runBeforeChange(config, input);
+			const flatData = toFlatDoc(data);
 			validateRequiredFields(config, flatData);
 			rejectUnknownFields(config, flatData);
+			await assertValid(config, data, {
+				operation: "create",
+				db,
+				table,
+				registry
+			});
 			let row;
 			try {
 				const [inserted] = await db.insert(table).values(flatData).returning();
@@ -446,8 +793,17 @@ function createLocalApi(db, table, config, registry) {
 		},
 		async update(context, id, input) {
 			await checkAccess(config, "update", context);
-			const flatData = toFlatDoc(await runBeforeChange(config, input));
+			const data = await runBeforeChange(config, input);
+			const flatData = toFlatDoc(data);
 			rejectUnknownFields(config, flatData);
+			await assertValid(config, data, {
+				operation: "update",
+				id,
+				onlyFields: new Set(Object.keys(flatData)),
+				db,
+				table,
+				registry
+			});
 			let row;
 			try {
 				const [updated] = await db.update(table).set(flatData).where(eq(idColumn, id)).returning();
@@ -510,6 +866,13 @@ function createVersionedLocalApi(db, table, versionsTable, config, registry) {
 			validateRequiredFields(config, data);
 			rejectUnknownFields(config, data);
 			const parentId = versionRecord.parentId;
+			await assertValid(config, data, {
+				operation: "update",
+				id: parentId,
+				db,
+				table,
+				registry
+			});
 			let doc;
 			try {
 				const [row] = await db.update(table).set({
@@ -659,6 +1022,89 @@ function generateSchemaSource(config) {
 	].join("\n");
 }
 //#endregion
+//#region src/cms/structure.ts
+/**
+* Cadmea's Structure Builder — the framework half of issue #12.
+*
+* Adopts Sanity's `sanity/structure` idea (pattern, not code): **decouple
+* the admin nav from the raw collection list.** Instead of mapping every
+* `config.collections` entry to an `/admin/<slug>` link — which surfaces
+* system/log tables as editable links and produces dead links — the sidebar
+* renders from an explicit, grouped structure derived here from each
+* collection's `admin` hints (see {@link CollectionAdminConfig}) plus
+* optional per-slug overrides supplied at the call site.
+*
+* Pure data in / pure data out: no SolidJS, no DOM, no server imports — so
+* it's safe to import from a client studio component (e.g. the site's
+* `PanelNav`) and trivially testable.
+*/
+/** Default group heading for collections that don't declare `admin.group`. */
+const DEFAULT_STUDIO_GROUP = "Content";
+function capitalize(value) {
+	return value.length === 0 ? value : value[0].toUpperCase() + value.slice(1);
+}
+function resolveAdmin(collection, overrides) {
+	return {
+		...collection.admin,
+		...overrides?.[collection.slug]
+	};
+}
+/**
+* Build the studio sidebar structure from a resolved CMS config.
+*
+* - Hidden collections (`admin.hidden`) are dropped entirely.
+* - Each remaining collection is placed in its `admin.group` (or
+*   {@link DEFAULT_STUDIO_GROUP}).
+* - Within a group, items sort by `admin.order` (ascending; unset sorts
+*   after set), then by their original position in `config.collections` —
+*   so config order is the stable tiebreaker.
+* - Groups render in `options.groupOrder` first, then first-appearance
+*   order for the rest.
+*
+* The input is expected to be the *resolved* config (post-plugins), since
+* that's what carries plugin-injected collections like `products`.
+*/
+function buildStudioStructure(config, options = {}) {
+	const basePath = options.basePath ?? "/admin";
+	const groupOrder = options.groupOrder ?? [];
+	const ranked = config.collections.map((collection, index) => ({
+		collection,
+		index,
+		admin: resolveAdmin(collection, options.overrides)
+	}));
+	const groups = /* @__PURE__ */ new Map();
+	const appearance = [];
+	for (const { collection, admin } of ranked) {
+		if (admin.hidden) continue;
+		const title = admin.group ?? "Content";
+		if (!groups.has(title)) {
+			groups.set(title, []);
+			appearance.push(title);
+		}
+		groups.get(title).push({
+			slug: collection.slug,
+			label: admin.label ?? capitalize(collection.slug),
+			href: `${basePath}/${collection.slug}`,
+			readOnly: admin.readOnly ?? false,
+			singleton: admin.singleton ?? false,
+			...admin.icon ? { icon: admin.icon } : {}
+		});
+	}
+	const meta = new Map(ranked.map(({ collection, index, admin }) => [collection.slug, {
+		order: admin.order ?? Number.POSITIVE_INFINITY,
+		index
+	}]));
+	for (const items of groups.values()) items.sort((a, b) => {
+		const ma = meta.get(a.slug);
+		const mb = meta.get(b.slug);
+		return ma.order - mb.order || ma.index - mb.index;
+	});
+	return [...groupOrder.filter((title) => groups.has(title)), ...appearance.filter((title) => !groupOrder.includes(title))].map((title) => ({
+		title,
+		items: groups.get(title)
+	}));
+}
+//#endregion
 //#region src/cms/webhooks.ts
 /**
 * Builds an `afterChange` hook that enqueues a `WebhookMessage` for every
@@ -738,6 +1184,6 @@ async function deliverWebhookMessage(message) {
 	if (!response.ok) throw new CadmusQueueError(`Webhook delivery to "${message.url}" returned status ${response.status}`);
 }
 //#endregion
-export { can, cmsConfigToSchema, collectionSearchTableName, collectionSearchTableSQL, collectionToTable, collectionVersionsTable, createLocalApi, createVersionedLocalApi, createWebhookHook, defineCmsConfig, defineCollection, deliverWebhookMessage, extractSearchText, flattenDoc, flattenFields, generateSchemaSource, getCollectionsMeta, getRegisteredApi, nestDoc, relationshipJoinTables };
+export { DEFAULT_STUDIO_GROUP, Rule, assertValid, buildStudioStructure, can, cmsConfigToSchema, collectionSearchTableName, collectionSearchTableSQL, collectionToTable, collectionVersionsTable, createBlockRegistry, createLocalApi, createVersionedLocalApi, createWebhookHook, defineCmsConfig, defineCollection, defineField, deliverWebhookMessage, extractSearchText, flattenDoc, flattenFields, generateSchemaSource, getCollectionsMeta, getRegisteredApi, nestDoc, relationshipJoinTables, renderBlocksToString, rule, validateDocument };
 
 //# sourceMappingURL=index.js.map