caracms 0.1.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' };
 
@@ -43,6 +82,7 @@ const SKILL_BLURBS = {
 	'caracms-content': 'changing content: the JSON files in content/, rich text, images, references, Site Settings, and working on a branch',
 	'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',
 };
 
 const posix = (p) => p.split(sep).join('/');
@@ -294,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 = [];
@@ -308,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 ??= {};
@@ -340,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';
@@ -363,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);
@@ -414,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. */
@@ -516,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');
 }
@@ -607,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.');
@@ -621,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(
@@ -649,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) {
@@ -685,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/bin/templates/catch-all.astro.txt

@@ -12,8 +12,9 @@ import { site } from 'virtual:caracms/config';
 export const prerender = true;
 
 export async function getStaticPaths() {
-	// A file that can't be opened (invalid JSON, no title, a nested index.json) has no page.
-	const entries = (await listDocuments(site, 'pages')).filter((e) => !e.warning);
+	// A file that can't be opened (invalid JSON, no title, a nested index.json) has no page,
+	// and nor has a hidden one (or one under it): visitors get the 404 page.
+	const entries = (await listDocuments(site, 'pages')).filter((e) => !e.warning && !e.hidden);
 	return entries.map((e) => ({ params: { path: e.path === 'index' ? undefined : e.path }, props: { path: e.path } }));
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "caracms",
-  "version": "0.1.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
@@ -142,6 +144,11 @@ form, such as `<brand> | <tagline>`, goes in the home page's own `seo.title`
 the home page, where an editor changing it will look, and it wins whatever Site Settings
 holds.
 
+If the old site showed one site-wide title on every page without its own (a Tina template
+does), set the config's `titleFallback: 'site'` beside `titleSeparator`: step 2 then holds
+on every page, not only the home page (the paged-listing ` — page N` still follows). The
+default, `'page-and-brand'`, is the list above.
+
 **Per-page layout props.** The old routes often passed the layout something by hand: the
 header's colour or variant, `<main>`'s classes, a script in `<head>` for one page, the
 current page for the nav's highlight. A document has no route to do that, so the page
@@ -461,6 +468,13 @@ node .claude/skills/caracms-adopt/look-same.mjs --playwright /tmp/look-same \
     --pages pages.txt --out /tmp/look-same/report \
     --ignore-attr 'data-tina-*' --mask-ids auto
   ```
+- **An element that varies run to run on the old site itself** (a wordmark fitted to its box
+  while the display font loads, so two shots of the same build differ) can't be fixed by
+  either site. `--css <rules>` adds the same CSS to both pages just before each shot: hide
+  the element or pin its size, e.g.
+  `--css '[data-wordmark-wrap]{visibility:hidden!important}'`. It changes the shots only,
+  not the HTML diff, and the report names the rules; keep them to the one element, since
+  whatever they cover is no longer compared.
 - **Spaces**: a space between inline content shows as `␣` at the start of the next text,
   wherever it sat (`<span>sub </span><em>` and `<span>sub</span> <em>` are the same), and a
   space beside a block tag is dropped, since neither shows. So a `␣` line in the diff is a