emdash 0.40.0 → 0.41.0

package/src/api/handlers/snapshot.ts

@@ -80,6 +80,8 @@ export function parsePreviewSignatureHeader(
 // ── Media URL rewriting ─────────────────────────────────────────
 
 const MEDIA_FILE_PREFIX = "/_emdash/api/media/file/";
+const MEDIA_FILE_SUFFIX = /[?#]/;
+const EXTERNAL_OR_ROOT_URL = /^(?:[a-z][a-z0-9+.-]*:|\/)/i;
 
 /**
  * Parse a JSON string value and inject `src` for local media objects.
@@ -179,12 +181,59 @@ const SYSTEM_TABLES = [
 	"_emdash_widgets",
 	"_emdash_seo",
 	"_emdash_migrations",
-	"taxonomies",
 	"content_taxonomies",
-	"media",
+	"taxonomies",
 	"options",
+	"media",
 	"revisions",
-];
+] as const;
+
+type SystemTable = (typeof SYSTEM_TABLES)[number];
+type PublishedTablePolicy = "full" | "content-linked" | "omit";
+
+/**
+ * Published snapshots are available to preview-signature callers, so every
+ * system table must be classified explicitly. Adding a snapshot table without
+ * choosing a policy is a type error rather than an accidental data export.
+ */
+const PUBLISHED_TABLE_POLICIES: Record<SystemTable, PublishedTablePolicy> = {
+	_emdash_block_types: "full",
+	_emdash_block_type_versions: "full",
+	_emdash_collections: "full",
+	_emdash_fields: "full",
+	_emdash_taxonomy_defs: "full",
+	_emdash_taxonomy_def_groups: "full",
+	_emdash_menus: "full",
+	_emdash_menu_items: "content-linked",
+	_emdash_sections: "full",
+	_emdash_widget_areas: "full",
+	_emdash_widgets: "full",
+	_emdash_seo: "content-linked",
+	_emdash_migrations: "full",
+	content_taxonomies: "content-linked",
+	taxonomies: "content-linked",
+	options: "content-linked",
+	media: "content-linked",
+	revisions: "omit",
+};
+
+const SYSTEM_TABLE_SET: ReadonlySet<string> = new Set(SYSTEM_TABLES);
+
+function isSystemTable(tableName: string): tableName is SystemTable {
+	return SYSTEM_TABLE_SET.has(tableName);
+}
+
+interface PublishedContentReferences {
+	ids: Set<string>;
+	translationGroups: Set<string>;
+}
+
+interface PublishedProjection {
+	content: Map<string, PublishedContentReferences>;
+	taxonomyGroups: Set<string>;
+	mediaIds: Set<string>;
+	mediaStorageKeys: Set<string>;
+}
 
 /**
  * Table name prefixes excluded from snapshots (auth/security data).
@@ -256,6 +305,191 @@ function normalizeRows(
 	return rows;
 }
 
+function createPublishedProjection(): PublishedProjection {
+	return {
+		content: new Map(),
+		taxonomyGroups: new Set(),
+		mediaIds: new Set(),
+		mediaStorageKeys: new Set(),
+	};
+}
+
+function readString(value: unknown): string | null {
+	return typeof value === "string" && value.length > 0 ? value : null;
+}
+
+function recordPublishedContent(
+	projection: PublishedProjection,
+	tableName: string,
+	rows: Record<string, unknown>[],
+): void {
+	const references: PublishedContentReferences = {
+		ids: new Set(),
+		translationGroups: new Set(),
+	};
+	for (const row of rows) {
+		const id = readString(row.id);
+		const translationGroup = readString(row.translation_group);
+		if (id) references.ids.add(id);
+		if (translationGroup) references.translationGroups.add(translationGroup);
+	}
+	projection.content.set(tableName.slice("ec_".length), references);
+}
+
+function isPublishedContentReference(
+	projection: PublishedProjection,
+	collection: unknown,
+	reference: unknown,
+): boolean {
+	const collectionName = readString(collection);
+	const id = readString(reference);
+	if (!collectionName || !id) return false;
+	const references = projection.content.get(collectionName);
+	return references?.ids.has(id) === true || references?.translationGroups.has(id) === true;
+}
+
+function collectMediaReferences(value: unknown, projection: PublishedProjection): void {
+	if (typeof value === "string") {
+		if (value.startsWith(MEDIA_FILE_PREFIX)) {
+			const storageKey = value.slice(MEDIA_FILE_PREFIX.length).split(MEDIA_FILE_SUFFIX, 1)[0];
+			if (storageKey) projection.mediaStorageKeys.add(storageKey);
+			return;
+		}
+		const trimmed = value.trimStart();
+		if (trimmed.startsWith("{") || trimmed.startsWith("[")) {
+			try {
+				collectMediaReferences(JSON.parse(value), projection);
+			} catch {
+				// Not structured data.
+			}
+		}
+		return;
+	}
+	if (Array.isArray(value)) {
+		for (const item of value) collectMediaReferences(item, projection);
+		return;
+	}
+	if (!isRecord(value)) return;
+
+	const mediaId = readString(value.mediaId);
+	if (mediaId) projection.mediaIds.add(mediaId);
+
+	const provider = readString(value.provider);
+	const meta = isRecord(value.meta) ? value.meta : null;
+	const localMediaId = readString(value.id);
+	if ((provider === "local" || (!provider && meta)) && localMediaId) {
+		projection.mediaIds.add(localMediaId);
+	}
+	const storageKey = readString(value.storageKey) ?? readString(meta?.storageKey);
+	if (storageKey) projection.mediaStorageKeys.add(storageKey);
+
+	const asset = isRecord(value.asset) ? value.asset : null;
+	const assetRef = readString(asset?._ref);
+	if (assetRef) {
+		projection.mediaIds.add(assetRef);
+		projection.mediaStorageKeys.add(assetRef);
+	}
+
+	for (const child of Object.values(value)) collectMediaReferences(child, projection);
+}
+
+function projectTaxonomyRows(
+	rows: Record<string, unknown>[],
+	projection: PublishedProjection,
+): Record<string, unknown>[] {
+	const includedGroups = new Set(projection.taxonomyGroups);
+	const includedIds = new Set(projection.taxonomyGroups);
+	let changed = true;
+	while (changed) {
+		changed = false;
+		for (const row of rows) {
+			const id = readString(row.id);
+			const group = readString(row.translation_group);
+			if (!id) continue;
+			if (includedIds.has(id) || (group && includedGroups.has(group))) {
+				if (!includedIds.has(id)) {
+					includedIds.add(id);
+					changed = true;
+				}
+				if (group && !includedGroups.has(group)) {
+					includedGroups.add(group);
+					changed = true;
+				}
+				const parentId = readString(row.parent_id);
+				if (parentId && !includedIds.has(parentId)) {
+					includedIds.add(parentId);
+					changed = true;
+				}
+			}
+		}
+	}
+	return rows.filter((row) => {
+		const id = readString(row.id);
+		const group = readString(row.translation_group);
+		return (id && includedIds.has(id)) || (group && includedGroups.has(group));
+	});
+}
+
+function projectPublishedRows(
+	tableName: SystemTable,
+	rows: Record<string, unknown>[],
+	projection: PublishedProjection,
+): Record<string, unknown>[] {
+	switch (tableName) {
+		case "_emdash_seo":
+			return rows.filter((row) => {
+				const published = isPublishedContentReference(projection, row.collection, row.content_id);
+				if (!published) return false;
+				const image = readString(row.seo_image);
+				if (image) {
+					collectMediaReferences(image, projection);
+					if (!EXTERNAL_OR_ROOT_URL.test(image)) {
+						projection.mediaIds.add(image);
+						projection.mediaStorageKeys.add(image);
+					}
+				}
+				return true;
+			});
+		case "content_taxonomies":
+			return rows.filter((row) => {
+				const published = isPublishedContentReference(projection, row.collection, row.entry_id);
+				const taxonomyGroup = readString(row.taxonomy_id);
+				if (published && taxonomyGroup) projection.taxonomyGroups.add(taxonomyGroup);
+				return published;
+			});
+		case "taxonomies":
+			return projectTaxonomyRows(rows, projection);
+		case "_emdash_menu_items":
+			return rows.filter((row) => {
+				const type = readString(row.type);
+				const referenceId = readString(row.reference_id);
+				if (!referenceId || type === "custom") return true;
+				if (type === "taxonomy") {
+					projection.taxonomyGroups.add(referenceId);
+					return true;
+				}
+				if (type === "collection" && !row.reference_id) return true;
+				const collection =
+					readString(row.reference_collection) ??
+					(type === "post" || type === "page" ? `${type}s` : null);
+				return isPublishedContentReference(projection, collection, referenceId);
+			});
+		case "media":
+			return rows.filter((row) => {
+				const id = readString(row.id);
+				const storageKey = readString(row.storage_key);
+				return (
+					(id !== null && projection.mediaIds.has(id)) ||
+					(storageKey !== null && projection.mediaStorageKeys.has(storageKey))
+				);
+			});
+		case "options":
+			return rows;
+		default:
+			return [];
+	}
+}
+
 export interface GenerateSnapshotOptions {
 	/** Include draft and scheduled content (default: false) */
 	includeDrafts?: boolean;
@@ -288,6 +522,8 @@ export async function generateSnapshot(
 	const includeTrashed = options?.includeTrashed ?? false;
 	const optionPrefixes = options?.optionPrefixes ?? SAFE_OPTIONS_PREFIXES;
 	const optionKeys = new Set(options?.optionKeys);
+	const publishedOnly = !includeDrafts && !includeTrashed;
+	const publishedProjection = createPublishedProjection();
 
 	const contentTables = await listTablesLike(db, "ec_%");
 
@@ -340,6 +576,12 @@ export async function generateSnapshot(
 					`.execute(db)
 				).rows;
 			}
+		} else if (
+			publishedOnly &&
+			isSystemTable(tableName) &&
+			PUBLISHED_TABLE_POLICIES[tableName] === "omit"
+		) {
+			rows = [];
 		} else if (tableName === "options") {
 			rows = (
 				await sql<Record<string, unknown>>`
@@ -357,6 +599,18 @@ export async function generateSnapshot(
 			).rows;
 		}
 
+		if (publishedOnly) {
+			if (tableName.startsWith("ec_")) {
+				recordPublishedContent(publishedProjection, tableName, rows);
+			} else if (
+				isSystemTable(tableName) &&
+				PUBLISHED_TABLE_POLICIES[tableName] === "content-linked"
+			) {
+				rows = projectPublishedRows(tableName, rows, publishedProjection);
+			}
+			for (const row of rows) collectMediaReferences(row, publishedProjection);
+		}
+
 		if (rows.length > 0) {
 			tables[tableName] = normalizeRows(rows, types);
 		}

package/src/api/handlers/staged-references.ts

@@ -0,0 +1,142 @@
+import type { Kysely } from "kysely";
+
+import { RelationRepository } from "../../database/repositories/relation.js";
+import { RevisionRepository } from "../../database/repositories/revision.js";
+import type { Database } from "../../database/types.js";
+import { STAGED_REFERENCES_KEY, type StagedReferences } from "../../references/staged.js";
+import type { ApiResult } from "../types.js";
+import { validateOppositeSideLimit, writeReferenceSelection } from "./relations.js";
+import {
+	referenceFieldConstraints,
+	validateReferenceSelection,
+	type ReferenceFieldConstraints,
+} from "./validate-references.js";
+
+export {
+	mergeStagedReferences,
+	pageStagedGroups,
+	readStagedReferences,
+	REFERENCE_PAGE_LIMIT,
+	REFERENCE_PAGE_MAX_LIMIT,
+	STAGED_REFERENCES_KEY,
+} from "../../references/staged.js";
+export type { PageOfGroups, StagedReferences } from "../../references/staged.js";
+
+/** One bound field's live selection as translation groups. */
+async function liveFieldSelection(
+	repo: RelationRepository,
+	field: ReferenceFieldConstraints,
+	entryGroup: string,
+): Promise<string[]> {
+	const links =
+		field.relationSide === "child"
+			? await repo.getParents(field.relation, entryGroup)
+			: await repo.getChildren(field.relation, entryGroup);
+	return links.map((link) => (field.relationSide === "child" ? link.parentGroup : link.childGroup));
+}
+
+/**
+ * Re-check what publication is about to make live against the relation's current
+ * cardinality.
+ *
+ * A draft can sit unpublished across a schema edit that makes its field required
+ * or narrows the relation's limits, and across another entry claiming what it
+ * selected. It is publication — not the save that staged it — that has to hold
+ * the line on both ends. So this walks the collection's bound fields rather than
+ * the staged keys: a field added as required after the entry was written appears
+ * in no existing draft, and iterating `staged` would never reach it. A field the
+ * draft does stage needs no link read.
+ */
+export async function validateStagedReferences(
+	db: Kysely<Database>,
+	collection: string,
+	staged: StagedReferences,
+	entryGroup: string,
+): Promise<ApiResult<true>> {
+	const repo = new RelationRepository(db);
+	for (const field of (await referenceFieldConstraints(db, collection)).values()) {
+		const isStaged = Object.hasOwn(staged, field.slug);
+		const groups = isStaged
+			? (staged[field.slug] ?? [])
+			: await liveFieldSelection(repo, field, entryGroup);
+		const valid = validateReferenceSelection(field, groups);
+		if (!valid.success) return valid;
+
+		// Only a staged selection can have gone stale: a live one is already
+		// within the limits it was written under.
+		if (!isStaged || field.relationId === null) continue;
+		const far = await validateOppositeSideLimit(db, {
+			relationId: field.relationId,
+			farLimit: field.maxOpposite,
+			side: field.relationSide,
+			entryGroup,
+			groups,
+		});
+		if (!far.success) return far;
+	}
+	return { success: true, data: true };
+}
+
+/**
+ * The live selection, in the same shape a draft stages: every bound reference
+ * field on the collection, by field slug, as translation groups.
+ *
+ * One link read per bound field. Used where both selections have to be
+ * comparable — the live and draft sides of a compare — never on a render path.
+ */
+export async function liveReferenceSelection(
+	db: Kysely<Database>,
+	collection: string,
+	entryGroup: string,
+): Promise<StagedReferences> {
+	const repo = new RelationRepository(db);
+	const selection: StagedReferences = {};
+	for (const field of (await referenceFieldConstraints(db, collection)).values()) {
+		selection[field.slug] = await liveFieldSelection(repo, field, entryGroup);
+	}
+	return selection;
+}
+
+/**
+ * Record the complete live selection in the revision publication just made live.
+ *
+ * A draft stages only the fields its saves named, and a revision written from
+ * the columns stages none. Restoring either would otherwise leave whatever was
+ * published after it linked in the fields it does not carry.
+ */
+export async function recordPublishedReferences(
+	db: Kysely<Database>,
+	collection: string,
+	revisionId: string,
+	entryGroup: string,
+): Promise<void> {
+	const selection = await liveReferenceSelection(db, collection, entryGroup);
+	if (Object.keys(selection).length === 0) return;
+	await new RevisionRepository(db).mergeData(revisionId, { [STAGED_REFERENCES_KEY]: selection });
+}
+
+/**
+ * Promote a staged selection to live links.
+ *
+ * A field slug the collection no longer carries as a bound reference field is
+ * skipped: the revision outlived the field, and there is no relation left to
+ * write into.
+ */
+export async function applyStagedReferences(
+	db: Kysely<Database>,
+	collection: string,
+	entryGroup: string,
+	staged: StagedReferences,
+): Promise<void> {
+	const constraints = await referenceFieldConstraints(db, collection);
+	for (const [fieldSlug, groups] of Object.entries(staged)) {
+		const field = constraints.get(fieldSlug);
+		if (!field) continue;
+		await writeReferenceSelection(db, {
+			relation: field.relation,
+			side: field.relationSide,
+			entryGroup,
+			groups,
+		});
+	}
+}

package/src/api/handlers/validate-references.ts

@@ -0,0 +1,146 @@
+import type { Kysely } from "kysely";
+
+import type { Database } from "../../database/types.js";
+import { requestCached } from "../../request-cache.js";
+import type { ApiResult } from "../types.js";
+
+export interface ReferenceFieldConstraints {
+	/** Field slug — how the entry API addresses the selection. */
+	slug: string;
+	/** Relation slug the field binds to. */
+	relation: string;
+	/** Relation id, for the reads that address the link table directly. */
+	relationId: string | null;
+	/** Which end of the relation the field's own collection sits on. */
+	relationSide: "parent" | "child";
+	/** How many entries this side of the relation may hold. `null` is unlimited. */
+	maxSelected: number | null;
+	/** How many this field's selection may hand each entry it selects. */
+	maxOpposite: number | null;
+	required: boolean;
+}
+
+function validationError(message: string): ApiResult<never> {
+	return { success: false, error: { code: "VALIDATION_ERROR", message } };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null;
+}
+
+/**
+ * Every reference field on a collection that is bound to a relation, by field
+ * slug — the key the entry API takes a selection under.
+ */
+export function referenceFieldConstraints(
+	db: Kysely<Database>,
+	collection: string,
+): Promise<Map<string, ReferenceFieldConstraints>> {
+	return requestCached(`reference-field-constraints:${collection}`, async () => {
+		const fields = await db
+			.selectFrom("_emdash_fields")
+			.innerJoin("_emdash_collections", "_emdash_collections.id", "_emdash_fields.collection_id")
+			.select(["_emdash_fields.slug", "_emdash_fields.required", "_emdash_fields.validation"])
+			.where("_emdash_collections.slug", "=", collection)
+			.where("_emdash_fields.type", "=", "reference")
+			.execute();
+
+		// Cardinality lives on the relation, not the field: with both ends of a
+		// relation bindable, two fields carrying their own limits could disagree
+		// about one edge set. The field contributes only which end it views.
+		const relations = await db
+			.selectFrom("_emdash_relations")
+			.select(["id", "slug", "max_children_per_parent", "max_parents_per_child"])
+			.execute();
+		const limits = new Map(relations.map((r) => [r.slug, r]));
+
+		const constraints = new Map<string, ReferenceFieldConstraints>();
+		for (const field of fields) {
+			if (!field.validation) continue;
+
+			let parsed: unknown;
+			try {
+				parsed = JSON.parse(field.validation);
+			} catch {
+				continue;
+			}
+			if (!isRecord(parsed) || typeof parsed.relation !== "string") continue;
+
+			const relation = limits.get(parsed.relation);
+			const relationSide = parsed.relationSide === "child" ? "child" : "parent";
+			const onChildSide = relationSide === "child";
+
+			constraints.set(field.slug, {
+				slug: field.slug,
+				relation: parsed.relation,
+				relationId: relation?.id ?? null,
+				relationSide,
+				maxSelected: onChildSide
+					? (relation?.max_parents_per_child ?? null)
+					: (relation?.max_children_per_parent ?? null),
+				maxOpposite: onChildSide
+					? (relation?.max_children_per_parent ?? null)
+					: (relation?.max_parents_per_child ?? null),
+				required: field.required === 1,
+			});
+		}
+		return constraints;
+	});
+}
+
+/**
+ * The field viewing one end of a relation, for the relation-scoped routes, which
+ * address a relation rather than a field. At most one field binds each
+ * (relation, side), so this is unambiguous.
+ */
+export function constraintsForRelationSide(
+	constraints: Map<string, ReferenceFieldConstraints>,
+	relation: string,
+	side: "parent" | "child",
+): ReferenceFieldConstraints | undefined {
+	for (const field of constraints.values()) {
+		if (field.relation === relation && field.relationSide === side) return field;
+	}
+	return undefined;
+}
+
+export function validateReferenceSelection(
+	constraints: ReferenceFieldConstraints,
+	childIds: string[],
+): ApiResult<true> {
+	const max = constraints.maxSelected;
+	if (max !== null && childIds.length > max) {
+		return validationError(
+			max === 1
+				? `Field '${constraints.slug}' accepts a single reference, received ${childIds.length}.`
+				: `Field '${constraints.slug}' accepts at most ${max} references, received ${childIds.length}.`,
+		);
+	}
+	if (constraints.required && childIds.length === 0) {
+		return validationError(
+			`Field '${constraints.slug}' is required and must reference at least one entry.`,
+		);
+	}
+	return { success: true, data: true };
+}
+
+export async function validateRequiredReferencesPresent(
+	db: Kysely<Database>,
+	collection: string,
+	references: Record<string, string[]> | undefined,
+	translationOf: string | undefined,
+): Promise<ApiResult<true>> {
+	// References belong to a translation group, so a new locale row inherits
+	// the source group's existing edges when its payload omits them.
+	if (translationOf) return { success: true, data: true };
+
+	const constraints = await referenceFieldConstraints(db, collection);
+	for (const field of constraints.values()) {
+		if (!field.required) continue;
+		if (references && Object.hasOwn(references, field.slug)) continue;
+		return validationError(
+			`Field '${field.slug}' is required and must reference at least one entry.`,
+		);
+	}
+	return { success: true, data: true };
+}

package/src/api/schemas/content.ts

@@ -3,6 +3,7 @@ import { z } from "zod";
 import { SQL_BATCH_SIZE } from "../../utils/chunks.js";
 import { bylineSummarySchema, bylineCreditSchema, contentBylineInputSchema } from "./bylines.js";
 import { cursorPaginationQuery, httpUrl, localeCode } from "./common.js";
+import { referenceChildrenResponseSchema } from "./relations.js";
 
 // ---------------------------------------------------------------------------
 // Content: Input schemas
@@ -209,6 +210,10 @@ export const contentCreateBody = z
 			description:
 				"Taxonomy term assignments as { taxonomyName: [termSlug, ...] }, resolved in the entry's locale.",
 		}),
+		references: z.record(z.string(), z.array(z.string()).max(1000)).optional().meta({
+			description:
+				"Reference selections as { fieldSlug: [entryId, ...] }, in display order. Written as content-reference links in the same transaction as the entry. A field bound to the child end of its relation selects the entries pointing at this one, which carry no order.",
+		}),
 		publishedAt: contentDateOverride,
 		createdAt: contentDateOverride,
 		migrateBlocks: z.boolean().optional(),
@@ -234,6 +239,10 @@ export const contentUpdateBody = z
 			description:
 				"Replace taxonomy assignments as { taxonomyName: [termSlug, ...] }. Only named taxonomies are touched; pass an empty array to clear a taxonomy.",
 		}),
+		references: z.record(z.string(), z.array(z.string()).max(1000)).optional().meta({
+			description:
+				"Reference selections as { fieldSlug: [entryId, ...] }, in display order. Written as content-reference links in the same transaction as the entry. A field bound to the child end of its relation selects the entries pointing at this one, which carry no order.",
+		}),
 		publishedAt: contentDateOverride,
 		migrateBlocks: z.boolean().optional(),
 		replaceBlocks: z.boolean().optional(),
@@ -374,6 +383,10 @@ export const contentItemSchema = z
 		locale: z.string().nullable(),
 		translationGroup: z.string().nullable(),
 		seo: contentSeoSchema.optional(),
+		// First page of each reference field's selection, keyed by field slug. Only
+		// present when the editor GET path opts into hydration
+		// (`referenceOptions`); omitted otherwise, so it's optional here.
+		references: z.record(z.string(), referenceChildrenResponseSchema).optional(),
 	})
 	.meta({ id: "ContentItem" });