caracms 0.0.0-stage → 0.2.0

package/src/live/merge.ts

@@ -0,0 +1,197 @@
+/**
+ * The three-way merge (M4 Decisions 6 and 7), pure: text in, text out.
+ *
+ * One rule for every merge in live mode: committing an autosave (the autosave's
+ * base, the autosave, the file in `drafts` now), merging `main` into `drafts` (the
+ * merge base, `drafts`, `main`), and held edits re-sent after a sign-in. One side is
+ * always **the draft**, and the draft wins a conflict.
+ *
+ * - **A JSON object file** merges per top-level key: a key changed on one side takes
+ *   that side; a key changed on both takes the draft; a key added or removed on one
+ *   side follows that side.
+ * - **Anything else** (not JSON on any side, not an object, a file deleted on one
+ *   side and changed on the other, or a caller saying it isn't a content file) falls
+ *   back to the whole file, the draft winning.
+ * - **Byte-preserving** (M3 Decision 7's rule): the result is built on the draft's
+ *   text. Untouched keys keep their text and position exactly. A member taken from
+ *   the other side has its value's text spliced in at the draft member's span; a key
+ *   new on the other side is appended at the end, in that side's order, with its
+ *   text as written there; a key the other side removed is cut out with its comma.
+ *   Never `JSON.stringify`, never `applyEdits` (which only knows a title and blocks).
+ *
+ * "Changed" compares values, not text: a key re-indented but equal isn't a change.
+ */
+import { member, parseSource, slice, type MemberNode, type ObjectNode, type ParsedSource } from '../json-source.ts';
+
+export interface MergeInput {
+	/** The common ancestor's text; null when the file didn't exist there. */
+	base: string | null;
+	/** The draft's text (it wins conflicts); null when the draft deleted it. */
+	draft: string | null;
+	/** The other side's text; null when that side deleted it. */
+	other: string | null;
+	/** False forces the whole-file rule (a non-content file). Default true. */
+	perKey?: boolean;
+}
+
+export interface MergeResult {
+	/** The merged text, or null for "the file is deleted". */
+	text: string | null;
+	/** Some key, or the whole file, was changed on both sides and decided for the draft: show the notice. */
+	keptDraft: boolean;
+	/** The keys decided for the draft (empty for a whole-file decision). */
+	conflicts: string[];
+	/** How it was decided. */
+	how: 'same' | 'draft' | 'other' | 'keys' | 'whole-file';
+}
+
+export function mergeFile({ base, draft, other, perKey = true }: MergeInput): MergeResult {
+	if (draft === other) return { text: draft, keptDraft: false, conflicts: [], how: 'same' };
+	if (draft === base) return { text: other, keptDraft: false, conflicts: [], how: 'other' };
+	if (other === base) return { text: draft, keptDraft: false, conflicts: [], how: 'draft' };
+
+	const whole: MergeResult = { text: draft, keptDraft: true, conflicts: [], how: 'whole-file' };
+	if (!perKey || draft === null || other === null) return whole;
+	const d = objectSource(draft);
+	const o = objectSource(other);
+	// An added-on-both-sides file merges as if the ancestor were `{}`.
+	const b = base === null ? EMPTY : objectSource(base);
+	if (!d || !o || !b) return whole;
+
+	const value = (s: Parsed, key: string) => (Object.hasOwn(s.value, key) ? { v: s.value[key] } : null);
+	const same = (x: { v: unknown } | null, y: { v: unknown } | null) => (x === null || y === null ? x === y : equal(x.v, y.v));
+
+	const conflicts: string[] = [];
+	const replace: { member: MemberNode; text: string }[] = [];
+	const remove: string[] = [];
+	const append: string[] = [];
+	const keys = [...new Set([...unique(d.root), ...unique(o.root), ...unique(b.root)])];
+	for (const key of keys) {
+		const dv = value(d, key);
+		const ov = value(o, key);
+		const bv = value(b, key);
+		if (same(dv, ov)) continue; // the same on both sides
+		if (same(ov, bv)) continue; // only the draft changed it: the draft has it
+		if (same(dv, bv)) {
+			// Only the other side changed it: take that side's.
+			if (ov === null) remove.push(key);
+			else if (dv === null) append.push(key);
+			else replace.push({ member: member(d.root, key)!, text: slice(o.source, member(o.root, key)!.value) });
+			continue;
+		}
+		conflicts.push(key); // changed on both: the draft's stays
+	}
+	if (replace.length === 0 && remove.length === 0 && append.length === 0) {
+		return { text: draft, keptDraft: conflicts.length > 0, conflicts, how: 'keys' };
+	}
+	return { text: spliceMembers(d, o, replace, remove, append), keptDraft: conflicts.length > 0, conflicts, how: 'keys' };
+}
+
+interface Parsed {
+	source: ParsedSource;
+	root: ObjectNode;
+	value: Record<string, unknown>;
+}
+
+const EMPTY: Parsed = (() => {
+	const source = parseSource('{}');
+	return { source, root: source.root as ObjectNode, value: {} };
+})();
+
+function objectSource(text: string): Parsed | null {
+	let source: ParsedSource;
+	try {
+		source = parseSource(text);
+	} catch {
+		return null;
+	}
+	if (source.root.kind !== 'object') return null;
+	return { source, root: source.root, value: source.value as Record<string, unknown> };
+}
+
+/** Keys in the order they first appear. */
+const unique = (root: ObjectNode) => [...new Set(root.members.map((m) => m.key))];
+
+/** Deep equality of JSON values; object key order doesn't matter. */
+function equal(x: unknown, y: unknown): boolean {
+	if (x === y) return true;
+	if (typeof x !== 'object' || typeof y !== 'object' || x === null || y === null) return false;
+	if (Array.isArray(x) !== Array.isArray(y)) return false;
+	if (Array.isArray(x)) {
+		const ys = y as unknown[];
+		return x.length === ys.length && x.every((v, i) => equal(v, ys[i]));
+	}
+	const xk = Object.keys(x);
+	const yk = Object.keys(y);
+	return xk.length === yk.length && xk.every((k) => Object.hasOwn(y, k) && equal((x as Record<string, unknown>)[k], (y as Record<string, unknown>)[k]));
+}
+
+/** Where each member's key starts (its opening quote): parseSource records only values. */
+function keyStarts(source: ParsedSource, root: ObjectNode): number[] {
+	const text = source.text;
+	const skip = (i: number) => {
+		while (i < text.length && /\s/.test(text[i]!)) i++;
+		return i;
+	};
+	return root.members.map((_, k) => {
+		if (k === 0) return skip(root.start + 1);
+		return skip(skip(root.members[k - 1]!.value.end) + 1); // past the comma
+	});
+}
+
+/**
+ * The draft's text with members replaced (value spans), removed (with their comma)
+ * and appended (the other side's member text, in its order). Edits run from the end
+ * of the text back, so earlier offsets stay true.
+ */
+function spliceMembers(d: Parsed, o: Parsed, replace: { member: MemberNode; text: string }[], remove: string[], append: string[]): string {
+	const text = d.source.text;
+	const members = d.root.members;
+	const starts = keyStarts(d.source, d.root);
+	const edits: { from: number; to: number; text: string }[] = [];
+
+	for (const r of replace) edits.push({ from: r.member.value.start, to: r.member.value.end, text: r.text });
+
+	// Removing a key removes every member with it (JSON.parse keeps the last; all go).
+	const removing = new Set(remove);
+	const kept = members.map((m) => !removing.has(m.key));
+	for (let k = 0; k < members.length; k++) {
+		if (kept[k]) continue;
+		const next = kept.indexOf(true, k + 1) === -1 ? -1 : k + 1;
+		if (next !== -1) {
+			// Cut from this key to the next member's key: the member, its comma and the gap.
+			edits.push({ from: starts[k]!, to: starts[k + 1]!, text: '' });
+		} else {
+			// The last kept members are before it: cut from the end of the previous member.
+			const prev = k - 1;
+			const from = prev >= 0 ? members[prev]!.value.end : starts[k]!;
+			edits.push({ from, to: members[k]!.value.end, text: '' });
+		}
+	}
+
+	if (append.length) {
+		const oStarts = keyStarts(o.source, o.root);
+		const memberText = (key: string) => {
+			const k = o.root.members.findLastIndex((m) => m.key === key);
+			return o.source.text.slice(oStarts[k]!, o.root.members[k]!.value.end);
+		};
+		const order = unique(o.root).filter((k) => append.includes(k));
+		const lastKept = kept.lastIndexOf(true);
+		if (lastKept === -1) {
+			// No members left in the draft: lay them out with the other side's gaps.
+			const gap = o.source.text.slice(o.root.start + 1, oStarts[0]);
+			const close = o.source.text.slice(o.root.members.at(-1)!.value.end, o.root.end - 1);
+			edits.push({ from: d.root.start + 1, to: d.root.end - 1, text: gap + order.map(memberText).join(`,${gap}`) + close });
+		} else {
+			// The gap before the draft's members (`\n  `), so new keys line up with them.
+			const gap = lastKept > 0 ? text.slice(text.indexOf(',', members[lastKept - 1]!.value.end) + 1, starts[lastKept]) : text.slice(d.root.start + 1, starts[0]);
+			const at = members[lastKept]!.value.end;
+			edits.push({ from: at, to: at, text: order.map((k) => `,${gap}${memberText(k)}`).join('') });
+		}
+	}
+
+	edits.sort((a, b) => b.from - a.from || b.to - a.to);
+	let out = text;
+	for (const e of edits) out = out.slice(0, e.from) + e.text + out.slice(e.to);
+	return out;
+}

package/src/live/messages.ts

@@ -0,0 +1,151 @@
+/**
+ * The commit messages live mode writes, and reading them back (M4 Decisions 5, 8, 10).
+ * **The formats are a contract**: the waiting list, who changed what, the merge
+ * notices and the publish history are all rebuilt from them if Redis is flushed
+ * ("everything in it either expires or can be rebuilt from git"). Commits have no
+ * author, so GitHub signs them (M1 → G1); people go in the message.
+ *
+ * A draft commit (the sweep), one per batch:
+ *
+ *     Draft: Home, About
+ *
+ *     Edited-by: Aoife <aoife@fernhill.ie>: content/pages/index.json, content/pages/about.json
+ *     Edited-by: Ciarán <ciaran@fernhill.ie>: content/pages/about.json
+ *     Draft-kept: content/pages/about.json
+ *
+ * One `Edited-by` per editor, paths relative to the site's folder (Decision 3). A
+ * name is the part of the address before `@` when the person has no other name.
+ * `Draft-kept` is there only when the merge (merge.ts) decided a key or a file for
+ * the draft: the notice's data.
+ *
+ * Merging `main` into `drafts`:
+ *
+ *     Merge main into drafts
+ *
+ *     From-main: content/pages/about.json
+ *     Draft-kept: content/pages/index.json
+ *
+ * A publish, the one squashed commit on `main`:
+ *
+ *     Published: Home, About — by Aoife
+ *
+ *     Published-by: Aoife <aoife@fernhill.ie>
+ *     Published-files: content/pages/index.json, content/pages/about.json
+ */
+
+export interface Person {
+	email: string;
+	/** Shown instead of the address's local part when set. */
+	name?: string | null;
+}
+
+/** The name a person goes by in messages: their name, or the address before `@`. */
+export function displayName(person: Person): string {
+	const name = person.name?.trim();
+	return name || person.email.split('@')[0]!;
+}
+
+/** `Aoife <aoife@fernhill.ie>`, with anything that would break the trailer taken out. */
+const ident = (p: Person) => `${displayName(p).replace(/[<>\n\r]/g, '').trim()} <${p.email.replace(/[<>\s]/g, '')}>`;
+
+/**
+ * "Home, About", or "Home, About, Work, Contact, Journal and 3 more". A title's line
+ * breaks and control characters become spaces, so no title can start a trailer line.
+ */
+export function titleList(titles: string[]): string {
+	const unique = [...new Set(titles.map((t) => t.replace(/\p{Cc}+/gu, ' ').trim()))];
+	if (unique.length <= 5) return unique.join(', ');
+	return `${unique.slice(0, 5).join(', ')} and ${unique.length - 5} more`;
+}
+
+export interface DraftEdit {
+	/** Site-relative path. */
+	file: string;
+	title: string;
+	editor: Person;
+}
+
+/** A draft commit's headline and body. Editors in the order they first appear; their files in batch order. */
+export function draftMessage(edits: DraftEdit[], keptDraft: string[] = []): { headline: string; body: string } {
+	const byEditor = new Map<string, { person: Person; files: string[] }>();
+	for (const e of edits) {
+		const key = e.editor.email.toLowerCase();
+		const entry = byEditor.get(key) ?? { person: e.editor, files: [] };
+		if (!entry.files.includes(e.file)) entry.files.push(e.file);
+		byEditor.set(key, entry);
+	}
+	const lines = [...byEditor.values()].map(({ person, files }) => `Edited-by: ${ident(person)}: ${files.join(', ')}`);
+	if (keptDraft.length) lines.push(`Draft-kept: ${[...new Set(keptDraft)].join(', ')}`);
+	return { headline: `Draft: ${titleList(edits.map((e) => e.title))}`, body: lines.join('\n') };
+}
+
+export function mergeMessage(fromMain: string[], keptDraft: string[]): string {
+	const lines = [];
+	if (fromMain.length) lines.push(`From-main: ${fromMain.join(', ')}`);
+	if (keptDraft.length) lines.push(`Draft-kept: ${keptDraft.join(', ')}`);
+	return `Merge main into drafts${lines.length ? `\n\n${lines.join('\n')}` : ''}`;
+}
+
+export function publishMessage(titles: string[], files: string[], by: Person): string {
+	return `Published: ${titleList(titles)} — by ${displayName(by)}\n\nPublished-by: ${ident(by)}\nPublished-files: ${files.join(', ')}`;
+}
+
+// ── Reading them back ─────────────────────────────────────────────────────────
+
+export interface ParsedMessage {
+	kind: 'draft' | 'merge' | 'publish' | 'other';
+	/** Edited-by trailers: who changed which files. */
+	edits: { person: Person; files: string[] }[];
+	/** Draft-kept: files where the draft won a conflict. */
+	keptDraft: string[];
+	/** Published-by, for a publish. */
+	publishedBy: Person | null;
+	/** Published-files, for a publish. */
+	publishedFiles: string[];
+	/** The titles in a Draft or Published headline (without "and N more"). */
+	titles: string[];
+}
+
+const list = (value: string) =>
+	value
+		.split(',')
+		.map((s) => s.trim())
+		.filter(Boolean);
+
+const parsePerson = (value: string): Person | null => {
+	const m = /^(.*?)\s*<([^>]+)>$/.exec(value.trim());
+	if (!m) return null;
+	const name = m[1]!.trim();
+	const email = m[2]!.trim();
+	return { email, name: name && name !== email.split('@')[0] ? name : null };
+};
+
+/** Read a message written by the functions above. Anything else parses as `other` with no data. */
+export function parseMessage(message: string): ParsedMessage {
+	const [headline = '', ...rest] = message.split('\n');
+	const out: ParsedMessage = { kind: 'other', edits: [], keptDraft: [], publishedBy: null, publishedFiles: [], titles: [] };
+	const titles = (s: string) => list(s.replace(/ and \d+ more$/, ''));
+	if (headline.startsWith('Draft: ')) {
+		out.kind = 'draft';
+		out.titles = titles(headline.slice('Draft: '.length));
+	} else if (headline === 'Merge main into drafts') out.kind = 'merge';
+	else if (headline.startsWith('Published: ')) {
+		out.kind = 'publish';
+		out.titles = titles(headline.slice('Published: '.length).replace(/ — by .*$/, ''));
+	}
+	for (const line of rest) {
+		const m = /^([A-Za-z-]+): (.*)$/.exec(line.trim());
+		if (!m) continue;
+		const [, key, value] = m;
+		if (key === 'Edited-by') {
+			// `Name <email>: path, path`; the person ends at the first `>: `.
+			const at = value!.indexOf('>: ');
+			if (at === -1) continue;
+			const person = parsePerson(value!.slice(0, at + 1));
+			if (person) out.edits.push({ person, files: list(value!.slice(at + 3)) });
+		} else if (key === 'Draft-kept') out.keptDraft.push(...list(value!));
+		else if (key === 'Published-by') out.publishedBy = parsePerson(value!);
+		else if (key === 'Published-files') out.publishedFiles = list(value!);
+	}
+	return out;
+}

package/src/live/mode.ts

@@ -0,0 +1,210 @@
+/**
+ * Which mode the editor runs in, read from the environment (M4 Decision 1).
+ *
+ * - **Local mode**: `astro dev` with no `GITHUB_APP_ID`. M3's editor, files on disk.
+ * - **Live mode**: whenever the App is configured, and **always on a production
+ *   server**. It needs `GITHUB_APP_ID`, `GITHUB_APP_PRIVATE_KEY`, the repo
+ *   (`RAILWAY_GIT_REPO_OWNER` and `RAILWAY_GIT_REPO_NAME`, or `GITHUB_REPO=owner/name`;
+ *   Decision 3), `CARACMS_SECRET`, and `REDIS_URL` in production (dev may use the
+ *   stand-in). A production server missing any of them still serves the public site;
+ *   `/admin` answers 503 naming them (Phase 2 builds that from `missing`).
+ * - **The in-memory GitHub** (Decision 2): `CARACMS_GITHUB=memory`, for tests and local
+ *   browser runs, never against the site's own repo. It's live mode with no App and
+ *   no repo, and it's **refused in production**.
+ *
+ * This only reads; it doesn't wire anything (Phase 2 switches the routes on it,
+ * Phase 3 guards with it).
+ */
+import { DEFAULT_BRANCHES, type BranchNames } from './branches.ts';
+import { DEFAULT_TIMINGS, type LiveTimings } from './timings.ts';
+
+export interface LiveSettings {
+	/** `memory`: the in-memory GitHub backend (Decision 2). */
+	github:
+		| { kind: 'app'; appId: string; privateKey: string; owner: string; repo: string }
+		| { kind: 'memory' };
+	/** Null in dev without REDIS_URL: the in-memory stand-in. */
+	redisUrl: string | null;
+	/** CARACMS_SECRET: signs sessions (Phase 3). */
+	secret: string;
+	/** CARACMS_ALLOW, split: exact addresses and `@domain`s, lower-cased and trimmed (Decision 15). */
+	allow: string[];
+	/** GITHUB_WEBHOOK_SECRET; null means the webhook route answers 404 (Decision 14). */
+	webhookSecret: string | null;
+	/** Try again (Decision 12): all three, or null. */
+	railway: { token: string; serviceId: string; environmentId: string } | null;
+	/** CARACMS_BACKUP_USER and CARACMS_BACKUP_PASSWORD, both or neither (Phase 3 checks the length). */
+	backup: { user: string; password: string } | null;
+	/** CARACMS_RUNNING_COMMIT, else RAILWAY_GIT_COMMIT_SHA; null with no deploy pipeline (Decision 12). */
+	runningCommit: string | null;
+	/** Dev only: CARACMS_TIMINGS, a JSON object of LiveTimings to shorten (Decision 2). */
+	timings: LiveTimings;
+	/**
+	 * CARACMS_MAIN_BRANCH and CARACMS_DRAFTS_BRANCH (M9 Decision 6): the refs Publish and
+	 * autosave move, `main` and `drafts` unset. readMode always fills it; missing (a test's
+	 * settings) means the defaults.
+	 */
+	branches?: BranchNames;
+	production: boolean;
+}
+
+export type Mode =
+	| { kind: 'local' }
+	| { kind: 'live'; settings: LiveSettings }
+	/** Live mode, but not usable: `missing` names required variables; `problems` are sentences for anything else wrong. */
+	| { kind: 'unconfigured'; missing: string[]; problems: string[] };
+
+type Env = Record<string, string | undefined>;
+
+/**
+ * Read the mode. `production` is whether this is a production server (the
+ * integration knows: not `astro dev`); it defaults to `NODE_ENV === 'production'`.
+ */
+export function readMode(env: Env = process.env, production = env.NODE_ENV === 'production'): Mode {
+	const get = (name: string) => {
+		const v = env[name]?.trim();
+		return v ? v : null;
+	};
+	const memory = get('CARACMS_GITHUB') === 'memory';
+	if (!production && !memory && !get('GITHUB_APP_ID')) return { kind: 'local' };
+
+	const missing: string[] = [];
+	const problems: string[] = [];
+	const need = (name: string) => {
+		const v = get(name);
+		if (!v) missing.push(name);
+		return v ?? '';
+	};
+
+	if (memory && production) problems.push('CARACMS_GITHUB=memory is for tests and local runs; a production server never uses the in-memory GitHub.');
+	const other = get('CARACMS_GITHUB');
+	if (other && other !== 'memory') problems.push(`CARACMS_GITHUB must be "memory" or unset (got "${other}").`);
+
+	let github: LiveSettings['github'] = { kind: 'memory' };
+	if (!memory || production) {
+		const appId = need('GITHUB_APP_ID');
+		const privateKey = need('GITHUB_APP_PRIVATE_KEY');
+		const repo = readRepo(env, problems);
+		if (!repo) missing.push('RAILWAY_GIT_REPO_OWNER and RAILWAY_GIT_REPO_NAME (or GITHUB_REPO)');
+		github = { kind: 'app', appId, privateKey, owner: repo?.owner ?? '', repo: repo?.repo ?? '' };
+	}
+	const secret = need('CARACMS_SECRET');
+	const redisUrl = production ? need('REDIS_URL') : get('REDIS_URL');
+
+	const token = get('CARACMS_RAILWAY_TOKEN');
+	const serviceId = get('RAILWAY_SERVICE_ID');
+	const environmentId = get('RAILWAY_ENVIRONMENT_ID');
+	const user = get('CARACMS_BACKUP_USER');
+	const password = env.CARACMS_BACKUP_PASSWORD || null; // a password's spaces are its own
+
+	let timings = { ...DEFAULT_TIMINGS };
+	const rawTimings = get('CARACMS_TIMINGS');
+	if (rawTimings) {
+		if (production) problems.push('CARACMS_TIMINGS is for tests; a production server uses the real timings.');
+		else timings = { ...timings, ...parseTimings(rawTimings, problems) };
+	}
+
+	const branches = readBranches(get, problems);
+
+	if (missing.length || problems.length) return { kind: 'unconfigured', missing, problems };
+	return {
+		kind: 'live',
+		settings: {
+			github,
+			redisUrl: redisUrl || null,
+			secret,
+			allow: (get('CARACMS_ALLOW') ?? '')
+				.split(',')
+				.map((s) => s.trim().toLowerCase())
+				.filter(Boolean),
+			webhookSecret: get('GITHUB_WEBHOOK_SECRET'),
+			railway: token && serviceId && environmentId ? { token, serviceId, environmentId } : null,
+			backup: user && password ? { user, password } : null,
+			runningCommit: get('CARACMS_RUNNING_COMMIT') ?? get('RAILWAY_GIT_COMMIT_SHA'),
+			timings,
+			branches,
+			production,
+		},
+	};
+}
+
+/**
+ * The branch names (M9 Decision 6). Both set or neither (one alone would leave the other
+ * at its default, so a site meant to keep off `main` would still publish to it). Each must
+ * be a plain branch name, the two must differ, and autosaves never go to a branch called
+ * `main` under another name (that's the branch the settings exist to keep still).
+ */
+function readBranches(get: (name: string) => string | null, problems: string[]): BranchNames {
+	const main = get('CARACMS_MAIN_BRANCH');
+	const drafts = get('CARACMS_DRAFTS_BRANCH');
+	if ((main === null) !== (drafts === null)) {
+		problems.push(`CARACMS_MAIN_BRANCH and CARACMS_DRAFTS_BRANCH must be set together (only ${main === null ? 'CARACMS_DRAFTS_BRANCH' : 'CARACMS_MAIN_BRANCH'} is set), or neither for main and drafts.`);
+	}
+	const branches: BranchNames = {
+		main: get('CARACMS_MAIN_BRANCH') ?? DEFAULT_BRANCHES.main,
+		drafts: get('CARACMS_DRAFTS_BRANCH') ?? DEFAULT_BRANCHES.drafts,
+	};
+	for (const [name, value] of [
+		['CARACMS_MAIN_BRANCH', branches.main],
+		['CARACMS_DRAFTS_BRANCH', branches.drafts],
+	] as const) {
+		if (!isBranchName(value)) problems.push(`${name} must be a branch name, like port-caracms (got "${value}").`);
+	}
+	if (branches.main === branches.drafts) problems.push(`CARACMS_MAIN_BRANCH and CARACMS_DRAFTS_BRANCH must differ (both are "${branches.main}").`);
+	else if (branches.drafts === 'main') problems.push('CARACMS_DRAFTS_BRANCH can\'t be main: autosaves would land on main.');
+	return branches;
+}
+
+/** A plain branch name: no `refs/` prefix, nothing git refuses in a ref. */
+function isBranchName(name: string): boolean {
+	return (
+		/^[A-Za-z0-9._/-]+$/.test(name) &&
+		!name.startsWith('refs/') &&
+		!/^[-/.]|[/.]$|\.\.|\/\/|\/\.|\.lock$|\.lock\//.test(name)
+	);
+}
+
+/** The repo: GITHUB_REPO overrides Railway's own variables (Decision 3). */
+function readRepo(env: Env, problems: string[]): { owner: string; repo: string } | null {
+	const override = env.GITHUB_REPO?.trim();
+	if (override) {
+		const m = /^([A-Za-z0-9-]+)\/([A-Za-z0-9._-]+)$/.exec(override);
+		if (!m) {
+			problems.push(`GITHUB_REPO must be owner/name (got "${override}").`);
+			return null;
+		}
+		return { owner: m[1]!, repo: m[2]! };
+	}
+	const owner = env.RAILWAY_GIT_REPO_OWNER?.trim();
+	const repo = env.RAILWAY_GIT_REPO_NAME?.trim();
+	return owner && repo ? { owner, repo } : null;
+}
+
+function parseTimings(raw: string, problems: string[]): Partial<LiveTimings> {
+	let value: unknown;
+	try {
+		value = JSON.parse(raw);
+	} catch {
+		problems.push('CARACMS_TIMINGS must be a JSON object, like {"sweepIdleMs":2000}.');
+		return {};
+	}
+	const out: Partial<LiveTimings> = {};
+	if (!value || typeof value !== 'object' || Array.isArray(value)) {
+		problems.push('CARACMS_TIMINGS must be a JSON object, like {"sweepIdleMs":2000}.');
+		return out;
+	}
+	for (const [k, v] of Object.entries(value)) {
+		if (!Object.hasOwn(DEFAULT_TIMINGS, k)) problems.push(`CARACMS_TIMINGS: "${k}" isn't a timing (${Object.keys(DEFAULT_TIMINGS).join(', ')}).`);
+		else if (typeof v !== 'number' || !(v > 0)) problems.push(`CARACMS_TIMINGS: "${k}" must be a positive number of milliseconds.`);
+		else out[k as keyof LiveTimings] = v;
+	}
+	return out;
+}
+
+/** The sentence `/admin` shows when live mode isn't usable (Decision 1). */
+export function unconfiguredMessage(mode: Extract<Mode, { kind: 'unconfigured' }>): string {
+	const parts = [];
+	if (mode.missing.length) parts.push(`The editor isn't set up on this server yet: it needs ${mode.missing.join(', ')}.`);
+	parts.push(...mode.problems);
+	return parts.join(' ');
+}