caracms 0.0.0-stage → 0.2.0

package/bin/init.mjs

@@ -0,0 +1,712 @@
+// `caracms init [--write]` (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`).
+//   It never prompts.
+// - 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
+//   `.railway/railway.ts`) gets the lines to add printed instead, and is left alone.
+// - 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.
+
+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 { basename, dirname, join, relative, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const packageRoot = fileURLToPath(new URL('..', import.meta.url));
+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'));
+
+/** What init adds to a site's package.json (Decisions 7 and 11). */
+export const VERSIONS = { node: '^11.1.7', railway: '^3.16.0' };
+
+export const MARK_START = '<!-- caracms:start -->';
+export const MARK_END = '<!-- caracms:end -->';
+/** Where a site's skills link to: the installed package (Decision 12). */
+const SKILLS_LINK_BASE = '../../node_modules/caracms/skills/';
+/** The URLs the package reserves (src/slug.ts → addressProblem). */
+const RESERVED = ['/admin', '/_caracms', '/files'];
+const ROUTE_EXTENSIONS = ['.astro', '.md', '.mdx', '.markdown', '.html', '.ts', '.js', '.mjs', '.mts'];
+const LOCKFILES = ['pnpm-lock.yaml', 'package-lock.json', 'yarn.lock', 'bun.lock', 'bun.lockb', 'npm-shrinkwrap.json'];
+const ASTRO_CONFIGS = ['astro.config.mjs', 'astro.config.ts', 'astro.config.mts', 'astro.config.js', 'astro.config.cjs', 'astro.config.cts'];
+/** The schema files the starting config makes (bin/templates/caracms.config.ts.txt). */
+const STARTING_SCHEMAS = ['schemas/pages.schema.json', 'schemas/shared.schema.json', 'schemas/site-settings.schema.json'];
+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('/');
+const read = (path) => {
+	try {
+		return readFileSync(path, 'utf8');
+	} catch {
+		return null;
+	}
+};
+const isDir = (path) => {
+	try {
+		return statSync(path).isDirectory();
+	} catch {
+		return false;
+	}
+};
+const lstat = (path) => {
+	try {
+		return lstatSync(path);
+	} catch {
+		return null;
+	}
+};
+const titleCase = (name) => name.replace(/^@[^/]+\//, '').split(/[-_\s]+/).filter(Boolean).map((w) => w[0].toUpperCase() + w.slice(1)).join(' ');
+
+function git(root, args) {
+	try {
+		return { ok: true, out: execFileSync('git', args, { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }) };
+	} catch {
+		return { ok: false, out: '' };
+	}
+}
+
+// ── Routes (the same reading as src/code-routes.ts, in plain JavaScript) ─────────
+
+/** Every route file under src/pages (Astro's rules: `_` and `.` names skipped), with its URL and whether it has parameters. */
+function pageRoutes(root, srcDir) {
+	const pages = join(root, srcDir, 'pages');
+	const out = [];
+	const walk = (dir) => {
+		let names = [];
+		try {
+			names = readdirSync(dir).sort();
+		} catch {
+			return;
+		}
+		for (const name of names) {
+			if (name.startsWith('_') || name.startsWith('.')) continue;
+			const path = join(dir, name);
+			if (isDir(path)) {
+				walk(path);
+				continue;
+			}
+			if (/\.d\.[mc]?ts$/.test(name)) continue;
+			const ext = ROUTE_EXTENSIONS.find((e) => name.endsWith(e));
+			if (!ext) continue;
+			const parts = posix(relative(pages, path)).split('/');
+			const base = parts.pop().slice(0, -ext.length);
+			const segments = [...parts, ...(base === 'index' ? [] : [base])];
+			const first = segments.findIndex((s) => s.includes('['));
+			const file = posix(relative(root, path));
+			if (first === -1) out.push({ file, url: `/${segments.join('/')}`, dynamic: false, rest: false });
+			else out.push({ file, url: first ? `/${segments.slice(0, first).join('/')}/` : '/', dynamic: true, rest: /^\[\.\.\.[^\]]+\]$/.test(segments[first]) });
+		}
+	};
+	walk(pages);
+	return out;
+}
+
+/** Does `route` serve `url` or anything under it? */
+function routeReaches(route, url) {
+	const at = url.toLowerCase();
+	const r = route.url.toLowerCase().replace(/\/$/, '') || '/';
+	if (!route.dynamic) return r === at || r.startsWith(`${at}/`);
+	// A catch-all at the top never takes the package's own routes: Astro ranks a rest parameter last.
+	if (r === '/') return false;
+	return r === at || r.startsWith(`${at}/`) || at.startsWith(`${r}/`);
+}
+
+// ── The site as found ───────────────────────────────────────────────────────────
+
+function inspect(root) {
+	const pkgText = read(join(root, 'package.json'));
+	let pkg = null;
+	try {
+		pkg = pkgText === null ? null : JSON.parse(pkgText);
+	} catch {
+		pkg = undefined;
+	}
+	const deps = { ...(pkg?.dependencies ?? {}), ...(pkg?.devDependencies ?? {}) };
+	const configName = ASTRO_CONFIGS.find((n) => existsSync(join(root, n))) ?? null;
+	const configText = configName ? read(join(root, configName)) : null;
+	const srcDir = (configText && /\bsrcDir\s*:\s*(['"`])([^'"`]+)\1/.exec(configText)?.[2]) || 'src';
+	const lock = existsSync(join(root, 'pnpm-lock.yaml'))
+		? 'pnpm'
+		: existsSync(join(root, 'package-lock.json'))
+			? 'npm'
+			: existsSync(join(root, 'yarn.lock'))
+				? 'yarn'
+				: 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')) };
+}
+
+function installedAstro(root) {
+	try {
+		return JSON.parse(readFileSync(createRequire(join(root, 'package.json')).resolve('astro/package.json'), 'utf8')).version;
+	} catch {
+		return null;
+	}
+}
+
+const parseVersion = (v) => {
+	const m = /(\d+)\.(\d+)\.(\d+)/.exec(v ?? '');
+	return m ? m.slice(1, 4).map(Number) : null;
+};
+
+/** Does `version` satisfy the package's peer range for Astro (a caret range: `^7.3.8`)? */
+function inPeerRange(version, range) {
+	const v = parseVersion(version);
+	const r = parseVersion(range);
+	if (!v || !r) return true;
+	if (v[0] !== r[0]) return false;
+	return v[1] > r[1] || (v[1] === r[1] && v[2] >= r[2]);
+}
+
+/** The adapter astro.config uses: its import's module, or null for none. `unknown` when it can't be followed. */
+function adapterOf(configText) {
+	if (!configText) return null;
+	const m = /\badapter\s*:\s*([A-Za-z_$][\w$]*)\s*\(/.exec(configText);
+	if (!m) return /\badapter\s*:/.test(configText) ? 'unknown' : null;
+	const from = new RegExp(`import\\s+${m[1].replace(/\$/g, '\\$')}\\s+from\\s+['"]([^'"]+)['"]`).exec(configText);
+	return from ? from[1] : 'unknown';
+}
+
+// ── Problems (Decisions 8 and 9) ────────────────────────────────────────────────
+
+function problemsOf(site, write) {
+	const { root } = site;
+	const problems = [];
+	const inGit = git(root, ['rev-parse', '--is-inside-work-tree']).out.trim() === 'true';
+	if (!inGit) problems.push("This isn't a git repository: init only runs in one, so what it does is one reviewable diff. Run `git init` and commit the site first.");
+	else if (write) {
+		// Paths relative to the site's root (porcelain prints them from the repository's), so the `git add` line runs from here.
+		const prefix = git(root, ['rev-parse', '--show-prefix']).out.trim();
+		const dirty = git(root, ['status', '--porcelain', '--untracked-files=no', '--', '.'])
+			.out.split('\n')
+			.filter(Boolean)
+			.map((l) => l.slice(3))
+			.map((f) => (prefix && f.startsWith(prefix) ? f.slice(prefix.length) : f));
+		if (dirty.length && dirty.every((f) => f === 'package.json' || LOCKFILES.includes(f))) {
+			// Installing caracms (the step before init) changes exactly these: the refusal stays (Decision 8), with the step.
+			problems.push(`${dirty.join(' and ')} ${dirty.length === 1 ? 'has' : 'have'} uncommitted changes, which installing caracms makes. Commit the install first, so init's change is one reviewable diff of its own: \`git add ${dirty.join(' ')} && git commit -m "Install caracms"\`, then run init again.`);
+		} else if (dirty.length) problems.push(`There are uncommitted changes to tracked files (${dirty.slice(0, 5).join(', ')}${dirty.length > 5 ? ', …' : ''}): commit or stash them first, so init's change is one reviewable diff.`);
+	}
+	if (site.pkg === null) {
+		problems.push("There's no package.json here. Run init from the site's root.");
+		return problems;
+	}
+	if (site.pkg === undefined) problems.push("package.json isn't valid JSON. Fix it, then run init again.");
+
+	// Tina (Decision 9): named as one, by what's real (tinaOf).
+	const tina = tinaOf(site, inGit).reasons;
+	if (tina.length) problems.push(`This is a Tina site (${tina.join(' and ')}): Tina sites come in through a port, not \`init\`.`);
+
+	const astroVersion = installedAstro(root);
+	const peer = ownPackage.peerDependencies?.astro ?? '';
+	if (!site.deps.astro && !astroVersion) problems.push("There's no Astro here (no astro in package.json): caracms adds to an existing Astro site. Run init from the site's root.");
+	else {
+		const version = astroVersion ?? site.deps.astro;
+		if (!inPeerRange(version, peer)) problems.push(`Astro ${version} is outside the range caracms ${ownPackage.version} works with (${peer}). Move the site to an Astro in that range first.`);
+	}
+
+	const adapter = adapterOf(site.configText);
+	if (adapter === 'unknown') problems.push(`${site.configName} sets an adapter init can't follow. caracms needs @astrojs/node in standalone mode: set \`adapter: node({ mode: 'standalone' })\` (import node from '@astrojs/node') by hand, then run init again.`);
+	else if (adapter && adapter !== '@astrojs/node') problems.push(`${site.configName} uses the ${adapter} adapter. caracms runs on the Node adapter (@astrojs/node, standalone): move the site to it first.`);
+	else if (adapter === '@astrojs/node' && /\bmode\s*:\s*['"]middleware['"]/.test(site.configText)) problems.push(`${site.configName} has the Node adapter in middleware mode. caracms's server (\`caracms start\`) needs standalone mode: change it to \`node({ mode: 'standalone' })\`.`);
+
+	// content/ (Decision 9): caracms's own. A set-up site's is its documents.
+	if (!site.setUp && isDir(join(root, 'content'))) {
+		const files = listFiles(join(root, 'content')).map((f) => posix(relative(root, f)));
+		if (files.length) problems.push(`content/ already holds files that aren't caracms's (${files.slice(0, 3).join(', ')}${files.length > 3 ? ', …' : ''}). caracms keeps its content there: move them (Astro's own content collections can live in src/content/), then run init again.`);
+	}
+
+	const routes = pageRoutes(root, site.srcDir);
+	for (const url of RESERVED) {
+		for (const r of routes.filter((r) => routeReaches(r, url))) problems.push(`${r.file} serves ${r.dynamic ? `addresses under ${r.url.replace(/\/$/, '')}` : r.url}, which caracms reserves (${url} and everything under it). Move that page elsewhere.`);
+		const inPublic = join(root, 'public', url.slice(1));
+		if (existsSync(inPublic)) problems.push(`public${url} is at ${url}, which caracms reserves (${url} and everything under it). Move it elsewhere in public/.`);
+	}
+	for (const [url, why] of [
+		['/sitemap.xml', 'caracms makes the sitemap from its documents (when SITE_URL is set)'],
+		['/robots.txt', "caracms's server (`caracms start`) answers /robots.txt itself, before Astro and public/ (bin/gate.mjs), so this would never be reached"],
+	]) {
+		for (const r of routes.filter((r) => !r.dynamic && r.url === url)) problems.push(`${r.file} is the site's own ${url}, and ${why}. Delete it; to keep pages out of search, use SITE_URL and Site Settings.`);
+		// A static file is the same address: the adapter serves public/ before Astro's routes (and robots.txt never gets that far).
+		if (existsSync(join(root, 'public', url.slice(1)))) problems.push(`public${url} is the site's own ${url}, and ${why}. Delete it; to keep pages out of search, use SITE_URL and Site Settings.`);
+	}
+	if (!site.setUp) {
+		// caracms's own catch-all counts as done only when it's the template, byte for byte (as health.ts is compared).
+		const own = `${posix(site.srcDir)}/pages/[...path].astro`;
+		const isOwn = (r) => r.file === own && read(join(root, own)) === template('catch-all.astro.txt');
+		for (const r of routes.filter((r) => r.dynamic && r.url === '/' && !isOwn(r))) {
+			if (r.file === own) problems.push(`${r.file} is the site's own: it isn't the page caracms adds at that path, and it catches addresses at the top of the site, where caracms's pages go. Move it under a folder of its own (src/pages/<folder>/), or delete it if caracms's documents replace it, then run init again.`);
+			else problems.push(`${r.file} already catches addresses at the top of the site, where caracms's pages go. Rename it under a folder of its own (src/pages/<folder>/), then run init again.`);
+		}
+	}
+	return problems;
+}
+
+/**
+ * Is this a Tina site (Decision 9)? `tinacms` (or an `@tinacms/` package) in its dependencies,
+ * or a tina/ folder holding tracked files. MEC trial item 1: a site stripped of Tina can keep an
+ * untracked, git-ignored tina/__generated__/, which alone isn't a Tina site: `leftover` names
+ * what's there, for a note. Outside git there's no telling, so a tina/ folder counts.
+ */
+function tinaOf(site, inGit = git(site.root, ['rev-parse', '--is-inside-work-tree']).out.trim() === 'true') {
+	const reasons = [];
+	let leftover = null;
+	if (isDir(join(site.root, 'tina'))) {
+		const tracked = inGit ? git(site.root, ['ls-files', '--', 'tina']).out.trim() !== '' : true;
+		if (tracked) reasons.push('a tina/ folder with tracked files');
+		else leftover = readdirSync(join(site.root, 'tina')).filter((n) => n !== '.DS_Store').sort().map((n) => `tina/${n}${isDir(join(site.root, 'tina', n)) ? '/' : ''}`);
+	}
+	if (Object.keys(site.deps).some((d) => d === 'tinacms' || d.startsWith('@tinacms/'))) reasons.push('tinacms in its dependencies');
+	return { reasons, leftover };
+}
+
+function listFiles(dir) {
+	const out = [];
+	const walk = (d) => {
+		for (const name of readdirSync(d).sort()) {
+			if (name === '.DS_Store') continue;
+			const p = join(d, name);
+			if (isDir(p)) walk(p);
+			else out.push(p);
+		}
+	};
+	walk(dir);
+	return out;
+}
+
+// ── The changes ─────────────────────────────────────────────────────────────────
+
+/**
+ * Everything init would do, as a list of changes ({ kind: 'add' | 'edit' | 'link' |
+ * 'unlink' | 'schemas', file, before?, after?, target? }), notes (printed, nothing written),
+ * and what's already done.
+ */
+function changesOf(site) {
+	const { root } = site;
+	const changes = [];
+	const notes = [];
+	const done = [];
+	const add = (file, text, what) => {
+		if (existsSync(join(root, file))) done.push(what ?? file);
+		else changes.push({ kind: 'add', file, after: text });
+	};
+	const edit = (file, before, after, what) => {
+		if (after === before) done.push(what ?? file);
+		else changes.push({ kind: before === null ? 'add' : 'edit', file, before, after });
+	};
+
+	// package.json: @astrojs/node, `start`, and railway when its file is made.
+	const railwayFile = '.railway/railway.ts';
+	const makeRailway = !existsSync(join(root, railwayFile));
+	{
+		const pkg = structuredClone(site.pkg);
+		pkg.dependencies ??= {};
+		if (!site.deps['@astrojs/node']) pkg.dependencies = withKey(pkg.dependencies, '@astrojs/node', VERSIONS.node);
+		// Decision 3: a site pins the exact version. An existing entry (on the trial, the tarball) is left alone.
+		if (!site.deps.caracms) pkg.dependencies = withKey(pkg.dependencies, 'caracms', ownPackage.version);
+		if (makeRailway && !site.deps.railway) pkg.devDependencies = withKey(pkg.devDependencies ?? {}, 'railway', VERSIONS.railway);
+		pkg.scripts = { ...(pkg.scripts ?? {}) };
+		pkg.scripts.start = 'caracms start';
+		if (Object.keys(pkg.dependencies).length === 0 && !site.pkg.dependencies) delete pkg.dependencies;
+		edit('package.json', site.pkgText, jsonText(pkg, site.pkgText), 'package.json (@astrojs/node, `start`)');
+	}
+
+	// astro.config: the adapter, the integration, no dev toolbar.
+	{
+		const result = astroConfigEdit(site);
+		if (result.edit) edit(result.file, site.configText, result.edit, `${result.file} (adapter, integration)`);
+		else if (result.done) done.push(`${result.file} (adapter, integration)`);
+		else notes.push(result.note);
+	}
+
+	add('caracms.config.ts', template('caracms.config.ts.txt'));
+	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'));
+	const health = pageRoutes(root, site.srcDir).find((r) => !r.dynamic && r.url === '/health');
+	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.`);
+
+	{
+		const name = titleCase(site.pkg.name ?? basename(root)) || 'Site';
+		const settings = { $schema: '../schemas/site-settings.schema.json', title: 'Site Settings', editors: [], brand: { name } };
+		add('content/site-settings.json', `${JSON.stringify(settings, null, 2)}\n`);
+	}
+
+	{
+		const before = read(join(root, '.gitignore'));
+		const has = before !== null && before.split('\n').some((l) => /^\/?\.caracms\/?$/.test(l.trim()));
+		const lines = "# caracms's working files\n.caracms/\n";
+		const after = has ? before : before === null || before === '' ? lines : `${before}${before.endsWith('\n') ? '' : '\n'}\n${lines}`;
+		edit('.gitignore', before, after, '.gitignore (.caracms/)');
+	}
+
+	{
+		const before = read(join(root, 'tsconfig.json'));
+		const after = tsconfigEdit(before);
+		if (after === undefined) notes.push('tsconfig.json: init couldn\'t follow it. Add `"allowImportingTsExtensions": true` to its compilerOptions by hand (caracms.config.ts imports .ts files by name).');
+		else edit('tsconfig.json', before, after, 'tsconfig.json (allowImportingTsExtensions)');
+	}
+
+	// Railway (Decision 11).
+	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);
+		const run = site.pm === 'npm' ? 'npm run' : site.pm;
+		const text = template('railway.ts.txt')
+			.replaceAll('{{SITE}}', repoName)
+			.replaceAll('{{GITHUB_REPO}}', repo ?? 'OWNER/REPO')
+			.replaceAll('{{BUILD}}', `${run} build`)
+			.replaceAll('{{START}}', `${site.pm} start`);
+		changes.push({ kind: 'add', file: railwayFile, after: text });
+		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));
+	} else done.push(railwayFile);
+
+	// Skills (Decision 12), linked from the installed package.
+	const skills = skillNames();
+	const skillsDir = join(root, '.claude/skills');
+	for (const name of skills) {
+		const file = `.claude/skills/${name}`;
+		const target = `${SKILLS_LINK_BASE}${name}`;
+		const st = lstat(join(root, file));
+		if (!st) changes.push({ kind: 'link', file, target });
+		else if (st.isSymbolicLink() && readlinkSync(join(root, file)) === target) done.push(file);
+		else if (st.isSymbolicLink() && readlinkSync(join(root, file)).startsWith(SKILLS_LINK_BASE)) changes.push({ kind: 'link', file, target, replace: true });
+		else notes.push(`${file} is the site's own, so init doesn't link caracms's ${name} skill over it.`);
+	}
+	if (isDir(skillsDir)) {
+		for (const name of readdirSync(skillsDir).sort()) {
+			const path = join(skillsDir, name);
+			if (skills.includes(name) || !lstat(path)?.isSymbolicLink()) continue;
+			if (readlinkSync(path).startsWith(SKILLS_LINK_BASE)) changes.push({ kind: 'unlink', file: `.claude/skills/${name}` });
+		}
+	}
+
+	// The CLAUDE.md block (Decision 12): into the link's target when CLAUDE.md is a link.
+	{
+		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 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)`);
+	}
+	// 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 };
+}
+
+/** `object` with `key` added, in alphabetical order when the object already is. */
+function withKey(object, key, value) {
+	if (Object.hasOwn(object, key)) return object;
+	const keys = Object.keys(object);
+	const sorted = keys.every((k, i) => i === 0 || keys[i - 1].localeCompare(k) <= 0);
+	const entries = [...Object.entries(object), [key, value]];
+	if (sorted) entries.sort(([a], [b]) => a.localeCompare(b));
+	return Object.fromEntries(entries);
+}
+
+/** JSON in the file's own indentation, with its trailing newline. */
+function jsonText(value, like) {
+	const indent = /\n([ \t]+)"/.exec(like ?? '')?.[1] ?? '  ';
+	return `${JSON.stringify(value, null, indent)}${like?.endsWith('\n') === false ? '' : '\n'}`;
+}
+
+/** tsconfig.json's text with `allowImportingTsExtensions`, or undefined when it can't be followed. */
+function tsconfigEdit(text) {
+	if (text === null) return `{\n  "extends": "astro/tsconfigs/base",\n  "compilerOptions": {\n    "allowImportingTsExtensions": true\n  }\n}\n`;
+	if (/"allowImportingTsExtensions"\s*:\s*true/.test(text)) return text;
+	if (/"allowImportingTsExtensions"/.test(text)) return undefined;
+	const options = /"compilerOptions"\s*:\s*\{/.exec(text);
+	const indent = /\n([ \t]+)"/.exec(text)?.[1] ?? '  ';
+	if (options) {
+		const at = options.index + options[0].length;
+		const empty = /^\s*\}/.test(text.slice(at));
+		return `${text.slice(0, at)}\n${indent}${indent}"allowImportingTsExtensions": true${empty ? `\n${indent}` : ','}${empty ? text.slice(at).replace(/^\s*/, '') : text.slice(at)}`;
+	}
+	const end = text.lastIndexOf('}');
+	if (end === -1) return undefined;
+	const body = text.slice(0, end).replace(/\s*$/, '');
+	const comma = body.endsWith('{') ? '' : ',';
+	return `${body}${comma}\n${indent}"compilerOptions": {\n${indent}${indent}"allowImportingTsExtensions": true\n${indent}}\n${text.slice(end)}`;
+}
+
+const INTEGRATION_LINES = (indent, { adapter, integrations, toolbar }) =>
+	[
+		adapter ? `${indent}// caracms: pages stay prerendered; the Node server adds the editor (caracms start).\n${indent}adapter: node({ mode: 'standalone' }),` : null,
+		integrations ? `${indent}// caracms reads caracms.config.ts: collections, blocks, text styles and the page component.\n${indent}integrations: [caracms(site)],` : null,
+		toolbar ? `${indent}// Astro's dev toolbar would fight the editor's preview.\n${indent}devToolbar: { enabled: false },` : null,
+	].filter(Boolean);
+
+/** astro.config's new text: `{ file, edit }`, `{ file, done: true }`, or `{ file, note }` (lines to add by hand). */
+function astroConfigEdit(site) {
+	const file = site.configName ?? 'astro.config.mjs';
+	const imports = ["import node from '@astrojs/node';", "import caracms from 'caracms';", "import site from './caracms.config.ts';"];
+	const text = site.configText;
+	if (text === null) {
+		const body = INTEGRATION_LINES('\t', { adapter: true, integrations: true, toolbar: true }).join('\n');
+		return { file, edit: `// @ts-check\nimport { defineConfig } from 'astro/config';\n${imports.join('\n')}\n\nexport default defineConfig({\n${body}\n});\n` };
+	}
+	if (/\bcaracms\s*\(/.test(text)) return { file, done: true };
+	const hasAdapter = adapterOf(text) !== null;
+	const hasToolbar = /\bdevToolbar\s*:/.test(text);
+	const hasIntegrations = /\bintegrations\s*:/.test(text);
+	const needed = imports.filter((line, i) => !(i === 0 && hasAdapter));
+	const byHand = (why) => {
+		const lines = [...needed, ...INTEGRATION_LINES('  ', { adapter: !hasAdapter, integrations: !hasIntegrations, toolbar: !hasToolbar }).map((l) => l.trimStart())];
+		if (hasIntegrations) lines.push('caracms(site) in its integrations: [ … ]');
+		return { file, note: `${file}: ${why}, so init leaves it alone. Add these by hand, then run init again:\n${lines.map((l) => `    ${l}`).join('\n')}` };
+	};
+	const open = /defineConfig\(\s*\{/.exec(text);
+	if (!open) return byHand("it doesn't export `defineConfig({ … })`");
+	const integrationsArray = hasIntegrations ? /\bintegrations\s*:\s*\[/.exec(text) : null;
+	if (hasIntegrations && !integrationsArray) return byHand('its integrations aren\'t a plain list');
+
+	let out = text;
+	// The integration first (later offsets move), then the keys after `defineConfig({`, then the imports.
+	if (integrationsArray) {
+		const at = integrationsArray.index + integrationsArray[0].length;
+		const empty = /^\s*\]/.test(out.slice(at));
+		out = `${out.slice(0, at)}caracms(site)${empty ? '' : ', '}${out.slice(at)}`;
+	}
+	const openAt = open.index + open[0].length;
+	const nextLine = /\n([ \t]*)\S/.exec(out.slice(openAt));
+	const indent = nextLine?.[1] || '  ';
+	const lines = INTEGRATION_LINES(indent, { adapter: !hasAdapter, integrations: !hasIntegrations, toolbar: !hasToolbar });
+	if (lines.length) out = `${out.slice(0, openAt)}\n${lines.join('\n')}${out.slice(openAt)}`;
+
+	const importRe = /^import\s(?:[^;'"]*?\sfrom\s*)?['"][^'"]+['"];?[ \t]*$/gm;
+	let lastImportEnd = -1;
+	for (let m; (m = importRe.exec(out)); ) lastImportEnd = m.index + m[0].length;
+	const importText = needed.join('\n');
+	if (lastImportEnd >= 0) out = `${out.slice(0, lastImportEnd)}\n${importText}${out.slice(lastImportEnd)}`;
+	else {
+		const check = /^\/\/ @ts-check[ \t]*\n/.exec(out);
+		const at = check ? check[0].length : 0;
+		out = `${out.slice(0, at)}${importText}\n${out.slice(at)}`;
+	}
+	return { file, edit: out };
+}
+
+function railwayNeeds(file) {
+	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.',
+		'    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 whole of it, as caracms\'s starter writes it: node_modules/caracms/bin/templates/railway.ts.txt.',
+	].join('\n');
+}
+
+/** The package's skills: its `skills/<name>/` folders. */
+export function skillNames() {
+	const dir = join(packageRoot, 'skills');
+	if (!isDir(dir)) return [];
+	return readdirSync(dir).filter((n) => !n.startsWith('.') && isDir(join(dir, n))).sort();
+}
+
+export function claudeBlock(skills) {
+	const lines = [
+		MARK_START,
+		'## caracms',
+		'',
+		"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]}.` : ''}`),
+		...(skills.length ? [''] : []),
+		'Run `caracms validate` before a pull request.',
+		MARK_END,
+	];
+	return lines.join('\n');
+}
+
+/**
+ * The file's text with the block between the markers replaced, or appended. Nothing outside the markers changes.
+ * Null when there's a start marker with no end marker after it: where the old block ends can't be told, so it isn't safe to edit.
+ */
+export function withBlock(text, block) {
+	if (text === null || text === '') return `${block}\n`;
+	const start = text.indexOf(MARK_START);
+	const end = start === -1 ? -1 : text.indexOf(MARK_END, start);
+	if (start !== -1 && end === -1) return null;
+	if (start !== -1) return text.slice(0, start) + block + text.slice(end + MARK_END.length);
+	return `${text.replace(/\n*$/, '')}\n\n${block}\n`;
+}
+
+// ── Output ──────────────────────────────────────────────────────────────────────
+
+/** A unified diff of two texts, three lines of context. */
+export function diff(file, before, after) {
+	const a = before === null ? [] : before.replace(/\n$/, '').split('\n');
+	const b = after.replace(/\n$/, '').split('\n');
+	// The longest common subsequence, by a table (config files are small).
+	const lcs = Array.from({ length: a.length + 1 }, () => new Uint32Array(b.length + 1));
+	for (let i = a.length - 1; i >= 0; i--) for (let j = b.length - 1; j >= 0; j--) lcs[i][j] = a[i] === b[j] ? lcs[i + 1][j + 1] + 1 : Math.max(lcs[i + 1][j], lcs[i][j + 1]);
+	const ops = [];
+	let i = 0;
+	let j = 0;
+	while (i < a.length || j < b.length) {
+		if (i < a.length && j < b.length && a[i] === b[j]) ops.push([' ', a[i++], j++]);
+		else if (i < a.length && (j === b.length || lcs[i + 1][j] >= lcs[i][j + 1])) ops.push(['-', a[i++]]);
+		else ops.push(['+', b[j++]]);
+	}
+	const out = [`--- ${before === null ? '/dev/null' : `a/${file}`}`, `+++ b/${file}`];
+	const changed = ops.map((o, k) => (o[0] !== ' ' ? k : -1)).filter((k) => k >= 0);
+	let k = 0;
+	while (k < changed.length) {
+		let from = Math.max(0, changed[k] - 3);
+		let to = Math.min(ops.length, changed[k] + 4);
+		while (k + 1 < changed.length && changed[k + 1] - 3 <= to) to = Math.min(ops.length, changed[++k] + 4);
+		k++;
+		const hunk = ops.slice(from, to);
+		const aStart = ops.slice(0, from).filter((o) => o[0] !== '+').length + 1;
+		const bStart = ops.slice(0, from).filter((o) => o[0] !== '-').length + 1;
+		const aLen = hunk.filter((o) => o[0] !== '+').length;
+		const bLen = hunk.filter((o) => o[0] !== '-').length;
+		out.push(`@@ -${aLen ? aStart : aStart - 1},${aLen} +${bLen ? bStart : bStart - 1},${bLen} @@`);
+		for (const o of hunk) out.push(`${o[0]}${o[1]}`);
+	}
+	return out.join('\n');
+}
+
+function describe(change) {
+	switch (change.kind) {
+		case 'add':
+			return `  add     ${change.file}`;
+		case 'edit':
+			return `  edit    ${change.file}`;
+		case 'link':
+			return `  link    ${change.file} → ${change.target}`;
+		case 'unlink':
+			return `  unlink  ${change.file} (that skill is no longer in the package)`;
+		case 'schemas':
+			return `  ${change.before === null ? 'add   ' : change.after === null ? 'remove' : 'edit  '}  ${change.file}${change.generated ? ' (generated: caracms schemas)' : ''}`;
+	}
+}
+
+function report({ changes, notes, done }, { write, pm }) {
+	const parts = [];
+	if (changes.length === 0) {
+		parts.push('caracms init: nothing to do. caracms is set up here.');
+	} else {
+		parts.push(write ? 'caracms init: done. It changed:' : 'caracms init: the change it would make. Nothing is written: `caracms init --write` applies exactly this.');
+		parts.push(changes.map(describe).join('\n'));
+		if (!write) {
+			const diffs = changes.filter((c) => (c.kind === 'add' || c.kind === 'edit' || (c.kind === 'schemas' && !c.generated && c.after !== null)));
+			if (diffs.length) parts.push(diffs.map((c) => diff(c.file, c.before ?? null, c.after)).join('\n\n'));
+		}
+	}
+	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 (changes.length) {
+		const install = `${pm} install`;
+		parts.push(
+			write
+				? `Next: \`${install}\` (it adds @astrojs/node), commit this as one change, then follow the caracms-adopt skill to bring the pages in.`
+				: `Then, after --write: \`${install}\`, and the caracms-adopt skill.`,
+		);
+	}
+	return `${parts.join('\n\n')}\n`;
+}
+
+// ── Schemas ─────────────────────────────────────────────────────────────────────
+
+/** The schema and `$schema` changes, from the site's config through its Vite. A fresh site's are the starting config's. */
+async function schemaChanges(site) {
+	if (!site.setUp) return STARTING_SCHEMAS.map((file) => ({ kind: 'schemas', file, before: null, after: '', generated: true }));
+	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];
+	});
+}
+
+// ── The command ─────────────────────────────────────────────────────────────────
+
+/** The plan: problems (nothing happens when there are any), or the changes. */
+export async function plan(root, { write = 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);
+	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, changes, notes, done };
+}
+
+function apply(root, changes) {
+	for (const c of changes) {
+		const path = join(root, c.file);
+		switch (c.kind) {
+			case 'add':
+			case 'edit':
+				mkdirSync(dirname(path), { recursive: true });
+				writeFileSync(path, c.after);
+				break;
+			case 'link':
+				mkdirSync(dirname(path), { recursive: true });
+				if (c.replace) rmSync(path, { force: true });
+				symlinkSync(c.target, path);
+				break;
+			case 'unlink':
+				rmSync(path, { force: true });
+				break;
+			// 'schemas' is written by the schemas command, after everything else.
+		}
+	}
+}
+
+/**
+ * `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
+ */
+export async function run({ root, write = false, out = process.stdout, err = process.stderr }) {
+	const p = await plan(root, { write });
+	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;
+	}
+	if (write && p.changes.length) {
+		apply(root, p.changes);
+		if (p.changes.some((c) => c.kind === 'schemas')) {
+			try {
+				const { withPackageModule } = await import('./site-runner.mjs');
+				await withPackageModule(root, 'schemas', (m) => m.command(root));
+			} catch (error) {
+				err.write(`caracms init: the files are written, but the schemas couldn't be: ${error.message}\nFix that, then run \`caracms schemas\`.\n`);
+				return 1;
+			}
+		}
+	}
+	out.write(report(p, { write, pm: p.site.pm }));
+	return 0;
+}