caracms 0.0.0-stage → 0.2.0

package/src/content-schema.ts

@@ -0,0 +1,166 @@
+/**
+ * The generated JSON Schemas (M8 Decision 14): one per collection, plus Site Settings and
+ * shared blocks, written to `schemas/` (`caracms schemas`, `init`, `validate --fix`, and
+ * `astro dev` at start). Each content file names its own with `$schema` (schema-key.ts),
+ * so an agent's or a person's editor checks and completes the file as it's typed.
+ *
+ * They describe the stored shapes (fields.ts, media-value.ts, rich-text.ts, seo.ts),
+ * strictly: a key the config doesn't know is refused, as `validate` reports it. They're a
+ * help for editing, never the check: `validate` judges content by the config itself
+ * (validate.ts), so a stale schema can't pass bad content. JSON Schema draft 2020-12.
+ *
+ * Pure (no file access): the CLI and the integration write what `siteSchemas` returns.
+ */
+import type { ResolvedCollection, ResolvedSite } from './config.ts';
+import type { Field, Fields } from './fields.ts';
+import { siteCollections } from './config.ts';
+import { SCHEMA_KEY, schemaFileName } from './schema-key.ts';
+
+type Schema = Record<string, unknown>;
+
+const DRAFT = 'https://json-schema.org/draft/2020-12/schema';
+const string: Schema = { type: 'string' };
+const strings: Schema = { type: 'array', items: string };
+const size: Schema = { type: 'number', exclusiveMinimum: 0 };
+const focal: Schema = { type: 'array', items: { type: 'number', minimum: 0, maximum: 1 }, minItems: 2, maxItems: 2 };
+
+const described = (schema: Schema, field: { label?: string; help?: string }): Schema => ({
+	...(field.label ? { title: field.label } : {}),
+	...(field.help ? { description: field.help } : {}),
+	...schema,
+});
+
+/** An object with exactly these keys allowed. */
+const closed = (properties: Record<string, Schema>, required: string[] = []): Schema => ({
+	type: 'object',
+	properties,
+	...(required.length ? { required } : {}),
+	additionalProperties: false,
+});
+
+const image: Schema = closed({ key: { type: 'string', minLength: 1 }, alt: string, decorative: { type: 'boolean' }, focal, w: size, h: size }, ['key']);
+const clip: Schema = closed(
+	{ video: { type: 'string', minLength: 1 }, play: { enum: ['loop', 'player'] }, poster: { type: 'number', minimum: 0 }, name: string, duration: size, w: size, h: size },
+	['video'],
+);
+/** An image slot with no alt (the brand's logo and icon, the share image). */
+const plainImage: Schema = closed({ key: { type: 'string', minLength: 1 }, w: size, h: size, focal }, ['key']);
+const seo: Schema = closed({ title: string, description: string, image: plainImage });
+
+function richText(headings: readonly string[], lists = true): Schema {
+	const kinds = ['p', ...headings];
+	const unit: Schema[] = [
+		...kinds.map((k) => closed({ [k]: string }, [k])),
+		// M9 Decision 11: a heading rich-text field is paragraphs only.
+		...(lists ? ['ul', 'ol'] : []).map((k) => closed({ [k]: strings }, [k])),
+	];
+	// A plain string reads as rich text too (rich-text.ts → "A plain string is read as rich text").
+	return { anyOf: [string, { type: 'array', items: { oneOf: unit } }] };
+}
+
+/** A field's stored value (fields.ts → parseField reads it; fieldToJson writes it). */
+export function fieldSchema(field: Field): Schema {
+	switch (field.kind) {
+		case 'text':
+			return described(string, field);
+		case 'lockup':
+			// Decision 10 (M2): the plain list, or `{ lines, phone }` once it has phone lines.
+			return described({ anyOf: [strings, closed({ lines: strings, phone: strings }, ['lines'])] }, field);
+		case 'select':
+			return described({ enum: field.options.map((o) => o.value) }, field);
+		case 'richText':
+			return described(richText(field.headings, !field.heading), field);
+		case 'link':
+			return described(field.addressOnly ? closed({ href: string }) : closed({ label: string, href: string }), field);
+		case 'buttons':
+			return described({ type: 'array', items: closed({ label: string, href: string, style: { enum: field.styles.map((s) => s.value) } }) }, field);
+		case 'toggle':
+			return described({ type: 'boolean' }, field);
+		case 'number':
+			return described({ type: ['number', 'null'] }, field);
+		case 'date':
+			return described({ anyOf: [{ type: 'string', pattern: '^\\d{4}-\\d{2}-\\d{2}$' }, { type: 'null' }] }, field);
+		case 'reference':
+			return described({ type: ['string', 'null'], description: `The path of a document in "${field.to}".` }, field);
+		case 'media': {
+			const kinds = field.only === 'image' ? [image] : field.only === 'video' ? [clip] : [image, clip];
+			return described({ anyOf: [...kinds, { type: 'null' }] }, field);
+		}
+		case 'list': {
+			const items = field.item ? fieldSchema(field.item) : fieldsObject(field.fields ?? {});
+			return described({ type: 'array', items }, field);
+		}
+		case 'group':
+			return described(fieldsObject(field.fields), field);
+	}
+}
+
+/** Fields stored as one object (a group, a list item of several fields), every key optional. */
+function fieldsObject(fields: Fields): Schema {
+	return closed(Object.fromEntries(Object.entries(fields).map(([key, f]) => [key, fieldSchema(f)])));
+}
+
+function blockDefs(site: Pick<ResolvedSite, 'blocks'>): Record<string, Schema> {
+	const defs: Record<string, Schema> = {};
+	for (const block of Object.values(site.blocks)) {
+		const properties: Record<string, Schema> = { type: { const: block.type } };
+		for (const [key, f] of Object.entries(block.fields)) properties[key] = fieldSchema(f);
+		defs[`block:${block.type}`] = { title: block.label, ...(block.help ? { description: block.help } : {}), ...closed(properties, ['type']) };
+	}
+	return defs;
+}
+
+/** Any of the site's blocks: `{ "type", …its fields }`. */
+const anyBlock = (site: Pick<ResolvedSite, 'blocks'>): Schema => ({ anyOf: Object.keys(site.blocks).map((type) => ({ $ref: `#/$defs/block:${type}` })) });
+
+/** A page's entry for a shared block (M5a Decision 8). */
+const sharedEntry: Schema = { description: 'A shared block, by its path in content/shared.', ...closed({ shared: { type: 'string', minLength: 1 }, type: string }, ['shared']) };
+
+function document(collection: ResolvedCollection, properties: Record<string, Schema>, required: string[], defs?: Record<string, Schema>): Schema {
+	return {
+		$schema: DRAFT,
+		title: collection.label,
+		...closed({ [SCHEMA_KEY]: string, title: string, ...properties }, required),
+		...(defs ? { $defs: defs } : {}),
+	};
+}
+
+/** A collection's schema (`schemas/<collection>.schema.json`, or the reserved two's names). */
+export function collectionSchema(site: Pick<ResolvedSite, 'blocks'>, collection: ResolvedCollection): Schema {
+	const own = Object.fromEntries(Object.entries(collection.fields ?? {}).map(([key, f]) => [key, fieldSchema(f)]));
+	switch (collection.kind) {
+		case 'sections':
+			// M9 Decision 7: `hidden: true` keeps the page off the site; absent, it's shown.
+			const hidden: Schema = { description: 'Hidden from the site: not served, not in the sitemap, still edited in /admin.', const: true };
+			return document(collection, { hidden, ...own, blocks: { type: 'array', items: { anyOf: [{ $ref: '#/$defs/shared' }, anyBlock(site)] } }, seo }, ['title', 'blocks'], { shared: sharedEntry, ...blockDefs(site) });
+		case 'fields':
+			return document(collection, { ...own, seo }, ['title']);
+		case 'shared':
+			return document(collection, { block: anyBlock(site) }, ['title', 'block'], blockDefs(site));
+		case 'settings':
+			return document(
+				collection,
+				{
+					editors: { ...strings, description: 'The email addresses of the people who can sign in to the editor.' },
+					brand: closed({ name: string, accent: string, logo: { anyOf: [plainImage, { type: 'null' }] }, icon: { anyOf: [plainImage, { type: 'null' }] } }),
+					seo,
+					googleTag: string,
+					formRecipients: { type: 'object', additionalProperties: strings },
+					redirects: { type: 'array', items: closed({ from: string, to: string }, ['from', 'to']) },
+					...own,
+				},
+				['title'],
+			);
+	}
+}
+
+/** Every schema file's name and schema, in the site's collection order, then shared blocks and Site Settings. */
+export function siteSchemas(site: Pick<ResolvedSite, 'blocks' | 'collections'>): Map<string, Schema> {
+	const out = new Map<string, Schema>();
+	for (const c of siteCollections(site)) out.set(schemaFileName(c), collectionSchema(site, c));
+	for (const c of Object.values(site.collections)) if (c.kind === 'shared' || c.kind === 'settings') out.set(schemaFileName(c), collectionSchema(site, c));
+	return out;
+}
+
+/** A schema file's text. */
+export const schemaText = (schema: Schema): string => `${JSON.stringify(schema, null, 2)}\n`;

package/src/content.ts

@@ -0,0 +1,422 @@
+/**
+ * The content reader: a collection's documents from its folder on disk.
+ *
+ * - **Read at request time, never imported** (Decision 5): plain `fs`, so dev keeps
+ *   seeing what's on disk once content is out of Vite's watch.
+ * - **Pure enough to be the drafts store's local implementation** (Phase 2): the
+ *   seam is `list`, `read` and `write`; `listDocuments` and `readDocument` are its
+ *   `list` and `read`, and `resolveDocumentFile` is the confinement check the
+ *   write route reuses. No caches, no module state.
+ * - **Pages nest** (Decision 8) in a collection with `nested: true`: the file's path
+ *   is the URL, `index.json` at the top is the collection's `urlBase`, and an
+ *   `index.json` any deeper is an error, listed with a warning and not opened.
+ * - **Order** (Decision 8): the reader provides it. `listDocuments` returns a nested
+ *   collection in tree order (each level: Home first, then alphabetical by title,
+ *   with a folder that has no page of its own sorted by its label), and a flat
+ *   collection alphabetically by title. `pageTree` builds the tree itself.
+ * - A file that isn't valid JSON, or has no `title`, is listed with a warning and
+ *   can't be opened (Decision 9).
+ * - **Two sources, one set of rules** (M4 Current state): the files come from a
+ *   ContentSource, the disk by default (`diskSource`), or live mode's in-memory
+ *   `drafts` copy (`filesSource`). Parsing, ordering and warnings are the same code
+ *   either way, so a document never reads differently in the two modes.
+ * - **Every kind of document** (M5a): a collection's kind says how its files parse
+ *   (document.ts → parseAnyDocument). The two reserved collections are read like any
+ *   other: `shared` is a flat folder of shared blocks, `settings` holds exactly one
+ *   document, `site-settings` (`content/site-settings.json`). Neither has URLs.
+ * - **"Used on"** (Decision 8): the full listing (every collection) gives each shared
+ *   block the documents whose block list has an entry for it (`usedOn`), from the
+ *   same source, so live mode's counts include autosaves.
+ */
+import { readdir, readFile } from 'node:fs/promises';
+import { isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { SETTINGS_PATH, type ResolvedCollection, type ResolvedSite } from './config.ts';
+import { titleCase } from './fields.ts';
+import { isBuiltInColumn } from './columns.ts';
+import { fieldsCover, sectionsCover, type CardCover } from './cards.ts';
+import { own, parseAnyDocument, type AnyDocument, type DocumentKind } from './document.ts';
+import { parseSource } from './json-source.ts';
+
+// Posts and tags, Decision 14: a route's reader on the disk (read.ts).
+export { contentReader } from './read.ts';
+// M8 trial (item 1): Site Settings for a site's own routes, as the page component gets them.
+export { siteSettings } from './read.ts';
+
+export type WarningCode = 'invalid-json' | 'no-title' | 'nested-index';
+
+export interface DocumentWarning {
+	code: WarningCode;
+	/** A plain sentence for the editor's list. */
+	message: string;
+}
+
+export interface DocumentEntry {
+	collection: string;
+	/** The kind of document (its collection's kind, M5a). The reader always sets it; absent reads as `sections`. */
+	kind?: DocumentKind;
+	/**
+	 * The document's path inside its collection's folder, `/`-separated, without
+	 * `.json`: `index`, `about`, `services/branding`, `my-first-post`. With the
+	 * collection, it's the document's identity (and its `/admin/<collection>/<path>`).
+	 */
+	path: string;
+	/** The file, relative to the site's root, `/`-separated. */
+	file: string;
+	/** The page's URL: `/`, `/services/branding`, `/journal/my-first-post`. Null for a nested `index.json`. */
+	url: string | null;
+	/** The document's `title`, or `''` if it has none or can't be read. */
+	title: string;
+	/** The title, or the file name title-cased when there's no title: what the editor lists. */
+	label: string;
+	/** Set when the file can't be opened. */
+	warning: DocumentWarning | null;
+	/**
+	 * M9 Decision 7: hidden from the site, by the page's own `"hidden": true` or (`hiddenBy`, the
+	 * path of the hidden page above it) a page it's nested under. A site's routes, the sitemap and
+	 * `contentReader().documents()` leave it out; the editor lists it, marked. Never the home page.
+	 */
+	hidden?: true;
+	hiddenBy?: string;
+	/** A section builder's shared-block entries, by shared block path, in block order, once each (Decision 8). Absent otherwise. */
+	uses?: string[];
+	/** A shared block: its block's type (`''` when it has none). Absent otherwise. */
+	blockType?: string;
+	/**
+	 * A shared block, in a listing of every collection: the documents whose block list
+	 * has an entry for it, in listing order (Decision 8's "used on"). Absent otherwise.
+	 */
+	usedOn?: { collection: string; path: string }[];
+	/**
+	 * A list-of-fields document whose collection names table `columns` (pre-M7 polish):
+	 * those fields' values, as parsed, so the editor's table draws without opening each.
+	 * Absent otherwise.
+	 */
+	columns?: Record<string, unknown>;
+	/**
+	 * M6c (G5): in a collection with the List / Grid switch, the document's card picture
+	 * before it's signed (cards.ts, Decision 14): absent when it has none (a text card).
+	 * The editor's listing swaps it for signed URLs (editor/server/cards.ts) on the way out.
+	 */
+	cover?: CardCover;
+}
+
+export interface ReadDocument {
+	entry: DocumentEntry;
+	/** The file's text exactly as read: the serializer's base (serialize.ts → applyDocumentEdits). */
+	text: string;
+	document: AnyDocument;
+}
+
+export type DocumentErrorCode = WarningCode | 'not-found' | 'bad-path' | 'unknown-collection';
+
+export class DocumentError extends Error {
+	readonly code: DocumentErrorCode;
+	constructor(code: DocumentErrorCode, message: string) {
+		super(message);
+		this.name = 'DocumentError';
+		this.code = code;
+	}
+}
+
+const posix = (p: string) => p.split(sep).join('/');
+
+/**
+ * Where the reader's files come from. Paths are absolute, as on disk; an in-memory
+ * source maps them back to the site's own relative paths.
+ */
+export interface ContentSource {
+	/** A file's text, or null when it doesn't exist. */
+	readText(file: string): Promise<string | null>;
+	/**
+	 * The `.json` file names under a folder, relative to it and `/`-separated, in any
+	 * order: every depth when `recursive`, else only the folder's own. Empty when the
+	 * folder doesn't exist.
+	 */
+	listJson(dir: string, recursive: boolean): Promise<string[]>;
+}
+
+/** The content files on disk (M3). */
+export const diskSource: ContentSource = {
+	async readText(file) {
+		try {
+			return await readFile(file, 'utf8');
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code === 'ENOENT') return null;
+			throw error;
+		}
+	},
+	async listJson(dir, recursive) {
+		let names: string[];
+		try {
+			names = (await readdir(dir, { recursive })) as string[];
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code === 'ENOENT') return [];
+			throw error;
+		}
+		return names.map(posix).filter((n) => n.endsWith('.json'));
+	},
+};
+
+/**
+ * Files held in memory, keyed by their path relative to the site's root
+ * (`content/pages/index.json`): live mode's `drafts` copy. `files` is read on every
+ * call, so the source follows a copy that changes under it.
+ */
+export function filesSource(root: string, files: () => ReadonlyMap<string, string>): ContentSource {
+	const rel = (file: string) => posix(relative(root, file));
+	return {
+		async readText(file) {
+			return files().get(rel(file)) ?? null;
+		},
+		async listJson(dir, recursive) {
+			const folder = rel(dir);
+			const prefix = folder === '' ? '' : `${folder}/`;
+			const out: string[] = [];
+			for (const path of files().keys()) {
+				if (!path.startsWith(prefix) || !path.endsWith('.json')) continue;
+				const inside = path.slice(prefix.length);
+				if (!recursive && inside.includes('/')) continue;
+				out.push(inside);
+			}
+			return out;
+		},
+	};
+}
+
+/** A document path's URL in its collection (`index` at the top of a nested collection is its base); null in the reserved collections. */
+export function documentUrl(collection: ResolvedCollection, path: string): string | null {
+	if (collection.urlBase === null) return null;
+	if (collection.nested) {
+		if (path === 'index') return collection.urlBase;
+		if (path.endsWith('/index')) return null;
+	}
+	return collection.urlBase + path;
+}
+
+/**
+ * The absolute file for a document path, confined to the collection's folder.
+ * Refuses (DocumentError 'bad-path') an absolute path, `..`, an empty segment, a
+ * backslash, a dot-file, or anything that resolves outside the folder; and an
+ * undeclared collection ('unknown-collection'). Phase 2's write route uses this as
+ * its security check (Decision 5).
+ */
+export function resolveDocumentFile(site: Pick<ResolvedSite, 'collections'>, collectionName: string, path: string): string {
+	const collection = own(site.collections, collectionName);
+	if (!collection) {
+		throw new DocumentError('unknown-collection', `No collection "${collectionName}" is declared.`);
+	}
+	const bad = () => new DocumentError('bad-path', `"${path}" isn't a document path in ${collectionName}.`);
+	if (typeof path !== 'string' || path.length === 0 || isAbsolute(path) || path.includes('\\') || path.includes('\0')) throw bad();
+	const segments = path.split('/');
+	if (segments.some((s) => s === '' || s === '.' || s === '..' || s.startsWith('.'))) throw bad();
+	if (!collection.nested && segments.length > 1) throw bad();
+	// Site Settings is one document (M4 Decision 15), however its folder is shared.
+	if (collection.kind === 'settings' && path !== SETTINGS_PATH) throw bad();
+	const file = resolve(collection.dir, `${path}.json`);
+	const inside = relative(collection.dir, file);
+	if (inside.startsWith('..') || isAbsolute(inside)) throw bad();
+	return file;
+}
+
+/** Every document in one collection, or in all of them (in config order), with warnings, in the editor's order. */
+export async function listDocuments(
+	site: Pick<ResolvedSite, 'collections' | 'root' | 'blocks'>,
+	collectionName?: string,
+	source: ContentSource = diskSource,
+): Promise<DocumentEntry[]> {
+	const names = collectionName ? [collectionName] : Object.keys(site.collections);
+	const all: DocumentEntry[] = [];
+	for (const name of names) {
+		const collection = own(site.collections, name);
+		if (!collection) throw new DocumentError('unknown-collection', `No collection "${name}" is declared.`);
+		const paths = await documentPaths(collection, source);
+		const entries = (await Promise.all(paths.map((path) => entryFor(site, collection, path, source)))).filter((e) => e !== null);
+		if (collection.nested) hideChildren(entries);
+		all.push(...(collection.nested ? flattenTree(pageTree(entries)) : entries.sort(byLabel)));
+	}
+	if (!collectionName) {
+		// Decision 8's "used on": every document whose block list has an entry for the shared block.
+		for (const entry of all) {
+			if (entry.kind !== 'shared') continue;
+			entry.usedOn = all.filter((d) => d.uses?.includes(entry.path)).map((d) => ({ collection: d.collection, path: d.path }));
+		}
+	}
+	return all;
+}
+
+/** M9 Decision 7: a hidden page's children are hidden with it; `hiddenBy` names the topmost hidden page above. */
+function hideChildren(entries: DocumentEntry[]): void {
+	const hidden = new Set(entries.filter((e) => e.hidden).map((e) => e.path));
+	if (hidden.size === 0) return;
+	for (const entry of entries) {
+		const parts = entry.path.split('/');
+		for (let n = 1; n < parts.length; n++) {
+			const above = parts.slice(0, n).join('/');
+			if (!hidden.has(above)) continue;
+			entry.hidden = true;
+			entry.hiddenBy = above;
+			break;
+		}
+	}
+}
+
+/**
+ * Read one document. Throws DocumentError: 'not-found', 'bad-path',
+ * 'unknown-collection', or the listing's warning codes ('invalid-json',
+ * 'no-title', 'nested-index') for a file that can't be opened.
+ */
+export async function readDocument(
+	site: Pick<ResolvedSite, 'collections' | 'root' | 'blocks'>,
+	collectionName: string,
+	path: string,
+	source: ContentSource = diskSource,
+): Promise<ReadDocument> {
+	const file = resolveDocumentFile(site, collectionName, path);
+	const collection = site.collections[collectionName]!;
+	const text = await source.readText(file);
+	if (text === null) throw new DocumentError('not-found', `${collection.label}: no document "${path}".`);
+	const { entry, document } = inspect(site, collection, path, text);
+	if (entry.warning || !document) throw new DocumentError(entry.warning!.code, entry.warning!.message);
+	return { entry, text, document };
+}
+
+/** Document paths in a collection's folder (sorted, `/`-separated, without `.json`). A missing folder is empty. */
+async function documentPaths(collection: ResolvedCollection, source: ContentSource): Promise<string[]> {
+	const names = await source.listJson(collection.dir, collection.nested);
+	if (collection.kind === 'settings') return names.includes(`${SETTINGS_PATH}.json`) ? [SETTINGS_PATH] : [];
+	return names
+		.filter((n) => !n.split('/').some((s) => s.startsWith('.')))
+		.map((n) => n.slice(0, -'.json'.length))
+		.sort();
+}
+
+/** A listed path's entry; null when the file went away between listing and reading. */
+async function entryFor(site: Pick<ResolvedSite, 'root' | 'blocks'>, collection: ResolvedCollection, path: string, source: ContentSource): Promise<DocumentEntry | null> {
+	const text = await source.readText(join(collection.dir, `${path}.json`));
+	return text === null ? null : inspect(site, collection, path, text).entry;
+}
+
+function inspect(
+	site: Pick<ResolvedSite, 'root' | 'blocks'>,
+	collection: ResolvedCollection,
+	path: string,
+	text: string,
+): { entry: DocumentEntry; document: AnyDocument | null } {
+	const base = {
+		collection: collection.name,
+		kind: collection.kind,
+		path,
+		file: posix(relative(site.root, join(collection.dir, `${path}.json`))),
+		url: documentUrl(collection, path),
+	};
+	const fileLabel = titleCase(path.split('/').pop()!);
+	const warn = (code: WarningCode, message: string, title = '') => ({
+		entry: { ...base, title, label: title || fileLabel, warning: { code, message } },
+		document: null,
+	});
+
+	if (collection.nested && path.endsWith('/index')) {
+		const parent = path.slice(0, -'/index'.length);
+		return warn('nested-index', `index.json only means the top of ${collection.label}. Rename it to ${parent}.json to make it the ${parent} page.`);
+	}
+	let document: AnyDocument;
+	let raw: unknown;
+	try {
+		raw = parseSource(text).value;
+		document = parseAnyDocument(raw, site, collection);
+	} catch (error) {
+		return warn('invalid-json', `This file isn't valid JSON (${error instanceof Error ? error.message : String(error)}).`);
+	}
+	const title = (raw as { title?: unknown } | null)?.title;
+	if (typeof title !== 'string' || title.trim() === '') {
+		return warn('no-title', 'This file has no title, so it can’t be opened. Add a "title".');
+	}
+	const entry: DocumentEntry = { ...base, title, label: title, warning: null };
+	// M9 Decision 7: the home page is never hidden.
+	if ((document.kind === undefined || document.kind === 'sections') && document.hidden && path !== 'index') entry.hidden = true;
+	if (document.kind === undefined || document.kind === 'sections') {
+		entry.uses = [...new Set(document.blocks.flatMap((b) => (b.shared !== undefined ? [b.shared] : [])))];
+	} else if (document.kind === 'shared') {
+		entry.blockType = document.block.type;
+	}
+	// A field column's values ride on the listing (pre-M7 polish); a section builder's page fields too (posts and tags, Decision 13).
+	if ((document.kind === 'fields' || document.kind === undefined || document.kind === 'sections') && collection.columns) {
+		const data = (document.data ?? {}) as Record<string, unknown>;
+		const keys = collection.columns.filter((k) => !isBuiltInColumn(k));
+		if (keys.length) entry.columns = Object.fromEntries(keys.map((k) => [k, data[k] ?? null]));
+	}
+	if (collection.view) {
+		const cover =
+			document.kind === 'fields'
+				? fieldsCover(collection.fields ?? {}, document.data as Record<string, unknown>, collection.view.image)
+				: document.kind === undefined || document.kind === 'sections'
+					? sectionsCover(collection.fields, document.data, document.blocks, site.blocks)
+					: null;
+		if (cover) entry.cover = cover;
+	}
+	return { entry, document };
+}
+
+// ── The Pages tree (Decision 8) ───────────────────────────────────────────────
+
+export type PageTreeNode =
+	| { kind: 'page'; path: string; label: string; entry: DocumentEntry; children: PageTreeNode[] }
+	| {
+			/** A folder with no page of its own: shows or hides its children only. */
+			kind: 'group';
+			path: string;
+			/** The folder's name, hyphens as spaces, capital first letter (`case-studies` → "Case studies"). */
+			label: string;
+			children: PageTreeNode[];
+	  };
+
+/**
+ * A nested collection's entries as a tree that mirrors their paths. A page with
+ * pages under it (`about.json` beside `about/`) is one node with children; a folder
+ * with no page is a group. Each level is ordered Home (`index`) first, then
+ * alphabetically by label.
+ */
+export function pageTree(entries: readonly DocumentEntry[]): PageTreeNode[] {
+	interface Draft {
+		path: string;
+		entry?: DocumentEntry;
+		children: Map<string, Draft>;
+	}
+	const top: Draft = { path: '', children: new Map() };
+	for (const entry of entries) {
+		const segments = entry.path.split('/');
+		let node = top;
+		segments.forEach((segment, i) => {
+			const path = segments.slice(0, i + 1).join('/');
+			let child = node.children.get(segment);
+			if (!child) {
+				child = { path, children: new Map() };
+				node.children.set(segment, child);
+			}
+			node = child;
+		});
+		node.entry = entry;
+	}
+	const build = (draft: Draft): PageTreeNode[] =>
+		[...draft.children.values()]
+			.map((d): PageTreeNode => {
+				const children = build(d);
+				if (d.entry) return { kind: 'page', path: d.path, label: d.entry.label, entry: d.entry, children };
+				return { kind: 'group', path: d.path, label: titleCase(d.path.split('/').pop()!), children };
+			})
+			.sort((a, b) => {
+				if (a.path === 'index' || a.path.endsWith('/index')) return -1;
+				if (b.path === 'index' || b.path.endsWith('/index')) return 1;
+				return byLabel(a, b);
+			});
+	return build(top);
+}
+
+function flattenTree(nodes: PageTreeNode[]): DocumentEntry[] {
+	return nodes.flatMap((n) => [...(n.kind === 'page' ? [n.entry] : []), ...flattenTree(n.children)]);
+}
+
+const collator = new Intl.Collator('en', { sensitivity: 'base', numeric: true });
+function byLabel(a: { label: string; path: string }, b: { label: string; path: string }): number {
+	return collator.compare(a.label, b.label) || collator.compare(a.path, b.path);
+}