caracms 0.2.0 → 0.3.0

package/bin/gate.mjs

@@ -4,6 +4,10 @@
 // with no flags, so nothing here may import the package's TypeScript.
 //
 // Its order, per request:
+//   0. The visitor's IP, from the one source `CARACMS_CLIENT_IP_HEADER` names (or the
+//      host's default), set as `x-caracms-client-ip` on every request, replacing any
+//      copy the request brought (runs-anywhere spec, Decision 8 and Contracts). The
+//      header is trusted only in a process `caracms start` marked (`GATED_MARK`).
 //   1. `/robots.txt` is answered here, before the password.
 //   2. The pre-launch password (`CARACMS_PRELAUNCH`), except for the editor and its
 //      API, `/_astro/…` and `/health`.
@@ -11,6 +15,10 @@
 //   4. The adapter's own handler (static files first, then Astro).
 
 import { createHash, timingSafeEqual } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { isIP } from 'node:net';
+import { join } from 'node:path';
+import { CLOUDFLARE_IPV4, CLOUDFLARE_IPV6 } from './cloudflare-ips.mjs';
 
 /** The header the gate owns. */
 const ROBOTS_HEADER = 'X-Robots-Tag';
@@ -123,6 +131,60 @@ export function parsePrelaunch(raw) {
 	return { user: value.slice(0, colon) };
 }
 
+/**
+ * The file the build writes beside the server's entry (`BUILD_INFO_FILE` in the package's
+ * src/index, runs-anywhere Decisions 7 and 9): `{ "site": "https://…" | null, "commit": … }`,
+ * `site` being Astro's `site` as built. Read by path, since this file imports only built-ins.
+ */
+export const BUILD_INFO_FILE = 'caracms-build.json';
+
+/**
+ * `dist/server/caracms-build.json` under `root`, or null when it's missing, unreadable or
+ * not an object (a site built before the file existed): the address chain then starts at
+ * `SITE_URL`.
+ * @returns {{ site: string | null, commit: string | null } | null}
+ */
+export function readBuildInfo(root) {
+	let info;
+	try {
+		info = JSON.parse(readFileSync(join(root, 'dist/server', BUILD_INFO_FILE), 'utf8'));
+	} catch {
+		return null;
+	}
+	if (!info || typeof info !== 'object' || Array.isArray(info)) return null;
+	const text = (v) => (typeof v === 'string' && v.trim() !== '' ? v.trim() : null);
+	return { site: text(info.site), commit: text(info.commit) };
+}
+
+/**
+ * The site's public address at run time, by Decision 7's whole chain: Astro's `site` as
+ * built (from `caracms-build.json`: the config's `site`, else `SITE_URL` at build), then
+ * `SITE_URL`, then Railway's `RAILWAY_PUBLIC_DOMAIN`. The same order as `addressFrom()` in
+ * the package's src/live/mode, which takes the built `site` through a define instead. A
+ * built `site` that isn't an http(s) URL is passed over, as `addressFrom()` does.
+ * @param {{ site?: string | null } | null} [built] what `readBuildInfo()` read
+ * @returns {{ value: string, from: "Astro's site" | 'SITE_URL' | 'RAILWAY_PUBLIC_DOMAIN' } | null}
+ */
+export function publicAddress(env = process.env, built = null) {
+	const astroSite = typeof built?.site === 'string' ? built.site.trim() : '';
+	if (astroSite && parseSiteUrl(astroSite)) return { value: astroSite, from: "Astro's site" };
+	const siteUrl = typeof env.SITE_URL === 'string' ? env.SITE_URL.trim() : '';
+	if (siteUrl) return { value: siteUrl, from: 'SITE_URL' };
+	const railway = typeof env.RAILWAY_PUBLIC_DOMAIN === 'string' ? env.RAILWAY_PUBLIC_DOMAIN.trim() : '';
+	if (railway) return { value: `https://${railway}`, from: 'RAILWAY_PUBLIC_DOMAIN' };
+	return null;
+}
+
+/** Hosts' own addresses, never indexable whatever `SITE_URL` says (Decision 13): the domain itself or any name under it. */
+const PLATFORM_DOMAINS = ['localhost', 'up.railway.app', 'onrender.com', 'fly.dev'];
+
+/** True for a hostname a search engine should never index: localhost, a host's platform address, or a bare IP. */
+export function isNeverIndexableHostname(hostname) {
+	const name = String(hostname).toLowerCase().replace(/\.+$/, '');
+	if (name === '' || isIP(name.replace(/^\[|\]$/g, '')) !== 0) return true;
+	return PLATFORM_DOMAINS.some((domain) => name === domain || name.endsWith('.' + domain));
+}
+
 /** `SITE_URL`'s host and origin, or null when it's unset or not an http(s) URL. */
 export function parseSiteUrl(value) {
 	if (typeof value !== 'string' || value.trim() === '') return null;
@@ -133,19 +195,222 @@ export function parseSiteUrl(value) {
 		return null;
 	}
 	if (url.protocol !== 'https:' && url.protocol !== 'http:') return null;
-	const hostname = url.hostname.toLowerCase();
-	const indexable = hostname !== 'localhost' && !hostname.endsWith('.localhost') && !hostname.endsWith('.up.railway.app');
+	const indexable = !isNeverIndexableHostname(url.hostname);
 	return { host: url.host.toLowerCase(), origin: url.origin, indexable };
 }
 
+// ── The visitor's IP (Decision 8) ───────────────────────────────────────────────
+
+/** The header the gate sets on every request; `clientIp()` (src/live/auth/request.ts) reads only this in production. */
+export const CLIENT_IP_HEADER = 'x-caracms-client-ip';
+
+/**
+ * The mark that says this process is behind the gate: `globalThis[Symbol.for('caracms.gated')] === true`.
+ * `caracms start` sets it (`markProcessGated()`) before it imports the built site, which
+ * runs in this same process, and `clientIp()` (src/live/auth/request.ts, `GATED_MARK`)
+ * trusts `x-caracms-client-ip` in production only when it's there. Without it, a server
+ * started some other way (`node dist/server/entry.mjs`) has nothing replacing the header,
+ * so a visitor could send their own copy and pick their IP for the limits; with the mark
+ * off, that server answers 503 instead, whatever the request carries. A request can't set
+ * it: it lives in the process, not on the wire.
+ */
+export const GATED_MARK = Symbol.for('caracms.gated');
+
+/** Marks this process as gated. Only `caracms start` calls it, and only once the adapter's own server is off, so every request reaches the site through the gate. */
+export function markProcessGated() {
+	globalThis[GATED_MARK] = true;
+}
+
+/** The exact fix, printed when no source is known or the one set isn't allowed. `caracms init` and the hosting docs print the same. */
+export const CLIENT_IP_FIX =
+	'Set CARACMS_CLIENT_IP_HEADER to the header your proxy sets: x-real-ip for nginx with `proxy_set_header X-Real-IP $remote_addr`, x-forwarded-for for Caddy, or socket if nothing sits in front of this server.';
+
+/**
+ * Where the IP may come from. `socket`: the connection's own address. `x-forwarded-for`:
+ * its last entry, the one the nearest proxy added. Any other: a header the nearest proxy
+ * sets and overwrites. (Render documents no such header, so it has none here.)
+ */
+export const CLIENT_IP_SOURCES = ['socket', 'x-forwarded-for', 'x-real-ip', 'fly-client-ip', 'cf-connecting-ip'];
+
+/**
+ * Hosts detected from a variable they set, with their default source.
+ * - Railway: its edge overwrites X-Real-IP (relied on since M4).
+ * - Fly: its proxy sets Fly-Client-IP (docs.fly.io/networking/request-headers) and
+ *   replaces a forged one (checked against debug.fly.dev, 2026-10-24). Its
+ *   X-Forwarded-For can't be used: Fly's docs say the last entry is the app's own address.
+ * - Render: no overwritten header is documented, so the spec's fallback: X-Forwarded-For's last entry.
+ */
+export const HOST_DEFAULTS = [
+	{ variable: 'RAILWAY_ENVIRONMENT_ID', host: 'Railway', source: 'x-real-ip' },
+	{ variable: 'FLY_APP_NAME', host: 'Fly', source: 'fly-client-ip' },
+	{ variable: 'RENDER', host: 'Render', source: 'x-forwarded-for' },
+];
+
+const isSet = (value) => typeof value === 'string' && value.trim() !== '';
+
+/**
+ * Reads `CARACMS_CLIENT_IP_HEADER`, or the detected host's default. A set value always
+ * wins. `problem` is the sentence `caracms start` exits with.
+ * @returns {{ source: string, from: string, problem: null } | { source: null, from: null, problem: string }}
+ */
+export function readClientIpSource(env = process.env) {
+	const raw = env.CARACMS_CLIENT_IP_HEADER;
+	if (raw !== undefined && raw.trim() !== '') {
+		const source = raw.trim().toLowerCase();
+		if (!CLIENT_IP_SOURCES.includes(source)) {
+			return { source: null, from: null, problem: `CARACMS_CLIENT_IP_HEADER is "${raw.trim()}", which isn't one caracms can use. ${CLIENT_IP_FIX}` };
+		}
+		return { source, from: 'CARACMS_CLIENT_IP_HEADER', problem: null };
+	}
+	const detected = HOST_DEFAULTS.find((h) => isSet(env[h.variable]));
+	if (detected) return { source: detected.source, from: `${detected.host}'s default, from ${detected.variable}`, problem: null };
+	return { source: null, from: null, problem: `no host was detected, so caracms can't tell where a visitor's IP comes from. ${CLIENT_IP_FIX}` };
+}
+
+/** The line `caracms start` prints. */
+export function describeClientIpSource({ source, from }) {
+	const where = source === 'socket' ? 'the socket' : source === 'x-forwarded-for' ? "X-Forwarded-For's last entry" : headerName(source);
+	return source === 'cf-connecting-ip' ? `${where} (${from})` : `${where} (${from}); CF-Connecting-IP when that address is Cloudflare's, on the site's own domain`;
+}
+
+const headerName = (lower) => lower.replace(/(^|-)([a-z])/g, (_, dash, c) => dash + c.toUpperCase()).replace(/\bIp\b/, 'IP').replace(/^Cf-/, 'CF-');
+
+/** An address in canonical form (IPv4-mapped IPv6 as IPv4, IPv6 lowercased), or null when it isn't one. Brackets and an IPv4 port are dropped. */
+export function normaliseIp(value) {
+	if (typeof value !== 'string') return null;
+	let text = value.trim();
+	const bracketed = /^\[([^\]]+)\](?::\d+)?$/.exec(text);
+	if (bracketed) text = bracketed[1];
+	else if (/^\d{1,3}(\.\d{1,3}){3}:\d+$/.test(text)) text = text.slice(0, text.lastIndexOf(':'));
+	const mapped = /^::ffff:(\d{1,3}(?:\.\d{1,3}){3})$/i.exec(text);
+	if (mapped) text = mapped[1];
+	const kind = isIP(text);
+	if (kind === 4) return text;
+	if (kind === 6) return text.toLowerCase();
+	return null;
+}
+
+function ipv4ToInt(ip) {
+	return ip.split('.').reduce((n, part) => n * 256 + Number(part), 0);
+}
+
+function ipv6ToBigInt(ip) {
+	let text = ip;
+	// A trailing dotted quad (`::1.2.3.4`) as two groups.
+	const quad = /(\d{1,3}(?:\.\d{1,3}){3})$/.exec(text);
+	if (quad) {
+		const n = ipv4ToInt(quad[1]);
+		text = text.slice(0, -quad[1].length) + ((n >>> 16) & 0xffff).toString(16) + ':' + (n & 0xffff).toString(16);
+	}
+	const [head, tail] = text.split('::');
+	const headParts = head ? head.split(':') : [];
+	const tailParts = tail === undefined ? [] : tail ? tail.split(':') : [];
+	const groups = tail === undefined ? headParts : [...headParts, ...Array(8 - headParts.length - tailParts.length).fill('0'), ...tailParts];
+	return groups.reduce((n, g) => (n << 16n) + BigInt(parseInt(g, 16)), 0n);
+}
+
+const V4_RANGES = CLOUDFLARE_IPV4.map((cidr) => {
+	const [base, bits] = cidr.split('/');
+	const size = 2 ** (32 - Number(bits));
+	const start = Math.floor(ipv4ToInt(base) / size) * size;
+	return [start, start + size];
+});
+const V6_RANGES = CLOUDFLARE_IPV6.map((cidr) => {
+	const [base, bits] = cidr.split('/');
+	const shift = BigInt(128 - Number(bits));
+	return [ipv6ToBigInt(base) >> shift, shift];
+});
+
+/** True when a normalised address is in Cloudflare's published ranges (cloudflare-ips.mjs). */
+export function isCloudflareIp(ip) {
+	const kind = isIP(ip);
+	if (kind === 4) {
+		const n = ipv4ToInt(ip);
+		return V4_RANGES.some(([start, end]) => n >= start && n < end);
+	}
+	if (kind === 6) {
+		const n = ipv6ToBigInt(ip);
+		return V6_RANGES.some(([prefix, shift]) => n >> shift === prefix);
+	}
+	return false;
+}
+
+/** The last comma-separated entry of a header (Node joins repeated lines with ", "), normalised. */
+function lastEntry(value) {
+	if (Array.isArray(value)) value = value.join(',');
+	if (typeof value !== 'string') return null;
+	const entries = value.split(',');
+	return normaliseIp(entries[entries.length - 1]);
+}
+
+/**
+ * True when the request's Host is a host's own address (Decision 13's list: localhost,
+ * `*.up.railway.app`, `*.onrender.com`, `*.fly.dev`, a bare IP), or missing or unreadable.
+ */
+export function isPlatformHost(host) {
+	if (typeof host !== 'string' || host.trim() === '') return true;
+	let hostname;
+	try {
+		hostname = new URL(`http://${host.trim()}`).hostname;
+	} catch {
+		return true;
+	}
+	return isNeverIndexableHostname(hostname);
+}
+
+/**
+ * The visitor's IP for one request: from `source`; then, when that address is
+ * Cloudflare's and the request's Host isn't a host's own address, from CF-Connecting-IP
+ * (kept as the Cloudflare address if that's missing or not an address). `missing` is
+ * true when the source header was missing or held no address, so the socket's address
+ * was used instead.
+ *
+ * Why the Host matters: a Cloudflare Worker's fetch to an origin outside Cloudflare
+ * leaves from Cloudflare's ranges and may set CF-Connecting-IP to anything
+ * (developers.cloudflare.com/fundamentals/reference/http-headers/). So anyone's Worker
+ * calling `x.up.railway.app` or `x.fly.dev` directly arrives with a Cloudflare address in
+ * the host's header and a CF-Connecting-IP of its choosing. A site behind Cloudflare's
+ * proxy is reached at its own domain, where the request passes through the site's zone
+ * and Cloudflare sets CF-Connecting-IP itself, a Worker's fetch included. On a host's own
+ * address the Cloudflare address is kept: those requests share one bucket, which is
+ * what a Worker hammering it deserves.
+ * @param {{ headers: Record<string, string | string[] | undefined>, socket?: { remoteAddress?: string } }} req
+ */
+export function resolveClientIp(req, source) {
+	const socketIp = normaliseIp(req.socket?.remoteAddress) ?? 'unknown';
+	let ip = source === 'socket' ? socketIp : lastEntry(req.headers[source]);
+	const missing = ip === null;
+	if (missing) ip = socketIp;
+	if (source !== 'cf-connecting-ip' && isCloudflareIp(ip) && !isPlatformHost(req.headers.host)) {
+		const viaCloudflare = lastEntry(req.headers['cf-connecting-ip']);
+		if (viaCloudflare) ip = viaCloudflare;
+	}
+	return { ip, missing };
+}
+
+/** Puts the IP on the request as the only `x-caracms-client-ip`, in `headers` and `rawHeaders` alike. */
+function setClientIp(req, ip) {
+	req.headers[CLIENT_IP_HEADER] = ip;
+	const raw = req.rawHeaders;
+	if (Array.isArray(raw)) {
+		const kept = [];
+		for (let i = 0; i < raw.length; i += 2) if (String(raw[i]).toLowerCase() !== CLIENT_IP_HEADER) kept.push(raw[i], raw[i + 1]);
+		kept.push(CLIENT_IP_HEADER, ip);
+		raw.splice(0, raw.length, ...kept);
+	}
+}
+
 const sha256 = (buf) => createHash('sha256').update(buf).digest();
 
 /**
  * The gate, as `(req, res) => void` around the adapter's `handler`.
  * @param {{ handler: (req: import('node:http').IncomingMessage, res: import('node:http').ServerResponse) => unknown,
- *   siteUrl?: string, prelaunch?: string, brandName?: string }} options
+ *   clientIpSource: string, siteUrl?: string, prelaunch?: string, brandName?: string,
+ *   log?: (line: string) => void }} options
  */
-export function createGate({ handler, siteUrl, prelaunch, brandName }) {
+export function createGate({ handler, clientIpSource, siteUrl, prelaunch, brandName, log = (line) => console.error(line) }) {
+	if (!CLIENT_IP_SOURCES.includes(clientIpSource)) throw new Error(`createGate: clientIpSource must be one of ${CLIENT_IP_SOURCES.join(', ')}.`);
+	let warnedMissing = false;
 	const site = parseSiteUrl(siteUrl);
 	const password = parsePrelaunch(prelaunch) ? sha256(Buffer.from(trimPrelaunch(prelaunch), 'utf8')) : null;
 	const realm = `${cleanRealmName(brandName) || NEUTRAL_REALM_NAME} (not launched yet)`;
@@ -170,6 +435,14 @@ export function createGate({ handler, siteUrl, prelaunch, brandName }) {
 	};
 
 	const gate = (req, res) => {
+		// 0. The visitor's IP, before anything can answer.
+		const { ip, missing } = resolveClientIp(req, clientIpSource);
+		setClientIp(req, ip);
+		if (missing && !warnedMissing) {
+			warnedMissing = true;
+			log(`caracms start: a request came without ${headerName(clientIpSource)}, so its socket's address was used. If every request says so, CARACMS_CLIENT_IP_HEADER doesn't match the proxy in front. (Said once.)`);
+		}
+
 		const views = pathViews(req.url);
 		const indexable = isIndexableHost(req);
 

package/bin/init.mjs

@@ -1,5 +1,5 @@
-// `caracms init [--write]` (M8 Decisions 7–13): add caracms's plumbing to an existing
-// Astro site, and nothing about its design.
+// `caracms init [--write] [--railway]` (M8 Decisions 7–13): 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`).
@@ -8,6 +8,10 @@
 //   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
 //   `.railway/railway.ts`) gets the lines to add printed instead, and is left alone.
+// - `.railway/railway.ts` and the `railway` dependency come only with `--railway`, or are
+//   left as they are on a site that already has the file (runs-anywhere Decision 12).
+//   Otherwise init writes no host file and prints the variables any host needs
+//   (HOST_VARIABLES), on the dry run and on `--write`.
 // - Run again, it re-links the skills, refreshes the CLAUDE.md block and the schemas, and
 //   reports the rest as already done.
 //
@@ -25,6 +29,41 @@ const templates = fileURLToPath(new URL('./templates/', import.meta.url));
 const template = (name) => readFileSync(join(templates, name), 'utf8');
 const ownPackage = JSON.parse(readFileSync(join(packageRoot, 'package.json'), 'utf8'));
 
+/**
+ * The variables any host needs (runs-anywhere Decision 12): the one list, printed by init
+ * without `--railway`. The package README's Hosting section matches it. Names as
+ * `src/live/mode.ts` reads them, and the gate's `CARACMS_CLIENT_IP_HEADER`.
+ */
+export const HOST_VARIABLES = [
+	{ name: 'GITHUB_REPO', need: 'required', what: "The site's repository, as owner/name." },
+	{ name: 'CARACMS_GITHUB_TOKEN', need: 'required, or the App', what: 'A fine-grained token (github_pat_…) on that one repo: Contents read and write, Metadata read (Deployments read is optional). Never GITHUB_TOKEN.' },
+	{ name: 'GITHUB_APP_ID', need: 'instead of the token', what: "The GitHub App's ID, for anyone setting up many sites. Set the token or the App, not both." },
+	{ name: 'GITHUB_APP_PRIVATE_KEY', need: 'with GITHUB_APP_ID', what: "The App's private key." },
+	{ name: 'SITE_URL', need: 'required', what: "The site's public address, https://. The same value at build and at run time." },
+	{ name: 'REDIS_URL', need: 'required', what: "The editor's drafts and sessions: redis:// or rediss:// (Upstash works, in the site's region)." },
+	{ name: 'CARACMS_SECRET', need: 'required', what: "Signs the editors' sessions. A long random string." },
+	{ name: 'CARACMS_CLIENT_IP_HEADER', need: 'required off Railway, Fly and Render', what: "Where the visitor's IP comes from: x-real-ip for nginx with `proxy_set_header X-Real-IP $remote_addr`, x-forwarded-for for Caddy, or socket if nothing sits in front of this server. `caracms start` won't start without it." },
+	{ name: 'CARACMS_ALLOW', need: 'for email sign-in', what: 'Who may sign in, comma-separated: addresses (aoife@fernhill.ie) or whole domains (@fernhill.ie). The client adds their own people in Site Settings.' },
+	{ name: 'RESEND_API_KEY', need: 'for email sign-in', what: 'Sends the sign-in links (and form notifications) through Resend.' },
+	{ name: 'FORMS_FROM', need: 'for email sign-in', what: 'The address those emails come from, on a domain verified in Resend.' },
+	{ name: 'CARACMS_BACKUP_USER', need: 'for the backup sign-in', what: "The backup sign-in, for when email sign-in links can't arrive. Both or neither." },
+	{ name: 'CARACMS_BACKUP_PASSWORD', need: 'for the backup sign-in', what: "The backup sign-in's password." },
+	{ name: 'CARACMS_RUNNING_COMMIT', need: 'optional', what: "The commit this server runs, where the host doesn't say (Railway and Render do)." },
+	{ name: 'CARACMS_DEPLOY_HOOK_URL', need: 'optional', what: "Try again on a publish POSTs here to redeploy the site (the host's deploy hook)." },
+	{ 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];
+	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.",
+		...rows.map((r) => `  ${r.name.padEnd(w1)}  ${r.need.padEnd(w2)}  ${r.what}`),
+	].join('\n');
+}
+
 /** What init adds to a site's package.json (Decisions 7 and 11). */
 export const VERSIONS = { node: '^11.1.7', railway: '^3.16.0' };
 
@@ -295,7 +334,7 @@ function listFiles(dir) {
  * 'unlink' | 'schemas', file, before?, after?, target? }), notes (printed, nothing written),
  * and what's already done.
  */
-function changesOf(site) {
+function changesOf(site, { railway = false } = {}) {
 	const { root } = site;
 	const changes = [];
 	const notes = [];
@@ -309,9 +348,10 @@ function changesOf(site) {
 		else changes.push({ kind: before === null ? 'add' : 'edit', file, before, after });
 	};
 
-	// package.json: @astrojs/node, `start`, and railway when its file is made.
+	// package.json: @astrojs/node, `start`, and railway when its file is made (only with --railway).
 	const railwayFile = '.railway/railway.ts';
-	const makeRailway = !existsSync(join(root, railwayFile));
+	const hasRailway = existsSync(join(root, railwayFile));
+	const makeRailway = railway && !hasRailway;
 	{
 		const pkg = structuredClone(site.pkg);
 		pkg.dependencies ??= {};
@@ -341,7 +381,7 @@ function changesOf(site) {
 	const healthFile = `${posix(site.srcDir)}/pages/health.ts`;
 	if (!health) changes.push({ kind: 'add', file: healthFile, after: template('health.ts.txt') });
 	else if (health.file === healthFile && read(join(root, healthFile)) === template('health.ts.txt')) done.push(healthFile);
-	else notes.push(`The site already has a /health route (${health.file}), so init leaves it alone. Railway's healthcheck asks /health for a 200.`);
+	else notes.push(`The site already has a /health route (${health.file}), so init leaves it alone. Hosts' healthchecks (Railway's, for one) ask /health for a 200.`);
 
 	{
 		const name = titleCase(site.pkg.name ?? basename(root)) || 'Site';
@@ -364,8 +404,11 @@ function changesOf(site) {
 		else edit('tsconfig.json', before, after, 'tsconfig.json (allowImportingTsExtensions)');
 	}
 
-	// Railway (Decision 11).
-	if (makeRailway) {
+	// Railway (Decision 11): with --railway, or the site's existing file. Otherwise no host file
+	// and report() prints HOST_VARIABLES (runs-anywhere Decision 12).
+	if (!railway && !hasRailway) {
+		// nothing to write
+	} else if (makeRailway) {
 		const remote = git(root, ['remote', 'get-url', 'origin']).out.trim();
 		const repo = /github\.com[:/]([^/]+\/[^/]+?)(?:\.git)?\/?$/.exec(remote)?.[1] ?? null;
 		const repoName = basename(git(root, ['rev-parse', '--show-toplevel']).out.trim() || root);
@@ -415,7 +458,7 @@ function changesOf(site) {
 	// MEC trial item 1: what Tina left behind, untracked (tinaOf).
 	const { leftover } = tinaOf(site);
 	if (leftover) notes.push(`${leftover.length ? leftover.join(', ') : 'tina/'} ${leftover.length > 1 ? 'are' : 'is'} left over from Tina (nothing under tina/ is tracked): delete ${leftover.length > 1 ? 'them' : 'it'}.`);
-	return { changes, notes, done };
+	return { changes, notes, done, hostVariables: !railway && !hasRailway };
 }
 
 /** `object` with `key` added, in alphabetical order when the object already is. */
@@ -517,7 +560,7 @@ function railwayNeeds(file) {
 		'    A media bucket: uploaded images. The site gets S3_ENDPOINT, S3_REGION, S3_BUCKET, S3_ACCESS_KEY_ID and S3_SECRET_ACCESS_KEY.',
 		'    A submissions bucket: form submissions, apart from the media imgproxy can read. The site gets SUBMISSIONS_S3_BUCKET, SUBMISSIONS_S3_ACCESS_KEY_ID and SUBMISSIONS_S3_SECRET_ACCESS_KEY.',
 		'    imgproxy (ghcr.io/imgproxy/imgproxy), reading only the media bucket: it serves the images, signed. The site gets CARACMS_MEDIA_URL (imgproxy\'s public address), IMGPROXY_KEY and IMGPROXY_SALT (the same as imgproxy\'s).',
-		'    The site: NODE_ENV=production, SITE_URL (its public address), GITHUB_REPO (owner/name), start command `caracms start`, healthcheck /health; set by hand: GITHUB_APP_ID, GITHUB_APP_PRIVATE_KEY, GITHUB_WEBHOOK_SECRET, CARACMS_SECRET, CARACMS_ALLOW, CARACMS_BACKUP_USER, CARACMS_BACKUP_PASSWORD, CARACMS_RAILWAY_TOKEN, MUX_TOKEN_ID, MUX_TOKEN_SECRET, RESEND_API_KEY, FORMS_FROM.',
+		'    The site: NODE_ENV=production, SITE_URL (its public address), GITHUB_REPO (owner/name), start command `caracms start`, healthcheck /health; set by hand: CARACMS_GITHUB_TOKEN (a fine-grained token on that one repo; or, instead, the App: GITHUB_APP_ID and GITHUB_APP_PRIVATE_KEY), GITHUB_WEBHOOK_SECRET, CARACMS_SECRET, CARACMS_ALLOW, CARACMS_BACKUP_USER, CARACMS_BACKUP_PASSWORD, CARACMS_RAILWAY_TOKEN, MUX_TOKEN_ID, MUX_TOKEN_SECRET, RESEND_API_KEY, FORMS_FROM.',
 		'    The whole of it, as caracms\'s starter writes it: node_modules/caracms/bin/templates/railway.ts.txt.',
 	].join('\n');
 }
@@ -608,7 +651,7 @@ function describe(change) {
 	}
 }
 
-function report({ changes, notes, done }, { write, pm }) {
+function report({ changes, notes, done, hostVariables }, { write, pm }) {
 	const parts = [];
 	if (changes.length === 0) {
 		parts.push('caracms init: nothing to do. caracms is set up here.');
@@ -622,6 +665,7 @@ function report({ changes, notes, done }, { 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) {
 		const install = `${pm} install`;
 		parts.push(
@@ -650,17 +694,17 @@ async function schemaChanges(site) {
 // ── The command ─────────────────────────────────────────────────────────────────
 
 /** The plan: problems (nothing happens when there are any), or the changes. */
-export async function plan(root, { write = false } = {}) {
+export async function plan(root, { write = false, railway = false } = {}) {
 	const site = inspect(root);
 	const problems = problemsOf(site, write);
-	if (problems.length) return { site, problems, changes: [], notes: [], done: [] };
-	const { changes, notes, done } = changesOf(site);
+	if (problems.length) return { site, problems, changes: [], notes: [], done: [], hostVariables: false };
+	const { changes, notes, done, hostVariables } = changesOf(site, { railway });
 	try {
 		changes.push(...(await schemaChanges(site)));
 	} catch (error) {
-		return { site, problems: [`The schemas couldn't be made from caracms.config.ts: ${error.message}`], changes: [], notes: [], done: [] };
+		return { site, problems: [`The schemas couldn't be made from caracms.config.ts: ${error.message}`], changes: [], notes: [], done: [], hostVariables: false };
 	}
-	return { site, problems, changes, notes, done };
+	return { site, problems, changes, notes, done, hostVariables };
 }
 
 function apply(root, changes) {
@@ -686,11 +730,11 @@ function apply(root, changes) {
 }
 
 /**
- * `caracms init [--write]`, from `root`. Returns the exit code; prints to `out` and `err` (stdout and stderr).
- * @param {{ root: string, write?: boolean, out?: { write(text: string): unknown }, err?: { write(text: string): unknown } }} options
+ * `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
  */
-export async function run({ root, write = false, out = process.stdout, err = process.stderr }) {
-	const p = await plan(root, { write });
+export async function run({ root, write = false, railway = false, out = process.stdout, err = process.stderr }) {
+	const p = await plan(root, { write, railway });
 	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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "caracms",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "A visual CMS for Astro sites, with content in git.",
   "license": "MIT",
   "type": "module",

package/skills/caracms-adopt/SKILL.md

@@ -69,10 +69,12 @@ unapproved, and don't approve it in passing (`pnpm approve` also reviews build s
   it), and `schemas/`;
 - `astro.config` edits: the Node adapter (standalone), `integrations: [caracms(site)]`,
   `devToolbar: { enabled: false }`;
-- `package.json`: `@astrojs/node`, `railway` (dev), `"start": "caracms start"`;
+- `package.json`: `@astrojs/node`, `"start": "caracms start"`;
   `.gitignore`: `.caracms/`; the tsconfig's `allowImportingTsExtensions`;
-- `.railway/railway.ts` (when the site had none), the skill links and a block in
-  `CLAUDE.md`.
+- the skill links and a block in `CLAUDE.md`;
+- with `--railway` only, `.railway/railway.ts` (when the site had none) and `railway`
+  (dev). Without it, `init` prints the variables any host needs instead. Where and how
+  the site runs (Railway, Render, Fly, a VPS) is the caracms README's Hosting section.
 
 Then `astro build`: every existing page must still build. The pages stay prerendered, but
 the output moves to `dist/client/` and `dist/server/`, and `npm start` is now

package/skills/caracms-adopt/look-same.mjs

@@ -110,7 +110,7 @@
 // Exit codes: 0 when the report is written (whatever the scores, statuses or image caps), 1 for
 // a usage error, 2 when the report is written but some page couldn't be fetched at all.
 
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { join, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
@@ -142,7 +142,9 @@ function parseArgs(argv) {
 }
 
 function readPages(spec) {
-	const lines = existsSync(spec) ? readFileSync(spec, 'utf8').split('\n') : spec.split(',');
+	// A list file only when it's a file: `--pages /` is the home page, not the disk's root.
+	const isFile = existsSync(spec) && statSync(spec).isFile();
+	const lines = isFile ? readFileSync(spec, 'utf8').split('\n') : spec.split(',');
 	return lines
 		.map((line) => line.replace(/#.*/, '').trim())
 		.filter(Boolean)
@@ -337,11 +339,13 @@ async function shoot(browser, url, width, imageWaitMs, css) {
 				const bottom = document.documentElement.scrollHeight - window.innerHeight;
 				if (y >= bottom) break;
 				y = Math.min(y + Math.round(window.innerHeight * 0.75), bottom);
-				window.scrollTo(0, y);
+				// Instant, whatever the page's own `scroll-behavior`: a smooth scroll still moving at
+				// the shot puts a sticky header somewhere else each run (Urban Return port).
+				window.scrollTo({ top: y, behavior: 'instant' });
 				await pause(120);
 			}
 			await pause(300);
-			window.scrollTo(0, 0);
+			window.scrollTo({ top: 0, behavior: 'instant' });
 		});
 		await page.waitForLoadState('networkidle', { timeout: 30_000 }).catch(() => {});
 		await page.evaluate(() => document.fonts.ready);

package/skills/caracms-blocks/SKILL.md

@@ -272,8 +272,26 @@ editor's preview alike. It gets `PageProps` (`caracms/document`): `document`,
   collection's component).
 - `document.kind === 'shared'` is a shared block's own preview: render it without the
   header and footer.
-- `<Media>` needs a block's `cms`, so images in the page's frame (a logo) stay the site's
-  own files.
+- **An image in the page's frame** (a header logo, a mega-menu photo, a footer badge) is a
+  `media()` field in Site Settings, drawn with `settingsImageUrl` from `caracms/content`
+  (`<Media>` needs a block's `cms`, which the frame doesn't have):
+
+  ```astro
+  ---
+  import { settingsImageUrl, siteSettings } from 'caracms/content';
+  import { site } from 'virtual:caracms/config';
+  const settings = await siteSettings(site, Astro.locals);
+  const photo = settingsImageUrl(settings.megaPhoto, { width: 640, height: 400 });
+  ---
+  <div class="mega" data-image={photo ?? '/images/placeholder.svg'}></div>
+  ```
+
+  It gives one URL by `<Media>`'s rules: one side is a `fit`, both are a `fill` cropped to
+  the focal point, a GIF or an SVG passes through unresized, no size is a `fit` at 1920. Ask
+  for the size it's shown at (twice it for a sharp 2× screen); there's no `srcset`. It's
+  null when the field is empty or the media isn't set up, so give the frame a fallback. It
+  works in the build, in the editor's preview (the draft's image) and under
+  `CARACMS_MEDIA=memory`.
 
 ## Forms
 

package/skills/caracms-tina/SKILL.md

@@ -55,8 +55,9 @@ Work on a branch (`caracms-port`, say) in a worktree of the site. Commit after e
    before anything else changes. If the site pins its own `vite`, bump it with Astro:
    left behind, it leaves a second Vite in the tree and `astro check` fails in the Astro
    config. **Bump `.nvmrc` and `engines.node` in `package.json` with Astro** (Astro 7.4
-   needs Node 22.23.4 or later, and so does caracms): Railway builds on the older Node
-   and fails with exit 1 and no error text in the build log.
+   needs Node 22.23.4 or later, and so does caracms): a host that reads them builds on
+   the older Node otherwise (Railway fails with exit 1 and no error text in the build
+   log).
 2. **Strip Tina** (section 3): `tina/`, `server.mjs`, `server/`, Tina's routes and admin,
    **including the untracked `tina/__generated__/` and `public/admin/`** (they're in
    `.gitignore`; delete them from disk too, or `init` and the build trip on them).
@@ -65,11 +66,12 @@ Work on a branch (`caracms-port`, say) in a worktree of the site. Commit after e
    `caracms start` serves `dist/server/entry.mjs` and refuses any other mode.
 5. **`npx caracms init`**, read the dry run, then **`npx caracms init --write`** and install
    again (caracms-adopt → section 1). It links the four skills, writes the config, the
-   CLAUDE.md block, the health route and, on a site without one, `.railway/railway.ts`.
-   **A template site already has a `.railway/railway.ts` that describes production: leave
-   it alone and never apply it** (applying it can switch production's CDN off). `init`
-   leaves an existing one untouched, which is the expected outcome. Set the branch
-   environment up with the Railway CLI or MCP, scoped to that environment (section 9).
+   CLAUDE.md block and the health route. **A template site already has a
+   `.railway/railway.ts` that describes production: leave it alone and never apply it**
+   (applying it can switch production's CDN off). `init` treats a site that has one as
+   a Railway site and leaves the file untouched, which is the expected outcome. Set the
+   branch environment up with the Railway CLI or MCP, scoped to that environment
+   (section 9).
 6. **Copy the script and run it** (section 2) against a **built** checkout of `main`.
    First run with `--scaffold-config` for a starting `caracms.config.ts`. It names a
    component per block before any is written, so nothing builds until they exist: point
@@ -365,7 +367,9 @@ conversion: caracms's inbox reads the template's records as they are (`<id>.json
 
 ## 9. The branch environment
 
-The port is deployed from its branch to its own environment, **never production**:
+The port is deployed from its branch to its own environment, **never production**. The
+template sites run on Railway, so this section is written for it. A site on another host
+needs the same pieces there (the caracms README's Hosting section has each host):
 
 - A new environment in the site's Railway project (`caracms`), with its own `web`, Redis, a
   signed imgproxy and its own submissions bucket. It reads the live media bucket (caracms
@@ -378,8 +382,8 @@ The port is deployed from its branch to its own environment, **never production*
   commits to the port branch and redeploys the environment, and the live site's `main`
   never moves. With the defaults, the first Publish would land caracms's content on the
   live site's `main`.
-- A GitHub App with Contents read/write on the site's repo, its variables on the
-  environment (as for any caracms site).
+- A GitHub credential on the environment, as for any caracms site: a fine-grained token
+  on the site's repo, or the App (the caracms README → Hosting → GitHub).
 - Convert with `--recipients <agency address>`, so test submissions never reach the client.
 - **Never `railway config apply` against production**: production's variables are set
   with `railway variables --set` (a template's Railway file can switch its CDN off).