caracms 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Caracode
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,58 @@
-# Temporary Holding Version
+# caracms
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A visual CMS for Astro sites, with the content in git. Editors change a site in its own
+pages, at `/admin`; what they publish is JSON files in the site's repository, which the
+site builds from.
+
+**caracms is unsupported.** It's published so that the sites built on it can be installed
+and run by whoever looks after them. There's no issue tracker and no support: use it as it
+is, under the MIT license.
+
+## Start
+
+caracms goes into an existing Astro site (Astro 7, on Node 22.12 or later). From the
+site's root, in a clean git checkout, install it and commit the install:
+
+```sh
+npm install caracms --save-exact
+git add package.json package-lock.json
+git commit -m "Add caracms"
+```
+
+That commit matters: installing changes `package.json` and the lockfile, and
+`init --write` refuses while tracked files have uncommitted changes, so its own change is
+one diff to review. Then look at what `init` would do:
+
+```sh
+npx caracms init
+```
+
+It prints every file it would add and every edit it would make, as a diff, and changes
+nothing. When it looks right, apply it and install what it added:
+
+```sh
+npx caracms init --write
+npm install
+```
+
+`init` adds the plumbing (the Node adapter, the integration, a minimal `caracms.config.ts`
+and page component, the route that serves documents, the schemas) and links caracms's
+skills into `.claude/skills/`. It doesn't touch the site's pages. Bringing them in is the
+job of the `caracms-adopt` skill, one page at a time.
+
+## Commands
+
+Run from the site's root:
+
+- `caracms init [--write]`: add caracms to an Astro site, or bring a set-up site's skills,
+  schemas and CLAUDE.md block up to date.
+- `caracms validate [--fix] [--json]`: check the content against `caracms.config.ts`.
+  Exits 1 when there are errors. `--fix` runs `caracms schemas` first, then lays each
+  content file out as the editor saves it (two-space JSON; only whitespace changes).
+- `caracms schemas`: write `schemas/` from the config, and give each content file its
+  `$schema`.
+- `caracms media import <files…>`: put local images into the site's media bucket.
+- `caracms start`: serve the built site.
+
+The skills (`caracms-content`, `caracms-blocks` and `caracms-adopt`, in `skills/`) say how
+the rest works, matching the installed version.

package/bin/caracms.mjs

@@ -0,0 +1,174 @@
+#!/usr/bin/env node
+// The `caracms` command (M8 → Contracts): `init`, `schemas`, `validate`, `media import`
+// and `start`, each run from the site's root. Exit codes: 0 fine, 1 problems found or
+// refused, 2 bad usage.
+//
+// Plain JavaScript importing only Node built-ins, so it runs on Node 22.12 with no flags.
+// `schemas` and `validate` need the site's caracms.config.ts, which is TypeScript: they
+// load the package's src/cli/*.ts through the site's own Vite (site-runner.mjs).
+//
+// `caracms start`: the site's production server (M6 Decision 2).
+//
+// The Node adapter's standalone server sends prerendered pages and static files
+// before Astro's middleware runs, so a password or a `noindex` header can't be added
+// there. This serves the adapter's own handler (static files, then Astro) behind the
+// gate (gate.mjs): robots.txt, the pre-launch password, then `X-Robots-Tag`.
+//
+// It runs from the site's root (the directory with `dist/` and `content/`) and reads,
+// once at start:
+//   PORT (default 8080), HOST (default 0.0.0.0), SITE_URL, CARACMS_PRELAUNCH
+//   (`user:password`), and content/site-settings.json → brand.name.
+
+import { existsSync, readFileSync } from 'node:fs';
+import { createServer } from 'node:http';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { createGate, parsePrelaunch, parseSiteUrl } from './gate.mjs';
+
+const USAGE = `Usage: caracms <command>, from the site's root
+
+  init [--write]            Add caracms to an existing Astro site. Shows the change; --write applies it.
+  schemas                   Write schemas/ from caracms.config.ts, and add $schema to content files.
+  validate [--fix] [--json] Check content against caracms.config.ts. --fix runs \`schemas\` first,
+                            then lays content files out as the editor saves them;
+                            --json prints { errors, warnings }.
+  media import <files…>     Put local images into the site's media bucket; prints JSON.
+  start                     Serve the built site (dist/server/entry.mjs).
+`;
+
+/** The command running, for `fatal`'s sentence: set by `main`. */
+let running = '';
+
+const fatal = (message) => {
+	console.error(`caracms${running ? ` ${running}` : ''}: ${message}`);
+	process.exit(1);
+};
+
+function readBrandName(root) {
+	try {
+		const settings = JSON.parse(readFileSync(join(root, 'content/site-settings.json'), 'utf8'));
+		const name = settings?.brand?.name;
+		return typeof name === 'string' ? name : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+async function start() {
+	const root = process.cwd();
+	const entry = join(root, 'dist/server/entry.mjs');
+	if (!existsSync(entry)) fatal(`there's no ${entry}. Run \`astro build\` in the site's root first.`);
+
+	const portText = process.env.PORT ?? '';
+	const port = portText === '' ? 8080 : Number(portText);
+	if (!Number.isInteger(port) || port < 0 || port > 65535) fatal(`PORT must be a port number, not "${portText}".`);
+	const host = process.env.HOST || '0.0.0.0';
+
+	// A built site is a production server: the submissions store and the email sender read NODE_ENV (M6 Decision 7),
+	// and this command is the one thing that starts the built site. An explicit NODE_ENV is left as it is.
+	process.env.NODE_ENV ??= 'production';
+	// The adapter starts its own server on import unless told not to.
+	process.env.ASTRO_NODE_AUTOSTART = 'disabled';
+	const built = await import(pathToFileURL(entry).href);
+	if (typeof built.handler !== 'function') fatal(`${entry} exports no handler. Is the site built with @astrojs/node?`);
+	if (built.options && built.options.mode !== 'standalone') fatal(`the site's Node adapter must be in standalone mode, not "${built.options.mode}".`);
+
+	const siteUrl = process.env.SITE_URL;
+	const prelaunch = process.env.CARACMS_PRELAUNCH;
+	const gate = createGate({ handler: built.handler, siteUrl, prelaunch, brandName: readBrandName(root) });
+
+	const server = createServer(gate);
+	server.on('error', (err) => fatal(err.message));
+	server.listen(port, host, () => {
+		const address = server.address();
+		const shown = typeof address === 'object' && address ? `${address.address.includes(':') ? `[${address.address}]` : address.address}:${address.port}` : `${host}:${port}`;
+		const site = parseSiteUrl(siteUrl);
+		const indexing = site?.indexable ? `indexable on ${site.host} only` : 'never indexable (SITE_URL is unset, or not a custom domain)';
+		const password = parsePrelaunch(prelaunch) ? 'on (CARACMS_PRELAUNCH)' : 'off';
+		console.log(`caracms start: listening on http://${shown}\n  indexing: ${indexing}\n  pre-launch password: ${password}`);
+	});
+
+	const stop = () => {
+		server.close(() => process.exit(0));
+		server.closeIdleConnections?.();
+		setTimeout(() => process.exit(0), 10_000).unref();
+	};
+	process.once('SIGTERM', stop);
+	process.once('SIGINT', stop);
+}
+
+/** Bad usage: the sentence and the usage, exit 2. */
+function usage(message) {
+	process.stderr.write(`caracms: ${message}\n\n${USAGE}`);
+	process.exitCode = 2;
+}
+
+/** Load the package's src/cli/<name>.ts through the site's Vite and run its `command`. */
+async function viaSite(name, ...args) {
+	const { withPackageModule } = await import('./site-runner.mjs');
+	const root = process.cwd();
+	try {
+		const { code, out, err } = await withPackageModule(root, name, (m) => m.command(root, ...args));
+		if (out) process.stdout.write(out);
+		if (err) process.stderr.write(err);
+		process.exitCode = code;
+	} catch (error) {
+		// A CommandError (src/cli/site.ts) or the runner's own: one sentence, no stack.
+		process.stderr.write(`caracms ${name}: ${error?.message ?? String(error)}\n`);
+		process.exitCode = 1;
+	}
+}
+
+/** Flags out of `args`: every one must be in `allowed`; no other arguments. */
+function flags(command, args, allowed) {
+	const set = new Set();
+	for (const a of args) {
+		if (!allowed.includes(a)) return { error: `"${a}" isn't an option of ${command}.` };
+		set.add(a);
+	}
+	return { set };
+}
+
+async function main(argv) {
+	const [command, ...rest] = argv;
+	running = command === 'media' && rest[0] && !rest[0].startsWith('-') ? `media ${rest[0]}` : (command ?? '');
+	switch (command) {
+		case 'start':
+			if (rest.length) return usage(`start takes no arguments.`);
+			return start();
+		case 'init': {
+			const f = flags('init', rest, ['--write']);
+			if (f.error) return usage(f.error);
+			const { run } = await import('./init.mjs');
+			process.exitCode = await run({ root: process.cwd(), write: f.set.has('--write') });
+			return;
+		}
+		case 'schemas':
+			if (rest.length) return usage('schemas takes no arguments.');
+			return viaSite('schemas');
+		case 'validate': {
+			const f = flags('validate', rest, ['--fix', '--json']);
+			if (f.error) return usage(f.error);
+			return viaSite('validate', { fix: f.set.has('--fix'), json: f.set.has('--json') });
+		}
+		case 'media': {
+			// The media commands are their own module (bin/media.mjs): it takes the arguments after `media`.
+			const { run } = await import('./media.mjs');
+			process.exitCode = await run(rest);
+			return;
+		}
+		case undefined:
+			process.stdout.write(USAGE);
+			process.exitCode = 2;
+			return;
+		case '--help':
+		case '-h':
+		case 'help':
+			process.stdout.write(USAGE);
+			return;
+		default:
+			return usage(`unknown command "${argv.join(' ')}".`);
+	}
+}
+
+main(process.argv.slice(2)).catch((err) => fatal(err?.stack ?? String(err)));

package/bin/gate.mjs

@@ -0,0 +1,275 @@
+// The gate in front of the Node adapter's handler (M6 Decisions 2, 10, 11).
+//
+// Plain JavaScript with Node built-ins only: `caracms start` must run on Node 22.12
+// with no flags, so nothing here may import the package's TypeScript.
+//
+// Its order, per request:
+//   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`.
+//   3. `X-Robots-Tag` on the way out, kept whatever the adapter writes.
+//   4. The adapter's own handler (static files first, then Astro).
+
+import { createHash, timingSafeEqual } from 'node:crypto';
+
+/** The header the gate owns. */
+const ROBOTS_HEADER = 'X-Robots-Tag';
+const NOINDEX = 'noindex';
+const NOINDEX_NOFOLLOW = 'noindex, nofollow';
+
+/** Used when Site Settings has no brand name, or none that survives cleaning. */
+export const NEUTRAL_REALM_NAME = 'This site';
+
+// ── Paths ───────────────────────────────────────────────────────────────────────
+
+/** The path part of a request target, or null for anything but origin-form (`/…`). */
+function rawPathOf(url) {
+	if (typeof url !== 'string' || !url.startsWith('/')) return null;
+	const end = url.search(/[?#]/);
+	return end === -1 ? url : url.slice(0, end);
+}
+
+const safeDecode = (s) => {
+	try {
+		return decodeURIComponent(s);
+	} catch {
+		return null;
+	}
+};
+
+/** Resolves `.` and `..` segments on an absolute path, never above the root. */
+function resolveDots(path) {
+	const out = [];
+	const parts = path.split('/');
+	for (let i = 1; i < parts.length; i++) {
+		const part = parts[i];
+		if (part === '.') {
+			if (i === parts.length - 1) out.push('');
+		} else if (part === '..') {
+			out.pop();
+			if (i === parts.length - 1) out.push('');
+		} else out.push(part);
+	}
+	return '/' + out.join('/');
+}
+
+/**
+ * Two views of a path, and the gate only exempts what both agree on:
+ * - `app`: what Astro's router and the guard see. The adapter builds the request's
+ *   URL from the raw target (WHATWG resolves dot segments, `%2e` ones too), then the
+ *   guard decodes, turns backslashes into slashes and collapses repeated slashes.
+ * - `full`: decoded first, then slashes collapsed and dot segments resolved, so
+ *   `/_astro/..%2Fcontact` is `/contact`.
+ * Either is null when the path won't decode (or isn't a path at all).
+ */
+export function pathViews(url) {
+	const raw = rawPathOf(url);
+	if (raw === null) return { app: null, full: null };
+	let app = null;
+	try {
+		const decoded = safeDecode(new URL('http://gate.invalid' + raw).pathname);
+		if (decoded !== null) app = decoded.replace(/\\/g, '/').replace(/\/{2,}/g, '/');
+	} catch {}
+	const decoded = safeDecode(raw);
+	const full = decoded === null ? null : resolveDots(decoded.replace(/\\/g, '/').replace(/\/{2,}/g, '/'));
+	return { app, full };
+}
+
+/** The guard's prefix rule (`live/auth/guard.ts` → isGuardedPath) on a normalised path. */
+function isGuardedView(view) {
+	const path = view.toLowerCase();
+	return path === '/admin' || path.startsWith('/admin/') || path.startsWith('/admin.') || path === '/_caracms' || path.startsWith('/_caracms/');
+}
+
+/** The editor and its API: a path that won't decode counts, as in the guard. */
+export function isGuarded(views) {
+	if (views.app === null || views.full === null) return true;
+	return isGuardedView(views.app) || isGuardedView(views.full);
+}
+
+function isExemptView(view) {
+	return isGuardedView(view) || view.startsWith('/_astro/') || view === '/health';
+}
+
+/** Reached without the site's password: only when both views agree. */
+export function isPasswordExempt(views) {
+	if (views.app === null || views.full === null) return false;
+	return isExemptView(views.app) && isExemptView(views.full);
+}
+
+const isRobotsTxt = (views) => views.full === '/robots.txt';
+
+// ── Settings, read once at start ────────────────────────────────────────────────
+
+/** Strips what can't go in a quoted header value: quotes, backslashes, controls, non-ASCII. */
+export function cleanRealmName(name) {
+	if (typeof name !== 'string') return '';
+	return name
+		.replace(/[^\x20-\x7e]/g, '')
+		.replace(/["\\]/g, '')
+		.replace(/ {2,}/g, ' ')
+		.trim();
+}
+
+/** The pre-launch value with surrounding whitespace and newlines dropped (as `SITE_URL` is trimmed), or '' when it isn't a string. */
+const trimPrelaunch = (value) => (typeof value === 'string' ? value.trim() : '');
+
+/** `user:password`, split at the first colon, after trimming the whole value. Null (the site is public) unless both are there. */
+export function parsePrelaunch(raw) {
+	const value = trimPrelaunch(raw);
+	if (value === '') return null;
+	const colon = value.indexOf(':');
+	if (colon <= 0 || colon === value.length - 1) return null;
+	return { user: value.slice(0, colon) };
+}
+
+/** `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;
+	let url;
+	try {
+		url = new URL(value.trim());
+	} catch {
+		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');
+	return { host: url.host.toLowerCase(), origin: url.origin, indexable };
+}
+
+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
+ */
+export function createGate({ handler, siteUrl, prelaunch, brandName }) {
+	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)`;
+
+	const robotsIndexable = site ? `User-agent: *\nDisallow: /admin\nDisallow: /_caracms/\nSitemap: ${site.origin}/sitemap.xml\n` : '';
+	const robotsClosed = 'User-agent: *\nDisallow: /\n';
+
+	const isIndexableHost = (req) => {
+		if (!site || !site.indexable) return false;
+		const host = req.headers.host;
+		return typeof host === 'string' && host.toLowerCase() === site.host;
+	};
+
+	const hasPassword = (req) => {
+		const header = req.headers.authorization;
+		if (typeof header !== 'string') return false;
+		const match = /^\s*basic\s+(\S+)\s*$/i.exec(header);
+		if (!match) return false;
+		// Hashing both sides first gives equal lengths, so the comparison is constant-time
+		// whatever was sent.
+		return timingSafeEqual(sha256(Buffer.from(match[1], 'base64')), password);
+	};
+
+	const gate = (req, res) => {
+		const views = pathViews(req.url);
+		const indexable = isIndexableHost(req);
+
+		// 1. robots.txt, before the password.
+		if (isRobotsTxt(views)) {
+			const headers = { 'Content-Type': 'text/plain; charset=utf-8', 'Cache-Control': 'public, max-age=300' };
+			if (!indexable) headers[ROBOTS_HEADER] = NOINDEX;
+			if (req.method !== 'GET' && req.method !== 'HEAD') {
+				res.writeHead(405, { ...headers, Allow: 'GET, HEAD' });
+				res.end();
+				return;
+			}
+			const body = indexable ? robotsIndexable : robotsClosed;
+			res.writeHead(200, { ...headers, 'Content-Length': Buffer.byteLength(body) });
+			res.end(req.method === 'HEAD' ? undefined : body);
+			return;
+		}
+
+		const guarded = isGuarded(views);
+
+		// 2. The password.
+		if (password && !isPasswordExempt(views) && !hasPassword(req)) {
+			const body = "This site isn't launched yet.\n";
+			res.writeHead(401, {
+				'WWW-Authenticate': `Basic realm="${realm}"`,
+				[ROBOTS_HEADER]: guarded ? NOINDEX_NOFOLLOW : NOINDEX,
+				'Content-Type': 'text/plain; charset=utf-8',
+				'Content-Length': Buffer.byteLength(body),
+				'Cache-Control': 'no-store',
+			});
+			res.end(req.method === 'HEAD' ? undefined : body);
+			return;
+		}
+
+		// 3. The header, kept on whatever the adapter writes.
+		const robots = guarded ? NOINDEX_NOFOLLOW : indexable ? null : NOINDEX;
+		if (robots) holdHeader(res, ROBOTS_HEADER, robots);
+
+		// 4. The adapter.
+		try {
+			const result = handler(req, res);
+			if (result && typeof result.catch === 'function') result.catch((err) => fail(res, err));
+		} catch (err) {
+			fail(res, err);
+		}
+	};
+	return gate;
+}
+
+function fail(res, err) {
+	console.error('caracms start: the request failed:', err);
+	if (!res.headersSent) {
+		res.writeHead(500, { 'Content-Type': 'text/plain; charset=utf-8' });
+		res.end('Internal server error');
+	} else res.destroy();
+}
+
+/**
+ * Sets a header and keeps it: whatever the handler sets, appends, removes or passes
+ * to `writeHead` under that name is replaced by this value.
+ */
+function holdHeader(res, name, value) {
+	const lower = name.toLowerCase();
+	const isIt = (key) => typeof key === 'string' && key.toLowerCase() === lower;
+	const setHeader = res.setHeader.bind(res);
+	setHeader(name, value);
+
+	res.setHeader = (key, v) => (isIt(key) ? setHeader(name, value) : setHeader(key, v));
+	if (typeof res.appendHeader === 'function') {
+		const appendHeader = res.appendHeader.bind(res);
+		res.appendHeader = (key, v) => (isIt(key) ? setHeader(name, value) : appendHeader(key, v));
+	}
+	const removeHeader = res.removeHeader.bind(res);
+	res.removeHeader = (key) => (isIt(key) ? undefined : removeHeader(key));
+
+	const writeHead = res.writeHead.bind(res);
+	res.writeHead = (status, ...rest) => {
+		const i = rest.findIndex((a) => a !== undefined && typeof a !== 'string');
+		if (i !== -1) rest[i] = withHeader(rest[i], name, value, isIt);
+		if (!res.headersSent) setHeader(name, value);
+		return writeHead(status, ...rest);
+	};
+}
+
+/** A `writeHead` headers argument (object, `[k, v]` pairs or a flat list) with the held value. */
+function withHeader(headers, name, value, isIt) {
+	if (Array.isArray(headers)) {
+		if (headers.length > 0 && Array.isArray(headers[0])) {
+			return [...headers.filter(([k]) => !isIt(k)), [name, value]];
+		}
+		const out = [];
+		for (let i = 0; i < headers.length; i += 2) if (!isIt(headers[i])) out.push(headers[i], headers[i + 1]);
+		out.push(name, value);
+		return out;
+	}
+	if (headers && typeof headers === 'object') {
+		const out = {};
+		for (const key of Object.keys(headers)) if (!isIt(key)) out[key] = headers[key];
+		out[name] = value;
+		return out;
+	}
+	return headers;
+}