caracms 0.7.0 → 0.8.1

package/src/live/github.ts

@@ -15,7 +15,8 @@
  *
  * - **Every request times out** after `timeoutMs` (20 s), its body included: a GitHub
  *   that stops answering fails the operation instead of holding it (and Publish's or
- *   the check's callers) forever.
+ *   the check's callers) forever. The cloud's token call is the one exception: 35 s
+ *   unless `timeoutMs` is given (cloud.ts, `CLOUD_TOKEN_TIMEOUT_MS`).
  *
  * - **Access problems** (Decision 5): every response is watched for a refused credential
  *   (401), a write refused for lack of a permission (403 "not accessible"), and, for a
@@ -25,13 +26,21 @@
  * - **CaraCMS Cloud** (`CARACMS_CLOUD_KEY`; caracms-cloud M2 Decisions 12–14) mints the
  *   installation token instead: `POST /v1/github/token` (cloud.ts), refreshed five minutes
  *   early like the App's. A refusal from the cloud is an access problem of kind `cloud`
- *   carrying the cloud's sentence (and its install link), cleared by the next token; so is
- *   a token answer for another repo than the one the server started on.
+ *   carrying the cloud's sentence (and its install link), cleared by the next token.
+ * - **A rename or transfer on GitHub** (caracms-cloud adversarial review, finding 7; this
+ *   retires M2 Decision 13's refusal of a token answer for another repo, whose only way out
+ *   was a developer restarting the server): the settings are read again, and when they name
+ *   the new repo too, the client takes that name for the rest of the process. Every path,
+ *   GraphQL variable and commit asks for it from then on (the backend reads `owner`, `repo`
+ *   and `nameWithOwner` on each call), a call that was waiting on the token is moved to it,
+ *   one line is logged and the editor gets an information note (`renamed`) until the next
+ *   restart. Settings that don't name it yet, or can't be read, fail that refresh as an
+ *   access problem of kind `cloud`; the next token asks again.
  *
  * The private key, the site key and the tokens are never logged.
  */
 import { createSign } from 'node:crypto';
-import { CLOUD_REPO_CHANGED, CloudRefusal, isCloudRefusal, cloudToken } from './cloud.ts';
+import { CLOUD_REPO_CHANGED, CloudRefusal, confirmCloudRepo, isCloudRefusal, cloudToken } from './cloud.ts';
 
 const API = 'https://api.github.com';
 
@@ -61,6 +70,8 @@ export interface TokenConnection extends ConnectionBase {
 export interface CloudConnection extends ConnectionBase {
 	cloudKey: string;
 	cloudUrl: string;
+	/** Finding 7's one line when the repo's new name is taken. Default: the console, as `[caracms] …`. */
+	log?: (line: string) => void;
 }
 
 export type GitHubConnection = AppConnection | TokenConnection | CloudConnection;
@@ -77,7 +88,9 @@ export type GitHubAccessProblem =
 	| { kind: 'permission'; credential: GitHubCredential; permission: string }
 	| { kind: 'expiring'; credential: 'token'; expires: string }
 	/** CaraCMS Cloud refused a token (caracms-cloud M2 Decision 14): its sentence as it came, and its install link. */
-	| { kind: 'cloud'; credential: 'cloud'; message: string; installUrl: string | null };
+	| { kind: 'cloud'; credential: 'cloud'; message: string; installUrl: string | null }
+	/** Not a problem: information (finding 7). The repo was renamed or transferred, and work carries on under `repo`. */
+	| { kind: 'renamed'; credential: 'cloud'; repo: string; was: string };
 
 /** A token expiring within this long shows in the editor (Decision 5). */
 export const TOKEN_EXPIRY_WARNING_MS = 14 * 24 * 60 * 60_000;
@@ -115,6 +128,8 @@ export function accessProblemMessage(problem: GitHubAccessProblem): string {
 			return `GitHub refused a change because this site's ${what} lacks the "${problem.permission}" permission. A developer can add it in the ${problem.credential === 'token' ? "token's settings" : "App's settings"}.`;
 		case 'cloud':
 			return problem.message;
+		case 'renamed':
+			return `This site's GitHub repo is now ${problem.repo} (it was ${problem.was}). Changes save and publish to it as before; nothing needs doing.`;
 		case 'expiring': {
 			const date = new Date(problem.expires).toLocaleDateString('en-IE', { day: 'numeric', month: 'long', year: 'numeric', timeZone: 'UTC' });
 			return `This site's ${what} expires on ${date}. After that, changes can't be saved to GitHub: a developer can regenerate it, or make a new one, and set it before then.`;
@@ -229,8 +244,6 @@ function shorten(p: string): string {
 
 export class GitHubClient {
 	readonly tracker: Tracker;
-	readonly owner: string;
-	readonly repo: string;
 	/** Which credential this client signs in with. */
 	readonly credential: GitHubCredential;
 	private readonly appId: string;
@@ -239,6 +252,8 @@ export class GitHubClient {
 	private readonly fetcher: typeof fetch;
 	private readonly now: () => number;
 	private readonly timeoutMs: number;
+	/** The connection's own `timeoutMs` (tests), else undefined: the token call then waits its 35 s (cloud.ts). */
+	private readonly givenTimeoutMs: number | undefined;
 	private token = '';
 	private tokenExpires = 0;
 	private signingIn: Promise<void> | null = null;
@@ -248,6 +263,11 @@ export class GitHubClient {
 	private personalTokenExpires: number | null = null;
 	/** The cloud's last refusal, until a token comes. */
 	private cloudProblem: { message: string; installUrl: string | null } | null = null;
+	/** The repo, as the server started on it or as a rename made it since (finding 7). */
+	private name: { owner: string; repo: string };
+	/** The name before the last rename taken, for the editor's note until a restart. */
+	private renamedFrom: string | null = null;
+	private readonly log: (line: string) => void = (line) => console.log(`[caracms] ${line}`);
 
 	constructor(connection: GitHubConnection, tracker: Tracker) {
 		if ('token' in connection) {
@@ -261,16 +281,17 @@ export class GitHubClient {
 			this.appId = '';
 			this.key = '';
 			this.cloud = { key: connection.cloudKey, url: connection.cloudUrl };
+			if (connection.log) this.log = connection.log;
 		} else {
 			this.credential = 'app';
 			this.appId = connection.appId;
 			this.key = connection.privateKey.includes('\\n') ? connection.privateKey.replace(/\\n/g, '\n') : connection.privateKey;
 		}
-		this.owner = connection.owner;
-		this.repo = connection.repo;
+		this.name = { owner: connection.owner, repo: connection.repo };
 		this.fetcher = connection.fetch ?? fetch;
 		this.now = connection.now ?? Date.now;
 		this.timeoutMs = connection.timeoutMs ?? GITHUB_TIMEOUT_MS;
+		this.givenTimeoutMs = connection.timeoutMs;
 		this.tracker = tracker;
 	}
 
@@ -283,6 +304,7 @@ export class GitHubClient {
 		if (this.credential === 'token' && expires !== null && expires - this.now() < TOKEN_EXPIRY_WARNING_MS) {
 			return { kind: 'expiring', credential: 'token', expires: new Date(expires).toISOString() };
 		}
+		if (this.renamedFrom) return { kind: 'renamed', credential: 'cloud', repo: this.nameWithOwner, was: this.renamedFrom };
 		return null;
 	}
 
@@ -306,6 +328,14 @@ export class GitHubClient {
 		if (notPermitted && write && !/\/deployments/.test(path)) this.missingPermission = CONTENTS_PERMISSION;
 	}
 
+	get owner() {
+		return this.name.owner;
+	}
+
+	get repo() {
+		return this.name.repo;
+	}
+
 	get nameWithOwner() {
 		return `${this.owner}/${this.repo}`;
 	}
@@ -339,15 +369,25 @@ export class GitHubClient {
 	private async cloudSignIn(cloud: { key: string; url: string }): Promise<void> {
 		let answer;
 		try {
-			answer = await cloudToken({ ...cloud, fetch: this.fetcher, timeoutMs: this.timeoutMs });
+			// Seam note (caracms-cloud adversarial review): the token route's worst case passes 20 s, so
+			// it gets cloud.ts's 35 s; the settings read below keeps the 20 s every other call has.
+			answer = await cloudToken({ ...cloud, fetch: this.fetcher, timeoutMs: this.givenTimeoutMs });
 		} catch (error) {
 			if (isCloudRefusal(error) && error.error !== 'unreachable') this.cloudProblem = { message: error.message, installUrl: error.installUrl };
 			throw error;
 		}
 		if (answer.repo.toLowerCase() !== this.nameWithOwner.toLowerCase()) {
-			const refusal = new CloudRefusal('repo_changed', CLOUD_REPO_CHANGED(answer.repo));
-			this.cloudProblem = { message: refusal.message, installUrl: null };
-			throw refusal;
+			// Finding 7: a rename or transfer. Taken only when the settings, read again, name it too.
+			const repo = await confirmCloudRepo({ ...cloud, fetch: this.fetcher, timeoutMs: this.timeoutMs }, answer.repo);
+			if (!repo) {
+				const refusal = new CloudRefusal('repo_changed', CLOUD_REPO_CHANGED(answer.repo));
+				this.cloudProblem = { message: refusal.message, installUrl: null };
+				throw refusal;
+			}
+			const was = this.nameWithOwner;
+			this.name = repo;
+			this.renamedFrom = was;
+			this.log(`the site's repo is now ${this.nameWithOwner} (was ${was})`);
 		}
 		this.cloudProblem = null;
 		this.token = answer.token;
@@ -372,18 +412,43 @@ export class GitHubClient {
 	}
 
 	async rest<T = unknown>(method: string, path: string, body?: unknown): Promise<T> {
-		return (await this.request(method, path, body, await this.auth())) as T;
+		const was = this.nameWithOwner;
+		const bearer = await this.auth();
+		return (await this.request(method, this.movedPath(path, was), body, bearer)) as T;
 	}
 
 	/** A GET whose body is bytes (the tarball). Follows GitHub's redirect to codeload. */
 	async bytes(path: string): Promise<Buffer> {
-		const res = await this.fetcher(`${API}${path}`, { headers: this.headers(await this.auth()), redirect: 'follow', signal: this.signal() });
+		const was = this.nameWithOwner;
+		const bearer = await this.auth();
+		path = this.movedPath(path, was);
+		const res = await this.fetcher(`${API}${path}`, { headers: this.headers(bearer), redirect: 'follow', signal: this.signal() });
 		this.tracker.record({ endpoint: `GET ${shorten(path.replace(/^\/repos\/[^/]+\/[^/]+/, '').replace(/\?.*$/, ''))}`, status: res.status, creating: false });
 		this.observe(res, path, false, false);
 		if (!res.ok) throw new HttpError(res.status, `GET ${path} -> ${res.status}`, await res.text().catch(() => ''));
 		return Buffer.from(await res.arrayBuffer());
 	}
 
+	/**
+	 * Finding 7: a call's path was made on `was` (its caller read `repoPath()` before the
+	 * token), and the token it waited for took a new name. It goes to the new name, so no
+	 * call after a rename leans on GitHub's redirect from the old one.
+	 */
+	private movedPath(path: string, was: string): string {
+		const from = `/repos/${was}`;
+		return was !== this.nameWithOwner && (path === from || path.startsWith(`${from}/`) || path.startsWith(`${from}?`)) ? `/repos/${this.nameWithOwner}${path.slice(from.length)}` : path;
+	}
+
+	/** The same for GraphQL's variables: an `owner` and `name` pair, or a `repositoryNameWithOwner`, on `was`. */
+	private movedVariables(value: unknown, was: string): unknown {
+		if (was === this.nameWithOwner || !value || typeof value !== 'object') return value;
+		if (Array.isArray(value)) return value.map((v) => this.movedVariables(v, was));
+		const o = Object.fromEntries(Object.entries(value).map(([k, v]) => [k, this.movedVariables(v, was)]));
+		if (o.repositoryNameWithOwner === was) o.repositoryNameWithOwner = this.nameWithOwner;
+		if (`${o.owner}/${o.name}` === was) Object.assign(o, { owner: this.owner, name: this.repo });
+		return o;
+	}
+
 	/** Aborts the request (and the reading of its body) after `timeoutMs`. */
 	private signal(): AbortSignal {
 		return AbortSignal.timeout(this.timeoutMs);
@@ -427,11 +492,13 @@ export class GitHubClient {
 	/** GraphQL as the installation (or the token). Throws GraphQLError when the answer has `errors`. */
 	async graphql<T = unknown>(query: string, variables: Record<string, unknown>, name: string): Promise<T> {
 		const isMutation = /^\s*mutation\b/.test(query);
+		const was = this.nameWithOwner;
+		const bearer = await this.auth();
 		const res = await this.fetcher(`${API}/graphql`, {
 			method: 'POST',
 			// updateRefs worked with this preview header in M1 (G2); whether it still needs it is untested (G6 (f)).
-			headers: { ...this.headers(await this.auth(), true), accept: 'application/vnd.github.update-refs-preview+json, application/json' },
-			body: JSON.stringify({ query, variables }),
+			headers: { ...this.headers(bearer, true), accept: 'application/vnd.github.update-refs-preview+json, application/json' },
+			body: JSON.stringify({ query, variables: this.movedVariables(variables, was) }),
 			signal: this.signal(),
 		});
 		this.tracker.record({ endpoint: `graphql ${name}`, status: res.status, creating: isMutation });

package/src/live/locks.ts

@@ -302,6 +302,28 @@ export class Locks {
 		this.cache?.hash(this.presenceKey(), fields);
 	}
 
+	/** The tabs on this document now (polled with it within their record's hold), with their people (Discard changes). */
+	async tabsOn(file: string): Promise<{ tab: string; person: Person }[]> {
+		const now = this.now();
+		const out: { tab: string; person: Person }[] = [];
+		for (const [tab, raw] of Object.entries(await this.redis.hgetall(this.presenceKey()))) {
+			try {
+				const r = JSON.parse(raw) as PresenceRecord;
+				const hold = typeof r.hold === 'number' ? r.hold : this.timings.presenceMs;
+				if (r.file === file && now - r.at <= hold) out.push({ tab, person: r.person });
+			} catch {
+				/* skip */
+			}
+		}
+		return out;
+	}
+
+	/** Discard changes: let go of a lock whoever holds it (only while it's still what was read). */
+	async drop(read: ReadLock, file: string): Promise<void> {
+		if (await landed(this.cache, this.key(file), () => this.redis.compareAndDelete(this.key(file), read.raw))) this.cache?.string(this.key(file), null);
+		else this.cache?.drop(this.key(file));
+	}
+
 	/** Who is on which document now (polled with it within the record's hold). Long-gone tabs are pruned. */
 	async presence(): Promise<PresenceView[]> {
 		return this.presenceFrom(Object.entries(await this.redis.hgetall(this.presenceKey())));

package/src/live/messages.ts

@@ -31,6 +31,25 @@
  *
  *     Published-by: Aoife <aoife@fernhill.ie>
  *     Published-files: content/pages/index.json, content/pages/about.json
+ *
+ * Discarding a document's unpublished changes (its files put back as `main` has them):
+ *
+ *     Discarded: About — by Aoife
+ *
+ *     Discarded-by: Aoife <aoife@fernhill.ie>
+ *     Discarded-files: content/pages/about.json
+ *
+ * Publish holding documents back (caracms-cloud adversarial review, finding 15): the one
+ * commit on `drafts`, on top of the publish, putting back what `main` didn't get. It says
+ * again who changed each file, so they're still waiting with who changed them:
+ *
+ *     Held back: About
+ *
+ *     Held-back-files: content/pages/about.json
+ *     Edited-by: Ciarán <ciaran@fernhill.ie>: content/pages/about.json
+ *
+ * Reading back, a discard ends what the commits before it said about those files: who
+ * changed them and any `Draft-kept` (status.ts → `waitingFromCommits`).
  */
 
 export interface Person {
@@ -86,6 +105,28 @@ export function mergeMessage(fromMain: string[], keptDraft: string[]): string {
 	return `Merge main into drafts${lines.length ? `\n\n${lines.join('\n')}` : ''}`;
 }
 
+/** A discard's commit on `drafts`: the document's files put back as `main` has them. */
+export function discardMessage(titles: string[], files: string[], by: Person): string {
+	return `Discarded: ${titleList(titles)} — by ${displayName(by)}\n\nDiscarded-by: ${ident(by)}\nDiscarded-files: ${files.join(', ')}`;
+}
+
+/** Finding 15: Publish's commit on `drafts` putting back the files it held back. `waiting`: who changed each, newest first (status.ts → waitingFromCommits). */
+export function heldMessage(titles: string[], files: string[], waiting: { file: string; editors: { person: Person }[]; keptDraft: boolean }[]): string {
+	const byEditor = new Map<string, { person: Person; files: string[] }>();
+	// Oldest first, so reading back puts the newest editor in front again.
+	for (const w of waiting)
+		for (const e of [...w.editors].reverse()) {
+			const key = e.person.email.toLowerCase();
+			const entry = byEditor.get(key) ?? { person: e.person, files: [] };
+			entry.files.push(w.file);
+			byEditor.set(key, entry);
+		}
+	const lines = [`Held-back-files: ${files.join(', ')}`, ...[...byEditor.values()].map(({ person, files }) => `Edited-by: ${ident(person)}: ${files.join(', ')}`)];
+	const kept = waiting.filter((w) => w.keptDraft).map((w) => w.file);
+	if (kept.length) lines.push(`Draft-kept: ${kept.join(', ')}`);
+	return `Held back: ${titleList(titles)}\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(', ')}`;
 }
@@ -93,7 +134,7 @@ export function publishMessage(titles: string[], files: string[], by: Person): s
 // ── Reading them back ─────────────────────────────────────────────────────────
 
 export interface ParsedMessage {
-	kind: 'draft' | 'merge' | 'publish' | 'other';
+	kind: 'draft' | 'merge' | 'publish' | 'discard' | 'other';
 	/** Edited-by trailers: who changed which files. */
 	edits: { person: Person; files: string[] }[];
 	/** Draft-kept: files where the draft won a conflict. */
@@ -104,6 +145,8 @@ export interface ParsedMessage {
 	publishedFiles: string[];
 	/** The titles in a Draft or Published headline (without "and N more"). */
 	titles: string[];
+	/** Discarded-files, for a discard: what came before about these files no longer counts. */
+	discardedFiles: string[];
 }
 
 const list = (value: string) =>
@@ -123,7 +166,7 @@ const parsePerson = (value: string): Person | 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 out: ParsedMessage = { kind: 'other', edits: [], keptDraft: [], publishedBy: null, publishedFiles: [], titles: [], discardedFiles: [] };
 	const titles = (s: string) => list(s.replace(/ and \d+ more$/, ''));
 	if (headline.startsWith('Draft: ')) {
 		out.kind = 'draft';
@@ -132,6 +175,9 @@ export function parseMessage(message: string): ParsedMessage {
 	else if (headline.startsWith('Published: ')) {
 		out.kind = 'publish';
 		out.titles = titles(headline.slice('Published: '.length).replace(/ — by .*$/, ''));
+	} else if (headline.startsWith('Discarded: ')) {
+		out.kind = 'discard';
+		out.titles = titles(headline.slice('Discarded: '.length).replace(/ — by .*$/, ''));
 	}
 	for (const line of rest) {
 		const m = /^([A-Za-z-]+): (.*)$/.exec(line.trim());
@@ -146,6 +192,7 @@ export function parseMessage(message: string): ParsedMessage {
 		} 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!);
+		else if (key === 'Discarded-files' && out.kind === 'discard') out.discardedFiles = list(value!);
 	}
 	return out;
 }

package/src/live/mode.ts

@@ -17,12 +17,20 @@
  *   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**.
  *
+ * - **The config's `services`** (caracms-cloud M5, live/services.ts, baked in as `Baked.services`):
+ *   with it, the other mode's variables are removed before anything here reads them, so the
+ *   "not both" sentences below only ever apply to a config without the field (Decision 3);
+ *   `'cloud'` without the key is `CLOUD_KEY_MISSING_PROBLEM` on a production server (Decision 4).
+ *
  * This only reads; it doesn't wire anything (Phase 2 switches the routes on it,
  * Phase 3 guards with it).
  */
 import { CLOUD_KEY_SHAPE, DEFAULT_CLOUD_URL } from './cloud.ts';
 import { DEFAULT_BRANCHES, type BranchNames } from './branches.ts';
 import { DEFAULT_TIMINGS, type LiveTimings } from './timings.ts';
+import { bakedServices, CLOUD_KEY_MISSING_PROBLEM, OWN_FORMS_VARIABLES, OWN_MEDIA_VARIABLES, OWN_MUX_VARIABLES, servicesEnv, type Services } from './services.ts';
+
+export { OWN_FORMS_VARIABLES, OWN_MEDIA_VARIABLES, OWN_MUX_VARIABLES };
 
 export interface LiveSettings {
 	/** `memory`: the in-memory GitHub backend (Decision 2). `token`: CARACMS_GITHUB_TOKEN (runs-anywhere Decision 3). */
@@ -81,6 +89,8 @@ export interface Baked {
 	site?: string | null;
 	/** The commit the build was made from (runs-anywhere Decision 9). */
 	commit?: string | null;
+	/** The config's `services` (caracms-cloud M5 Decision 1; live/services.ts). Null or missing: the key decides (Decision 3). */
+	services?: Services | null;
 }
 
 // The sentences the configuration problems print, kept here so the docs can quote them.
@@ -97,15 +107,9 @@ export const CLOUD_KEY_PROBLEM =
 	"CARACMS_CLOUD_KEY isn't a CaraCMS Cloud site key: a key is cck_ followed by 43 letters, digits, - and _. Copy it again from app.caracms.com.";
 export const CLOUD_AND_GITHUB_PROBLEM = (other: string) =>
 	`Both CARACMS_CLOUD_KEY and ${other} are set: a site uses one GitHub credential, so remove ${other}.`;
-/** The site's own media variables, which `CARACMS_CLOUD_KEY` replaces (caracms-cloud M3 Decision 19). */
-export const OWN_MEDIA_VARIABLES = ['S3_ENDPOINT', 'S3_REGION', 'S3_BUCKET', 'S3_ACCESS_KEY_ID', 'S3_SECRET_ACCESS_KEY', 'IMGPROXY_KEY', 'IMGPROXY_SALT', 'CARACMS_MEDIA_URL'] as const;
 const listed = (names: readonly string[]) => (names.length <= 1 ? names.join('') : `${names.slice(0, -1).join(', ')} and ${names[names.length - 1]}`);
 export const CLOUD_AND_MEDIA_PROBLEM = (names: readonly string[]) => `Set CARACMS_CLOUD_KEY or the site's own media variables, not both: remove ${listed(names)}.`;
-/** The site's own Mux token, which `CARACMS_CLOUD_KEY` replaces (caracms-cloud M4.5 Decision 15). */
-export const OWN_MUX_VARIABLES = ['MUX_TOKEN_ID', 'MUX_TOKEN_SECRET'] as const;
 export const CLOUD_AND_MUX_PROBLEM = (names: readonly string[]) => `Set CARACMS_CLOUD_KEY or the site's own Mux variables, not both: remove ${listed(names)}.`;
-/** The site's own forms and email variables, which `CARACMS_CLOUD_KEY` replaces (caracms-cloud M4 Decision 22). */
-export const OWN_FORMS_VARIABLES = ['SUBMISSIONS_S3_BUCKET', 'SUBMISSIONS_S3_ACCESS_KEY_ID', 'SUBMISSIONS_S3_SECRET_ACCESS_KEY', 'RESEND_API_KEY', 'FORMS_FROM'] as const;
 export const CLOUD_AND_FORMS_PROBLEM = (names: readonly string[]) => `Set CARACMS_CLOUD_KEY or the site's own forms and email variables, not both: remove ${listed(names)}.`;
 
 /** The key beside any of the site's own forms and email variables: Decision 22's sentence, or null. */
@@ -121,7 +125,8 @@ export function cloudFormsConflict(env: Env): string | null {
  * email variables beside it, a bad `CARACMS_CLOUD_URL`). Null: not a cloud site. Whether
  * the cloud is *used* is the caller's (only on a production server; the Core framing).
  */
-export function cloudForms(env: Env): { connection: { key: string; url: string }; problems: string[] } | null {
+export function cloudForms(env: Env, services: Services | null = bakedServices()): { connection: { key: string; url: string }; problems: string[] } | null {
+	env = servicesEnv(env, services);
 	const get = (name: string) => env[name]?.trim() || null;
 	const key = get('CARACMS_CLOUD_KEY');
 	if (!key) return null;
@@ -192,6 +197,9 @@ const isLocalhost = (host: string) => host === 'localhost' || host.endsWith('.lo
  * `baked` is what the build baked in (the address and the commit).
  */
 export function readMode(env: Env = process.env, production = env.NODE_ENV === 'production', baked: Baked = {}): Mode {
+	// caracms-cloud M5 Decision 2: with the config's `services`, the other mode's variables are never read.
+	const services = baked.services ?? null;
+	env = servicesEnv(env, services);
 	const get = (name: string) => {
 		const v = env[name]?.trim();
 		return v ? v : null;
@@ -215,7 +223,10 @@ export function readMode(env: Env = process.env, production = env.NODE_ENV === '
 	if (other && other !== 'memory') problems.push(`CARACMS_GITHUB must be "memory" or unset (got "${other}").`);
 
 	let github: LiveSettings['github'] = { kind: 'memory' };
-	if (cloudKey && (!memory || production)) {
+	if (services === 'cloud' && !cloudKey && (!memory || production)) {
+		// M5 Decision 4: never the self-hosted variables instead (they were removed above).
+		problems.push(CLOUD_KEY_MISSING_PROBLEM);
+	} else if (cloudKey && (!memory || production)) {
 		// The cloud names the repo (Decision 13), so GITHUB_REPO is a mistake and Railway's own variables are ignored.
 		if (!CLOUD_KEY_SHAPE.test(cloudKey)) problems.push(CLOUD_KEY_PROBLEM);
 		if (ghToken) problems.push(CLOUD_AND_GITHUB_PROBLEM('CARACMS_GITHUB_TOKEN'));

package/src/live/notices.ts

@@ -4,6 +4,8 @@
  *
  * - **"Published as it stood"** (`caracms:notices`, a hash by notice id): Publish leaves
  *   one for each person who had a published document open; dismissing it deletes it.
+ * - **"Discarded"** (Discard changes), in the same hash: one for each person who had edits in
+ *   the document or had it open, but didn't discard it; dismissing it deletes it.
  * - **Dismissed "draft kept" notices** (`caracms:dismissed`, a set of ids): those are
  *   shared, worked out from git (`git.keptDraftNotices()`), so a dismissal is remembered
  *   here; a new conflict has a new id and shows again.
@@ -25,6 +27,8 @@ export interface StoodNotice {
 	title: string;
 	by: Person;
 	at: string;
+	/** Absent: "published as it stood". `discarded`: "Aoife discarded the unpublished changes to About". */
+	kind?: 'discarded';
 }
 
 export class Notices {
@@ -90,7 +94,7 @@ export class Notices {
 		for (const raw of stood) {
 			try {
 				const n = JSON.parse(raw) as StoodNotice;
-				if (n.for === email) out.push({ id: n.id, kind: 'published-as-it-stood', file: n.file, title: n.title, by: n.by, at: n.at });
+				if (n.for === email) out.push({ id: n.id, kind: n.kind === 'discarded' ? 'discarded' : 'published-as-it-stood', file: n.file, title: n.title, by: n.by, at: n.at });
 			} catch {
 				/* skip */
 			}

package/src/live/runtime.ts

@@ -93,8 +93,9 @@ export async function createLiveRuntime(options: RuntimeOptions): Promise<LiveRu
 			if (gh.kind === 'cloud') {
 				// caracms-cloud M2 Decision 13: the repo from the cloud's settings, then the first
 				// token, so a refusal of either stops the start (the sign-in guard shows its sentence).
+				// A rename on GitHub after this is taken by the client (adversarial review, finding 7).
 				const { owner, repo } = await cloudRepoForStart({ key: gh.key, url: gh.url, fetch });
-				client = new GitHubClient({ cloudKey: gh.key, cloudUrl: gh.url, owner, repo, now, fetch }, tracker);
+				client = new GitHubClient({ cloudKey: gh.key, cloudUrl: gh.url, owner, repo, now, fetch, log }, tracker);
 				await client.ready();
 				log(`live mode on ${owner}/${repo} through CaraCMS Cloud`);
 			} else {

package/src/live/services.ts

@@ -0,0 +1,114 @@
+/**
+ * Where the site's services come from (caracms-cloud M5): the config's `services` field,
+ * not whichever variables happen to be set.
+ *
+ * - **`'cloud'`**: `CARACMS_CLOUD_KEY` is the one credential. The self-hosted variables
+ *   (`REPLACED_VARIABLES`) are **removed from the environment the readers see**, so none is
+ *   ever read, not even as a fallback (Decision 2, check 5), and each is named once per
+ *   process as ignored.
+ * - **`'self-hosted'`**: the site's own variables; `CARACMS_CLOUD_KEY` is removed and named
+ *   as ignored the same way.
+ * - **Unset**: the environment as it is, so the key decides and the "not both" refusals
+ *   stand (Decision 3).
+ *
+ * Every key-or-own reader (live/mode.ts `readMode` and `cloudForms`, media.ts, the editor's
+ * media config, forms/store.ts, cloud-middleware.ts, and `media import` in bin/media.mjs)
+ * starts from `servicesEnv`. The running site's value is baked in at build
+ * (`__CARACMS_SERVICES__`, a Vite define from the config: `bakedServices`), since the readers
+ * are synchronous and have no config in hand.
+ */
+import type { Services } from '../config.ts';
+
+export type { Services };
+type Env = Record<string, string | undefined>;
+
+/** The site's own media variables, which `CARACMS_CLOUD_KEY` replaces (caracms-cloud M3 Decision 19). */
+export const OWN_MEDIA_VARIABLES = ['S3_ENDPOINT', 'S3_REGION', 'S3_BUCKET', 'S3_ACCESS_KEY_ID', 'S3_SECRET_ACCESS_KEY', 'IMGPROXY_KEY', 'IMGPROXY_SALT', 'CARACMS_MEDIA_URL'] as const;
+/** The site's own Mux token, which `CARACMS_CLOUD_KEY` replaces (caracms-cloud M4.5 Decision 15). */
+export const OWN_MUX_VARIABLES = ['MUX_TOKEN_ID', 'MUX_TOKEN_SECRET'] as const;
+/** The site's own forms and email variables, which `CARACMS_CLOUD_KEY` replaces (caracms-cloud M4 Decision 22). */
+export const OWN_FORMS_VARIABLES = ['SUBMISSIONS_S3_BUCKET', 'SUBMISSIONS_S3_ACCESS_KEY_ID', 'SUBMISSIONS_S3_SECRET_ACCESS_KEY', 'RESEND_API_KEY', 'FORMS_FROM'] as const;
+
+/** The site's own GitHub variables, which the cloud key replaces (caracms-cloud M2 Decision 11). `GITHUB_WEBHOOK_SECRET` is harmless and not here. */
+export const OWN_GITHUB_VARIABLES = ['CARACMS_GITHUB_TOKEN', 'GITHUB_APP_ID', 'GITHUB_APP_PRIVATE_KEY', 'GITHUB_REPO'] as const;
+
+/** Every variable the cloud replaces, by group, in the move list's order of retiring (M5 Contracts). */
+export const REPLACED_VARIABLES = {
+	media: OWN_MEDIA_VARIABLES,
+	video: OWN_MUX_VARIABLES,
+	forms: OWN_FORMS_VARIABLES,
+	github: OWN_GITHUB_VARIABLES,
+} as const;
+
+/** What each group's ignored line ends with: when it can go. */
+const RETIRE: Record<keyof typeof REPLACED_VARIABLES, string> = {
+	media: 'Remove them once the old bucket and imgproxy are retired.',
+	video: 'Remove them once every clip is uploaded again in the editor.',
+	forms: 'Remove them once the old submissions are exported or no longer wanted.',
+	github: 'Remove them: the cloud gives the site its repo and access.',
+};
+
+/** The sentence Decision 4 fails a production build and `/admin` with. */
+export const CLOUD_KEY_MISSING_PROBLEM = "This site runs on CaraCMS Cloud (caracms.config.ts), but CARACMS_CLOUD_KEY isn't set. Make a key for it in app.caracms.com.";
+
+const listed = (names: readonly string[]) => (names.length <= 1 ? names.join('') : `${names.slice(0, -1).join(', ')} and ${names[names.length - 1]}`);
+
+/** The ignored line for some of one group's variables (cloud), or for the key (self-hosted). */
+export function ignoredMessage(names: readonly string[], services: Services, group?: keyof typeof REPLACED_VARIABLES): string {
+	const one = names.length === 1;
+	const set = `${listed(names)} ${one ? 'is' : 'are'} set`;
+	if (services === 'self-hosted') return `${set}, but this site is self-hosted (caracms.config.ts): ${one ? "it's" : "they're"} ignored. Remove ${one ? 'it' : 'them'}, or run \`caracms init --cloud\` to move the site to CaraCMS Cloud.`;
+	const tail = group ? RETIRE[group] : 'Remove them once the move is done.';
+	return `${set}, but this site runs on CaraCMS Cloud (caracms.config.ts): ${one ? "it's" : "they're"} ignored. ${one ? tail.replace(/them/g, 'it') : tail}`;
+}
+
+const WARNED = Symbol.for('caracms.ignoredVariables');
+type Shared = { [WARNED]?: Set<string> };
+const warned = () => ((globalThis as Shared)[WARNED] ??= new Set());
+
+/** Forget which variables were named (tests). */
+export function resetIgnoredWarnings(): void {
+	delete (globalThis as Shared)[WARNED];
+}
+
+const set = (env: Env, name: string) => Boolean(env[name]?.trim());
+
+/**
+ * The environment the readers see for this `services` (null: the environment as it is),
+ * with the other mode's variables removed. Each removed variable is named once per process
+ * (shared on globalThis, so the build's own module and its bundled chunks warn once between them).
+ */
+export function servicesEnv(env: Env, services: Services | null | undefined, log: (line: string) => void = (line) => console.warn(line)): Env {
+	if (!services) return env;
+	const seen = warned();
+	const out: Env = { ...env };
+	if (services === 'self-hosted') {
+		if (!set(env, 'CARACMS_CLOUD_KEY')) return env;
+		delete out.CARACMS_CLOUD_KEY;
+		if (!seen.has('CARACMS_CLOUD_KEY')) log(`[caracms] ${ignoredMessage(['CARACMS_CLOUD_KEY'], services)}`);
+		seen.add('CARACMS_CLOUD_KEY');
+		return out;
+	}
+	for (const [group, names] of Object.entries(REPLACED_VARIABLES) as [keyof typeof REPLACED_VARIABLES, readonly string[]][]) {
+		const found = names.filter((name) => set(env, name));
+		for (const name of found) delete out[name];
+		const fresh = found.filter((name) => !seen.has(name));
+		if (fresh.length) log(`[caracms] ${ignoredMessage(fresh, services, group)}`);
+		for (const name of fresh) seen.add(name);
+	}
+	return out;
+}
+
+/** The names `servicesEnv` would ignore in `env` for `services` (init's move list, tests). */
+export function ignoredVariables(env: Env, services: Services | null | undefined): string[] {
+	if (!services) return [];
+	if (services === 'self-hosted') return set(env, 'CARACMS_CLOUD_KEY') ? ['CARACMS_CLOUD_KEY'] : [];
+	return Object.values(REPLACED_VARIABLES).flatMap((names) => names.filter((name) => set(env, name)));
+}
+
+declare const __CARACMS_SERVICES__: Services | null | undefined;
+
+/** The config's `services` as the build baked it in; null in plain Node (tests) and for a config without one. */
+export function bakedServices(): Services | null {
+	return typeof __CARACMS_SERVICES__ === 'string' ? __CARACMS_SERVICES__ : null;
+}

package/src/live/status.ts

@@ -29,6 +29,11 @@ export function waitingFromCommits(files: Iterable<string>, commits: CommitSumma
 	for (const file of files) out.set(file, { file, editors: [], changedAt: null, keptDraft: false });
 	for (const commit of commits) {
 		const parsed = parseMessage(commit.message);
+		// A discard: what came before about its files no longer counts (they matched `main` after it).
+		for (const file of parsed.discardedFiles) {
+			const w = out.get(file);
+			if (w) Object.assign(w, { editors: [], changedAt: null, keptDraft: false });
+		}
 		for (const edit of parsed.edits) {
 			for (const file of edit.files) {
 				const w = out.get(file);