caracms 0.3.3 → 0.4.0

package/src/held.ts

@@ -0,0 +1,116 @@
+/**
+ * Collections under pages (Decisions 2, 7, 11, 13): a held collection's address is the
+ * address of the page that holds it, worked out from a listing, never from the config.
+ *
+ * - **The mount is in the content:** a page of the collection `heldBy` names says
+ *   `"holds": "<collection>"` (content.ts reads it into the entry's `holds`). The
+ *   collection's base is that page's address + `/` (`/journal/`), so its documents follow
+ *   the page wherever it moves.
+ * - **One holder or none.** No page holding it, two pages holding it, Home holding it, or
+ *   the holder's own file unopenable (invalid JSON, no title): the collection has no
+ *   addresses (base null) and `problem` says why, naming the files. `validate` reports the
+ *   same sentence as an error; the editor shows it on the collection's sidebar entry.
+ * - **A hidden holder hides its documents** (Decision 11), as a hidden page hides the pages
+ *   under it: `hidden` here, and content.ts marks each document.
+ * - **Pure and browser-safe** (no imports): the server resolves bases for the editor's
+ *   payload, and the browser can do the same from a fresh listing.
+ */
+
+/** What resolving needs of a collection (config.ts → ResolvedCollection, the editor's payload). */
+export interface HoldableCollection {
+	name: string;
+	label: string;
+	urlBase: string | null;
+	heldBy?: string | null;
+}
+
+/** What resolving needs of a listed document (content.ts → DocumentEntry). */
+export interface HoldingEntry {
+	collection: string;
+	path: string;
+	file: string;
+	url: string | null;
+	label: string;
+	warning: { message: string } | null;
+	hidden?: true;
+	/** The collection key the page's file says it holds (`"holds"`), even when the file can't be opened. */
+	holds?: string;
+}
+
+export interface HeldBase {
+	collection: string;
+	/** The holder's address + `/` (`/journal/`); null while no page holds it, or the holding is a problem. */
+	base: string | null;
+	/** The page that holds it; null when none does (or two do). */
+	holder: { collection: string; path: string; file: string; label: string } | null;
+	/** The holder is hidden from the site (itself, or a page above it), so the documents are too (Decision 11). */
+	hidden: boolean;
+	/** Decision 13's sentence when the collection has no addresses, naming the files; null when it's held. */
+	problem: string | null;
+}
+
+const and = (items: readonly string[]): string => (items.length <= 1 ? (items[0] ?? '') : `${items.slice(0, -1).join(', ')} and ${items[items.length - 1]}`);
+
+/** Every held collection's base, from a listing that has (at least) every document of the collections their `heldBy` names. */
+export function heldBases(collections: Readonly<Record<string, HoldableCollection>>, entries: readonly HoldingEntry[]): Record<string, HeldBase> {
+	const out: Record<string, HeldBase> = {};
+	for (const collection of Object.values(collections)) {
+		if (!collection.heldBy) continue;
+		const { name, label } = collection;
+		const holders = entries.filter((e) => e.collection === collection.heldBy && e.holds === name);
+		const none: HeldBase = { collection: name, base: null, holder: null, hidden: false, problem: null };
+		if (holders.length === 0) {
+			out[name] = { ...none, problem: `No page holds ${label}, so its documents have no addresses and aren't on the site. Add "holds": "${name}" to the page they go under.` };
+			continue;
+		}
+		if (holders.length > 1) {
+			const files = holders.map((h) => h.file);
+			out[name] = { ...none, problem: `${and(files)} ${files.length === 2 ? 'both' : 'all'} hold ${label}, but only one page can hold it, so its documents have no addresses. Take "holds" out of ${files.length === 2 ? 'one of them' : 'all but one'}.` };
+			continue;
+		}
+		const page = holders[0]!;
+		const holder = { collection: page.collection, path: page.path, file: page.file, label: page.label };
+		if (page.path === 'index') {
+			out[name] = { ...none, holder, problem: `${page.file} is Home, which can't hold ${label} (its address is the whole site's), so ${label}'s documents have no addresses. Put "holds": "${name}" on another page.` };
+			continue;
+		}
+		if (page.warning || page.url === null) {
+			const why = page.warning ? ` ${page.warning.message}` : '';
+			out[name] = { ...none, holder, problem: `${page.file} holds ${label}, but it can't be opened, so ${label}'s documents have no addresses until it's fixed.${why}` };
+			continue;
+		}
+		out[name] = { collection: name, base: `${page.url.replace(/\/+$/, '')}/`, holder, hidden: page.hidden === true, problem: null };
+	}
+	return out;
+}
+
+/** The site with each held collection's `urlBase` as resolved (null while it has a problem): what every address rule and the editor read. */
+export function withHeldBases<C extends HoldableCollection, S extends { collections: Record<string, C> }>(site: S, bases: Readonly<Record<string, HeldBase>>): S {
+	const held = Object.values(bases);
+	if (held.length === 0) return site;
+	const collections = { ...site.collections };
+	for (const b of held) if (Object.hasOwn(collections, b.collection)) collections[b.collection] = { ...collections[b.collection]!, urlBase: b.base };
+	return { ...site, collections };
+}
+
+/** Does the site have a collection a page holds? (Most don't, and skip the extra listing.) */
+export const hasHeld = (collections: Readonly<Record<string, HoldableCollection>>): boolean => Object.values(collections).some((c) => !!c.heldBy);
+
+/**
+ * A held collection's word for its documents, as the editor's `singular` (documents/actions.ts)
+ * names one: a plural label as it is ("case studies", "posts"), any other with "entries"
+ * ("journal entries"). A held collection is flat and never shared blocks, so the label is all it takes.
+ */
+export function documentsNoun(label: string): string {
+	const l = label.toLowerCase();
+	return /ies$/.test(l) || /[^s]s$/.test(l) ? l : `${l} entries`;
+}
+
+/**
+ * Decision 12's sentence: "Journal holds the journal entries. Delete the “holds” line in its
+ * file, or move the journal entries to another page, first." Delete… on the page says it instead of asking.
+ */
+export function holdsMessage(page: string, collection: string): string {
+	const noun = documentsNoun(collection);
+	return `${page} holds the ${noun}. Delete the “holds” line in its file, or move the ${noun} to another page, first.`;
+}

package/src/index.ts

@@ -58,7 +58,8 @@ import { lockupCss } from './lockup-css.ts';
 import { shareBuildReads } from './read.ts';
 import { writeSchemaFiles } from './cli/schemas.ts';
 import { configFile } from './cli/site.ts';
-import { readCodeRoutes } from './code-routes-disk.ts';
+import { pagesRoutes } from './code-routes-disk.ts';
+import { codeRoutesFrom } from './code-routes.ts';
 import { GUARD_MIDDLEWARE, LOGIN_ROUTES } from './live/auth/routes.ts';
 import { HOST_COMMIT_VARIABLES } from './live/mode.ts';
 
@@ -352,7 +353,8 @@ export default function caracms(config: SiteConfig): AstroIntegration {
 				const configName = configFile(site.root);
 				if (configName) addWatchFile(join(site.root, configName));
 				// M8 Decision 10: the site's own routes, read once here, for the editor's server and browser alike.
-				site.codeRoutes = readCodeRoutes(site.root, astroConfig.srcDir ? fileURLToPath(astroConfig.srcDir) : 'src', Object.values(site.collections));
+				site.pageRoutes = pagesRoutes(site.root, astroConfig.srcDir ? fileURLToPath(astroConfig.srcDir) : 'src');
+				site.codeRoutes = codeRoutesFrom(site.pageRoutes, Object.values(site.collections));
 				// M5b Decision 5: local dev (and a local build) read the media variables from the site's
 				// `.env`, which Astro doesn't put in process.env. Only those names; a set value wins.
 				const siteEnv = await loadSiteEnv(command === 'dev' ? 'development' : 'production', site.root);

package/src/live/README.md

@@ -7,7 +7,7 @@ live drafts store, sweep, locks and status route, and Phase 3's sign-in, sit on
 | File | What |
 |---|---|
 | `mode.ts` | `readMode(env, production)` → `local`, `live` (with `LiveSettings`) or `unconfigured` (`missing`, `problems`); `unconfiguredMessage()` for the 503 |
-| `runtime.ts` | `liveRuntime(site, settings)`: one per process, lazy. `createLiveRuntime({...})` for tests (inject backend, Redis, clock). `CARACMS_GITHUB=memory`: a MemoryBackend seeded from disk (`siteFiles`), refused in production |
+| `runtime.ts` | `liveRuntime(site, settings)`: one per process, lazy. With a cloud key it reads the repo from the cloud and takes its first token before anything else, so a refusal stops the start (the guard answers 503 with the cloud's sentence; the next request tries again). `createLiveRuntime({...})` for tests (inject backend, Redis, clock). `CARACMS_GITHUB=memory`: a MemoryBackend seeded from disk (`siteFiles`), refused in production |
 | `git.ts` | `LiveGit`: the `drafts` copy (`files()`, `read()`, `contentSource()`), `commitDrafts()`, `check()`, `publish()` and its `commitPending` hook, `waiting()`, `publishStatus()`, `history()`, `tryAgain()`. M5a: a draft entry with `text` null removes the file; "Contact (deleted)" in the headlines; `mainHas`, `changeOf` (new, deleted or changed), `titleFor` |
 | `timings.ts` | `LiveTimings` and `DEFAULT_TIMINGS`: every timing, Phase 2's sweep and lock ones included |
 | `merge.ts` | `mergeFile({ base, draft, other })`: the per-key three-way merge, pure and byte-preserving |
@@ -18,7 +18,8 @@ live drafts store, sweep, locks and status route, and Phase 3's sign-in, sit on
 | `notices.ts` | Redis diet. `Notices`: "published as it stood" notices and dismissed "draft kept" ones, written through the status cache |
 | `backend.ts` | `GitBackend`; `GitHubBackend`, `MemoryBackend` (test helpers: `seed`, `push`, `file`, `deployments`, `beforeRequest`); `StaleHeadError` |
 | `branches.ts` | `Branch` (a role: `main` or `drafts`), `BranchNames` (the refs behind them), `DEFAULT_BRANCHES`. `CARACMS_MAIN_BRANCH` and `CARACMS_DRAFTS_BRANCH` (read by `mode.ts`, M9 Decision 6) name the branch Publish commits to and the one autosaves land on; unset, `main` and `drafts`. They're set together or not at all: one alone is a problem, so the mode is unconfigured (`/admin` answers 503 saying both must be set; the public site still serves). Only the backends turn a role into a ref name, so with both set a branch called `main` is never read or moved. `MemoryBackend.refs` is keyed by name |
-| `github.ts` | The App's JWT, the installation token (one repo, refreshed early), `Tracker` (request counts) |
+| `github.ts` | The App's JWT, the installation token (one repo, refreshed early), `Tracker` (request counts). A third credential, `cloud`: the token from CaraCMS Cloud, refreshed the same way; its refusals are an access problem of kind `cloud` |
+| `cloud.ts` | CaraCMS Cloud (`CARACMS_CLOUD_KEY`; caracms-cloud M2): `DEFAULT_CLOUD_URL`, `cloudSettings()` (the repo, at start), `cloudToken()`, `CloudRefusal` (the cloud's `error`, `message`, `installUrl`), and `cloudUnavailable()`, the sign-in guard's 503 for a refusal at start |
 | `webhook.ts` | `handleGithubWebhook()`, behind `POST /_caracms/github` (`../editor/routes/github.ts`) |
 | `autosaves.ts` | Phase 2. Autosaves in Redis (`caracms:autosave:<file>`, a week; stored compare-and-set, ordered per tab by `X-Caracms-Seq`), the session's last commit (the merge's ancestor) and who last changed a document (Decision 11; no expiry, and `known: false` when neither Redis nor git can say). M5a: a new document's autosave carries `created: { over }` (its ancestor until committed), a deletion is a "gone" autosave (`text` and `document` null, `gone: { title }`) |
 | `locks.ts` | Phase 2. `Locks`: taken by the first write, heartbeat on the poll (Redis diet: only when `needsBeat`), lapse only once committed, releasing, Edit here; presence, each record holding for twice its tab's poll interval plus 3 s |

package/src/live/auth/middleware.ts

@@ -14,11 +14,18 @@
  *   answering 503 here until the GitHub App's variables were set). A GET to it is as
  *   unavailable as any other guarded path, as live mode's let-through is POST-only too.
  *
+ * - **A start that fails** answers 503 and the next request tries again (runtime.ts). When
+ *   CaraCMS Cloud refused the start or couldn't be reached (caracms-cloud M2 Decision 14), the
+ *   answer is the cloud's own sentence, as an HTML page with its install link as a link
+ *   (JSON under `/_caracms/`, as ../../editor/middleware.ts answers); any other failure keeps
+ *   the plain sentence. Neither the log line nor the page carries the site key or a token.
+ *
  * The mode is Phase 2's `editorMode()`, so the two agree on live and local.
  */
 import type { MiddlewareHandler } from 'astro';
 import { site } from 'virtual:caracms/config';
 import { editorMode } from '../../editor/server/mode.ts';
+import { CloudRefusal, cloudUnavailable } from '../cloud.ts';
 import { setPerson } from '../locals.ts';
 import { guard, isFormEndpoint, isGuardedPath } from './guard.ts';
 import { authFor } from './index.ts';
@@ -35,6 +42,10 @@ export const onRequest: MiddlewareHandler = async (context, next) => {
 	try {
 		auth = await authFor(site, mode.settings, context.site);
 	} catch (error) {
+		if (error instanceof CloudRefusal) {
+			console.error(`[caracms] sign-in: the live runtime could not start: CaraCMS Cloud (${error.error}): ${error.message}`);
+			return cloudUnavailable(error, context.url.pathname.startsWith('/_caracms/'));
+		}
 		console.error('[caracms] sign-in: the live runtime could not start:', error);
 		return unavailable("The editor couldn't start. Try again in a moment.");
 	}

package/src/live/autosaves.ts

@@ -120,6 +120,21 @@ export interface Read<T> {
 
 /** The Redis hash of moves waiting to publish (old file → new file). */
 export const movesKey = (prefix: string) => `${prefix}moves`;
+/**
+ * Collections under pages: the moves hash also holds each moved document's live address,
+ * as `@<file now>` → the address (see `recordAddresses`), so the status poll reads no more
+ * keys than before (Redis diet). `splitMoves` parts the two.
+ */
+export const ADDRESS_FIELD = '@';
+export function splitMoves(fields: Iterable<[string, string]>): { records: Map<string, string>; addresses: Map<string, string> } {
+	const records = new Map<string, string>();
+	const addresses = new Map<string, string>();
+	for (const [k, v] of fields) {
+		if (k.startsWith(ADDRESS_FIELD)) addresses.set(k.slice(ADDRESS_FIELD.length), v);
+		else records.set(k, v);
+	}
+	return { records, addresses };
+}
 
 const parse = <T>(raw: string | null): T | null => {
 	if (raw === null) return null;
@@ -243,7 +258,7 @@ export class Autosaves {
 
 	/** Pre-M7 item 8: the moves waiting to publish, old file → new file. */
 	async moves(): Promise<Map<string, string>> {
-		return new Map(Object.entries(await this.redis.hgetall(movesKey(this.prefix))));
+		return splitMoves(Object.entries(await this.redis.hgetall(movesKey(this.prefix)))).records;
 	}
 
 	private async setMove(from: string, to: string): Promise<void> {
@@ -271,11 +286,83 @@ export class Autosaves {
 		} else if (wasLive) await this.setMove(from, to);
 	}
 
+	/**
+	 * Several documents moved at once (the many-move engine), each as `recordMove` would,
+	 * but every one read against the records before the plan: in a chain (A → B, B → C)
+	 * the second move's `from` is the first's `to`, and read one at a time it would take
+	 * over the first's record. In a swap each gets its record (`movesIn` counts neither
+	 * while both files are there).
+	 */
+	async recordMoves(entries: readonly { from: string; to: string; wasLive: boolean }[]): Promise<void> {
+		if (entries.length === 0) return;
+		const before = await this.moves();
+		const after = new Map(before);
+		const origins = entries.map((e) => [...before].find(([, t]) => t === e.from)?.[0] ?? (e.wasLive ? e.from : null));
+		for (const origin of origins) if (origin !== null) after.delete(origin);
+		entries.forEach((e, i) => {
+			const origin = origins[i]!;
+			if (origin !== null && origin !== e.to) after.set(origin, e.to);
+		});
+		const drop = [...before.keys()].filter((f) => !after.has(f));
+		if (drop.length) await this.dropMoves(...drop);
+		for (const [f, t] of after) if (before.get(f) !== t) await this.setMove(f, t);
+	}
+
+	/** Collections under pages: each moved document's live address, by its file now. */
+	async addresses(): Promise<Map<string, string>> {
+		return splitMoves(Object.entries(await this.redis.hgetall(movesKey(this.prefix)))).addresses;
+	}
+
+	/**
+	 * Collections under pages (Decision 9): each address a move changed, in one write. The
+	 * record is the document's live address, by its file now: a held document keeps its file
+	 * when its holder moves, so its old address can't be worked out from a file's move, nor
+	 * from its holder's address now. Moved since the last Publish already: the record follows
+	 * it to its new file; back at its live address: the record goes. A document that was
+	 * never live (`wasLive` false, no record) gets none.
+	 */
+	async recordAddresses(entries: readonly { from: string; to: string; toUrl: string; fromUrl: string; wasLive: boolean }[]): Promise<void> {
+		if (entries.length === 0) return;
+		// Every live address from the records as they were before the plan, never from the
+		// map being changed: in a swap or a chain one entry's `to` is another's `from`.
+		const before = await this.addresses();
+		const same = (a: string, b: string) => a.replace(/\/+$/, '').toLowerCase() === b.replace(/\/+$/, '').toLowerCase();
+		const live = entries.map((e) => before.get(e.from) ?? (e.wasLive ? e.fromUrl : null));
+		const after = new Map(before);
+		for (const e of entries) if (e.from !== e.to) after.delete(e.from);
+		entries.forEach((e, i) => {
+			const address = live[i]!;
+			if (address === null || same(address, e.toUrl)) after.delete(e.to);
+			else after.set(e.to, address);
+		});
+		const drop = new Set([...before.keys()].filter((f) => !after.has(f)));
+		const set: Record<string, string> = {};
+		for (const [f, v] of after) if (before.get(f) !== v) set[f] = v;
+		const key = movesKey(this.prefix);
+		const field = (file: string) => `${ADDRESS_FIELD}${file}`;
+		if (drop.size) {
+			const fields = [...drop].map(field);
+			await landed(this.cache, key, () => this.redis.hdel(key, ...fields));
+			this.cache?.hash(key, {}, fields);
+		}
+		if (Object.keys(set).length) {
+			const fields = Object.fromEntries(Object.entries(set).map(([f, v]) => [field(f), v]));
+			await landed(this.cache, key, () => this.redis.hset(key, fields));
+			this.cache?.hash(key, fields);
+		}
+	}
+
 	/** A deleted document's move, if it was moved, is no move any more: it's a deletion. */
 	async forgetMoveTo(file: string): Promise<void> {
 		const moves = await this.moves();
 		const olds = [...moves].filter(([, t]) => t === file).map(([o]) => o);
 		if (olds.length) await this.dropMoves(...olds);
+		if ((await this.addresses()).has(file)) {
+			const key = movesKey(this.prefix);
+			const field = `${ADDRESS_FIELD}${file}`;
+			await landed(this.cache, key, () => this.redis.hdel(key, field));
+			this.cache?.hash(key, {}, [field]);
+		}
 	}
 
 	/** The merge's ancestor for an autosave (Decision 6). See `ancestorFor`. */

package/src/live/cloud.ts

@@ -0,0 +1,131 @@
+/**
+ * CaraCMS Cloud as the site's GitHub credential (caracms-cloud M2, Decisions 11–14).
+ *
+ * - `CARACMS_CLOUD_KEY` (the site key, `cck_…`) is sent as `Authorization: Bearer` and
+ *   nowhere else; `CARACMS_CLOUD_URL` overrides the production address below.
+ * - `cloudSettings()`: `GET /v1/settings` at start, for the site's repo (`github.repo`;
+ *   null is `no_repo`, with the cloud's own sentence).
+ * - `cloudToken()`: `POST /v1/github/token`, a fresh installation token on the site's repo,
+ *   about an hour long. `GitHubClient` calls it and refreshes five minutes early.
+ * - **A refusal** (any answer that isn't 2xx, carrying `{ error, message }`) throws a
+ *   `CloudRefusal` with the cloud's `message` as it came, and `installUrl` when there is
+ *   one. A cloud that can't be reached, or answers with something else, throws a
+ *   `CloudRefusal` whose `error` is `unreachable`, with the package's own sentence.
+ *
+ * - `cloudUnavailable()`: the sign-in guard's 503 for a refusal at start (Decision 14),
+ *   the sentence escaped and the install link a link.
+ *
+ * The key and the tokens are never logged and never put in an error.
+ */
+
+/** The production API's address (caracms-cloud M0 → Contracts). The one place it's written. */
+export const DEFAULT_CLOUD_URL = 'https://glad-bird-412.ap-southeast-2.convex.site';
+
+/** A site key: `cck_` and 43 base64url characters (caracms-cloud M1). */
+export const CLOUD_KEY_SHAPE = /^cck_[A-Za-z0-9_-]{43}$/;
+
+export const CLOUD_UNREACHABLE = "CaraCMS Cloud couldn't be reached, so the editor can't start. Try again in a minute.";
+/** The cloud's own `no_repo` sentence (Contracts), for `github.repo: null` in the settings. */
+export const CLOUD_NO_REPO = 'This site has no GitHub repo in CaraCMS Cloud yet. Ask CaraCMS to set one.';
+/** Decision 13: a token answer named another repo than the one the server started with. */
+export const CLOUD_REPO_CHANGED = (repo: string) => `This site's repo was changed in CaraCMS Cloud to ${repo}. Restart the server to use it.`;
+
+/** How long a call to the cloud may take before it counts as unreachable. */
+export const CLOUD_TIMEOUT_MS = 20_000;
+
+export interface CloudConnection {
+	key: string;
+	url: string;
+	/** For tests. Default: global fetch. */
+	fetch?: typeof fetch;
+	timeoutMs?: number;
+}
+
+/** The cloud said no (or couldn't be reached). `message` is safe to show and to log. */
+export class CloudRefusal extends Error {
+	/** The cloud's `error` (`no_repo`, `app_not_installed`, `unknown_key`…), or the package's `unreachable` / `repo_changed`. */
+	readonly error: string;
+	/** An `https://` link the message names (the App's install page), or null. */
+	readonly installUrl: string | null;
+	constructor(error: string, message: string, installUrl: string | null = null) {
+		super(message);
+		this.name = 'CloudRefusal';
+		this.error = error;
+		this.installUrl = installUrl;
+	}
+}
+
+const unreachable = () => new CloudRefusal('unreachable', CLOUD_UNREACHABLE);
+
+async function call(connection: CloudConnection, method: 'GET' | 'POST', path: string): Promise<Record<string, unknown>> {
+	let res: Response;
+	let body: unknown;
+	try {
+		res = await (connection.fetch ?? fetch)(`${connection.url}${path}`, {
+			method,
+			headers: { authorization: `Bearer ${connection.key}`, accept: 'application/json', 'user-agent': 'caracms' },
+			signal: AbortSignal.timeout(connection.timeoutMs ?? CLOUD_TIMEOUT_MS),
+		});
+		body = await res.json();
+	} catch {
+		throw unreachable();
+	}
+	const answer = body && typeof body === 'object' && !Array.isArray(body) ? (body as Record<string, unknown>) : null;
+	if (!answer) throw unreachable();
+	if (!res.ok) {
+		const { error, message, installUrl } = answer;
+		if (typeof error !== 'string' || typeof message !== 'string' || !message.trim()) throw unreachable();
+		throw new CloudRefusal(error, message, typeof installUrl === 'string' && /^https:\/\//i.test(installUrl) ? installUrl : null);
+	}
+	return answer;
+}
+
+const REPO = /^([A-Za-z0-9-]+)\/([A-Za-z0-9._-]+)$/;
+
+/** The site's repo, from `GET /v1/settings`. */
+export async function cloudSettings(connection: CloudConnection): Promise<{ owner: string; repo: string }> {
+	const answer = await call(connection, 'GET', '/v1/settings');
+	const github = answer.github as { repo?: unknown } | undefined;
+	if (!github || typeof github !== 'object') throw unreachable();
+	if (github.repo === null) throw new CloudRefusal('no_repo', CLOUD_NO_REPO);
+	const m = typeof github.repo === 'string' ? REPO.exec(github.repo) : null;
+	if (!m) throw unreachable();
+	return { owner: m[1]!, repo: m[2]! };
+}
+
+/** A fresh installation token on the site's repo, from `POST /v1/github/token`. */
+export async function cloudToken(connection: CloudConnection): Promise<{ token: string; expiresAt: number; repo: string }> {
+	const answer = await call(connection, 'POST', '/v1/github/token');
+	const { token, expiresAt, repo } = answer;
+	const at = typeof expiresAt === 'string' ? Date.parse(expiresAt) : Number.NaN;
+	if (typeof token !== 'string' || !token || Number.isNaN(at) || typeof repo !== 'string') throw unreachable();
+	return { token, expiresAt: at, repo };
+}
+
+const escapeHtml = (s: string) => s.replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' })[c]!);
+
+/**
+ * The message as HTML, escaped, with `link` (when there is one) as a link: where the
+ * message names it, in place; otherwise after it. The message's words are never changed.
+ */
+export function messageHtml(message: string, link: string | null): string {
+	if (!link) return escapeHtml(message);
+	const a = `<a href="${escapeHtml(link)}">${escapeHtml(link)}</a>`;
+	const parts = message.split(link);
+	return parts.length > 1 ? parts.map(escapeHtml).join(a) : `${escapeHtml(message)} ${a}`;
+}
+
+/** The cloud's refusal at start (Decision 14): its sentence, the install link as a link. */
+export function cloudUnavailable(refusal: CloudRefusal, api: boolean): Response {
+	const headers = { 'Cache-Control': 'private, no-store' };
+	if (api) {
+		return new Response(JSON.stringify({ error: refusal.message, code: refusal.error, installUrl: refusal.installUrl }), {
+			status: 503,
+			headers: { ...headers, 'Content-Type': 'application/json; charset=utf-8' },
+		});
+	}
+	return new Response(
+		`<!doctype html><meta charset="utf-8"><meta name="robots" content="noindex"><title>Editor unavailable</title><p>${messageHtml(refusal.message, refusal.installUrl)}</p>`,
+		{ status: 503, headers: { ...headers, 'Content-Type': 'text/html; charset=utf-8' } },
+	);
+}