caracms 0.7.0 → 0.8.0

package/bin/init.mjs

@@ -1,9 +1,16 @@
-// `caracms init [--write] [--railway]` (M8 Decisions 7–13): add caracms's plumbing to an
-// existing Astro site, and nothing about its design.
+// `caracms init [--write] [--railway] [--cloud | --self-hosted]` (M8 Decisions 7–13,
+// caracms-cloud M5 Decisions 5–11): add caracms's plumbing to an existing Astro site, and
+// nothing about its design.
 //
 // - Run plainly, it prints every file it would add and every edit as a diff, and writes
 //   nothing. `--write` applies exactly that, then writes the schemas (`caracms schemas`).
-//   It never prompts.
+// - Where the site runs (the config's `services`, M5): `--cloud` or `--self-hosted` writes
+//   it into the `defineSite({` literal. With neither and no field yet, it asks only when a
+//   person can answer (a terminal on both ends); otherwise a new site stops and names both
+//   flags, and a site already set up gets everything else and "Mode not set". A field
+//   already there is the mode, never asked again; a flag against it is the move: `--cloud`
+//   prints the move list for a self-hosted site, `--self-hosted` the way back. `--cloud`
+//   checks the key (`GET /v1/settings`) when it can find one, never printing it.
 // - It stops on anything in the way (Decision 9), naming each problem with what to do, and
 //   writes nothing. One run reports every problem, the git checks included.
 // - An existing file it can't edit safely (an astro.config it can't follow, an existing
@@ -15,14 +22,17 @@
 // - Run again, it re-links the skills, refreshes the CLAUDE.md block and the schemas, and
 //   reports the rest as already done.
 //
-// Plain JavaScript importing only Node built-ins (and, for the schemas, the site's own
-// Vite through site-runner.mjs), so it runs on Node 22.12 with no flags.
+// Plain JavaScript importing only Node built-ins and media.mjs (and, for the schemas and the
+// config's `services`, the site's own Vite through site-runner.mjs), so it runs on Node
+// 22.12 with no flags.
 
 import { execFileSync } from 'node:child_process';
 import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, readlinkSync, rmSync, statSync, symlinkSync, writeFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
+import { createInterface } from 'node:readline/promises';
 import { basename, dirname, join, relative, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { DEFAULT_CLOUD_URL, OWN_MEDIA_NAMES, parseDotenv, REPLACED_NAMES } from './media.mjs';
 
 const packageRoot = fileURLToPath(new URL('..', import.meta.url));
 const templates = fileURLToPath(new URL('./templates/', import.meta.url));
@@ -53,13 +63,20 @@ export const HOST_VARIABLES = [
 	{ name: 'GITHUB_WEBHOOK_SECRET', need: 'optional', what: "For a webhook added in the repo's settings. Without it, a check once a minute does the same job." },
 ];
 
-/** HOST_VARIABLES as init prints it: one table, name, whether it's needed, what it's for. */
-export function hostVariablesText() {
-	const rows = [{ name: 'Name', need: 'Needed', what: "What it's for" }, ...HOST_VARIABLES];
+/** What the cloud key replaces in HOST_VARIABLES (M5 Contracts), and the key itself. */
+const CLOUD_KEY_VARIABLE = { name: 'CARACMS_CLOUD_KEY', need: 'required', what: "The site's key from app.caracms.com (cck_…), labelled for this server. It brings the site's GitHub access, images, video, and forms and email." };
+
+/** HOST_VARIABLES as init prints it: one table, name, whether it's needed, what it's for. On CaraCMS Cloud, the key in place of what it replaces. */
+/** @param {string | null} [mode] the config's `services` */
+export function hostVariablesText(mode = null) {
+	const variables = mode === 'cloud' ? [CLOUD_KEY_VARIABLE, ...HOST_VARIABLES.filter((v) => !REPLACED_NAMES.includes(v.name) && v.name !== 'GITHUB_WEBHOOK_SECRET').map((v) => (v.name === 'CARACMS_ALLOW' ? { ...v, need: 'for email sign-in (sent by the cloud)' } : v))] : HOST_VARIABLES;
+	const rows = [{ name: 'Name', need: 'Needed', what: "What it's for" }, ...variables];
 	const w1 = Math.max(...rows.map((r) => r.name.length));
 	const w2 = Math.max(...rows.map((r) => r.need.length));
 	return [
-		"The variables any host needs, on the site's server (`caracms start` runs it; one instance, behind HTTPS). Set email sign-in, the backup sign-in or both, or nobody can sign in. Images, video and forms have their own variables: the caracms README's Hosting section lists them. `caracms init --railway` writes a Railway setup instead.",
+		mode === 'cloud'
+			? "The variables any host needs, on the site's server (`caracms start` runs it; one instance, behind HTTPS), on CaraCMS Cloud. Set email sign-in, the backup sign-in or both, or nobody can sign in. `caracms init --railway` writes a Railway setup instead."
+			: "The variables any host needs, on the site's server (`caracms start` runs it; one instance, behind HTTPS). Set email sign-in, the backup sign-in or both, or nobody can sign in. Images, video and forms have their own variables: the caracms README's Hosting section lists them. `caracms init --railway` writes a Railway setup instead.",
 		...rows.map((r) => `  ${r.name.padEnd(w1)}  ${r.need.padEnd(w2)}  ${r.what}`),
 	].join('\n');
 }
@@ -83,6 +100,7 @@ const SKILL_BLURBS = {
 	'caracms-blocks': 'building the site: blocks and their fields, collections, text styles, the page component, forms, and scripts beside the editor',
 	'caracms-adopt': 'bringing the site\'s existing pages onto caracms, one page at a time, and checking they look the same',
 	'caracms-tina': 'porting a site built on Tina (a Tina template site) onto caracms with the reference conversion script, re-runnable on newer content',
+	'caracms-hosting': "where the site runs, CaraCMS Cloud or self-hosted: choosing the mode with `caracms init`, the server's host, moving a self-hosted site onto the cloud, and what to do about each of the cloud's refusals",
 };
 
 const posix = (p) => p.split(sep).join('/');
@@ -186,7 +204,8 @@ function inspect(root) {
 				: existsSync(join(root, 'bun.lock')) || existsSync(join(root, 'bun.lockb'))
 					? 'bun'
 					: (pkg?.packageManager?.split('@')[0] ?? 'npm');
-	return { root, pkgText, pkg, deps, configName, configText, srcDir, pm: lock, setUp: existsSync(join(root, 'caracms.config.ts')) };
+	const caracmsConfigText = read(join(root, 'caracms.config.ts'));
+	return { root, pkgText, pkg, deps, configName, configText, srcDir, pm: lock, setUp: caracmsConfigText !== null, caracmsConfigText };
 }
 
 function installedAstro(root) {
@@ -327,6 +346,219 @@ function listFiles(dir) {
 	return out;
 }
 
+// ── Where the site runs (caracms-cloud M5) ──────────────────────────────────────
+
+/** The config's `services` values, as the flags name them. */
+export const MODES = ['cloud', 'self-hosted'];
+/** Decision 5: a new site with no mode, no flag and no terminal to ask in. */
+export const NO_MODE_PROBLEM =
+	"Where will this site run? There's no terminal to ask in, so run init again with `--cloud` (CaraCMS Cloud) or `--self-hosted` (the site's own GitHub access, buckets and imgproxy).";
+export const BOTH_MODES_PROBLEM = '`--cloud` and `--self-hosted` are the two places a site runs: give one of them.';
+/** The CLAUDE.md block's and the report's line for the mode (Decision 8). */
+export const MODE_LINES = {
+	cloud: 'This site runs on CaraCMS Cloud: see the `caracms-hosting` skill.',
+	'self-hosted': 'This site is self-hosted (its own GitHub access, buckets and imgproxy): see the `caracms-hosting` skill.',
+	none: 'Mode not set: run `caracms init --cloud` or `--self-hosted`.',
+};
+
+/** The end of a string literal starting at `i` (its closing quote's index). */
+function stringEnd(text, i) {
+	const quote = text[i];
+	for (let j = i + 1; j < text.length; j++) {
+		if (text[j] === '\\') j++;
+		else if (text[j] === quote) return j;
+	}
+	return text.length;
+}
+
+/**
+ * The config's text with `services: '<mode>',` written (Decision 7): an existing `services`
+ * property of the `defineSite({` object literal set to the string, or the property inserted
+ * as the literal's first. `{ text }`, or `{ problem }` naming the line to add by hand when
+ * the argument isn't an object literal or `services` is set from something else.
+ * @returns {{ text?: string, problem?: string }}
+ */
+export function withServices(text, mode, file = 'caracms.config.ts') {
+	const line = `services: '${mode}',`;
+	const lineOf = (i) => text.slice(0, i).split('\n').length;
+	const byHand = (where) => ({
+		problem: `${file}: ${where}, so init can't write where the site runs. Add this line by hand, as the first inside \`defineSite({ … })\`, then run init again:\n      ${line}`,
+	});
+	const call = /\bdefineSite\s*\(\s*/.exec(text);
+	if (!call) return byHand("there's no `defineSite(…)` call in it");
+	const open = call.index + call[0].length;
+	if (text[open] !== '{') return byHand(`what line ${lineOf(call.index)} passes to defineSite isn't an object literal ({ … })`);
+	// The literal's top level: strings and comments skipped, brackets counted.
+	let depth = 0;
+	let found = -1;
+	for (let i = open; i < text.length; i++) {
+		const c = text[i];
+		if (c === '"' || c === "'" || c === '`') {
+			const end = stringEnd(text, i);
+			if (depth === 1 && text.slice(i + 1, end) === 'services' && /^\s*:/.test(text.slice(end + 1))) {
+				found = i;
+				break;
+			}
+			i = end;
+		} else if (c === '/' && text[i + 1] === '/') {
+			const end = text.indexOf('\n', i);
+			i = end === -1 ? text.length : end;
+		} else if (c === '/' && text[i + 1] === '*') {
+			const end = text.indexOf('*/', i + 2);
+			i = end === -1 ? text.length : end + 1;
+		} else if ('{[('.includes(c)) depth++;
+		else if ('}])'.includes(c)) {
+			if (--depth === 0) break;
+		} else if (depth === 1 && /[A-Za-z_$]/.test(c) && !/[\w$]/.test(text[i - 1] ?? '')) {
+			const word = /^[A-Za-z_$][\w$]*/.exec(text.slice(i))[0];
+			if (word === 'services' && /^\s*:/.test(text.slice(i + word.length))) {
+				found = i;
+				break;
+			}
+			i += word.length - 1;
+		}
+	}
+	if (found !== -1) {
+		const m = /^(['"]?services['"]?\s*:\s*)(?:(['"])[^'"\n]*\2)?/.exec(text.slice(found));
+		if (!m[2]) return byHand(`line ${lineOf(found)} sets services from something other than a string`);
+		return { text: `${text.slice(0, found)}${m[1]}'${mode}'${text.slice(found + m[0].length)}` };
+	}
+	const rest = text.slice(open + 1);
+	if (rest.startsWith('\n') || rest.startsWith('\r\n')) {
+		const indent = /\n([ \t]*)\S/.exec(rest)?.[1] ?? '\t';
+		return { text: `${text.slice(0, open + 1)}\n${indent}${line}${rest}` };
+	}
+	return { text: `${text.slice(0, open + 1)} ${line}${/^\s/.test(rest) ? '' : ' '}${rest}` };
+}
+
+/** The cloud's replaced variables, by group, for the move list (src/live/services.ts `REPLACED_VARIABLES`). */
+const REPLACED_GROUPS = [
+	['Images', OWN_MEDIA_NAMES],
+	['Video', ['MUX_TOKEN_ID', 'MUX_TOKEN_SECRET']],
+	['Forms and email', ['SUBMISSIONS_S3_BUCKET', 'SUBMISSIONS_S3_ACCESS_KEY_ID', 'SUBMISSIONS_S3_SECRET_ACCESS_KEY', 'RESEND_API_KEY', 'FORMS_FROM']],
+	['GitHub', ['CARACMS_GITHUB_TOKEN', 'GITHUB_APP_ID', 'GITHUB_APP_PRIVATE_KEY', 'GITHUB_REPO']],
+];
+
+/**
+ * A self-hosted site's signs in the repo (Decision 9): each replaced variable found in
+ * `.env` or `.railway/railway.ts` (name → where), and whether railway.ts declares buckets or imgproxy.
+ */
+export function selfHostedSigns(root) {
+	const railwayText = read(join(root, '.railway/railway.ts'));
+	const dotenv = parseDotenv(read(join(root, '.env')) ?? '');
+	const found = new Map();
+	for (const name of REPLACED_NAMES) {
+		if (dotenv[name]?.trim()) found.set(name, '.env');
+		else if (railwayText && new RegExp(`\\b${name}\\b`).test(railwayText)) found.set(name, '.railway/railway.ts');
+	}
+	const services = Boolean(railwayText && /\bbucket\s*\(|\bservice\(\s*["']imgproxy|ghcr\.io\/imgproxy/.test(railwayText));
+	return { found, railway: railwayText !== null, services, any: found.size > 0 || services };
+}
+
+/** The move to the cloud, in the Contracts' order, only the steps that apply, each with its check (Decision 9). */
+export function moveList(signs, { write }) {
+	const has = (names) => names.some((n) => signs.found.has(n));
+	const media = has(OWN_MEDIA_NAMES) || signs.services;
+	const video = has(['MUX_TOKEN_ID', 'MUX_TOKEN_SECRET']);
+	const steps = [];
+	const step = (id, text, check) => steps.push({ id, text, check });
+	step('setup', "Make the site and a key for it in app.caracms.com, and install the caracms GitHub App on this repo (only this one). Then open the site's page in app.caracms.com: the cloud refreshes the App's install state only when that page opens (or a repo is linked, or the site mints a token).", 'run `caracms init --cloud` again: it shows "App installed".');
+	step('push', `Commit and push \`services: 'cloud'\` in caracms.config.ts${write ? '' : ' (after `caracms init --cloud --write`)'}.`, 'the host\'s build fails with "CARACMS_CLOUD_KEY isn\'t set" until the key is on the host. That\'s expected: the old deployment keeps serving.');
+	if (media) step('images', "Copy the images into the site's cloud folder: `caracms media push`, with the old bucket's S3_* on its command line (or in .env) and the key in .env.", 'it reports failed: 0, and a second run skips everything.');
+	step('key', 'Set CARACMS_CLOUD_KEY on the host. Leave the old variables there for now: they\'re ignored.', "the deploy's logs list them as ignored; an editor signs in; an upload lands in the cloud.");
+	if (video) step('video', 'Upload each video clip again in the editor, and place it again.', 'no page plays a clip from the old Mux account.');
+	const marked = REPLACED_GROUPS.map(([group, names]) => `       ${group}: ${names.map((n) => (signs.found.has(n) ? `${n} (* ${signs.found.get(n)})` : n)).join(', ')}`);
+	step('remove', ['Remove every variable the cloud replaces from the host, one by one (* found in this repo):', ...marked].join('\n'), 'the next deploy logs no "ignored" lines.');
+	const n = Object.fromEntries(steps.map((s, i) => [s.id, i + 1]));
+	const after = ['key', 'video', 'remove'].filter((id) => n[id]).map((id) => n[id]);
+	step(
+		'retire',
+		`Once ${after.length > 1 ? `${after[0]}–${after[after.length - 1]}` : after[0]} hold, retire what the cloud replaced: imgproxy; the media bucket; the GitHub token or App on this repo; Resend. Keep the submissions bucket until its old submissions are exported or no longer wanted (the cloud doesn't copy them)${video ? `, and the old Mux account until step ${n.video} is done` : ''}.`,
+		null,
+	);
+	if (signs.railway) step('railway', 'Cut .railway/railway.ts down to the site and Redis: what `caracms init --cloud --railway` writes for a new site, keeping this site\'s names. init leaves the file alone: cut down any earlier, `railway config apply` would remove the buckets before the images are copied.', '`railway config plan` shows nothing to create or change.');
+	return [
+		"The move to CaraCMS Cloud, in order. init only sees this repo (.env and .railway/railway.ts): check the variables on the host's own page against the list in step " +
+			`${n.remove} too.`,
+		...steps.map((s, i) => `  ${i + 1}. ${s.text}${s.check ? `\n     Check: ${s.check}` : ''}`),
+	].join('\n');
+}
+
+/** The way back from the cloud (Decision 12; the README's leaving notes). */
+export const WAY_BACK = [
+	"Leaving CaraCMS Cloud: the site's services are its own again.",
+	"  1. Set them up as the caracms README's Hosting section says: GitHub access (a token or an App), a media bucket and imgproxy, a submissions bucket, Resend, and Mux for video.",
+	"  2. Copy the site's folder in CaraCMS Cloud's media bucket to the new media bucket: the keys in content (uploads/…) stay the same. There's no export command yet: ask CaraCMS for a copy of the folder.",
+	'  3. Set the variables on the host, deploy, and check the editor and an upload.',
+	'  4. Remove CARACMS_CLOUD_KEY from the host (it\'s ignored now), then revoke the key in app.caracms.com.',
+].join('\n');
+
+/** A variable from the environment, else the site's `.env` (as `media import` reads it). */
+function envOrDotenv(root, env) {
+	const dotenv = parseDotenv(read(join(root, '.env')) ?? '');
+	return (name) => {
+		const v = env[name]?.trim();
+		if (v) return { value: v, from: 'the environment' };
+		const d = dotenv[name]?.trim();
+		return d ? { value: d, from: '.env' } : null;
+	};
+}
+
+/**
+ * Decision 11: the key, when one can be found, checked against `GET /v1/settings`: the site,
+ * its team, its repo and whether the App is installed on it, or the cloud's own sentence.
+ * The key's value is never in what this returns.
+ */
+export async function keyCheck(root, { env = process.env, fetch: fetchImpl = fetch, timeoutMs = 10_000 } = {}) {
+	const get = envOrDotenv(root, env);
+	const key = get('CARACMS_CLOUD_KEY');
+	if (!key) return "CaraCMS Cloud key: none here (CARACMS_CLOUD_KEY in the environment or .env). Make one in app.caracms.com, a labelled key per laptop or environment, and put this laptop's in .env (never committed); then run `caracms init --cloud` again to check it.";
+	const url = (get('CARACMS_CLOUD_URL')?.value ?? DEFAULT_CLOUD_URL).replace(/\/+$/, '');
+	let res;
+	let answer;
+	try {
+		res = await fetchImpl(`${url}/v1/settings`, { headers: { authorization: `Bearer ${key.value}`, accept: 'application/json', 'user-agent': 'caracms' }, signal: AbortSignal.timeout(timeoutMs) });
+		answer = await res.json();
+	} catch {
+		return `CaraCMS Cloud key (from ${key.from}): CaraCMS Cloud couldn't be reached at ${url} to check it. Try again in a minute.`;
+	}
+	const obj = (v) => (v && typeof v === 'object' && !Array.isArray(v) ? v : {});
+	if (!res.ok) {
+		const message = typeof obj(answer).message === 'string' && obj(answer).message.trim() ? obj(answer).message.trim() : `the cloud answered ${res.status}.`;
+		return `CaraCMS Cloud key (from ${key.from}): refused. ${message}`;
+	}
+	const site = obj(obj(answer).site).name;
+	const team = obj(obj(answer).team).name;
+	const github = obj(obj(answer).github);
+	const repo = typeof github.repo === 'string' && github.repo ? github.repo : null;
+	const app = github.installed === true ? 'App installed' : github.installed === false ? "App not installed: install the caracms App on it from the site's page in app.caracms.com" : 'App not checked yet: the site\'s page in app.caracms.com checks it';
+	return [
+		`CaraCMS Cloud key (from ${key.from}):`,
+		`  Site: ${typeof site === 'string' && site ? site : '(not named)'}`,
+		`  Team: ${typeof team === 'string' && team ? team : '(this cloud doesn\'t say)'}`,
+		`  Repo: ${repo ? `${repo} (${app})` : "none linked yet: link it on the site's page in app.caracms.com"}`,
+	].join('\n');
+}
+
+/** Ask where the site runs (Decision 5), on a terminal. Null when there's no answer (the input closed). */
+export async function askMode({ input = process.stdin, output = process.stdout } = {}) {
+	const rl = createInterface({ input, output });
+	try {
+		for (;;) {
+			let answer;
+			try {
+				answer = (await rl.question('Where will this site run?\n  1. CaraCMS Cloud\n  2. Self-hosted (its own GitHub access, buckets and imgproxy)\nChoose 1 or 2: ')).trim().toLowerCase();
+			} catch {
+				return null;
+			}
+			if (answer === '1' || answer === 'cloud' || answer === 'caracms cloud') return 'cloud';
+			if (answer === '2' || answer === 'self-hosted' || answer === 'self hosted') return 'self-hosted';
+		}
+	} finally {
+		rl.close();
+	}
+}
+
 // ── The changes ─────────────────────────────────────────────────────────────────
 
 /**
@@ -334,7 +566,7 @@ function listFiles(dir) {
  * 'unlink' | 'schemas', file, before?, after?, target? }), notes (printed, nothing written),
  * and what's already done.
  */
-function changesOf(site, { railway = false } = {}) {
+function changesOf(site, { railway = false, mode = null, field = null } = {}) {
 	const { root } = site;
 	const changes = [];
 	const notes = [];
@@ -373,7 +605,11 @@ function changesOf(site, { railway = false } = {}) {
 		else notes.push(result.note);
 	}
 
-	add('caracms.config.ts', template('caracms.config.ts.txt'));
+	// The config: a new site's from the template, with where it runs (M5 Decision 7); a set-up site's
+	// field written when the mode is new or moves (plan() has checked withServices can).
+	if (!site.setUp) add('caracms.config.ts', mode ? withServices(template('caracms.config.ts.txt'), mode).text : template('caracms.config.ts.txt'));
+	else if (mode && mode !== field) edit('caracms.config.ts', site.caracmsConfigText, withServices(site.caracmsConfigText, mode).text);
+	else if (mode) done.push(`caracms.config.ts (services: '${mode}')`);
 	add('src/components/caracms/Page.astro', template('Page.astro.txt'));
 	add('src/components/caracms/TextBlock.astro', template('TextBlock.astro.txt'));
 	add(`${posix(site.srcDir)}/pages/[...path].astro`, template('catch-all.astro.txt'));
@@ -413,7 +649,8 @@ function changesOf(site, { railway = false } = {}) {
 		const repo = /github\.com[:/]([^/]+\/[^/]+?)(?:\.git)?\/?$/.exec(remote)?.[1] ?? null;
 		const repoName = basename(git(root, ['rev-parse', '--show-toplevel']).out.trim() || root);
 		const run = site.pm === 'npm' ? 'npm run' : site.pm;
-		const text = template('railway.ts.txt')
+		// M5 Decision 10: on the cloud, the site and Redis only.
+		const text = template(mode === 'cloud' ? 'railway-cloud.ts.txt' : 'railway.ts.txt')
 			.replaceAll('{{SITE}}', repoName)
 			.replaceAll('{{GITHUB_REPO}}', repo ?? 'OWNER/REPO')
 			.replaceAll('{{BUILD}}', `${run} build`)
@@ -422,7 +659,7 @@ function changesOf(site, { railway = false } = {}) {
 		if (!repo) notes.push(`${railwayFile}: the git remote isn't on GitHub, so GITHUB_REPO is "OWNER/REPO". Set it to the site's repository.`);
 	} else if (!read(join(root, railwayFile))?.includes('(written by `caracms init` from the')) {
 		// One init wrote is set up; a site's own (every Tina site has one) gets caracms's needs printed.
-		notes.push(railwayNeeds(railwayFile));
+		notes.push(railwayNeeds(railwayFile, mode));
 	} else done.push(railwayFile);
 
 	// Skills (Decision 12), linked from the installed package.
@@ -450,7 +687,7 @@ function changesOf(site, { railway = false } = {}) {
 		const link = lstat(join(root, 'CLAUDE.md'))?.isSymbolicLink() ? readlinkSync(join(root, 'CLAUDE.md')) : null;
 		const file = link ? posix(relative(root, resolve(root, link))) : 'CLAUDE.md';
 		const before = read(join(root, file));
-		const block = claudeBlock(skills);
+		const block = claudeBlock(skills, mode);
 		const after = withBlock(before, block);
 		if (after === null) notes.push(`${file} has a ${MARK_START} line with no ${MARK_END} after it, so init can't tell where its block ends and leaves the file alone. Replace the old block with this one by hand, then run init again:\n${block.split('\n').map((l) => `    ${l}`).join('\n')}`);
 		else edit(file, before, after, `${file} (the caracms block)`);
@@ -553,7 +790,15 @@ function astroConfigEdit(site) {
 	return { file, edit: out };
 }
 
-function railwayNeeds(file) {
+function railwayNeeds(file, mode = null) {
+	if (mode === 'cloud') {
+		return [
+			`${file} exists, so init doesn't edit it (every Tina site has one). On CaraCMS Cloud, the project needs only these:`,
+			'    Redis: the editor\'s drafts and sessions. The site gets REDIS_URL.',
+			'    The site: NODE_ENV=production, SITE_URL (its public address), start command `caracms start`, healthcheck /health; set by hand: CARACMS_CLOUD_KEY, CARACMS_SECRET, CARACMS_ALLOW, CARACMS_BACKUP_USER, CARACMS_BACKUP_PASSWORD, CARACMS_RAILWAY_TOKEN.',
+			'    The whole of it, as init writes it for a new cloud site: node_modules/caracms/bin/templates/railway-cloud.ts.txt.',
+		].join('\n');
+	}
 	return [
 		`${file} exists, so init doesn't edit it (every Tina site has one). Add what caracms needs to it by hand:`,
 		'    Redis: the editor\'s drafts and sessions. The site gets REDIS_URL.',
@@ -572,11 +817,17 @@ export function skillNames() {
 	return readdirSync(dir).filter((n) => !n.startsWith('.') && isDir(join(dir, n))).sort();
 }
 
-export function claudeBlock(skills) {
+/**
+ * @param {string[]} skills
+ * @param {string | null} [mode] the config's `services`; null: not set
+ */
+export function claudeBlock(skills, mode = null) {
 	const lines = [
 		MARK_START,
 		'## caracms',
 		'',
+		MODE_LINES[mode ?? 'none'],
+		'',
 		"This site's content is edited with caracms (the `caracms` package). Its skills are linked from the installed package into `.claude/skills/`, so they always match the installed version:",
 		'',
 		...skills.map((name) => `- \`${name}\`${SKILL_BLURBS[name] ? `: ${SKILL_BLURBS[name]}.` : ''}`),
@@ -651,7 +902,8 @@ function describe(change) {
 	}
 }
 
-function report({ changes, notes, done, hostVariables }, { write, pm }) {
+function report({ changes, notes, done, hostVariables, mode, where, site }, { write, pm }) {
+	const setUp = site.setUp;
 	const parts = [];
 	if (changes.length === 0) {
 		parts.push('caracms init: nothing to do. caracms is set up here.');
@@ -665,8 +917,12 @@ function report({ changes, notes, done, hostVariables }, { write, pm }) {
 	}
 	if (done.length && changes.length) parts.push(`Already done: ${done.join('; ')}.`);
 	if (notes.length) parts.push(`Notes:\n${notes.map((n) => `  - ${n}`).join('\n')}`);
-	if (hostVariables) parts.push(hostVariablesText());
-	if (changes.length) {
+	// M5: where the site runs, the key's check, and the move or the way back.
+	parts.push(...where);
+	if (hostVariables) parts.push(hostVariablesText(mode));
+	if (changes.length && setUp) {
+		parts.push(write ? 'Next: commit this as one change.' : 'Then, after --write: commit it as one change.');
+	} else if (changes.length) {
 		const install = `${pm} install`;
 		parts.push(
 			write
@@ -679,32 +935,68 @@ function report({ changes, notes, done, hostVariables }, { write, pm }) {
 
 // ── Schemas ─────────────────────────────────────────────────────────────────────
 
-/** The schema and `$schema` changes, from the site's config through its Vite. A fresh site's are the starting config's. */
+/**
+ * The schema and `$schema` changes, and the config's `services` (M5 Decision 7), from the
+ * site's config through its Vite, in one load. A fresh site's are the starting config's, and no field.
+ */
 async function schemaChanges(site) {
-	if (!site.setUp) return STARTING_SCHEMAS.map((file) => ({ kind: 'schemas', file, before: null, after: '', generated: true }));
+	if (!site.setUp) return { schemas: STARTING_SCHEMAS.map((file) => ({ kind: 'schemas', file, before: null, after: '', generated: true })), services: null };
 	const { withPackageModule } = await import('./site-runner.mjs');
 	return withPackageModule(site.root, 'schemas', async (m) => {
 		const loaded = await m.loadSite(site.root);
 		const files = m.schemaFileChanges(loaded).map((c) => ({ kind: 'schemas', file: c.file, before: c.before, after: c.text, generated: true }));
 		const stamps = (await m.stampChanges(loaded)).map((c) => ({ kind: 'schemas', file: c.file, before: c.before, after: c.text }));
-		return [...files, ...stamps];
+		return { schemas: [...files, ...stamps], services: loaded.services ?? null };
 	});
 }
 
 // ── The command ─────────────────────────────────────────────────────────────────
 
-/** The plan: problems (nothing happens when there are any), or the changes. */
-export async function plan(root, { write = false, railway = false } = {}) {
+/**
+ * The plan: problems (nothing happens when there are any), or the changes. `mode` is the
+ * flag's (`'cloud'`, `'self-hosted'`, `'both'` for both flags, or null); `choose()` asks a
+ * person where the site runs, only called with no flag and no field (Decision 5).
+ * @param {string} root
+ * @param {{ write?: boolean, railway?: boolean, mode?: string | null, choose?: (() => Promise<string | null>) | null }} [options]
+ */
+export async function plan(root, { write = false, railway = false, mode: flag = null, choose = null } = {}) {
 	const site = inspect(root);
+	/** @param {string[]} problems */
+	const nothing = (problems) => ({ site, problems, changes: /** @type {any[]} */ ([]), notes: /** @type {string[]} */ ([]), done: /** @type {string[]} */ ([]), hostVariables: false, mode: null, field: null, where: /** @type {string[]} */ ([]), checkKey: false });
 	const problems = problemsOf(site, write);
-	if (problems.length) return { site, problems, changes: [], notes: [], done: [], hostVariables: false };
-	const { changes, notes, done, hostVariables } = changesOf(site, { railway });
+	if (flag === 'both') problems.push(BOTH_MODES_PROBLEM);
+	if (problems.length) return nothing(problems);
+	let loaded;
 	try {
-		changes.push(...(await schemaChanges(site)));
+		loaded = await schemaChanges(site);
 	} catch (error) {
-		return { site, problems: [`The schemas couldn't be made from caracms.config.ts: ${error.message}`], changes: [], notes: [], done: [], hostVariables: false };
+		return nothing([`The schemas couldn't be made from caracms.config.ts: ${error.message}`]);
+	}
+	// M5 Decisions 5–6: the flag, else the field, else a person's answer.
+	const field = loaded.services;
+	let mode = flag ?? field;
+	let asked = false;
+	if (!mode && choose) {
+		mode = await choose();
+		asked = Boolean(mode);
+	}
+	if (!mode && !site.setUp) return nothing([NO_MODE_PROBLEM]);
+	if (mode && mode !== field && site.setUp) {
+		const edited = withServices(site.caracmsConfigText, mode);
+		if (edited.problem) return nothing([edited.problem]);
+	}
+	const { changes, notes, done, hostVariables } = changesOf(site, { railway, mode, field });
+	changes.push(...loaded.schemas);
+
+	const where = [MODE_LINES[mode ?? 'none']];
+	// Decision 9: --cloud on a self-hosted site (or one with no field) with self-hosted signs is the move.
+	if (mode === 'cloud' && field !== 'cloud') {
+		const signs = selfHostedSigns(root);
+		if (signs.any) where.push(moveList(signs, { write }));
 	}
-	return { site, problems, changes, notes, done, hostVariables };
+	// Decision 12: --self-hosted on a cloud site, the way back.
+	if (mode === 'self-hosted' && field === 'cloud') where.push(WAY_BACK);
+	return { site, problems, changes, notes, done, hostVariables, mode, field, where, checkKey: mode === 'cloud' && (flag === 'cloud' || asked) };
 }
 
 function apply(root, changes) {
@@ -730,11 +1022,15 @@ function apply(root, changes) {
 }
 
 /**
- * `caracms init [--write] [--railway]`, from `root`. Returns the exit code; prints to `out` and `err` (stdout and stderr).
- * @param {{ root: string, write?: boolean, railway?: boolean, out?: { write(text: string): unknown }, err?: { write(text: string): unknown } }} options
+ * `caracms init [--write] [--railway] [--cloud | --self-hosted]`, from `root`. Returns the exit code; prints to `out` and `err` (stdout and stderr).
+ * `cloud` and `selfHosted` are the flags. `ask` is how a person is asked where the site runs: by default only when stdin and stdout
+ * are both a terminal (Decision 5), never otherwise. `env` and `fetch` are the key check's (Decision 11).
+ * @param {{ root: string, write?: boolean, railway?: boolean, cloud?: boolean, selfHosted?: boolean, ask?: (() => Promise<string | null>) | null, env?: Record<string, string | undefined>, fetch?: typeof fetch, out?: { write(text: string): unknown }, err?: { write(text: string): unknown } }} options
  */
-export async function run({ root, write = false, railway = false, out = process.stdout, err = process.stderr }) {
-	const p = await plan(root, { write, railway });
+export async function run({ root, write = false, railway = false, cloud = false, selfHosted = false, ask, env = process.env, fetch: fetchImpl = fetch, out = process.stdout, err = process.stderr }) {
+	const flag = cloud && selfHosted ? 'both' : cloud ? 'cloud' : selfHosted ? 'self-hosted' : null;
+	const choose = ask !== undefined ? ask : process.stdin.isTTY && process.stdout.isTTY ? () => askMode() : null;
+	const p = await plan(root, { write, railway, mode: flag, choose });
 	if (p.problems.length) {
 		err.write(`caracms init: ${p.problems.length === 1 ? 'one thing is' : `${p.problems.length} things are`} in the way, so nothing was ${write ? 'written' : 'planned'}:\n${p.problems.map((x) => `  - ${x}`).join('\n')}\n`);
 		return 1;
@@ -751,6 +1047,8 @@ export async function run({ root, write = false, railway = false, out = process.
 			}
 		}
 	}
+	// Decision 11: the key, checked after anything is written (it reads only), never printed.
+	if (p.checkKey) p.where.splice(1, 0, await keyCheck(root, { env, fetch: fetchImpl }));
 	out.write(report(p, { write, pm: p.site.pm }));
 	return 0;
 }

package/bin/media.mjs

@@ -41,7 +41,7 @@
 // `upload_limit` stops the run there, with its sentence), 2 for bad usage.
 
 import { createHash, createHmac } from 'node:crypto';
-import { readFileSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
 import { basename, join, resolve } from 'node:path';
 
@@ -510,16 +510,57 @@ export function readS3Env(env, cwd) {
 
 const listed = (names) => (names.length <= 1 ? names.join('') : `${names.slice(0, -1).join(', ')} and ${names[names.length - 1]}`);
 
+/** Every variable the cloud key replaces, in the Contracts' order (src/live/services.ts `REPLACED_VARIABLES`; a test keeps the two equal). */
+export const REPLACED_NAMES = [
+	...OWN_MEDIA_NAMES,
+	'MUX_TOKEN_ID',
+	'MUX_TOKEN_SECRET',
+	'SUBMISSIONS_S3_BUCKET',
+	'SUBMISSIONS_S3_ACCESS_KEY_ID',
+	'SUBMISSIONS_S3_SECRET_ACCESS_KEY',
+	'RESEND_API_KEY',
+	'FORMS_FROM',
+	'CARACMS_GITHUB_TOKEN',
+	'GITHUB_APP_ID',
+	'GITHUB_APP_PRIVATE_KEY',
+	'GITHUB_REPO',
+];
+
+/** Decision 4's sentence (src/live/services.ts `CLOUD_KEY_MISSING_PROBLEM`). */
+export const CLOUD_KEY_MISSING = "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.";
+
 /**
  * The cloud key and address, as the `S3_*` are read, or null without a key; `own` names the
  * site's own media variables also set (the running site's "not both", src/media.ts).
+ * With the config's `services` (caracms-cloud M5 Decision 2) the other mode's variables are
+ * ignored instead, each named once in `ignored`: on `'cloud'` `own` is always empty, on
+ * `'self-hosted'` the key is never read and this is null.
  */
-export function readCloudEnv(env, cwd) {
+export function readCloudEnv(env, cwd, services = null) {
 	const get = envReader(env, cwd);
-	const key = get('CARACMS_CLOUD_KEY').trim();
+	const key = services === 'self-hosted' ? '' : get('CARACMS_CLOUD_KEY').trim();
 	if (!key) return null;
 	const url = (get('CARACMS_CLOUD_URL').trim() || DEFAULT_CLOUD_URL).replace(/\/+$/, '');
-	return { key, url, own: OWN_MEDIA_NAMES.filter((name) => get(name)) };
+	if (services === 'cloud') return { key, url, own: [], ignored: REPLACED_NAMES.filter((name) => get(name)) };
+	return { key, url, own: OWN_MEDIA_NAMES.filter((name) => get(name)), ignored: [] };
+}
+
+/** The line naming what a cloud or self-hosted site ignores: src/live/services.ts `ignoredMessage` without a group, word for word (a test keeps the two equal; this file can't import the TypeScript). */
+export function ignoredLine(names, services) {
+	const one = names.length === 1;
+	const where = services === 'self-hosted' ? 'this site is self-hosted' : 'this site runs on CaraCMS Cloud';
+	const tail = services === 'self-hosted' ? `Remove ${one ? 'it' : 'them'}, or run \`caracms init --cloud\` to move the site to CaraCMS Cloud.` : `Remove ${one ? 'it' : 'them'} once the move is done.`;
+	return `${listed(names)} ${one ? 'is' : 'are'} set, but ${where} (caracms.config.ts): ${one ? "it's" : "they're"} ignored. ${tail}`;
+}
+
+/** The config file names, in the order they're looked for (src/cli/site.ts `CONFIG_FILES`). */
+const CONFIG_FILES = ['ts', 'mts', 'mjs', 'js'].map((ext) => `caracms.config.${ext}`);
+
+/** The config's `services` (caracms-cloud M5 Decision 1), through the site's own Vite; null without a config. */
+export async function readServices(cwd) {
+	if (!CONFIG_FILES.some((name) => existsSync(join(cwd, name)))) return null;
+	const { withPackageModule } = await import('./site-runner.mjs');
+	return withPackageModule(cwd, 'site', async (m) => (await m.loadSite(cwd)).services);
 }
 
 export const bothMessage = (names) => `Set CARACMS_CLOUD_KEY or the site's own media variables, not both: remove ${listed(names)}.`;
@@ -717,8 +758,21 @@ export async function run(argv, io = {}) {
 		return 2;
 	}
 
-	// The cloud key, when it's set, is the one credential (caracms-cloud M3 Decisions 6 and 19).
-	const cloud = readCloudEnv(env, cwd);
+	// caracms-cloud M5: the config's `services` decides; without one, the key does (M3 Decisions 6 and 19).
+	let services;
+	try {
+		services = io.services !== undefined ? io.services : await readServices(cwd);
+	} catch (error) {
+		say(`The site's caracms.config.ts couldn't be read, so it isn't known whether the images go to CaraCMS Cloud: ${error.message}`);
+		return 1;
+	}
+	const cloud = readCloudEnv(env, cwd, services);
+	if (services === 'cloud' && !cloud) {
+		say(CLOUD_KEY_MISSING);
+		return 1;
+	}
+	if (services === 'self-hosted' && envReader(env, cwd)('CARACMS_CLOUD_KEY').trim()) say(ignoredLine(['CARACMS_CLOUD_KEY'], services));
+	if (cloud?.ignored.length) say(ignoredLine(cloud.ignored, services));
 	if (cloud && cloud.own.length > 0) {
 		say(bothMessage(cloud.own));
 		return 1;