caracms 0.6.0 → 0.8.0

package/src/forms/store.ts

@@ -9,8 +9,12 @@
  *   gets these. **The production server never falls back to disk**: with any of them
  *   unset, the store is `unset` (the endpoint's 502, the inbox's sentence).
  * - **Everywhere else**: `.caracms/submissions/` under the site's root (gitignored),
- *   **even with the bucket variables set**, so a laptop never lands a test enquiry in
+ *   **even with the bucket variables or the cloud key set**, so a laptop never lands a test enquiry in
  *   the client's inbox, nor copies their visitors' data down.
+ * - **CaraCMS Cloud** (caracms-cloud M4 Decision 23): a production server with
+ *   `CARACMS_CLOUD_KEY` stores through the cloud's API (cloud-store.ts), and the cloud sends
+ *   the email. The key with any of the site's own forms and email variables is `unset`
+ *   with Decision 22's sentence.
  * - **`CARACMS_SUBMISSIONS=memory`**: in memory, one per process, for tests. Refused in
  *   production, as `CARACMS_MEDIA=memory` is.
  *
@@ -31,6 +35,9 @@ import { createHash, randomInt } from 'node:crypto';
 import { mkdir, readdir, readFile, rmdir, unlink, writeFile } from 'node:fs/promises';
 import { dirname, join, resolve, sep } from 'node:path';
 import { AwsClient } from 'aws4fetch';
+import { cloudForms } from '../live/mode.ts';
+import { bakedServices, CLOUD_KEY_MISSING_PROBLEM, servicesEnv, type Services } from '../live/services.ts';
+import { cloudStore } from './cloud-store.ts';
 import { isSubmissionId, shownFileName } from './rules.ts';
 
 type Env = Record<string, string | undefined>;
@@ -77,8 +84,24 @@ export interface NewFile {
 	data: Uint8Array;
 }
 
+/**
+ * What a cloud site's server sends with a submission (caracms-cloud M4 Decision 11): the
+ * email, written, or the reason there is none. The cloud sends it once the row is stored.
+ */
+export type WrittenEmail =
+	| { email: { to: string[]; subject: string; text: string; replyTo?: string; fromName: string } }
+	| { emailSkipped: string }
+	| { emailFailed: string };
+
 export interface SubmissionStore {
-	create(input: { form: string; receivedAt: string; fields: Record<string, string>; files?: NewFile[] }): Promise<StoredSubmission>;
+	/**
+	 * `email` writes the email for the submission as stored (its id, files and time), and only
+	 * the cloud store calls it (M4 Decision 23): it may call it twice, when the cloud already
+	 * had the first id. The other stores ignore it; the endpoint sends their email itself.
+	 */
+	create(input: { form: string; receivedAt: string; fields: Record<string, string>; files?: NewFile[]; email?: (submission: StoredSubmission) => WrittenEmail }): Promise<StoredSubmission>;
+	/** True for the cloud store: the email goes with `create`, and the cloud sends it and records the outcome. */
+	readonly sendsEmail?: boolean;
 	get(id: string): Promise<StoredSubmission | null>;
 	getFile(id: string, n: number): Promise<{ file: StoredFile; body: Uint8Array } | null>;
 	/** Newest first, `limit` (default 50) after `before`; `older` is the cursor for the next page, or null. */
@@ -426,6 +449,8 @@ export type SubmissionsConfig =
 	| { kind: 'memory' }
 	| { kind: 'folder'; dir: string }
 	| { kind: 'bucket'; bucket: SubmissionsBucket }
+	/** CaraCMS Cloud (caracms-cloud M4 Decision 23): a production server with `CARACMS_CLOUD_KEY`. */
+	| { kind: 'cloud'; connection: { key: string; url: string } }
 	/** The production server without its bucket: `message` names what's missing (the endpoint's log, the inbox's sentence). */
 	| { kind: 'unset'; message: string; missing: string[] };
 
@@ -435,15 +460,28 @@ const list = (names: readonly string[]) => (names.length <= 1 ? names.join('') :
 export const isProductionEnv = (env: Env): boolean => env['NODE_ENV'] === 'production';
 
 /** Decision 7's rule, from the environment. Read on each call (cheap). */
-export function readSubmissionsConfig(root: string, env: Env = process.env, production = isProductionEnv(env)): SubmissionsConfig {
+export function readSubmissionsConfig(root: string, env: Env = process.env, production = isProductionEnv(env), services: Services | null = bakedServices()): SubmissionsConfig {
+	// caracms-cloud M5 Decision 2: with the config's `services`, the other mode's variables are never read.
+	env = servicesEnv(env, services);
 	const get = (name: string) => env[name]?.trim() || '';
 	const mode = get('CARACMS_SUBMISSIONS');
 	if (mode === 'memory') return production ? { kind: 'unset', message: SUBMISSIONS_MEMORY_IN_PRODUCTION, missing: [] } : { kind: 'memory' };
 	if (mode) return { kind: 'unset', message: `CARACMS_SUBMISSIONS must be "memory" or unset (got "${mode}").`, missing: [] };
+	// The key with the site's own variables is a mistake everywhere (M4 Decision 22), as the media's is.
+	const cloud = cloudForms(env, services);
+	if (cloud?.problems.length) return { kind: 'unset', message: cloud.problems.join(' '), missing: [] };
+	// Outside production: the folder, even with the cloud key (M4's Core framing).
 	if (!production) return { kind: 'folder', dir: join(root, LOCAL_SUBMISSIONS_FOLDER) };
+	if (cloud) return { kind: 'cloud', connection: cloud.connection };
+	// M5 Decision 4: a cloud site without its key, never the site's own bucket instead.
+	if (services === 'cloud') return { kind: 'unset', message: CLOUD_KEY_MISSING_PROBLEM, missing: ['CARACMS_CLOUD_KEY'] };
 	const missing = [...SUBMISSIONS_ENV, ...SHARED_ENV].filter((name) => !get(name));
 	if (missing.length) {
-		return { kind: 'unset', message: `Form submissions aren't set up on this server: set ${list(missing)} to the site's submissions bucket.`, missing };
+		return {
+			kind: 'unset',
+			message: `Form submissions aren't set up on this server: set CARACMS_CLOUD_KEY to the site's CaraCMS Cloud key, or set ${list(missing)} to the site's submissions bucket.`,
+			missing,
+		};
 	}
 	return {
 		kind: 'bucket',
@@ -474,6 +512,8 @@ export function resetSubmissions(): void {
 /** The store for this config, one per process per backend (so the unread count is kept), or the `unset` config itself. */
 export function submissionStore(config: SubmissionsConfig, fetchImpl?: typeof fetch): SubmissionStore | Extract<SubmissionsConfig, { kind: 'unset' }> {
 	if (config.kind === 'unset') return config;
+	// One per call (a request): the cloud keeps the unread count, and the store holds only the count its own last answer gave.
+	if (config.kind === 'cloud') return cloudStore({ ...config.connection, ...(fetchImpl ? { fetch: fetchImpl } : {}) });
 	const s = shared();
 	const id = config.kind === 'memory' ? 'memory' : config.kind === 'folder' ? `folder:${config.dir}` : `bucket:${config.bucket.endpoint}:${config.bucket.bucket}:${config.bucket.accessKeyId}`;
 	let store = s.stores.get(id);

package/src/index.ts

@@ -466,6 +466,8 @@ export default function caracms(config: SiteConfig): AstroIntegration {
 							// Runs-anywhere Decisions 7 and 9: the address and the commit the build was made with (editor/server/mode.ts → bakedAtBuild).
 							__CARACMS_SITE__: JSON.stringify(astroConfig.site ?? address.url ?? null),
 							__CARACMS_BUILD_COMMIT__: JSON.stringify(commit),
+							// caracms-cloud M5 Decision 1: the config's `services`, for the key-or-own readers (live/services.ts → bakedServices).
+							__CARACMS_SERVICES__: JSON.stringify(site.services),
 							__CARACMS_TOKENS_CSS__: JSON.stringify(readFileSync(new URL('./editor/styles/tokens.css', import.meta.url), 'utf8')),
 						},
 						// Installed from npm, the package ships TypeScript and .astro source.
@@ -518,7 +520,7 @@ export default function caracms(config: SiteConfig): AstroIntegration {
 			// 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();
+				await cloudSettingsForBuild(process.env, site.services);
 			},
 			'astro:build:done': () => {
 				shareBuildReads(false);

package/src/live/auth/email.ts

@@ -7,10 +7,18 @@
  * server log and nothing is sent, so no test from a laptop reaches anyone's inbox.
  * The email names the site by its brand name. The link carries only the token.
  *
+ * **On CaraCMS Cloud** (caracms-cloud M4 Decision 25), a production server with
+ * `CARACMS_CLOUD_KEY` asks the cloud instead (`POST /v1/email/sign-in`), which writes the
+ * email from its own copy of this template and sends it from `accounts.caracms.com`. The
+ * key beside `RESEND_API_KEY` or `FORMS_FROM` (Decision 22) sends nothing and logs why.
+ * Outside production the link is logged, key or not.
+ *
  * The HTML part is one table layout with inline styles (mail clients strip `<style>`),
  * the system font stack, no images; the plain-text part says the same.
  */
 import { sendEmail, sendsEmail } from '../../email.ts';
+import { cloudCall, isCloudRefusal } from '../cloud.ts';
+import { cloudForms } from '../mode.ts';
 
 export { RESEND_URL } from '../../email.ts';
 const FONT = "ui-sans-serif,system-ui,-apple-system,'Segoe UI',Roboto,Helvetica,Arial,sans-serif";
@@ -76,6 +84,20 @@ export async function deliverLink(input: {
 		log(`sign-in link for ${to} (not emailed outside production): ${link}`);
 		return 'logged';
 	}
+	const cloud = cloudForms(env);
+	if (cloud) {
+		if (cloud.problems.length) {
+			log(`could not email a sign-in link: ${cloud.problems.join(' ')}`);
+			return 'failed';
+		}
+		try {
+			await cloudCall({ ...cloud.connection, ...(input.fetch ? { fetch: input.fetch } : {}) }, 'POST', '/v1/email/sign-in', { to, link, siteName });
+			return 'sent';
+		} catch (error) {
+			log(`could not email a sign-in link: CaraCMS Cloud${isCloudRefusal(error) ? ` (${error.error}): ${error.message}` : `: ${error instanceof Error ? error.message : String(error)}`}`);
+			return 'failed';
+		}
+	}
 	const { subject, text, html } = buildLinkEmail({ siteName, link, email: to });
 	const result = await sendEmail({ to: [to], subject, text, html }, { env, fetch: input.fetch });
 	if (result.status === 'sent') return 'sent';

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,10 +107,35 @@ 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)}.`;
+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)}.`;
+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. */
+export function cloudFormsConflict(env: Env): string | null {
+	if (!env.CARACMS_CLOUD_KEY?.trim()) return null;
+	const both = OWN_FORMS_VARIABLES.filter((name) => env[name]?.trim());
+	return both.length ? CLOUD_AND_FORMS_PROBLEM(both) : null;
+}
+
+/**
+ * The cloud as the forms and email credential (caracms-cloud M4 Decision 22): the
+ * connection when `CARACMS_CLOUD_KEY` is set, with any problems (the site's own forms and
+ * 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, 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;
+	const conflict = cloudFormsConflict(env);
+	const problems: string[] = conflict ? [conflict] : [];
+	const url = readCloudUrl(get('CARACMS_CLOUD_URL'), problems);
+	return { connection: { key, url }, problems };
+}
+
 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.`;
@@ -162,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;
@@ -185,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'));
@@ -194,6 +235,12 @@ export function readMode(env: Env = process.env, production = env.NODE_ENV === '
 		// M3 Decision 19: the key is the media credential too (unless the tests' in-memory media is on).
 		const ownMedia = OWN_MEDIA_VARIABLES.filter((name) => get(name));
 		if (ownMedia.length && get('CARACMS_MEDIA') !== 'memory') problems.push(CLOUD_AND_MEDIA_PROBLEM(ownMedia));
+		// M4.5 Decision 15: and the video credential.
+		const ownMux = OWN_MUX_VARIABLES.filter((name) => get(name));
+		if (ownMux.length && get('CARACMS_MEDIA') !== 'memory') problems.push(CLOUD_AND_MUX_PROBLEM(ownMux));
+		// M4 Decision 22: and the forms and email credential.
+		const formsConflict = cloudFormsConflict(env);
+		if (formsConflict) problems.push(formsConflict);
 		github = { kind: 'cloud', key: cloudKey, url: readCloudUrl(get('CARACMS_CLOUD_URL'), problems) };
 	} else if (!memory || production) {
 		const appId = get('GITHUB_APP_ID');

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/media.ts

@@ -35,6 +35,7 @@ import { createHmac } from 'node:crypto';
 import type { ImageFormat } from './fields.ts';
 import { CLOUD_NO_MEDIA, heldCloudSettings, type CloudConnection } from './live/cloud.ts';
 import { CLOUD_AND_MEDIA_PROBLEM, OWN_MEDIA_VARIABLES, readCloudUrl } from './live/mode.ts';
+import { bakedServices, CLOUD_KEY_MISSING_PROBLEM, servicesEnv, type Services } from './live/services.ts';
 import { renderMedia, type RenderImage } from './media-value.ts';
 
 /** The srcset width ladder every fluid image draws from (Decision 2). 1920 at the top: imgproxy doesn't upscale. */
@@ -92,8 +93,10 @@ export const CLOUD_MEDIA_UNREACHABLE = "CaraCMS Cloud couldn't be reached, so im
  * The cloud as the media credential: the connection when `CARACMS_CLOUD_KEY` is set and
  * `CARACMS_MEDIA` isn't `memory` (which wins over everything), with any problems (the
  * site's own media variables beside it, a bad `CARACMS_CLOUD_URL`). Null: not a cloud site's media.
+ * With the config's `services` (caracms-cloud M5), the other mode's variables aren't read.
  */
-export function cloudMedia(env: Env = process.env): { connection: Pick<CloudConnection, 'key' | 'url'>; problems: string[] } | null {
+export function cloudMedia(env: Env = process.env, services: Services | null = bakedServices()): { connection: Pick<CloudConnection, 'key' | 'url'>; problems: string[] } | null {
+	env = servicesEnv(env, services);
 	const get = (name: string) => env[name]?.trim() || null;
 	const key = get('CARACMS_CLOUD_KEY');
 	if (!key || get('CARACMS_MEDIA') === 'memory') return null;
@@ -117,7 +120,8 @@ function cloudMediaConfig(cloud: NonNullable<ReturnType<typeof cloudMedia>>, pro
 }
 
 /** The media variables (Decision 5). Read on each call (cheap), so tests can change them. */
-export function readMediaConfig(env: Env = process.env, production = isProductionBuild()): MediaConfig {
+export function readMediaConfig(env: Env = process.env, production = isProductionBuild(), services: Services | null = bakedServices()): MediaConfig {
+	env = servicesEnv(env, services);
 	const get = (name: string) => {
 		const v = env[name]?.trim();
 		return v ? v : null;
@@ -129,7 +133,9 @@ export function readMediaConfig(env: Env = process.env, production = isProductio
 		return { kind: 'ready', settings: { ...MEMORY_MEDIA, memory: true } };
 	}
 	if (mode) problems.push(`CARACMS_MEDIA must be "memory" or unset (got "${mode}").`);
-	const cloud = cloudMedia(env);
+	// M5 Decision 4: a cloud site without its key has no media, never the site's own instead.
+	if (services === 'cloud' && !get('CARACMS_CLOUD_KEY')) return { kind: 'unset', missing: [], problems: [...problems, CLOUD_KEY_MISSING_PROBLEM] };
+	const cloud = cloudMedia(env, services);
 	if (cloud) return cloudMediaConfig(cloud, problems);
 	const missing: string[] = [];
 	const need = (name: string) => {