caracms 0.0.0-stage → 0.2.0

package/src/editor/server/media/alt.ts

@@ -0,0 +1,107 @@
+/**
+ * Images with no alt text in a document (M5b Decision 9's server half): what Publish's
+ * summary names for each waiting document (`WaitingView.missingAlt`). It warns and never
+ * blocks.
+ *
+ * - **Read from the text it's given**: the caller passes the document as it will publish
+ *   (live/editor.ts: the autosave's text, else the `drafts` copy's).
+ * - **Only rendered slots count**: a known block's media fields (a page's, or a shared
+ *   block's own document), a fields document's or Site Settings' own fields, a section
+ *   builder's page fields (M6c G2). Not an
+ *   unknown block, nor a page's shared entry (its shared block lists its own images when
+ *   it's waiting), nor a value of a kind the slot doesn't take (it isn't shown), nor the
+ *   brand's logo and icon (Decision 11: they have no alt; the brand's name is it).
+ * - **A decorative image never counts.** The rule is the field's own warning
+ *   (fields.ts → `fieldWarnings`, code `missing-alt`), so the two never disagree, and its
+ *   list indexes are the editor's rows.
+ * - **The slot's label** (Decision 9): the block type's name plus "image" ("Hero image",
+ *   "Text and media image"), with its position in a list ("Gallery image 3", and in an inner list "Partners image 2, logos 1"); in a fields
+ *   document, the field's own label ("Cover image"). A block with more than one media
+ *   field says which ("Hero background").
+ */
+import type { ResolvedCollection, ResolvedSite } from '../../../config.ts';
+import { own, parseAnyDocument } from '../../../document.ts';
+import { fieldAt, fieldHoldsMedia, fieldWarnings, isIndexPart, splitPath, titleCase, type Field, type Fields } from '../../../fields.ts';
+import { parseSource } from '../../../json-source.ts';
+import type { MissingAltView } from '../../types.ts';
+
+type Site = Pick<ResolvedSite, 'blocks' | 'collections'>;
+
+const labelOf = (key: string, field: Field) => field.label?.trim() || titleCase(key);
+const lowerFirst = (s: string) => s.charAt(0).toLowerCase() + s.slice(1);
+
+/**
+ * The list rows a path is in, outermost first: the index after each list on the way down
+ * (`gallery.2.alt` → [2], through a group too: `left.gallery.0` → [0]; M7, an inner list:
+ * `partners.1.logos.0.alt` → [1, 0]), each with its list's field.
+ */
+function rowsOf(fields: Fields, path: string): { row: number; list: Field; key: string }[] {
+	const parts = splitPath(path);
+	const out: { row: number; list: Field; key: string }[] = [];
+	for (let i = 1; i < parts.length; i++) {
+		const field = fieldAt(fields, parts.slice(0, i).join('.'));
+		if (field?.kind === 'list' && isIndexPart(parts[i]!)) out.push({ row: Number(parts[i]), list: field, key: parts[i - 1]! });
+	}
+	return out;
+}
+
+/** The images with no alt text in one form's fields (a block's, or a fields document's). */
+function slots(fields: Fields, data: Record<string, unknown>, block: number | null, owner: string | null): MissingAltView[] {
+	const mediaFields = Object.entries(fields).filter(([, f]) => fieldHoldsMedia(f));
+	const out: MissingAltView[] = [];
+	for (const [key, field] of mediaFields) {
+		let base: string;
+		if (owner !== null) base = mediaFields.length === 1 ? `${owner} image` : `${owner} ${lowerFirst(labelOf(key, field))}`;
+		else {
+			const label = labelOf(key, field);
+			base = /\bimage\b/i.test(label) ? label : `${label} image`;
+		}
+		for (const warning of fieldWarnings(field, data[key])) {
+			if (warning.code !== 'missing-alt') continue;
+			const path = `${key}.${warning.path}`;
+			const [outer, inner] = rowsOf(fields, path);
+			// M7: an inner list's image adds its own list and row ("Partners image 2, logos 1").
+			const label = !outer ? base : `${base} ${outer.row + 1}${inner ? `, ${lowerFirst(labelOf(inner.key, inner.list))} ${inner.row + 1}` : ''}`;
+			out.push({ block, field: key, path, row: outer ? outer.row : null, label });
+		}
+	}
+	return out;
+}
+
+/**
+ * Every image with no alt text that isn't decorative, in a document's text (any kind),
+ * in document order. Empty for text that isn't a document (not JSON, a file no
+ * collection holds).
+ */
+export function missingAltIn(site: Site, collectionName: string | null, text: string | null): MissingAltView[] {
+	if (!collectionName || text === null) return [];
+	const collection: ResolvedCollection | undefined = own(site.collections, collectionName);
+	if (!collection) return [];
+	let raw: unknown;
+	try {
+		raw = parseSource(text).value;
+	} catch {
+		return [];
+	}
+	const document = parseAnyDocument(raw, site, collection);
+	switch (document.kind) {
+		case 'fields':
+			return slots(collection.fields ?? {}, document.data, null, null);
+		case 'settings':
+			// Only the site's own fields: `brand` (the logo and the icon) isn't one of them.
+			return slots(collection.fields ?? {}, document.data, null, null);
+		case 'shared': {
+			const block = document.block;
+			const schema = block.known ? own(site.blocks, block.type) : undefined;
+			return schema ? slots(schema.fields, block.data, 0, schema.label) : [];
+		}
+		default:
+			// M6c (G2): the page's own fields first (they come before the blocks), `block` null as a form's.
+			return [...slots(collection.fields ?? {}, document.data ?? {}, null, null), ...document.blocks.flatMap((block, index) => {
+				// An unknown block, or a shared entry (its own document carries its images), isn't counted here.
+				if (!block.known || block.shared !== undefined) return [];
+				const schema = own(site.blocks, block.type);
+				return schema ? slots(schema.fields, block.data, index, schema.label) : [];
+			})];
+	}
+}

package/src/editor/server/media/bucket.ts

@@ -0,0 +1,295 @@
+/**
+ * The media bucket (M5b Decision 6), behind one small seam: list, head, get, put. **No
+ * delete and no overwrite anywhere** (Spec → Media): `put` is only ever called after the
+ * upload route has checked that nothing exists under the key's `uploads/<hash>/`.
+ *
+ * - **`s3Bucket`**: S3's REST API over `fetch`, signed with **aws4fetch** (a standard,
+ *   dependency-free SigV4 signer, ~6 KB). Path-style requests (`<endpoint>/<bucket>/<key>`),
+ *   which Railway's endpoint (`https://t3.storageapi.dev`, region `ams`) takes. The
+ *   payload hash is signed (the route has the bytes in memory anyway).
+ * - **`MemoryBucket`**: the in-memory stand-in behind `CARACMS_MEDIA=memory` (memory.ts).
+ *
+ * The object metadata's names are fixed (M5b → Resolved decisions, Phase 0's script):
+ * `x-amz-meta-w`, `-h`, `-name` (URI-encoded, so any file name fits a header) and `-by`.
+ */
+import { AwsClient } from 'aws4fetch';
+import type { BucketSettings } from './config.ts';
+
+export interface BucketObject {
+	key: string;
+	/** ISO: S3's LastModified. */
+	lastModified: string | null;
+	size: number | null;
+}
+
+/** An object's metadata, as stored (strings decoded). */
+export interface ObjectMeta {
+	w: number | null;
+	h: number | null;
+	/** The original file name, or null. */
+	name: string | null;
+	/** Who uploaded it, or null (local mode). */
+	by: string | null;
+	contentType: string | null;
+	lastModified: string | null;
+	size: number | null;
+}
+
+export interface PutObject {
+	key: string;
+	body: Uint8Array;
+	contentType: string;
+	/** Hex SHA-256 of `body` (the route has it already). */
+	sha256: string;
+	/** `w` and `h` are an image's; a file (M6c G4) has neither. */
+	meta: { w?: number; h?: number; name: string; by: string | null };
+}
+
+/** An object's bytes, streamed (M6c G4: the public file route), and its length when the bucket says. */
+export interface ObjectBody {
+	body: ReadableStream<Uint8Array>;
+	size: number | null;
+}
+
+export interface Bucket {
+	/** Every object under `prefix`, following S3's continuation tokens. */
+	list(prefix: string): Promise<BucketObject[]>;
+	/** The first key under `prefix`, or null: the upload's existence check. */
+	first(prefix: string): Promise<string | null>;
+	/** An object's metadata, or null when there's no such object. */
+	head(key: string): Promise<ObjectMeta | null>;
+	/**
+	 * An object's bytes as a stream, or null when there's no such object. Only the public
+	 * file route (files-route.ts) calls it, and only for a key its allow-list passed.
+	 */
+	get(key: string): Promise<ObjectBody | null>;
+	/** Write a new object. Never called for a key that exists. */
+	put(object: PutObject): Promise<void>;
+}
+
+/** A bucket call that failed: its message is for the server log, never the browser. */
+export class BucketError extends Error {
+	/** The bucket's HTTP status when it answered with a refusal; null when it couldn't be reached. */
+	readonly status: number | null;
+	constructor(message: string, status: number | null = null) {
+		super(message);
+		this.name = 'BucketError';
+		this.status = status;
+	}
+}
+
+const metaNumber = (v: string | null | undefined) => {
+	const n = Number(v);
+	return v && Number.isFinite(n) && n > 0 ? Math.round(n) : null;
+};
+const decodeName = (v: string | null | undefined) => {
+	if (!v) return null;
+	try {
+		return decodeURIComponent(v);
+	} catch {
+		return v;
+	}
+};
+
+const XML_ENTITIES: Record<string, string> = { amp: '&', lt: '<', gt: '>', quot: '"', apos: "'" };
+const unxml = (s: string) =>
+	s.replace(/&(#x[0-9a-fA-F]+|#\d+|amp|lt|gt|quot|apos);/g, (_, e: string) =>
+		e[0] === '#' ? String.fromCodePoint(e[1] === 'x' ? parseInt(e.slice(2), 16) : Number(e.slice(1))) : XML_ENTITIES[e]!,
+	);
+const tag = (xml: string, name: string) => {
+	const m = new RegExp(`<${name}>([\\s\\S]*?)</${name}>`).exec(xml);
+	return m ? unxml(m[1]!) : null;
+};
+
+const S3_TIMEOUT_MS = 20_000;
+/** A runaway-token guard: 1000 pages of 1000 is far past one site's library. */
+const MAX_PAGES = 1000;
+
+export function s3Bucket(settings: BucketSettings, fetchImpl: typeof fetch = (...args) => globalThis.fetch(...args)): Bucket {
+	const client = new AwsClient({ accessKeyId: settings.accessKeyId, secretAccessKey: settings.secretAccessKey, service: 's3', region: settings.region });
+	const base = `${settings.endpoint}/${encodeURIComponent(settings.bucket)}`;
+	const objectUrl = (key: string) => `${base}/${key.split('/').map(encodeURIComponent).join('/')}`;
+
+	/**
+	 * One signed request. The timeout covers the whole exchange, except with `stream`
+	 * (`get`'s body, up to 40 MB to a slow visitor), where it covers only the wait for the
+	 * bucket's headers.
+	 */
+	async function call(method: string, url: string, init: { headers?: Record<string, string>; body?: Uint8Array; stream?: boolean } = {}): Promise<Response> {
+		const request = await client.sign(url, {
+			method,
+			headers: { 'X-Amz-Content-Sha256': init.headers?.['X-Amz-Content-Sha256'] ?? 'e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855', ...init.headers },
+			body: init.body as BodyInit | undefined,
+		});
+		const controller = init.stream ? new AbortController() : null;
+		const timer = controller ? setTimeout(() => controller.abort(new Error(`no answer in ${S3_TIMEOUT_MS / 1000} s`)), S3_TIMEOUT_MS) : null;
+		try {
+			return await fetchImpl(request, { signal: controller ? controller.signal : AbortSignal.timeout(S3_TIMEOUT_MS) });
+		} catch (error) {
+			throw new BucketError(`${method} ${new URL(url).pathname}: unreachable (${error instanceof Error ? error.message : String(error)})`);
+		} finally {
+			if (timer) clearTimeout(timer);
+		}
+	}
+
+	async function page(prefix: string, token: string | null, max?: number) {
+		const query = new URLSearchParams({ 'list-type': '2', prefix });
+		if (max) query.set('max-keys', String(max));
+		if (token) query.set('continuation-token', token);
+		const res = await call('GET', `${base}?${query}`);
+		const text = await res.text();
+		if (!res.ok) throw new BucketError(`list ${prefix}: ${res.status} ${text.slice(0, 300)}`, res.status);
+		const objects: BucketObject[] = [];
+		for (const m of text.matchAll(/<Contents>([\s\S]*?)<\/Contents>/g)) {
+			const key = tag(m[1]!, 'Key');
+			if (!key) continue;
+			const modified = tag(m[1]!, 'LastModified');
+			const size = Number(tag(m[1]!, 'Size'));
+			objects.push({ key, lastModified: modified && !Number.isNaN(Date.parse(modified)) ? new Date(modified).toISOString() : null, size: Number.isFinite(size) ? size : null });
+		}
+		const truncated = tag(text, 'IsTruncated') === 'true';
+		return { objects, next: truncated ? tag(text, 'NextContinuationToken') : null };
+	}
+
+	return {
+		async list(prefix) {
+			const out: BucketObject[] = [];
+			const seen = new Set<string>();
+			let token: string | null = null;
+			for (let n = 0; n < MAX_PAGES; n++) {
+				const { objects, next } = await page(prefix, token);
+				out.push(...objects);
+				if (!next || seen.has(next)) break;
+				seen.add(next);
+				token = next;
+			}
+			return out;
+		},
+		async first(prefix) {
+			const { objects } = await page(prefix, null, 1);
+			return objects[0]?.key ?? null;
+		},
+		async head(key) {
+			const res = await call('HEAD', objectUrl(key));
+			if (res.status === 404) return null;
+			if (!res.ok) throw new BucketError(`head ${key}: ${res.status}`, res.status);
+			const h = res.headers;
+			const modified = h.get('last-modified');
+			const size = Number(h.get('content-length'));
+			return {
+				w: metaNumber(h.get('x-amz-meta-w')),
+				h: metaNumber(h.get('x-amz-meta-h')),
+				name: decodeName(h.get('x-amz-meta-name')),
+				by: decodeName(h.get('x-amz-meta-by')),
+				contentType: h.get('content-type'),
+				lastModified: modified && !Number.isNaN(Date.parse(modified)) ? new Date(modified).toISOString() : null,
+				size: Number.isFinite(size) ? size : null,
+			};
+		},
+		async get(key) {
+			const res = await call('GET', objectUrl(key), { stream: true });
+			if (res.status === 404) {
+				await res.body?.cancel().catch(() => {});
+				return null;
+			}
+			if (!res.ok || !res.body) {
+				const text = await res.text().catch(() => '');
+				throw new BucketError(`get ${key}: ${res.status} ${text.slice(0, 300)}`, res.status);
+			}
+			const size = Number(res.headers.get('content-length'));
+			return { body: res.body, size: res.headers.has('content-length') && Number.isFinite(size) ? size : null };
+		},
+		async put({ key, body, contentType, sha256, meta }) {
+			const headers: Record<string, string> = {
+				'Content-Type': contentType,
+				'X-Amz-Content-Sha256': sha256,
+				...(meta.w !== undefined ? { 'x-amz-meta-w': String(meta.w) } : {}),
+				...(meta.h !== undefined ? { 'x-amz-meta-h': String(meta.h) } : {}),
+				'x-amz-meta-name': encodeURIComponent(meta.name),
+			};
+			// An address as it is (Phase 0 wrote `setup` so); anything a header can't carry, URI-encoded as `name` is.
+			if (meta.by) headers['x-amz-meta-by'] = /^[\x21-\x7e]+$/.test(meta.by) && !meta.by.includes('%') ? meta.by : encodeURIComponent(meta.by);
+			const res = await call('PUT', objectUrl(key), { headers, body });
+			if (!res.ok) throw new BucketError(`put ${key}: ${res.status} ${(await res.text().catch(() => '')).slice(0, 300)}`, res.status);
+			await res.body?.cancel().catch(() => {});
+		},
+	};
+}
+
+// ── The in-memory bucket (CARACMS_MEDIA=memory) ────────────────────────────────
+
+export interface MemoryObject {
+	body: Uint8Array | null;
+	meta: ObjectMeta;
+}
+
+/** A bucket in memory, for tests and local runs. `seed` puts objects in as Phase 0's script or another place would. */
+export class MemoryBucket implements Bucket {
+	readonly objects = new Map<string, MemoryObject>();
+	/** Every call, in order (`list:<prefix>`, `head:<key>`, `get:<key>`, `put:<key>`), for tests that count them. */
+	readonly calls: string[] = [];
+	now: () => number = () => Date.now();
+
+	async list(prefix: string): Promise<BucketObject[]> {
+		this.calls.push(`list:${prefix}`);
+		return [...this.objects]
+			.filter(([key]) => key.startsWith(prefix))
+			.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+			.map(([key, o]) => ({ key, lastModified: o.meta.lastModified, size: o.meta.size }));
+	}
+	async first(prefix: string): Promise<string | null> {
+		this.calls.push(`first:${prefix}`);
+		return [...this.objects.keys()].filter((k) => k.startsWith(prefix)).sort()[0] ?? null;
+	}
+	async head(key: string): Promise<ObjectMeta | null> {
+		this.calls.push(`head:${key}`);
+		const o = this.objects.get(key);
+		return o ? { ...o.meta } : null;
+	}
+	/** A seeded object with no bytes (the library's tests seed most so) answers as missing. */
+	async get(key: string): Promise<ObjectBody | null> {
+		this.calls.push(`get:${key}`);
+		const bytes = this.objects.get(key)?.body;
+		if (!bytes) return null;
+		const copy = new Uint8Array(bytes);
+		return {
+			body: new ReadableStream<Uint8Array>({
+				start(controller) {
+					controller.enqueue(copy);
+					controller.close();
+				},
+			}),
+			size: copy.byteLength,
+		};
+	}
+	async put({ key, body, contentType, meta }: PutObject): Promise<void> {
+		this.calls.push(`put:${key}`);
+		if (this.objects.has(key)) throw new BucketError(`put ${key}: the key exists, and nothing in caracms overwrites`);
+		this.objects.set(key, {
+			body: new Uint8Array(body),
+			meta: { w: meta.w ?? null, h: meta.h ?? null, name: meta.name, by: meta.by, contentType, lastModified: new Date(this.now()).toISOString(), size: body.byteLength },
+		});
+	}
+	/**
+	 * Put an object straight in (a test's or a browser test's library): no bytes needed.
+	 * `uploadedAt` (ISO) orders the library; default now.
+	 */
+	seed(key: string, meta: { w?: number | null; h?: number | null; name?: string | null; by?: string | null; uploadedAt?: string; size?: number; contentType?: string } = {}, body: Uint8Array | null = null): void {
+		this.objects.set(key, {
+			body,
+			meta: {
+				w: meta.w ?? null,
+				h: meta.h ?? null,
+				name: meta.name ?? null,
+				by: meta.by ?? null,
+				contentType: meta.contentType ?? null,
+				lastModified: meta.uploadedAt ?? new Date(this.now()).toISOString(),
+				size: meta.size ?? body?.byteLength ?? null,
+			},
+		});
+	}
+	clear(): void {
+		this.objects.clear();
+		this.calls.length = 0;
+	}
+}

package/src/editor/server/media/config.ts

@@ -0,0 +1,78 @@
+/**
+ * Whether the media routes are set up (M5b Decision 5), images and clips apart: **one
+ * missing never disables the other**. Read from `process.env` on each request (cheap),
+ * so `astro build` needs none of them and the Mux token is first read by the first
+ * request that needs it.
+ *
+ * - **`CARACMS_MEDIA=memory` always wins**: the in-memory bucket and the fake Mux
+ *   (memory.ts), whatever else is set, so nothing in a test can touch the real bucket or
+ *   Mux. **Refused on a production server**, as `CARACMS_GITHUB=memory` is.
+ * - Images need imgproxy's (`CARACMS_MEDIA_URL`, `IMGPROXY_KEY`, `IMGPROXY_SALT`, which
+ *   sign the thumbnails) and the bucket's (`S3_BUCKET`, `S3_ENDPOINT`, `S3_REGION`,
+ *   `S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY`). Clips need `MUX_TOKEN_ID` and `MUX_TOKEN_SECRET`.
+ */
+import { isProductionBuild, readMediaConfig, type MediaSettings } from '../../../media.ts';
+
+type Env = Record<string, string | undefined>;
+
+export interface BucketSettings {
+	endpoint: string;
+	region: string;
+	bucket: string;
+	accessKeyId: string;
+	secretAccessKey: string;
+}
+
+export type ImagesConfig =
+	| { kind: 'memory'; signing: MediaSettings }
+	| { kind: 's3'; signing: MediaSettings; bucket: BucketSettings }
+	| { kind: 'unset'; message: string; missing: string[] };
+
+export type MuxConfig = { kind: 'memory' } | { kind: 'mux'; tokenId: string; tokenSecret: string } | { kind: 'unset'; message: string; missing: string[] };
+
+export const MEMORY_IN_PRODUCTION = 'CARACMS_MEDIA=memory is for tests and local runs; a production server never uses the in-memory media.';
+
+const list = (names: string[]) => (names.length <= 1 ? names.join('') : `${names.slice(0, -1).join(', ')} and ${names[names.length - 1]}`);
+const get = (env: Env, name: string) => {
+	const v = env[name]?.trim();
+	return v ? v : null;
+};
+const memory = (env: Env) => get(env, 'CARACMS_MEDIA') === 'memory';
+
+/** The image routes' settings: the bucket, and imgproxy's for the thumbnails. */
+export function readImagesConfig(env: Env = process.env, production = isProductionBuild()): ImagesConfig {
+	if (memory(env)) {
+		if (production) return { kind: 'unset', message: MEMORY_IN_PRODUCTION, missing: [] };
+		const signing = readMediaConfig(env, production);
+		if (signing.kind !== 'ready') return { kind: 'unset', message: MEMORY_IN_PRODUCTION, missing: [] };
+		return { kind: 'memory', signing: signing.settings };
+	}
+	const signing = readMediaConfig(env, production);
+	const missing = signing.kind === 'unset' ? [...signing.missing] : [];
+	const problems = signing.kind === 'unset' ? [...signing.problems] : [];
+	const need = (name: string) => {
+		const v = get(env, name);
+		if (!v && !missing.includes(name)) missing.push(name);
+		return v ?? '';
+	};
+	const endpoint = need('S3_ENDPOINT').replace(/\/+$/, '');
+	const region = need('S3_REGION');
+	const accessKeyId = need('S3_ACCESS_KEY_ID');
+	const secretAccessKey = need('S3_SECRET_ACCESS_KEY');
+	if (endpoint && !/^https?:\/\/[^/]+$/.test(endpoint)) problems.push(`S3_ENDPOINT must be an origin like https://t3.storageapi.dev (got "${endpoint}").`);
+	if (missing.length || problems.length || signing.kind !== 'ready') {
+		const sentence = missing.length ? `The media library isn't set up here: set ${list(missing)} to the site's media bucket and imgproxy.` : '';
+		return { kind: 'unset', message: [sentence, ...problems].filter(Boolean).join(' '), missing };
+	}
+	return { kind: 's3', signing: signing.settings, bucket: { endpoint, region, bucket: signing.settings.bucket, accessKeyId, secretAccessKey } };
+}
+
+/** The clip routes' settings: the site's Mux environment's token. */
+export function readMuxConfig(env: Env = process.env, production = isProductionBuild()): MuxConfig {
+	if (memory(env)) return production ? { kind: 'unset', message: MEMORY_IN_PRODUCTION, missing: [] } : { kind: 'memory' };
+	const tokenId = get(env, 'MUX_TOKEN_ID');
+	const tokenSecret = get(env, 'MUX_TOKEN_SECRET');
+	const missing = [...(tokenId ? [] : ['MUX_TOKEN_ID']), ...(tokenSecret ? [] : ['MUX_TOKEN_SECRET'])];
+	if (missing.length) return { kind: 'unset', message: `Video isn't set up here: set ${list(missing)} to the site's Mux environment's token.`, missing };
+	return { kind: 'mux', tokenId: tokenId!, tokenSecret: tokenSecret! };
+}