caracms 0.3.4 → 0.5.0

package/src/live/git.ts

@@ -36,9 +36,10 @@
 import { randomBytes } from 'node:crypto';
 import { relative, sep } from 'node:path';
 import { repoPrefix, SITE_SETTINGS_FILE, type ResolvedSite } from '../config.ts';
-import { documentUrl, filesSource, type ContentSource } from '../content.ts';
+import { documentUrl, filesSource, heldBasesOf, type ContentSource } from '../content.ts';
+import { withHeldBases, type HeldBase } from '../held.ts';
 import { confinePath } from '../editor/server/write.ts';
-import { movesKey } from './autosaves.ts';
+import { ADDRESS_FIELD, movesKey, splitMoves } from './autosaves.ts';
 import type { WaitingChange } from '../editor/types.ts';
 import { MissingBranchError, StaleHeadError, type Branch, type CommitSummary, type Comparison, type GitBackend, type Head, type Heads, type TreeChange } from './backend.ts';
 import { HttpError } from './github.ts';
@@ -721,8 +722,12 @@ export class LiveGit {
 		// A file drafts no longer has is deleted: "Contact (deleted)", its title from main's copy first (M5a Decision 12).
 		const gone = files.filter((f) => this.read(f) === null);
 		const goneTitles = await this.titlesBeforeRemoval(gone, heads.main.commit);
-		const records = await this.moveRecords();
-		const moves = this.movesIn(files, records);
+		const { records, addresses } = splitMoves(Object.entries(await this.redis.hgetall(movesKey(this.keyPrefix))));
+		// Collections under pages: a held document's addresses come from its holder's (only `holds` is read, so no blocks are needed).
+		const bases = await heldBasesOf({ ...this.site, blocks: {} }, this.contentSource());
+		const moves = this.movesIn(files, records, bases, addresses);
+		// A held document whose holder moved keeps its file, unchanged: still one moved item in the headline.
+		const readdressed = [...moves.from.keys()].filter((f) => !files.includes(f));
 		// Each file's own title (a "stood" notice names the document by it), then the headline's items.
 		const fileTitles = files.map((f) => {
 			const text = this.read(f);
@@ -734,7 +739,11 @@ export class LiveGit {
 		});
 		// Pre-M7 item 8: a moved document is one item in the headline, "Visit (moved from /studio/visit)",
 		// listed first; its old file is part of that item, not one of its own.
-		const titles = [...items.filter((_, i) => moves.from.has(files[i]!)), ...items.filter((_, i) => !moves.from.has(files[i]!) && !moves.to.has(files[i]!))];
+		const titles = [
+			...items.filter((_, i) => moves.from.has(files[i]!)),
+			...readdressed.map((f) => `${titleOf(f, this.read(f))} (moved from ${moves.from.get(f)})`),
+			...items.filter((_, i) => !moves.from.has(files[i]!) && !moves.to.has(files[i]!)),
+		];
 		const commit = await this.backend.createCommit(heads.drafts.tree, [heads.main.commit], publishMessage(titles, files, by));
 		const moved = await this.moveRefs([
 			// main: a fast-forward onto the squash commit. drafts: not a fast-forward, so
@@ -758,6 +767,23 @@ export class LiveGit {
 			if (cleared) this.statusCache.hash(moves, {}, published);
 			else this.statusCache.drop(moves);
 		}
+		// Collections under pages: an address this publish took live is done with; one that
+		// changed since (still its live address in what was published) stays waiting.
+		const live = withHeldBases(this.site, bases);
+		const done = [...addresses].filter(([file, was]) => {
+			if (this.read(file) === null) return false;
+			const url = this.urlOf(live, file);
+			return url !== null && url !== was;
+		}).map(([file]) => `${ADDRESS_FIELD}${file}`);
+		if (done.length) {
+			const key = movesKey(this.keyPrefix);
+			const cleared = await this.redis.hdel(key, ...done).then(
+				() => true,
+				() => false,
+			);
+			if (cleared) this.statusCache.hash(key, {}, done);
+			else this.statusCache.drop(key);
+		}
 		const record: PublishRecord = { commit, by, at: new Date(this.now()).toISOString(), files, titles, tryAgainAt: null };
 		await this.setPublishRecord(record);
 		this.log(`published ${commit.slice(0, 7)} (attempt ${attempt}): ${titles.join(', ')}`);
@@ -817,13 +843,18 @@ export class LiveGit {
 	}
 
 	/** Pre-M7 item 8: the documents a publish moves (`movesIn`), over `drafts`' copy. */
-	private movesIn(files: string[], records: ReadonlyMap<string, string>): Moves {
-		return movesIn(this.site, files, (f) => this.read(f), records);
+	private movesIn(files: string[], records: ReadonlyMap<string, string>, bases: Readonly<Record<string, HeldBase>>, addresses: ReadonlyMap<string, string>): Moves {
+		return movesIn(this.site, files, (f) => this.read(f), records, bases, addresses);
 	}
 
-	/** Pre-M7 item 8: the moves recorded as they were made (autosaves.ts → `moves`), old file → new file. */
-	private async moveRecords(): Promise<Map<string, string>> {
-		return new Map(Object.entries(await this.redis.hgetall(movesKey(this.keyPrefix))));
+	/** A file's document address on a site with its held bases resolved; null when it isn't a document with one. */
+	private urlOf(site: Pick<ResolvedSite, 'root' | 'collections'>, file: string): string | null {
+		try {
+			const c = confinePath(site as ResolvedSite, file);
+			return documentUrl(site.collections[c.collection]!, c.path);
+		} catch {
+			return null;
+		}
 	}
 
 	/** A file's title for the waiting list and notices: the copy's, else the title it had when it was deleted, else its name. */
@@ -1060,7 +1091,22 @@ export interface Moves {
  * old one gone (`read` null) and the new one there. Publish's headline and the waiting
  * list read it ("Visit (moved from /studio/visit)").
  */
-export function movesIn(site: Pick<ResolvedSite, 'root' | 'collections'>, files: readonly string[], read: (file: string) => string | null, records: ReadonlyMap<string, string>): Moves {
+export function movesIn(
+	site: Pick<ResolvedSite, 'root' | 'collections'>,
+	files: readonly string[],
+	read: (file: string) => string | null,
+	records: ReadonlyMap<string, string>,
+	/** Collections under pages: the held collections' resolved bases (held.ts), so a held document's move has addresses. */
+	bases: Readonly<Record<string, HeldBase>> = {},
+	/**
+	 * Collections under pages: each moved document's live address, by its file now
+	 * (autosaves.ts → `recordAddresses`). It wins over one worked out from the old file
+	 * (whose holder may have moved too), and names a held document whose holder moved,
+	 * whose file stays as it is: that one counts whether or not its file is among `files`.
+	 */
+	addresses: ReadonlyMap<string, string> = new Map(),
+): Moves {
+	site = withHeldBases(site, bases);
 	const from = new Map<string, string>();
 	const to = new Map<string, string>();
 	const urlOf = (file: string) => {
@@ -1075,12 +1121,17 @@ export function movesIn(site: Pick<ResolvedSite, 'root' | 'collections'>, files:
 	for (const [old, moved] of records) {
 		if (old === moved || !changed.has(old) || !changed.has(moved) || from.has(moved) || to.has(old)) continue;
 		if (read(old) !== null || read(moved) === null) continue;
-		const fromUrl = urlOf(old);
+		const fromUrl = addresses.get(moved) ?? urlOf(old);
 		const toUrl = urlOf(moved);
 		if (!fromUrl || !toUrl) continue;
 		from.set(moved, fromUrl);
 		to.set(old, toUrl);
 	}
+	for (const [file, live] of addresses) {
+		if (from.has(file) || to.has(file) || read(file) === null) continue;
+		const url = urlOf(file);
+		if (url && url !== live) from.set(file, live);
+	}
 	return { from, to };
 }
 

package/src/live/github.ts

@@ -22,9 +22,16 @@
  *   token, an expiry within 14 days. `accessProblem()` says which holds now; a later
  *   success clears the first two.
  *
- * The private key and the token are never logged.
+ * - **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.
+ *
+ * The private key, the site key and the tokens are never logged.
  */
 import { createSign } from 'node:crypto';
+import { CLOUD_REPO_CHANGED, CloudRefusal, cloudToken } from './cloud.ts';
 
 const API = 'https://api.github.com';
 
@@ -50,16 +57,27 @@ export interface TokenConnection extends ConnectionBase {
 	token: string;
 }
 
-export type GitHubConnection = AppConnection | TokenConnection;
+/** CaraCMS Cloud mints the token (caracms-cloud M2 Decision 12); `fetch` reaches the cloud as well as GitHub. */
+export interface CloudConnection extends ConnectionBase {
+	cloudKey: string;
+	cloudUrl: string;
+}
+
+export type GitHubConnection = AppConnection | TokenConnection | CloudConnection;
+
+/** Which credential a client signs in with. */
+export type GitHubCredential = 'app' | 'token' | 'cloud';
 
 /**
  * What's wrong with GitHub access right now (Decision 5), shown in the editor while it holds.
  * `credential` says which one the site uses, so the sentence names the right fix.
  */
 export type GitHubAccessProblem =
-	| { kind: 'refused'; credential: 'app' | 'token' }
-	| { kind: 'permission'; credential: 'app' | 'token'; permission: string }
-	| { kind: 'expiring'; credential: 'token'; expires: string };
+	| { kind: 'refused'; credential: GitHubCredential }
+	| { 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 };
 
 /** A token expiring within this long shows in the editor (Decision 5). */
 export const TOKEN_EXPIRY_WARNING_MS = 14 * 24 * 60 * 60_000;
@@ -84,11 +102,19 @@ export function accessProblemMessage(problem: GitHubAccessProblem): string {
 	const what = problem.credential === 'token' ? 'GitHub token (CARACMS_GITHUB_TOKEN)' : 'GitHub App';
 	switch (problem.kind) {
 		case 'refused':
+			if (problem.credential === 'cloud') {
+				return "GitHub refused the token CaraCMS Cloud gave this site: the caracms App may have been uninstalled from the repo or suspended. Changes can't be saved to GitHub until it's installed again; ask CaraCMS to check the site.";
+			}
 			return problem.credential === 'token'
 				? `GitHub refused this site's ${what}: it may have expired or been revoked. Changes can't be saved to GitHub until a developer makes a new fine-grained token and sets it.`
 				: `GitHub refused this site's ${what}: it may have been uninstalled from the repo or suspended. Changes can't be saved to GitHub until a developer reinstalls it.`;
 		case 'permission':
+			if (problem.credential === 'cloud') {
+				return `GitHub refused a change because the caracms App, through CaraCMS Cloud, lacks the "${problem.permission}" permission on this site's repo. Ask CaraCMS to check the App.`;
+			}
 			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 '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.`;
@@ -206,9 +232,10 @@ export class GitHubClient {
 	readonly owner: string;
 	readonly repo: string;
 	/** Which credential this client signs in with. */
-	readonly credential: 'app' | 'token';
+	readonly credential: GitHubCredential;
 	private readonly appId: string;
 	private readonly key: string;
+	private readonly cloud: { key: string; url: string } | null = null;
 	private readonly fetcher: typeof fetch;
 	private readonly now: () => number;
 	private readonly timeoutMs: number;
@@ -219,6 +246,8 @@ export class GitHubClient {
 	private refused = false;
 	private missingPermission: string | null = null;
 	private personalTokenExpires: number | null = null;
+	/** The cloud's last refusal, until a token comes. */
+	private cloudProblem: { message: string; installUrl: string | null } | null = null;
 
 	constructor(connection: GitHubConnection, tracker: Tracker) {
 		if ('token' in connection) {
@@ -227,6 +256,11 @@ export class GitHubClient {
 			this.key = '';
 			this.token = connection.token;
 			this.tokenExpires = Number.POSITIVE_INFINITY;
+		} else if ('cloudKey' in connection) {
+			this.credential = 'cloud';
+			this.appId = '';
+			this.key = '';
+			this.cloud = { key: connection.cloudKey, url: connection.cloudUrl };
 		} else {
 			this.credential = 'app';
 			this.appId = connection.appId;
@@ -242,6 +276,7 @@ export class GitHubClient {
 
 	/** What's wrong with GitHub access now, the most serious first; null when nothing is (Decision 5). */
 	accessProblem(): GitHubAccessProblem | null {
+		if (this.cloudProblem) return { kind: 'cloud', credential: 'cloud', ...this.cloudProblem };
 		if (this.refused) return { kind: 'refused', credential: this.credential };
 		if (this.missingPermission) return { kind: 'permission', credential: this.credential, permission: this.missingPermission };
 		const expires = this.personalTokenExpires;
@@ -297,11 +332,38 @@ export class GitHubClient {
 		this.tokenExpires = Date.parse(tok.expires_at);
 	}
 
+	/**
+	 * Ask CaraCMS Cloud for a token. A refusal is kept as the access problem (and thrown); a
+	 * cloud that can't be reached only fails this call, as an unreachable GitHub does.
+	 */
+	private async cloudSignIn(cloud: { key: string; url: string }): Promise<void> {
+		let answer;
+		try {
+			answer = await cloudToken({ ...cloud, fetch: this.fetcher, timeoutMs: this.timeoutMs });
+		} catch (error) {
+			if (error instanceof CloudRefusal && 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;
+		}
+		this.cloudProblem = null;
+		this.token = answer.token;
+		this.tokenExpires = answer.expiresAt;
+	}
+
+	/** Sign in now (the cloud's first token at start, so a refusal stops the start). */
+	async ready(): Promise<void> {
+		await this.auth();
+	}
+
 	/** The installation token, refreshed five minutes before it expires; a personal token as it is. */
 	private async auth(): Promise<string> {
 		if (this.credential === 'token') return this.token;
 		if (!this.token || this.now() > this.tokenExpires - 5 * 60_000) {
-			this.signingIn ??= this.signIn().finally(() => {
+			this.signingIn ??= (this.cloud ? this.cloudSignIn(this.cloud) : this.signIn()).finally(() => {
 				this.signingIn = null;
 			});
 			await this.signingIn;

package/src/live/mode.ts

@@ -1,13 +1,15 @@
 /**
  * Which mode the editor runs in, read from the environment (M4 Decision 1).
  *
- * - **Local mode**: `astro dev` with no GitHub credentials (`GITHUB_APP_ID` or
- *   `CARACMS_GITHUB_TOKEN`). M3's editor, files on disk.
+ * - **Local mode**: `astro dev` with no GitHub credentials (`CARACMS_CLOUD_KEY`,
+ *   `GITHUB_APP_ID` or `CARACMS_GITHUB_TOKEN`). M3's editor, files on disk.
  * - **Live mode**: whenever a credential is configured, and **always on a production
  *   server**. It needs one GitHub credential (a fine-grained token, or the App's
  *   `GITHUB_APP_ID` and `GITHUB_APP_PRIVATE_KEY`; runs-anywhere Decisions 3–4), the repo
  *   (`GITHUB_REPO=owner/name`, or Railway's `RAILWAY_GIT_REPO_OWNER` and
- *   `RAILWAY_GIT_REPO_NAME`; Decision 6), `CARACMS_SECRET`, `REDIS_URL` and the site's
+ *   `RAILWAY_GIT_REPO_NAME`; Decision 6), or CaraCMS Cloud's site key instead of both
+ *   (`CARACMS_CLOUD_KEY`, with `CARACMS_CLOUD_URL` for another deployment than
+ *   production; caracms-cloud M2 Decision 11: the repo comes from the cloud at start), `CARACMS_SECRET`, `REDIS_URL` and the site's
  *   `https://` address in production (dev may use the stand-in Redis). A production
  *   server missing any of them still serves the public site; `/admin` answers 503
  *   naming them (Phase 2 builds that from `missing`).
@@ -18,6 +20,7 @@
  * 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';
 
@@ -26,6 +29,8 @@ export interface LiveSettings {
 	github:
 		| { kind: 'app'; appId: string; privateKey: string; owner: string; repo: string }
 		| { kind: 'token'; token: string; owner: string; repo: string }
+		/** CARACMS_CLOUD_KEY (caracms-cloud M2 Decision 11): the repo comes from the cloud when the runtime starts. */
+		| { kind: 'cloud'; key: string; url: string }
 		| { kind: 'memory' };
 	/** Null in dev without REDIS_URL: the in-memory stand-in. */
 	redisUrl: string | null;
@@ -88,6 +93,13 @@ export const NO_ADDRESS_PROBLEM =
 	"The site's public address isn't known: set SITE_URL to it, like https://fernhill.ie, both when the site is built and when it runs. Without it, sign-in links can't be sent and the editor's saves are refused.";
 export const HTTP_ADDRESS_PROBLEM = (address: string) =>
 	`The site's address (${address}) is http://, but signing in needs https://: the session cookie is only ever sent over https. Set SITE_URL to the https:// address (http:// works for localhost only).`;
+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}.`;
+export const CLOUD_REPO_PROBLEM = 'CARACMS_CLOUD_KEY is set, so the repo comes from CaraCMS Cloud; remove GITHUB_REPO.';
+export const CLOUD_URL_PROBLEM = (url: string) =>
+	`CARACMS_CLOUD_URL must be the cloud's https:// address (http:// works for localhost only; got "${url}"). Leave it unset for CaraCMS Cloud itself.`;
 export const BOTH_REDEPLOYERS_PROBLEM =
 	'Both CARACMS_DEPLOY_HOOK_URL and CARACMS_RAILWAY_TOKEN are set: Try again redeploys through one of them, so set only one.';
 
@@ -153,7 +165,8 @@ export function readMode(env: Env = process.env, production = env.NODE_ENV === '
 	const memory = get('CARACMS_GITHUB') === 'memory';
 	// Never GITHUB_TOKEN (Decision 4): the gh CLI and GitHub Actions export it.
 	const ghToken = get('CARACMS_GITHUB_TOKEN');
-	if (!production && !memory && !get('GITHUB_APP_ID') && !ghToken) return { kind: 'local' };
+	const cloudKey = get('CARACMS_CLOUD_KEY');
+	if (!production && !memory && !get('GITHUB_APP_ID') && !ghToken && !cloudKey) return { kind: 'local' };
 
 	const missing: string[] = [];
 	const problems: string[] = [];
@@ -168,7 +181,14 @@ 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 (!memory || production) {
+	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'));
+		if (get('GITHUB_APP_ID')) problems.push(CLOUD_AND_GITHUB_PROBLEM('GITHUB_APP_ID'));
+		if (get('GITHUB_REPO')) problems.push(CLOUD_REPO_PROBLEM);
+		github = { kind: 'cloud', key: cloudKey, url: readCloudUrl(get('CARACMS_CLOUD_URL'), problems) };
+	} else if (!memory || production) {
 		const appId = get('GITHUB_APP_ID');
 		const repo = readRepo(env, problems);
 		const owner = repo?.owner ?? '';
@@ -181,7 +201,7 @@ export function readMode(env: Env = process.env, production = env.NODE_ENV === '
 		} else if (appId) {
 			github = { kind: 'app', appId, privateKey: need('GITHUB_APP_PRIVATE_KEY'), owner, repo: name };
 		} else {
-			missing.push('CARACMS_GITHUB_TOKEN (or GITHUB_APP_ID and GITHUB_APP_PRIVATE_KEY)');
+			missing.push('CARACMS_CLOUD_KEY (or CARACMS_GITHUB_TOKEN, or GITHUB_APP_ID and GITHUB_APP_PRIVATE_KEY)');
 		}
 		if (!repo && !problems.some((p) => p.startsWith('GITHUB_REPO'))) {
 			missing.push(onRailway(env) ? 'RAILWAY_GIT_REPO_OWNER and RAILWAY_GIT_REPO_NAME (or GITHUB_REPO)' : 'GITHUB_REPO');
@@ -277,6 +297,22 @@ function isBranchName(name: string): boolean {
 	);
 }
 
+/** CARACMS_CLOUD_URL, without a trailing slash: https://, or http:// on localhost. Unset, the production address. */
+function readCloudUrl(raw: string | null, problems: string[]): string {
+	if (!raw) return DEFAULT_CLOUD_URL;
+	let url: URL | null = null;
+	try {
+		url = new URL(raw);
+	} catch {
+		/* a problem, below */
+	}
+	if (!url || !(url.protocol === 'https:' || (url.protocol === 'http:' && isLocalhost(url.hostname)))) {
+		problems.push(CLOUD_URL_PROBLEM(raw));
+		return raw;
+	}
+	return `${url.origin}${url.pathname}`.replace(/\/+$/, '');
+}
+
 /** The repo: GITHUB_REPO overrides Railway's own variables (M4 Decision 3; runs-anywhere Decision 6). */
 function readRepo(env: Env, problems: string[]): { owner: string; repo: string } | null {
 	const override = env.GITHUB_REPO?.trim();

package/src/live/runtime.ts

@@ -20,6 +20,7 @@ import { join, relative, sep } from 'node:path';
 import { repoPrefix, type ResolvedSite } from '../config.ts';
 import { GitHubBackend, MemoryBackend, type FileWrite, type GitBackend } from './backend.ts';
 import { DEFAULT_BRANCHES } from './branches.ts';
+import { cloudSettings } from './cloud.ts';
 import { GitHubClient, Tracker } from './github.ts';
 import { LiveGit, SITE_SETTINGS_FILE } from './git.ts';
 import type { LiveSettings } from './mode.ts';
@@ -52,6 +53,8 @@ export interface RuntimeOptions {
 	railwayFetch?: typeof fetch;
 	/** Tests: the deploy hook's fetch. */
 	deployHookFetch?: typeof fetch;
+	/** Tests: the fetch GitHub and CaraCMS Cloud are reached through. */
+	fetch?: typeof fetch;
 }
 
 /** Build and start a runtime (not shared: tests make their own). */
@@ -72,8 +75,21 @@ export async function createLiveRuntime(options: RuntimeOptions): Promise<LiveRu
 		} else {
 			const tracker = new Tracker(now);
 			const gh = settings.github;
-			const connection = gh.kind === 'token' ? { token: gh.token, owner: gh.owner, repo: gh.repo, now } : { appId: gh.appId, privateKey: gh.privateKey, owner: gh.owner, repo: gh.repo, now };
-			backend = new GitHubBackend(new GitHubClient(connection, tracker), settings.branches);
+			const fetch = options.fetch;
+			let client: GitHubClient;
+			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).
+				const { owner, repo } = await cloudSettings({ key: gh.key, url: gh.url, fetch });
+				client = new GitHubClient({ cloudKey: gh.key, cloudUrl: gh.url, owner, repo, now, fetch }, tracker);
+				await client.ready();
+				log(`live mode on ${owner}/${repo} through CaraCMS Cloud`);
+			} else {
+				const connection =
+					gh.kind === 'token' ? { token: gh.token, owner: gh.owner, repo: gh.repo, now, fetch } : { appId: gh.appId, privateKey: gh.privateKey, owner: gh.owner, repo: gh.repo, now, fetch };
+				client = new GitHubClient(connection, tracker);
+			}
+			backend = new GitHubBackend(client, settings.branches);
 		}
 	}
 	const { main, drafts } = backend.branches;