caracms 0.5.0 → 0.6.0

package/src/cloud-middleware.ts

@@ -0,0 +1,76 @@
+/**
+ * The settings fetch for a cloud site's media (caracms-cloud M3 Decision 20). The package
+ * has no boot hook in the built server, so **the first request that reaches the server, of
+ * any kind,** fetches `GET /v1/settings` (live/cloud.ts → `loadCloudSettings`) and every
+ * request waits on that one shared fetch before anything renders. The live runtime reads the
+ * same held answer, so it's one fetch per process. Prerendered pages are files and never wait.
+ *
+ * - Registered first (`addMiddleware({ order: 'pre' })` in index.ts), before the editor's.
+ * - Only for a cloud site's media: `CARACMS_CLOUD_KEY` set, `CARACMS_MEDIA` not `memory`,
+ *   and none of the site's own media variables (that's `readMediaConfig`'s problem sentence).
+ * - A fetch that fails leaves the media unset (v3's handling: the editor's media routes 503
+ *   with the cloud's sentence) and is tried again by a request after `RETRY_MS`, so a cloud
+ *   that's away doesn't hold every request for its timeout.
+ *
+ * `cloudSettingsForBuild()` is the build's start (`astro:build:start`): the same fetch, and
+ * a refusal or an unreachable cloud **fails the build** with the cloud's sentence or the
+ * package's own. The build ignores `github.repo`: a site with no repo linked still builds.
+ */
+import type { MiddlewareHandler } from 'astro';
+import { CLOUD_NO_MEDIA, CLOUD_UNREACHABLE_BUILD, isCloudRefusal, heldCloudSettings, loadCloudSettings } from './live/cloud.ts';
+import { cloudMedia } from './media.ts';
+
+type Env = Record<string, string | undefined>;
+
+/** After a failed fetch, requests in the next half minute don't wait on another. */
+export const RETRY_MS = 30_000;
+
+const NEXT_TRY = Symbol.for('caracms.cloudSettingsNextTry');
+const LOGGED = Symbol.for('caracms.cloudSettingsLogged');
+type Shared = { [NEXT_TRY]?: number; [LOGGED]?: string };
+
+/** Fetch the settings if this process doesn't hold them yet (and isn't waiting out a failure). */
+export async function ensureCloudSettings(env: Env = process.env, now = Date.now(), log: (line: string) => void = (line) => console.error(line)): Promise<void> {
+	const cloud = cloudMedia(env);
+	if (!cloud || cloud.problems.length) return;
+	if (heldCloudSettings(cloud.connection)?.kind === 'ready') return;
+	const g = globalThis as Shared;
+	if ((g[NEXT_TRY] ?? 0) > now) return;
+	try {
+		await loadCloudSettings(cloud.connection);
+		delete g[NEXT_TRY];
+		delete g[LOGGED];
+	} catch (error) {
+		g[NEXT_TRY] = now + RETRY_MS;
+		const line = isCloudRefusal(error) ? `CaraCMS Cloud (${error.error}): ${error.message}` : 'CaraCMS Cloud: the settings could not be read';
+		if (g[LOGGED] !== line) log(`[caracms] the media settings could not be fetched: ${line}`);
+		g[LOGGED] = line;
+	}
+}
+
+/** Forget the retry clock (tests). */
+export function resetCloudSettingsRetry(): void {
+	const g = globalThis as Shared;
+	delete g[NEXT_TRY];
+	delete g[LOGGED];
+}
+
+export const onRequest: MiddlewareHandler = async (_context, next) => {
+	await ensureCloudSettings();
+	return next();
+};
+
+/** The build's start: the settings, or an Error with the sentence that fails the build. Nothing for a site off the cloud. */
+export async function cloudSettingsForBuild(env: Env = process.env): Promise<void> {
+	const cloud = cloudMedia(env);
+	if (!cloud) return;
+	if (cloud.problems.length) throw new Error(`caracms: ${cloud.problems.join(' ')}`);
+	let settings;
+	try {
+		settings = await loadCloudSettings(cloud.connection);
+	} catch (error) {
+		const message = isCloudRefusal(error) && error.error !== 'unreachable' ? error.message : CLOUD_UNREACHABLE_BUILD;
+		throw new Error(`caracms: ${message}`);
+	}
+	if (!settings.media) throw new Error(`caracms: ${CLOUD_NO_MEDIA}`);
+}

package/src/editor/README.md

@@ -29,7 +29,8 @@ and an alt already used), `GET thumbnail?key=&width=` (a 302 to the signed URL),
 `POST video-upload`, `GET video-upload/<id>`, `GET clips`, `GET clips/<id>`, `GET playback/<id>`.
 Every shape is in `types.ts` → `MEDIA_ENDPOINTS`. `server/media/`: `sniff.ts` (the type and size
 from the bytes), `upload.ts` (the 40 MB cap, the key rule, no overwrite), `bucket.ts` (S3 through
-aws4fetch, and the in-memory bucket), `library.ts` (the 60 s listing, metadata per key,
+aws4fetch, and the in-memory bucket), `cloud-bucket.ts` (the same seam on CaraCMS Cloud's media
+API, `CARACMS_CLOUD_KEY`), `library.ts` (the 60 s listing, metadata per key,
 where-used), `mux.ts` (the template's Mux rules), `alt.ts` (`WaitingView.missingAlt`),
 `config.ts` (503s, images and clips apart) and `memory.ts` (`CARACMS_MEDIA=memory`: `memoryMedia()`
 to seed the bucket and the fake Mux in tests).

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

@@ -0,0 +1,144 @@
+/**
+ * The media bucket on CaraCMS Cloud (caracms-cloud M3 Decision 21), behind bucket.ts's
+ * seam, so the upload route (checks, key, dedupe, metadata) and the files route don't
+ * change. The site's server never holds R2 credentials: it asks the API (live/cloud.ts,
+ * the site key) and the API answers for the site's own folder. Keys stay `uploads/…`:
+ * the cloud adds `sites/<folder>/` and strips it again.
+ *
+ * - `list` and `first`: `GET /v1/media/list`, following its `next` tokens (`list`) or one page (`first`).
+ * - `head`: `GET /v1/media/object`; `404 not_found` is "no such object".
+ * - `get`: `POST /v1/media/download-url`, then the presigned GET, streamed (the files route).
+ * - `put`: `POST /v1/media/upload-url`, then the presigned PUT with exactly the headers it names.
+ *
+ * **The cloud's refusals are shown as sent** (`CloudRefusal`: `upload_limit`'s sentence,
+ * `storage_unavailable`'s); the media handler puts the message in its 502. A cloud that
+ * can't be reached, and the storage's own answers to the presigned URLs, are BucketErrors
+ * (the handler's own sentences). Presigned URLs go nowhere but the fetch here: never in
+ * a log line, an error or an answer to the browser.
+ */
+import { isCloudRefusal, cloudCall, type CloudConnection } from '../../../live/cloud.ts';
+import { BucketError, type Bucket, type BucketObject, type ObjectMeta } from './bucket.ts';
+
+const STORAGE_TIMEOUT_MS = 20_000;
+/** A runaway-token guard, as s3Bucket's: 1000 pages of 1000 is far past one site's library. */
+const MAX_PAGES = 1000;
+
+const num = (v: unknown) => (typeof v === 'number' && Number.isFinite(v) && v > 0 ? Math.round(v) : null);
+const text = (v: unknown) => (typeof v === 'string' && v ? v : null);
+const iso = (v: unknown) => (typeof v === 'string' && !Number.isNaN(Date.parse(v)) ? new Date(v).toISOString() : null);
+
+export function cloudBucket(connection: Pick<CloudConnection, 'key' | 'url'>, fetchImpl: typeof fetch = (...args) => globalThis.fetch(...args)): Bucket {
+	const conn: CloudConnection = { ...connection, fetch: fetchImpl };
+
+	/** One API call; a cloud that can't be reached is a BucketError, any other refusal goes up as sent. */
+	async function api(method: 'GET' | 'POST', path: string, body?: unknown): Promise<Record<string, unknown>> {
+		try {
+			return await cloudCall(conn, method, path, body);
+		} catch (error) {
+			if (isCloudRefusal(error) && error.error === 'unreachable') throw new BucketError(`${method} ${path.split('?')[0]}: CaraCMS Cloud unreachable`);
+			throw error;
+		}
+	}
+
+	/** A presigned URL's request. The timeout covers the wait for the storage's headers (a `get` streams after). */
+	async function storage(what: string, url: string, init: RequestInit): Promise<Response> {
+		const controller = new AbortController();
+		const timer = setTimeout(() => controller.abort(new Error(`no answer in ${STORAGE_TIMEOUT_MS / 1000} s`)), STORAGE_TIMEOUT_MS);
+		try {
+			return await fetchImpl(url, { ...init, signal: controller.signal });
+		} catch (error) {
+			throw new BucketError(`${what}: storage unreachable (${error instanceof Error ? error.message : String(error)})`);
+		} finally {
+			clearTimeout(timer);
+		}
+	}
+
+	async function page(prefix: string, after: string | null): Promise<{ objects: BucketObject[]; next: string | null }> {
+		const query = new URLSearchParams({ prefix });
+		if (after) query.set('after', after);
+		const answer = await api('GET', `/v1/media/list?${query}`);
+		if (!Array.isArray(answer.objects)) throw new BucketError(`list ${prefix}: the answer has no objects`);
+		const objects: BucketObject[] = [];
+		for (const o of answer.objects as Record<string, unknown>[]) {
+			const key = o && typeof o === 'object' ? text(o.key) : null;
+			if (!key) continue;
+			objects.push({ key, lastModified: iso(o.lastModified), size: typeof o.size === 'number' && Number.isFinite(o.size) ? o.size : null });
+		}
+		return { objects, next: text(answer.next) };
+	}
+
+	return {
+		async list(prefix) {
+			const out: BucketObject[] = [];
+			const seen = new Set<string>();
+			let after: string | null = null;
+			for (let n = 0; n < MAX_PAGES; n++) {
+				const { objects, next } = await page(prefix, after);
+				out.push(...objects);
+				if (!next || seen.has(next)) break;
+				seen.add(next);
+				after = next;
+			}
+			return out;
+		},
+		async first(prefix) {
+			const { objects } = await page(prefix, null);
+			return objects[0]?.key ?? null;
+		},
+		async head(key): Promise<ObjectMeta | null> {
+			let answer: Record<string, unknown>;
+			try {
+				answer = await api('GET', `/v1/media/object?${new URLSearchParams({ key })}`);
+			} catch (error) {
+				if (isCloudRefusal(error) && error.error === 'not_found') return null;
+				throw error;
+			}
+			return {
+				w: num(answer.w),
+				h: num(answer.h),
+				name: text(answer.name),
+				by: text(answer.by),
+				contentType: text(answer.contentType),
+				lastModified: iso(answer.lastModified),
+				size: typeof answer.size === 'number' && Number.isFinite(answer.size) ? answer.size : null,
+			};
+		},
+		async get(key) {
+			const { url } = await api('POST', '/v1/media/download-url', { key });
+			if (typeof url !== 'string' || !/^https?:\/\//.test(url)) throw new BucketError(`get ${key}: the answer has no URL`);
+			const res = await storage(`get ${key}`, url, { method: 'GET' });
+			if (res.status === 404) {
+				await res.body?.cancel().catch(() => {});
+				return null;
+			}
+			if (!res.ok || !res.body) {
+				await res.body?.cancel().catch(() => {});
+				throw new BucketError(`get ${key}: ${res.status}`, res.status);
+			}
+			const size = Number(res.headers.get('content-length'));
+			return { body: res.body, size: res.headers.has('content-length') && Number.isFinite(size) ? size : null };
+		},
+		async put({ key, body, contentType, sha256, meta }) {
+			const answer = await api('POST', '/v1/media/upload-url', {
+				key,
+				size: body.byteLength,
+				contentType,
+				sha256,
+				meta: { ...(meta.w !== undefined ? { w: meta.w } : {}), ...(meta.h !== undefined ? { h: meta.h } : {}), name: meta.name, by: meta.by },
+			});
+			const { url, method, headers } = answer;
+			if (typeof url !== 'string' || !/^https?:\/\//.test(url) || (method !== undefined && method !== 'PUT') || !headers || typeof headers !== 'object') {
+				throw new BucketError(`put ${key}: the upload answer isn't one`);
+			}
+			// The headers as the cloud named them, verbatim (the URL signs each one). Content-Length and Host
+			// are fetch's own to send: the body is exactly the declared size, and the URL's host is the signed one.
+			const sent = Object.fromEntries(
+				Object.entries(headers as Record<string, unknown>).filter(([name, v]) => typeof v === 'string' && !/^(content-length|host)$/i.test(name)),
+			) as Record<string, string>;
+			const res = await storage(`put ${key}`, url, { method: 'PUT', headers: sent, body: body as BodyInit });
+			await res.body?.cancel().catch(() => {});
+			// 412: R2 refused the signed If-None-Match: * because the key is there, and the key carries the bytes' hash: already stored.
+			if (!res.ok && res.status !== 412) throw new BucketError(`put ${key}: ${res.status}`, res.status);
+		},
+	};
+}

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

@@ -10,8 +10,12 @@
  * - Images need imgproxy's (`CARACMS_MEDIA_URL`, `IMGPROXY_KEY`, `IMGPROXY_SALT`, which
  *   sign the thumbnails) and the bucket's (`S3_BUCKET`, `S3_ENDPOINT`, `S3_REGION`,
  *   `S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY`). Clips need `MUX_TOKEN_ID` and `MUX_TOKEN_SECRET`.
+ * - **On CaraCMS Cloud** (caracms-cloud M3 Decision 19) `CARACMS_CLOUD_KEY` is the images'
+ *   one credential: the bucket is the cloud's (cloud-bucket.ts), the signing from the
+ *   settings the process holds (../../../media.ts). Mux is unchanged.
  */
-import { isProductionBuild, readMediaConfig, type MediaSettings } from '../../../media.ts';
+import type { CloudConnection } from '../../../live/cloud.ts';
+import { cloudMedia, isProductionBuild, readMediaConfig, type MediaSettings } from '../../../media.ts';
 
 type Env = Record<string, string | undefined>;
 
@@ -26,6 +30,7 @@ export interface BucketSettings {
 export type ImagesConfig =
 	| { kind: 'memory'; signing: MediaSettings }
 	| { kind: 's3'; signing: MediaSettings; bucket: BucketSettings }
+	| { kind: 'cloud'; signing: MediaSettings; connection: Pick<CloudConnection, 'key' | 'url'> }
 	| { kind: 'unset'; message: string; missing: string[] };
 
 export type MuxConfig = { kind: 'memory' } | { kind: 'mux'; tokenId: string; tokenSecret: string } | { kind: 'unset'; message: string; missing: string[] };
@@ -48,6 +53,11 @@ export function readImagesConfig(env: Env = process.env, production = isProducti
 		return { kind: 'memory', signing: signing.settings };
 	}
 	const signing = readMediaConfig(env, production);
+	const cloud = cloudMedia(env);
+	if (cloud) {
+		if (signing.kind === 'ready') return { kind: 'cloud', signing: signing.settings, connection: cloud.connection };
+		return { kind: 'unset', message: signing.problems.join(' '), missing: [] };
+	}
 	const missing = signing.kind === 'unset' ? [...signing.missing] : [];
 	const problems = signing.kind === 'unset' ? [...signing.problems] : [];
 	const need = (name: string) => {

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

@@ -41,6 +41,8 @@ import type { DraftsStore } from '../drafts-store.ts';
 import { parseReplaceBody } from '../replace.ts';
 import { checkOrigin, seqOf, tabOf, WriteRefused } from '../write.ts';
 import { BucketError, s3Bucket, type Bucket } from './bucket.ts';
+import { cloudBucket } from './cloud-bucket.ts';
+import { isCloudRefusal } from '../../../live/cloud.ts';
 import { readImagesConfig, readMuxConfig } from './config.ts';
 import { isFileKey } from '../../../files.ts';
 import { entryOf, fileEntryOf, libraryFor, mediaUses, UPLOADS, type Library, type MediaUses } from './library.ts';
@@ -76,6 +78,7 @@ function images(ctx: MediaContext): { library: Library; signing: MediaSettings }
 	const config = readImagesConfig(ctx.env ?? process.env, ctx.production);
 	if (config.kind === 'unset') return json(503, { error: config.message, code: 'media-unset', missing: config.missing } satisfies MediaUnset);
 	if (config.kind === 'memory') return { library: libraryFor('memory', () => memoryMedia().bucket), signing: config.signing };
+	if (config.kind === 'cloud') return { library: libraryFor(`cloud:${config.connection.url}:${config.signing.prefix}`, (): Bucket => cloudBucket(config.connection, ctx.fetch)), signing: config.signing };
 	const b = config.bucket;
 	return { library: libraryFor(`s3:${b.endpoint}:${b.bucket}:${b.accessKeyId}`, (): Bucket => s3Bucket(b, ctx.fetch)), signing: config.signing };
 }
@@ -210,6 +213,11 @@ export async function handleMedia(request: Request, ctx: MediaContext): Promise<
 		if (error instanceof UploadRefused) return json(error.status, { error: error.message, code: error.code } satisfies MediaRefusal);
 		if (error instanceof MuxRouteError) return json(error.status, { error: error.message } satisfies ApiError);
 		if (error instanceof WriteRefused) return json(error.status, { error: error.message, ...error.body });
+		if (isCloudRefusal(error)) {
+			// caracms-cloud M3: the cloud's own sentence, as sent (a full site, its storage away).
+			log(`[caracms] media bucket: CaraCMS Cloud (${error.error}): ${error.message}`);
+			return json(502, { error: error.message } satisfies ApiError);
+		}
 		if (error instanceof BucketError) {
 			log(`[caracms] media bucket: ${error.message}`);
 			const said = error.status !== null && error.status >= 400 && error.status < 500;

package/src/files-route.ts

@@ -32,6 +32,7 @@ import type { APIRoute } from 'astro';
 import { clientIp, NO_GATE_MESSAGE } from './live/auth/request.ts';
 import { fileAddress, fileKeyOf, fileTypeOf } from './files.ts';
 import { s3Bucket, type Bucket } from './editor/server/media/bucket.ts';
+import { cloudBucket } from './editor/server/media/cloud-bucket.ts';
 import { readImagesConfig } from './editor/server/media/config.ts';
 import { memoryMedia } from './editor/server/media/memory.ts';
 import { isProductionBuild } from './media.ts';
@@ -168,7 +169,7 @@ export async function handleFileRequest(request: Request, ctx: FileRouteContext
 	}
 
 	// 6. The one key the allow-list passed.
-	const bucket: Bucket = config.kind === 'memory' ? memoryMedia().bucket : s3Bucket(config.bucket, ctx.fetch);
+	const bucket: Bucket = config.kind === 'memory' ? memoryMedia().bucket : config.kind === 'cloud' ? cloudBucket(config.connection, ctx.fetch) : s3Bucket(config.bucket, ctx.fetch);
 	let object;
 	try {
 		object = await bucket.get(file.key);

package/src/index.ts

@@ -46,12 +46,13 @@
  * (Decision 5) and has Vite pre-bundle the editor's browser deps. The public pages
  * have no script, no React and no editor markers in either.
  */
+import { cloudSettingsForBuild } from './cloud-middleware.ts';
 import type { AstroIntegration } from 'astro';
 import { fontProviders } from 'astro/config';
 import { execFileSync } from 'node:child_process';
-import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, readFileSync, watch, writeFileSync, type FSWatcher } from 'node:fs';
 import { createRequire } from 'node:module';
-import { isAbsolute, join, sep } from 'node:path';
+import { basename, dirname, isAbsolute, join, sep } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { resolveSite, SITE_SETTINGS_FILE, type ResolvedSite, type SiteConfig } from './config.ts';
 import { lockupCss } from './lockup-css.ts';
@@ -198,6 +199,8 @@ export const REDIRECT_MIDDLEWARE = 'redirect-middleware.ts';
 
 /** M4 Phase 2: the unconfigured server's 503, registered before Phase 3's guard. */
 export const EDITOR_MIDDLEWARE = 'editor/middleware.ts';
+/** caracms-cloud M3 Decision 20: a cloud site's settings, fetched by the first request (cloud-middleware.ts). */
+export const CLOUD_MIDDLEWARE = 'cloud-middleware.ts';
 
 /**
  * Content files out of Vite's watch (Decision 5): a write never reloads `/admin`
@@ -219,6 +222,39 @@ export function contentWatchIgnores(site: Pick<ResolvedSite, 'collections' | 'ro
 	];
 }
 
+/**
+ * The content contentWatchIgnores takes out of Vite's watch, watched apart, so the dev server
+ * learns a page was added, moved, hidden or removed. Astro's dev server caches each route's
+ * `getStaticPaths` and clears it only on its own content changes, so without this the public
+ * site kept its old list of pages until a restart (an old address even answered 500 rather
+ * than its redirect). Every collection folder that exists at start, recursively, and the
+ * Site Settings file; `onChange` once per burst of changes. Returns the stop.
+ */
+export function watchContent(site: Pick<ResolvedSite, 'collections' | 'root'>, onChange: () => void, wait = 100): () => void {
+	let timer: ReturnType<typeof setTimeout> | undefined;
+	const changed = () => {
+		clearTimeout(timer);
+		timer = setTimeout(onChange, wait);
+	};
+	const watchers: FSWatcher[] = [];
+	const add = (path: string, recursive: boolean, only?: string) => {
+		if (!existsSync(path)) return;
+		const watcher = watch(path, { recursive, persistent: false }, (_event, name) => {
+			if (!only || name === only) changed();
+		});
+		// A watched folder that's removed mustn't take the dev server down with it.
+		watcher.on('error', () => watcher.close());
+		watchers.push(watcher);
+	};
+	for (const c of Object.values(site.collections)) if (c.kind !== 'settings') add(c.dir, true);
+	const settings = join(site.root, SITE_SETTINGS_FILE);
+	add(dirname(settings), false, basename(settings));
+	return () => {
+		clearTimeout(timer);
+		for (const watcher of watchers) watcher.close();
+	};
+}
+
 /**
  * The hosts Astro may take a request's address from (`security.allowedDomains`).
  * Without them, Astro ignores the Host header and every request reads as
@@ -377,6 +413,8 @@ export default function caracms(config: SiteConfig): AstroIntegration {
 					if (address.url) injectRoute({ pattern: SITEMAP_ROUTE.pattern, entrypoint: new URL(`./${SITEMAP_ROUTE.entrypoint}`, import.meta.url), prerender: true });
 					// M4 Phase 3: the sign-in pages (live/auth/routes.ts).
 					for (const route of LOGIN_ROUTES) injectRoute({ pattern: route.pattern, entrypoint: new URL(`./${route.entrypoint}`, import.meta.url), prerender: false });
+					// caracms-cloud M3 Decision 20: a cloud site's settings, awaited before anything renders. First of all.
+					addMiddleware({ order: 'pre', entrypoint: new URL(`./${CLOUD_MIDDLEWARE}`, import.meta.url) });
 					// M4 Phase 2: an unconfigured production server's 503 on /admin and /_caracms/*. First, so it runs before the guard.
 					addMiddleware({ order: 'pre', entrypoint: new URL(`./${EDITOR_MIDDLEWARE}`, import.meta.url) });
 					// M4 Phase 3: the sign-in guard on /admin and /_caracms/ (live mode only). Must stay after the 503 middleware.
@@ -461,16 +499,27 @@ export default function caracms(config: SiteConfig): AstroIntegration {
 			},
 			// M8 Decision 14: a dev server (at start, and on the restart a config change makes) regenerates
 			// schemas/ from the config. Never content files: a dev run only changes what your code change derives.
-			'astro:server:setup': ({ logger }) => {
+			'astro:server:setup': ({ server, logger }) => {
 				try {
 					const changed = writeSchemaFiles(site);
 					if (changed.length) logger.info(`updated ${changed.map((c) => c.file).join(', ')}`);
 				} catch (error) {
 					logger.warn(`couldn't write schemas/: ${(error as Error).message}`);
 				}
+				// A content change re-runs every route's getStaticPaths, as Astro does for its own content
+				// collections (the same event, to the same server environments). Never a browser reload:
+				// the editor writes these files.
+				const stop = watchContent(site, () => {
+					for (const name of ['ssr', 'prerender']) server.environments[name]?.hot.send('astro:content-changed', {});
+				});
+				server.httpServer?.once('close', stop);
 			},
 			// Posts and tags, Decision 15: a production build reads each document once (read.ts). Never in dev.
-			'astro:build:start': () => shareBuildReads(true),
+			// caracms-cloud M3 Decision 20: a cloud site's settings, fetched once before any page renders; a refusal fails the build.
+			'astro:build:start': async () => {
+				shareBuildReads(true);
+				await cloudSettingsForBuild();
+			},
 			'astro:build:done': () => {
 				shareBuildReads(false);
 				if (buildInfo && serverDir && existsSync(serverDir)) writeFileSync(new URL(BUILD_INFO_FILE, serverDir), `${JSON.stringify(buildInfo)}\n`);

package/src/live/README.md

@@ -19,7 +19,7 @@ live drafts store, sweep, locks and status route, and Phase 3's sign-in, sit on
 | `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). 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 |
+| `cloud.ts` | CaraCMS Cloud (`CARACMS_CLOUD_KEY`; caracms-cloud M2): `DEFAULT_CLOUD_URL`, `fetchCloudSettings()` (the repo and the media; M3), `loadCloudSettings()` / `heldCloudSettings()` (one fetch per process, shared by the media and the runtime), `cloudSettings()` (the repo, at start), `cloudCall()` (one call, for the cloud bucket too), `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

@@ -25,7 +25,7 @@
 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 { isCloudRefusal, cloudUnavailable } from '../cloud.ts';
 import { setPerson } from '../locals.ts';
 import { guard, isFormEndpoint, isGuardedPath } from './guard.ts';
 import { authFor } from './index.ts';
@@ -42,7 +42,7 @@ export const onRequest: MiddlewareHandler = async (context, next) => {
 	try {
 		auth = await authFor(site, mode.settings, context.site);
 	} catch (error) {
-		if (error instanceof CloudRefusal) {
+		if (isCloudRefusal(error)) {
 			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/'));
 		}