caracms 0.3.3 → 0.3.4

package/bin/caracms.mjs

@@ -12,20 +12,22 @@
 // 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`.
+// gate (gate.mjs): robots.txt, the pre-launch password, `X-Robots-Tag`, a page beside a
+// folder of the same name, then Site Settings' redirects.
 //
 // 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), the site's address (Astro's `site` from
 //   dist/server/caracms-build.json, else SITE_URL, else RAILWAY_PUBLIC_DOMAIN),
 //   CARACMS_PRELAUNCH (`user:password`), CARACMS_CLIENT_IP_HEADER (else the detected
-//   host's default; with neither, it exits with the fix), and content/site-settings.json → brand.name.
+//   host's default; with neither, it exits with the fix), and content/site-settings.json →
+//   brand.name and redirects.
 
 import { existsSync, readFileSync } from 'node:fs';
 import { createServer } from 'node:http';
-import { join } from 'node:path';
-import { pathToFileURL } from 'node:url';
-import { createGate, describeClientIpSource, markProcessGated, parsePrelaunch, parseSiteUrl, publicAddress, readBuildInfo, readClientIpSource } from './gate.mjs';
+import { join, relative, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { createGate, describeClientIpSource, markProcessGated, parsePrelaunch, parseSiteUrl, publicAddress, readBuildInfo, readClientIpSource, readRedirects } from './gate.mjs';
 
 const USAGE = `Usage: caracms <command>, from the site's root
 
@@ -56,6 +58,20 @@ function readBrandName(root) {
 	}
 }
 
+/**
+ * The adapter's static files folder, as it finds it (@astrojs/node → resolveClientDir):
+ * the built server-to-client path from its options, applied to `dist/server` here.
+ * `dist/client` when the options don't say.
+ */
+function clientDirOf(options, root) {
+	const serverDir = join(root, 'dist/server');
+	try {
+		return resolve(serverDir, relative(fileURLToPath(new URL(options.server)), fileURLToPath(new URL(options.client))));
+	} catch {
+		return join(root, 'dist/client');
+	}
+}
+
 async function start() {
 	const root = process.cwd();
 	const entry = join(root, 'dist/server/entry.mjs');
@@ -87,7 +103,15 @@ async function start() {
 	const publicSite = publicAddress(process.env, readBuildInfo(root));
 	const siteUrl = publicSite?.value;
 	const prelaunch = process.env.CARACMS_PRELAUNCH;
-	const gate = createGate({ handler: built.handler, clientIpSource: ipSource.source, siteUrl, prelaunch, brandName: readBrandName(root) });
+	const gate = createGate({
+		handler: built.handler,
+		clientIpSource: ipSource.source,
+		siteUrl,
+		prelaunch,
+		brandName: readBrandName(root),
+		clientDir: clientDirOf(built.options, root),
+		redirects: readRedirects(root),
+	});
 
 	const server = createServer(gate);
 	server.on('error', (err) => fatal(err.message));

package/bin/gate.mjs

@@ -12,12 +12,17 @@
 //   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).
+//   4. A page beside a folder of the same name (`services/advisory.html` and
+//      `services/advisory/`) is asked for by its file: the adapter would look in the
+//      folder for an index.html and answer 404.
+//   5. Site Settings' redirects, on what would be a 404: a prerendered 404 page never
+//      reaches Astro's middleware (redirect-middleware.ts, which serves them in dev).
+//   6. The adapter's own handler (static files first, then Astro).
 
 import { createHash, timingSafeEqual } from 'node:crypto';
-import { readFileSync } from 'node:fs';
+import { readFileSync, statSync } from 'node:fs';
 import { isIP } from 'node:net';
-import { join } from 'node:path';
+import { join, resolve, sep } from 'node:path';
 import { CLOUDFLARE_IPV4, CLOUDFLARE_IPV6 } from './cloudflare-ips.mjs';
 
 /** The header the gate owns. */
@@ -199,6 +204,88 @@ export function parseSiteUrl(value) {
 	return { host: url.host.toLowerCase(), origin: url.origin, indexable };
 }
 
+// ── Pages beside a folder, and redirects ────────────────────────────────────────
+
+const isFile = (path) => {
+	try {
+		return statSync(path).isFile();
+	} catch {
+		return false;
+	}
+};
+const isDirectory = (path) => {
+	try {
+		return statSync(path).isDirectory();
+	} catch {
+		return false;
+	}
+};
+
+/**
+ * The file to serve for a page whose address is also a folder: with `build.format:
+ * 'file'`, `/services/advisory` is `services/advisory.html`, beside a `services/advisory/`
+ * folder of the pages under it. The adapter sees the folder, looks for its index.html
+ * and answers 404, so the gate asks for the `.html` itself. Null for anything else: a
+ * path the two views don't agree on, `/`, a trailing slash, a file extension, a folder
+ * with its own index.html, or no such file under `clientDir`.
+ */
+export function pageBesideFolder(clientDir, views) {
+	const path = views.full;
+	if (!clientDir || path === null || views.app !== path || path === '/' || path.endsWith('/')) return null;
+	if (/\.[^/]*$/.test(path.slice(path.lastIndexOf('/')))) return null;
+	const root = resolve(clientDir);
+	const folder = resolve(root, '.' + path);
+	if (!folder.startsWith(root + sep)) return null;
+	if (!isDirectory(folder) || isFile(join(folder, 'index.html')) || !isFile(folder + '.html')) return null;
+	return path + '.html';
+}
+
+/**
+ * Site Settings' redirects, as the package reads them (src/redirects.ts; kept in step by
+ * gate.test.ts): `/path` addresses without a trailing slash; an entry that isn't two of
+ * them, goes nowhere or repeats a `from` is dropped.
+ */
+export function redirectAddress(value) {
+	if (typeof value !== 'string') return null;
+	const v = value.trim();
+	if (!/^\/(?!\/)[^\s?#]*$/.test(v)) return null;
+	const trimmed = v.replace(/\/+$/, '');
+	return trimmed === '' ? '/' : trimmed;
+}
+
+export function parseRedirects(raw) {
+	if (!Array.isArray(raw)) return [];
+	const same = (a, b) => a.toLowerCase() === b.toLowerCase();
+	const out = [];
+	for (const entry of raw) {
+		if (!entry || typeof entry !== 'object' || Array.isArray(entry)) continue;
+		const from = redirectAddress(entry.from);
+		const to = redirectAddress(entry.to);
+		if (!from || !to || same(from, to) || out.some((r) => same(r.from, from))) continue;
+		out.push({ from, to });
+	}
+	return out;
+}
+
+/** Where a request for `pathname` (as sent) goes, or null: matched decoded, without a trailing slash; letter case counts. */
+export function redirectFor(list, pathname) {
+	let path = pathname;
+	try {
+		path = decodeURI(pathname);
+	} catch {}
+	path = path.replace(/\/+$/, '') || '/';
+	return list.find((r) => r.from === path)?.to ?? null;
+}
+
+/** `content/site-settings.json` → `redirects` under `root`, read once at start (the file is the build's). Empty when it's missing or unreadable. */
+export function readRedirects(root) {
+	try {
+		return parseRedirects(JSON.parse(readFileSync(join(root, 'content/site-settings.json'), 'utf8'))?.redirects);
+	} catch {
+		return [];
+	}
+}
+
 // ── 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. */
@@ -406,9 +493,9 @@ 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,
  *   clientIpSource: string, siteUrl?: string, prelaunch?: string, brandName?: string,
- *   log?: (line: string) => void }} options
+ *   clientDir?: string, redirects?: { from: string, to: string }[], log?: (line: string) => void }} options
  */
-export function createGate({ handler, clientIpSource, siteUrl, prelaunch, brandName, log = (line) => console.error(line) }) {
+export function createGate({ handler, clientIpSource, siteUrl, prelaunch, brandName, clientDir, redirects = [], 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);
@@ -481,7 +568,24 @@ export function createGate({ handler, clientIpSource, siteUrl, prelaunch, brandN
 		const robots = guarded ? NOINDEX_NOFOLLOW : indexable ? null : NOINDEX;
 		if (robots) holdHeader(res, ROBOTS_HEADER, robots);
 
-		// 4. The adapter.
+		if (req.method === 'GET' || req.method === 'HEAD') {
+			// 4. A page beside a folder of the same name, by its file.
+			// (As sent, plus `.html`: the views are decoded, the request target mustn't be.)
+			const file = guarded ? null : pageBesideFolder(clientDir, views);
+			const raw = rawPathOf(req.url);
+			if (file && raw !== null) {
+				req.url = raw + '.html' + req.url.slice(raw.length);
+			} else if (!guarded && redirects.length) {
+				// 5. A redirect, only where the site answers 404: a real page always wins.
+				const to = raw === null ? null : redirectFor(redirects, raw);
+				if (to) {
+					const query = req.url.indexOf('?');
+					redirectOn404(res, to + (query === -1 ? '' : req.url.slice(query)));
+				}
+			}
+		}
+
+		// 6. The adapter.
 		try {
 			const result = handler(req, res);
 			if (result && typeof result.catch === 'function') result.catch((err) => fail(res, err));
@@ -492,6 +596,53 @@ export function createGate({ handler, clientIpSource, siteUrl, prelaunch, brandN
 	return gate;
 }
 
+/**
+ * Turns the response into a 301 to `location` if the handler answers 404, however it
+ * writes it (`writeHead`, or a status and an implicit head on the first write or end).
+ * The 404's own headers and body are dropped; the held robots header stays.
+ */
+function redirectOn404(res, location) {
+	const writeHead = res.writeHead.bind(res);
+	const write = res.write.bind(res);
+	const end = res.end.bind(res);
+	let redirected = false;
+	const redirect = () => {
+		redirected = true;
+		for (const name of res.getHeaderNames()) res.removeHeader(name);
+		writeHead(301, { Location: location, 'Cache-Control': 'no-cache', 'Content-Length': 0 });
+		end();
+	};
+	const callback = (args) => {
+		const cb = args.find((a) => typeof a === 'function');
+		if (cb) queueMicrotask(cb);
+	};
+	const is404 = () => !res.headersSent && res.statusCode === 404;
+	res.writeHead = (status, ...rest) => {
+		if (redirected) return res;
+		if (status === 404 && !res.headersSent) {
+			redirect();
+			return res;
+		}
+		return writeHead(status, ...rest);
+	};
+	res.write = (...args) => {
+		if (!redirected && is404()) redirect();
+		if (redirected) {
+			callback(args);
+			return true;
+		}
+		return write(...args);
+	};
+	res.end = (...args) => {
+		if (!redirected && is404()) redirect();
+		if (redirected) {
+			callback(args);
+			return res;
+		}
+		return end(...args);
+	};
+}
+
 function fail(res, err) {
 	console.error('caracms start: the request failed:', err);
 	if (!res.headersSent) {

package/package.json

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

package/src/redirect-middleware.ts

@@ -10,6 +10,9 @@
  *   goes out with the Publish that moves the page. Re-read when the file changes
  *   (its modification time), so local edits apply at once.
  * - The editor's own paths (`/admin`, `/_caracms/`) are never redirected.
+ *
+ * This serves them in dev. A built site's 404 page is prerendered, sent without this
+ * middleware running, so `caracms start`'s gate (bin/gate.mjs) serves them there.
  */
 import { readFile, stat } from 'node:fs/promises';
 import { join } from 'node:path';