caracms 0.0.0-stage → 0.2.0

package/src/editor/server/cards.ts

@@ -0,0 +1,61 @@
+/**
+ * M6c (G5, Decision 19): the documents listing's card pictures, signed on the way to
+ * the browser, as the library's listing carries its thumbnails (media/library.ts).
+ *
+ * Each listed document whose collection has the List / Grid switch and whose first
+ * image was found (content.ts → `cover`) gets `card`: imgproxy `rs:fill` at the
+ * collection's ratio with the focal point as gravity (media.ts → imageUrl), at
+ * CARD_WIDTH and its 2× rung of the ladder, and the alt text; a clip gets its Mux poster
+ * cropped the same. `cover` itself doesn't leave the server. So the grid draws at once,
+ * without opening each document and without the thumbnail route's uncached redirects.
+ *
+ * Without the image variables (no signing), a picture has no URL: the card is a text card.
+ */
+import { IMAGE_WIDTHS, imageUrl, type MediaSettings } from '../../media.ts';
+import { MUX_IMAGE_URL } from '../../media-value.ts';
+import { ratioValue, type CardCover, type CardRatio } from '../../cards.ts';
+import type { ResolvedSite } from '../../config.ts';
+import type { CardPicture, ListedDocument } from '../types.ts';
+import { readImagesConfig } from './media/config.ts';
+
+/** A card's picture width, a rung of the ladder; its 2× is the next rung up that doubles it. A card is 208px at its narrowest, rarely past 320. */
+export const CARD_WIDTH = 320;
+export const CARD_WIDTH_2X = 640;
+if (!IMAGE_WIDTHS.includes(CARD_WIDTH) || !IMAGE_WIDTHS.includes(CARD_WIDTH_2X)) throw new Error('The card widths must be rungs of IMAGE_WIDTHS.');
+
+/** The picture's height at a width and ratio, rounded. */
+export const cardHeight = (width: number, ratio: CardRatio) => Math.round(width / ratioValue(ratio));
+
+/** A clip's Mux poster, cropped to the card (Mux's own `fit_mode=crop`), at `time` seconds (0 when unset). WebP, never the default PNG. */
+export function cardPosterUrl(playbackId: string, time: number | null, width: number, ratio: CardRatio): string {
+	const t = typeof time === 'number' && Number.isFinite(time) && time >= 0 ? time : 0;
+	return `${MUX_IMAGE_URL}/${encodeURIComponent(playbackId)}/thumbnail.webp?width=${width}&height=${cardHeight(width, ratio)}&fit_mode=crop&time=${t}`;
+}
+
+/** One cover, signed. */
+export function cardPicture(signing: MediaSettings | null, cover: CardCover, ratio: CardRatio): CardPicture | null {
+	if (cover.kind === 'clip') {
+		return { kind: 'clip', src: cardPosterUrl(cover.playbackId, cover.time, CARD_WIDTH, ratio), src2x: cardPosterUrl(cover.playbackId, cover.time, CARD_WIDTH_2X, ratio), alt: cover.name, duration: cover.duration };
+	}
+	if (!signing) return null;
+	const at = (width: number) => imageUrl(signing, cover.key, { width, height: cardHeight(width, ratio), resize: 'fill', focal: cover.focal });
+	const position = cover.focal ? `${Math.round(cover.focal[0] * 100)}% ${Math.round(cover.focal[1] * 100)}%` : null;
+	return { kind: 'image', src: at(CARD_WIDTH), src2x: at(CARD_WIDTH_2X), alt: cover.alt, position };
+}
+
+/** The image side's signing settings, or null when the image variables aren't set. */
+export function cardSigning(): MediaSettings | null {
+	const config = readImagesConfig();
+	return config.kind === 'unset' ? null : config.signing;
+}
+
+/** The listing as the browser gets it: each `cover` swapped for its signed `card`. */
+export function withCards(site: Pick<ResolvedSite, 'collections'>, documents: readonly ListedDocument[], signing: MediaSettings | null = cardSigning()): ListedDocument[] {
+	return documents.map((doc) => {
+		if (!doc.cover) return doc;
+		const { cover, ...rest } = doc;
+		const view = site.collections[doc.collection]?.view;
+		const card = view ? cardPicture(signing, cover, view.ratio) : null;
+		return card ? { ...rest, card } : rest;
+	});
+}

package/src/editor/server/create.ts

@@ -0,0 +1,414 @@
+/**
+ * Creating and deleting documents (M5a Phase 3; Decisions 11 and 12): the rules both
+ * stores apply, the disk half (local mode), and the two routes' handling.
+ *
+ * **A security boundary, as the write route is** (M3 Decision 5): these take a path
+ * from the browser and make or remove a file. So:
+ *
+ * - **POST, JSON, same origin**, a small body (`handleCreateDelete`, beside write.ts's
+ *   `checkOrigin`); in live mode the guard also wants a session (M4 Decision 14: its
+ *   path-prefix rule covers `/_caracms/create` and `/_caracms/delete` with no list), and
+ *   the live store refuses a request with no person (401) or no tab (400).
+ * - **Confined exactly as the write route is** (`target`): the path goes through
+ *   content.ts → `resolveDocumentFile` (no `..`, `.`, empty parts, backslash, NUL,
+ *   absolute path or dot-file; one part in a flat collection), and the file it gives
+ *   must come back through write.ts → `confinePath` as the same collection and path
+ *   (a folder no collection declares, or one inside another collection's folder, is
+ *   refused). On disk, **every folder on the way is checked with symlinks resolved**:
+ *   an existing one must resolve inside the collection's folder; a missing one is made
+ *   inside the resolved parent (`createOnDisk`); a delete goes through write.ts →
+ *   `confineDocumentFile` (the parent resolved inside, the file itself not a link).
+ * - **Disk: an exclusive create.** The text is serialised first (nothing is touched if
+ *   that fails), written to a temp file beside it, then hard-linked into place, which
+ *   fails if a file is already there (409) and never leaves half a file under the
+ *   document's name. Folders made for it are removed again if it fails.
+ * - **Delete** removes the file, then each folder it leaves empty, walking up **to but
+ *   never including** the collection's folder, even if that ends up empty.
+ *
+ * The rules (`planCreate`, `planDelete`), the same in both stores, over the store's own
+ * listing (live mode: the copy with autosaves on top):
+ *
+ * - **Addresses** (slug.ts, browser-safe, the dialog's too): every new part of the path
+ *   is one `slugify` leaves as it is (a folder that already has documents in it may be
+ *   named otherwise); no part is `index`; nothing left (only symbols) is refused with
+ *   the field's message. The public address must be free in every collection, not
+ *   under `/admin` or `/_caracms`, and not strictly below another collection's
+ *   non-root `urlBase` (exactly at it is allowed).
+ * - **A document that exists is 409.** Site Settings is never created or deleted; a
+ *   nested collection's `index` (Home) is never deleted; a shared block anything uses
+ *   can't be deleted (409 `in-use`, naming where, from the listing's `usedOn`). A page
+ *   with pages under it can be: they stay, as a group.
+ * - **The new document's content:** a page `{ "title", "blocks": [] }`; a fields
+ *   document `{ "title" }`; a shared block `{ "title", "block": { "type" } }`.
+ */
+import { randomBytes } from 'node:crypto';
+import { link, lstat, mkdir, realpath, rm, rmdir, stat, unlink, writeFile } from 'node:fs/promises';
+import { basename, dirname, join, relative, sep } from 'node:path';
+import type { ResolvedCollection, ResolvedSite } from '../../config.ts';
+import { DocumentError, documentUrl, resolveDocumentFile, type DocumentEntry } from '../../content.ts';
+import { own, parseAnyDocument, type AnyDocument } from '../../document.ts';
+import type { Person } from '../../live/messages.ts';
+import { applyDocumentEdits } from '../../serialize.ts';
+import { addressProblem, INDEX_MESSAGE, isSlug, NO_ADDRESS_MESSAGE, RESERVED_SLUG, slugify } from '../../slug.ts';
+import { RELEASE_HEADER, type CreateDeleteCode, type CreateRequest, type CreateResponse, type DeleteRequest, type DeleteResponse } from '../types.ts';
+import { checkOrigin, confineDocumentFile, confinePath, seqOf, tabOf, WriteRefused, type WriteContext } from './write.ts';
+import { schemaRef, stampSchema } from '../../schema-key.ts';
+
+type Site = Pick<ResolvedSite, 'root' | 'collections' | 'blocks' | 'codeRoutes'>;
+
+/** Largest create or delete body: a collection, a path and a title. */
+export const MAX_CREATE_BODY_BYTES = 16 * 1024;
+/** The longest title a new document may have. */
+export const MAX_TITLE = 200;
+
+const posix = (p: string) => p.split(sep).join('/');
+
+/** A refusal with its code (types.ts → CreateDeleteRefusal). */
+export function refused(status: number, code: CreateDeleteCode, message: string, more: Record<string, unknown> = {}): WriteRefused {
+	return new WriteRefused(status, message, { code, ...more });
+}
+
+/** A path for a message: control characters shown escaped, long ones cut. */
+function printable(value: string): string {
+	const shown = JSON.stringify(value).slice(1, -1);
+	return shown.length > 120 ? `${shown.slice(0, 117)}...` : shown;
+}
+
+/** "Home", "Home and About", "Home, About and Work". */
+export function andList(items: string[]): string {
+	if (items.length <= 1) return items.join('');
+	return `${items.slice(0, -1).join(', ')} and ${items.at(-1)}`;
+}
+
+// ── Bodies ──────────────────────────────────────────────────────────────────
+
+const object = (body: unknown, shape: string): Record<string, unknown> => {
+	if (!body || typeof body !== 'object' || Array.isArray(body)) throw refused(400, 'bad-request', `Malformed body: it must be a JSON object. Send ${shape}.`);
+	return body as Record<string, unknown>;
+};
+
+const onlyKeys = (body: Record<string, unknown>, keys: string[], shape: string) => {
+	const extra = Object.keys(body).filter((k) => !keys.includes(k));
+	if (extra.length) throw refused(400, 'bad-request', `Malformed body: unexpected ${extra.map((k) => `"${printable(k)}"`).join(', ')}. Send ${shape}.`);
+};
+
+const CREATE_SHAPE = '{ collection, path, title } (and blockType for a shared block)';
+const DELETE_SHAPE = '{ collection, path }';
+
+/** Validate a create body's shape. Throws WriteRefused 400. */
+export function parseCreateBody(body: unknown): CreateRequest {
+	const b = object(body, CREATE_SHAPE);
+	onlyKeys(b, ['collection', 'path', 'title', 'blockType'], CREATE_SHAPE);
+	const bad = (message: string) => refused(400, 'bad-request', `Malformed body: ${message} Send ${CREATE_SHAPE}.`);
+	if (typeof b.collection !== 'string' || b.collection === '') throw bad('"collection" must be a collection\'s name.');
+	if (typeof b.path !== 'string') throw bad('"path" must be the new document\'s path in its collection.');
+	if (b.path.length > 512) throw refused(400, 'bad-path', 'That path is too long.');
+	if (typeof b.title !== 'string') throw bad('"title" must be a string.');
+	const title = b.title.trim();
+	if (title === '') throw refused(400, 'bad-name', 'Give it a name.');
+	if (title.length > MAX_TITLE) throw refused(400, 'bad-name', `That name is too long (at most ${MAX_TITLE} characters).`);
+	// One line (a title is one-line text): no breaks or control characters, which would also reach the commit headlines.
+	if (/\p{Cc}/u.test(title)) throw refused(400, 'bad-name', 'A name is one line, with no breaks or control characters.');
+	if (b.blockType !== undefined && typeof b.blockType !== 'string') throw bad('"blockType" must be a block type\'s name.');
+	return { collection: b.collection, path: b.path, title, ...(b.blockType !== undefined ? { blockType: b.blockType as string } : {}) };
+}
+
+/** Validate a delete body's shape. Throws WriteRefused 400. */
+export function parseDeleteBody(body: unknown): DeleteRequest {
+	const b = object(body, DELETE_SHAPE);
+	onlyKeys(b, ['collection', 'path'], DELETE_SHAPE);
+	if (typeof b.collection !== 'string' || b.collection === '') throw refused(400, 'bad-request', `Malformed body: "collection" must be a collection's name. Send ${DELETE_SHAPE}.`);
+	if (typeof b.path !== 'string' || b.path === '') throw refused(400, 'bad-request', `Malformed body: "path" must be the document's path in its collection. Send ${DELETE_SHAPE}.`);
+	if (b.path.length > 512) throw refused(400, 'bad-path', 'That path is too long.');
+	return { collection: b.collection, path: b.path };
+}
+
+// ── Confinement ────────────────────────────────────────────────────────────
+
+export interface Target {
+	collection: string;
+	path: string;
+	/** Relative to the site, `/`-separated. */
+	file: string;
+	/** Absolute, as configured (not symlink-resolved). */
+	absolute: string;
+}
+
+/**
+ * A collection and path as a file, confined as the write route confines a file: the
+ * reader's path rules, then write.ts → `confinePath` must give back the same
+ * collection and path. Throws WriteRefused 400 (`bad-path`).
+ */
+export function target(site: Site, collection: string, path: string): Target {
+	if (!own(site.collections, collection)) throw refused(400, 'bad-path', `No collection "${printable(collection)}" is declared.`);
+	let absolute: string;
+	try {
+		absolute = resolveDocumentFile(site, collection, path);
+	} catch (error) {
+		if (error instanceof DocumentError) throw refused(400, 'bad-path', error.message);
+		throw error;
+	}
+	const file = posix(relative(site.root, absolute));
+	let confined;
+	try {
+		confined = confinePath(site, file);
+	} catch (error) {
+		if (error instanceof WriteRefused) throw refused(400, 'bad-path', error.message);
+		throw error;
+	}
+	if (confined.collection !== collection || confined.path !== path) {
+		throw refused(400, 'bad-path', `"${printable(path)}" isn't a document path in ${site.collections[collection]!.label}.`);
+	}
+	return { collection, path, file, absolute };
+}
+
+// ── The rules ──────────────────────────────────────────────────────────────
+
+export interface CreatePlan extends Target {
+	title: string;
+	/** Its public address; null for a shared block. */
+	url: string | null;
+	/** The new file's text. */
+	text: string;
+	/** The new document, as the reader reads `text`. */
+	document: AnyDocument;
+}
+
+/** The new document's first text (Decision 11), serialised as the write route would. Throws if it can't be. */
+export function initialText(site: Site, collection: ResolvedCollection, title: string, blockType: string | undefined, file: string): string {
+	// M8 Decision 14: a new document names its schema, as its first key.
+	return stampSchema(firstText(site, collection, title, blockType), schemaRef(collection, file));
+}
+
+function firstText(site: Site, collection: ResolvedCollection, title: string, blockType: string | undefined): string {
+	switch (collection.kind) {
+		case 'sections':
+			return applyDocumentEdits(null, { title, blocks: [] }, site, collection);
+		case 'fields':
+			return applyDocumentEdits(null, { kind: 'fields', title, data: {} }, site, collection);
+		case 'shared':
+			return `${JSON.stringify({ title, block: { type: blockType } }, null, 2)}\n`;
+		default:
+			throw new Error(`caracms: a ${collection.kind} document is never created`);
+	}
+}
+
+/**
+ * Check a create against the rules and the store's listing (`documents`: every
+ * document in every collection now), and work out the new file. Throws WriteRefused.
+ */
+export function planCreate(site: Site, request: CreateRequest, documents: readonly DocumentEntry[]): CreatePlan {
+	const collection = own(site.collections, request.collection);
+	if (!collection) throw refused(400, 'bad-path', `No collection "${printable(request.collection)}" is declared.`);
+	if (collection.kind === 'settings') throw refused(400, 'not-allowed', 'Site Settings is always there, so it\'s never created.');
+	if (request.path === '') throw refused(400, 'bad-name', NO_ADDRESS_MESSAGE);
+	if (request.path.split('/').includes(RESERVED_SLUG)) throw refused(400, 'index', INDEX_MESSAGE);
+
+	const where = target(site, collection.name, request.path);
+	const parts = where.path.split('/');
+	parts.forEach((part, i) => {
+		// A folder that already has documents in it keeps its name, whatever it is.
+		const prefix = parts.slice(0, i + 1).join('/');
+		const existing = i < parts.length - 1 && documents.some((d) => d.collection === collection.name && d.path.startsWith(`${prefix}/`));
+		if (existing || isSlug(part)) return;
+		const better = slugify(part);
+		throw refused(400, 'bad-name', better ? `"${printable(part)}" can't be part of an address; "${better}" can.` : NO_ADDRESS_MESSAGE);
+	});
+
+	if (collection.kind === 'shared') {
+		if (request.blockType === undefined || request.blockType === '') throw refused(400, 'not-allowed', 'Choose a block type for the shared block.');
+		if (!own(site.blocks, request.blockType)) throw refused(400, 'not-allowed', `There's no block type "${printable(request.blockType)}".`);
+	} else if (request.blockType !== undefined) {
+		throw refused(400, 'bad-request', `Malformed body: "blockType" is only for a shared block. Send ${CREATE_SHAPE}.`);
+	}
+
+	const url = documentUrl(collection, where.path);
+	if (documents.some((d) => d.file === where.file)) {
+		throw refused(409, 'exists', url ? `There's already a page at ${url}.` : `There's already a ${collection.kind === 'shared' ? 'shared block' : 'document'} called "${where.path}".`);
+	}
+	if (url !== null) {
+		const collections = Object.values(site.collections).map(({ name, label, urlBase }) => ({ name, label, urlBase }));
+		const problem = addressProblem(url, collection.name, collections, documents, site.codeRoutes);
+		if (problem) throw refused(problem.code === 'address-taken' ? 409 : 400, problem.code, problem.message);
+	}
+
+	const text = initialText(site, collection, request.title, request.blockType, where.file);
+	const document = parseAnyDocument(JSON.parse(text), site, collection);
+	return { ...where, title: request.title, url, text, document };
+}
+
+export interface DeletePlan extends Target {
+	entry: DocumentEntry;
+}
+
+/** Check a delete against the rules and the store's listing. Throws WriteRefused. */
+export function planDelete(site: Site, request: DeleteRequest, documents: readonly DocumentEntry[]): DeletePlan {
+	const collection = own(site.collections, request.collection);
+	if (!collection) throw refused(400, 'bad-path', `No collection "${printable(request.collection)}" is declared.`);
+	if (collection.kind === 'settings') throw refused(400, 'not-allowed', 'Site Settings can\'t be deleted.');
+	const where = target(site, collection.name, request.path);
+	const entry = documents.find((d) => d.file === where.file);
+	if (collection.nested && where.path === 'index') {
+		throw refused(400, 'not-allowed', collection.urlBase === '/' ? 'Home can\'t be deleted.' : `${entry?.label ?? 'This page'} is the top of ${collection.label}, so it can't be deleted.`);
+	}
+	if (!entry) throw refused(404, 'not-found', `${collection.label}: no document "${printable(where.path)}".`);
+	if (collection.kind === 'shared' && entry.usedOn?.length) {
+		const usedOn = entry.usedOn.map((u) => ({ ...u, title: documents.find((d) => d.collection === u.collection && d.path === u.path)?.label ?? u.path }));
+		throw refused(
+			409,
+			'in-use',
+			`${entry.label} is used on ${andList(usedOn.map((u) => u.title))}, so it can't be deleted. Take it off ${usedOn.length === 1 ? 'that page' : 'those pages'} first.`,
+			{ usedOn },
+		);
+	}
+	return { ...where, entry };
+}
+
+// ── The disk (local mode) ──────────────────────────────────────────────────
+
+const code = (error: unknown) => (error as NodeJS.ErrnoException)?.code;
+
+/**
+ * Make the new file, exclusively: every folder on the way checked with symlinks
+ * resolved (inside the collection's folder), missing ones made, the text written to a
+ * temp file and hard-linked into place (EEXIST: 409). Folders it made are removed if it fails.
+ */
+export async function createOnDisk(site: Site, plan: CreatePlan): Promise<void> {
+	const collection = site.collections[plan.collection]!;
+	const outside = () => refused(400, 'bad-path', `"${printable(plan.file)}" leads outside ${collection.label}'s folder through a link.`);
+	await mkdir(collection.dir, { recursive: true }); // the config's own folder (an empty collection may not have it yet)
+	const realDir = await realpath(collection.dir);
+	const inside = (p: string) => p === realDir || p.startsWith(realDir + sep);
+	const made: string[] = [];
+	try {
+		let at = realDir;
+		const folders = plan.path.split('/').slice(0, -1);
+		for (const [i, name] of folders.entries()) {
+			const next = join(at, name);
+			try {
+				await mkdir(next);
+				made.push(next);
+				at = next;
+				continue;
+			} catch (error) {
+				if (code(error) !== 'EEXIST') throw error;
+			}
+			const info = await lstat(next);
+			const real = info.isSymbolicLink() ? await realpath(next) : next;
+			if (!inside(real)) throw outside();
+			if (!(await stat(real)).isDirectory()) throw refused(400, 'bad-path', `"${printable(folders.slice(0, i + 1).join('/'))}" is a file in ${collection.label}, not a folder.`);
+			at = real;
+		}
+		// Once more, now the folders are there: the file's folder, resolved, is still inside.
+		const parent = await realpath(at);
+		if (!inside(parent)) throw outside();
+		const file = join(parent, basename(plan.absolute));
+		const temp = join(parent, `.${basename(plan.absolute)}.${process.pid}.${randomBytes(6).toString('hex')}.tmp`);
+		await writeFile(temp, plan.text, { encoding: 'utf8', flag: 'wx', mode: 0o644 });
+		try {
+			await link(temp, file);
+		} catch (error) {
+			if (code(error) === 'EEXIST') throw refused(409, 'exists', plan.url ? `There's already a page at ${plan.url}.` : `There's already a document called "${plan.path}".`);
+			if (code(error) !== 'EPERM' && code(error) !== 'ENOTSUP' && code(error) !== 'EXDEV') throw error;
+			// A filesystem with no hard links: an exclusive write of the whole text at once.
+			try {
+				await writeFile(file, plan.text, { encoding: 'utf8', flag: 'wx', mode: 0o644 });
+			} catch (fallback) {
+				if (code(fallback) === 'EEXIST') throw refused(409, 'exists', `There's already a document called "${plan.path}".`);
+				throw fallback;
+			}
+		} finally {
+			await rm(temp, { force: true });
+		}
+	} catch (error) {
+		for (const dir of made.reverse()) await rmdir(dir).catch(() => {});
+		throw error;
+	}
+}
+
+/**
+ * An existing document's file on disk, through write.ts → `confineDocumentFile` (its
+ * folder resolved inside its collection's, the file itself not a link), with this
+ * route's codes: 400 `bad-path`, 404 `not-found`.
+ */
+export async function confineOnDisk(site: Site, file: string) {
+	try {
+		return await confineDocumentFile(site, file);
+	} catch (error) {
+		if (error instanceof WriteRefused && !error.body.code) throw refused(error.status, error.status === 404 ? 'not-found' : 'bad-path', error.message);
+		throw error;
+	}
+}
+
+/**
+ * Remove the file (write.ts → `confineDocumentFile`: inside its collection's folder with
+ * links resolved, and not itself a link), then every folder it leaves empty, up to but
+ * never including the collection's folder.
+ */
+export async function deleteOnDisk(site: Site, plan: DeletePlan): Promise<void> {
+	const confined = await confineOnDisk(site, plan.file);
+	const collection = site.collections[confined.collection]!;
+	const realDir = await realpath(collection.dir);
+	try {
+		await unlink(confined.absolute);
+	} catch (error) {
+		if (code(error) === 'ENOENT') throw refused(404, 'not-found', `${collection.label}: no document "${plan.path}".`);
+		throw error;
+	}
+	for (let dir = dirname(confined.absolute); dir !== realDir && dir.startsWith(realDir + sep); dir = dirname(dir)) {
+		try {
+			await rmdir(dir);
+		} catch {
+			break; // not empty (or gone): the folders above it stay too
+		}
+	}
+}
+
+// ── The routes ─────────────────────────────────────────────────────────────
+
+const json = (status: number, body: unknown, headers: Record<string, string> = {}) =>
+	new Response(JSON.stringify(body), {
+		status,
+		headers: { 'Content-Type': 'application/json; charset=utf-8', 'Cache-Control': 'no-store', ...headers },
+	});
+
+/** What the routes need of the drafts store. */
+export interface CreatesAndDeletes {
+	create(request: CreateRequest, context?: WriteContext): Promise<CreateResponse>;
+	delete(request: DeleteRequest, context?: WriteContext): Promise<DeleteResponse>;
+}
+
+async function handle(request: Request, who: { person?: Person | null }, run: (body: unknown, context: WriteContext) => Promise<unknown>, name: string): Promise<Response> {
+	try {
+		if (request.method !== 'POST') throw new WriteRefused(405, `The ${name} route only takes POST.`);
+		checkOrigin(request);
+		const type = request.headers.get('content-type') ?? '';
+		if (!/^application\/json\s*(;|$)/i.test(type)) throw new WriteRefused(415, 'Send JSON (Content-Type: application/json).');
+		const length = Number(request.headers.get('content-length') ?? 0);
+		if (length > MAX_CREATE_BODY_BYTES) throw new WriteRefused(413, 'That body is too large.');
+		const raw = await request.text();
+		if (Buffer.byteLength(raw) > MAX_CREATE_BODY_BYTES) throw new WriteRefused(413, 'That body is too large.');
+		let body: unknown;
+		try {
+			body = JSON.parse(raw);
+		} catch {
+			throw refused(400, 'bad-request', 'Malformed body: it isn\'t valid JSON.');
+		}
+		const context: WriteContext = { person: who.person ?? null, tab: tabOf(request), release: request.headers.get(RELEASE_HEADER) === '1', seq: seqOf(request) };
+		return json(200, await run(body, context));
+	} catch (error) {
+		if (error instanceof WriteRefused) return json(error.status, { error: error.message, ...error.body }, error.status === 405 ? { Allow: 'POST' } : {});
+		console.error(`[caracms] ${name} failed:`, error);
+		return json(500, { error: `That didn't work (${error instanceof Error ? error.message : String(error)}).` });
+	}
+}
+
+/** POST /_caracms/create: a Request in, a Response out, through the mode's store. */
+export function handleCreate(request: Request, store: Pick<CreatesAndDeletes, 'create'>, who: { person?: Person | null } = {}): Promise<Response> {
+	return handle(request, who, (body, context) => store.create(parseCreateBody(body), context), 'create');
+}
+
+/** POST /_caracms/delete: a Request in, a Response out, through the mode's store. */
+export function handleDelete(request: Request, store: Pick<CreatesAndDeletes, 'delete'>, who: { person?: Person | null } = {}): Promise<Response> {
+	return handle(request, who, (body, context) => store.delete(parseDeleteBody(body), context), 'delete');
+}

package/src/editor/server/drafts-store.ts

@@ -0,0 +1,127 @@
+/**
+ * The drafts store (Decision 5): read a document, list documents, write a document,
+ * behind one seam (M5a adds creating and deleting one: create.ts has the rules). M3's implementation, here, is the site's content files on disk
+ * (local mode). M4's live mode swaps in Redis autosaves over the `drafts` copy
+ * behind the same three calls (../../live/drafts-store.ts); server/mode.ts picks one.
+ *
+ * Everything reads at request time (never imported, Decision 5), and keeps no state.
+ */
+import { stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { SITE_SETTINGS_FILE, type ResolvedSite } from '../../config.ts';
+import { diskSource, listDocuments, readDocument, type ContentSource } from '../../content.ts';
+import type { AnyOpenedDocument, CreateRequest, CreateResponse, DeleteRequest, DeleteResponse, ListedDocument, MoveRequest, MoveResponse, OpenedDocument, ReplaceFileRequest, ReplaceFileResponse } from '../types.ts';
+import { confineOnDisk, createOnDisk, deleteOnDisk, planCreate, planDelete, target } from './create.ts';
+import { moveChanges, moveOnDisk, moveResponse, planMove, settingsWithoutRedirectFrom } from './move.ts';
+import { replaceChanges, replaceResponse } from './replace.ts';
+import { applyWrite, fileVersion, writeAtomic, type WriteContext, type WriteRequest, type WriteResponse } from './write.ts';
+
+export type { AnyOpenedDocument, ListedDocument, OpenedDocument };
+
+export interface DraftsStore {
+	/**
+	 * Every document, in the editor's order (content.ts → listDocuments), with warnings:
+	 * every collection's, the reserved `shared` and `settings` included (M5a Decision 8),
+	 * each with its public URL and its kind; a shared block with its `usedOn`.
+	 */
+	list(): Promise<ListedDocument[]>;
+	/** One document, of any kind (M5a). Throws content.ts's DocumentError ('not-found', 'bad-path', a warning code…). */
+	read(collection: string, path: string): Promise<AnyOpenedDocument>;
+	/**
+	 * The store's content as a content.ts source (M5a Decision 9): what a preview's
+	 * render reads other documents from. Local: the disk. Live: the `drafts` copy
+	 * with every autosave on top.
+	 */
+	source(): Promise<ContentSource>;
+	/**
+	 * Write one document (write.ts: confined, atomic). Throws WriteRefused. `context`
+	 * says who and which tab (M4): the live store needs it, the local one ignores it.
+	 */
+	write(request: WriteRequest, context?: WriteContext): Promise<WriteResponse>;
+	/**
+	 * Create a document (M5a Decision 11; create.ts has the rules, the same in both
+	 * stores). Local: an exclusive create on disk. Live: the creator's tab takes the lock
+	 * and the new document is its autosave, with no base in `drafts`. Throws WriteRefused.
+	 */
+	create(request: CreateRequest, context?: WriteContext): Promise<CreateResponse>;
+	/**
+	 * Delete a document (M5a Decision 12). Local: the file goes, then the folders it
+	 * leaves empty, up to the collection's. Live: the lock, then a "gone" autosave the
+	 * sweep commits as a removed file. Throws WriteRefused.
+	 */
+	delete(request: DeleteRequest, context?: WriteContext): Promise<DeleteResponse>;
+	/**
+	 * Change a document's address (pre-M7 item 8; move.ts has the rules, the same in both
+	 * stores): the document moves, every link and reference to it is rewritten, and Site
+	 * Settings gets a redirect from the old address. Local: on disk, the new file first and
+	 * the old one last. Live: every change is an autosave under this tab's locks, all going
+	 * out at the next Publish. Throws WriteRefused.
+	 */
+	move(request: MoveRequest, context?: WriteContext): Promise<MoveResponse>;
+	/**
+	 * M6c G4 (Decision 9): Replace… on a file. Every link to `from`, in every document, points
+	 * at `to` (replace.ts has the rules, the same in both stores). Local: each file written
+	 * as a local move writes them (no rollback). Live: autosaves under this tab's locks,
+	 * landing whole or rolled back. Throws WriteRefused.
+	 */
+	replaceFile(request: ReplaceFileRequest, context?: WriteContext): Promise<ReplaceFileResponse>;
+}
+
+type Site = Pick<ResolvedSite, 'root' | 'collections' | 'blocks'>;
+
+/** The local store: the content files on disk. */
+export function localDraftsStore(site: Site): DraftsStore {
+	return {
+		async list() {
+			const entries = await listDocuments(site);
+			return Promise.all(
+				entries.map(async (entry) => ({
+					...entry,
+					mtimeMs: await stat(join(site.root, entry.file)).then((s) => s.mtimeMs, () => null),
+				})),
+			);
+		},
+		async read(collection, path) {
+			const read = await readDocument(site, collection, path);
+			const { mtimeMs } = await stat(join(site.root, read.entry.file));
+			return { ...read, mtimeMs, version: fileVersion(read.text) };
+		},
+		write(request) {
+			return applyWrite(site, request);
+		},
+		async create(request) {
+			const plan = planCreate(site, request, await listDocuments(site));
+			await createOnDisk(site, plan);
+			// Pre-M7 item 8: a redirect from this address goes, now a page is here.
+			const settings = join(site.root, SITE_SETTINGS_FILE);
+			const without = settingsWithoutRedirectFrom(site, await diskSource.readText(settings), plan.url);
+			if (without !== null) await writeAtomic(settings, without);
+			return { ok: true, collection: plan.collection, path: plan.path, file: plan.file, url: plan.url, version: fileVersion(plan.text) };
+		},
+		async delete(request) {
+			// The file first (a link out of the collection is refused before anything else), then the rules.
+			await confineOnDisk(site, target(site, request.collection, request.path).file);
+			const plan = planDelete(site, request, await listDocuments(site));
+			await deleteOnDisk(site, plan);
+			return { ok: true, collection: plan.collection, path: plan.path, file: plan.file };
+		},
+		async move(request) {
+			// The file first (a link out of the collection is refused before anything else), then the rules.
+			await confineOnDisk(site, target(site, request.collection, request.path).file);
+			const documents = await listDocuments(site);
+			const plan = planMove(site, request, documents);
+			const changes = await moveChanges(site, plan, documents, (file) => diskSource.readText(join(site.root, file)), true);
+			await moveOnDisk(site, plan, changes);
+			return moveResponse(site, plan, changes);
+		},
+		async replaceFile(request) {
+			const changes = await replaceChanges(site, request, await listDocuments(site), (file) => diskSource.readText(join(site.root, file)));
+			// As a local move writes its relinked files: each confined and atomic, in listing order.
+			for (const c of changes) await writeAtomic((await confineOnDisk(site, c.file)).absolute, c.text);
+			return replaceResponse(request, changes);
+		},
+		async source() {
+			return diskSource;
+		},
+	};
+}