caracms 0.1.0 → 0.3.0

package/src/files-route.ts

@@ -29,7 +29,7 @@
  *    `CARACMS_PRELAUNCH` in this same process), so a shared cache never keeps it.
  */
 import type { APIRoute } from 'astro';
-import { clientIp } from './live/auth/request.ts';
+import { clientIp, NO_GATE_MESSAGE } from './live/auth/request.ts';
 import { fileAddress, fileKeyOf, fileTypeOf } from './files.ts';
 import { s3Bucket, type Bucket } from './editor/server/media/bucket.ts';
 import { readImagesConfig } from './editor/server/media/config.ts';
@@ -67,7 +67,7 @@ export interface FileRouteContext {
 	/** Default `process.env`, read on each request. */
 	env?: Env;
 	production?: boolean;
-	/** The socket's address (Astro's `clientAddress`), read after `X-Real-IP`. */
+	/** The socket's address (Astro's `clientAddress`), read after `X-Real-IP` under `astro dev`. */
 	clientAddress?: () => string | undefined;
 	/** Default the process's own (`filesLimiter`). */
 	limiter?: RateLimiter;
@@ -147,10 +147,15 @@ export async function handleFileRequest(request: Request, ctx: FileRouteContext
 		}
 	}
 
+	// Runs-anywhere Decision 8: a production server not started by `caracms start` has no gate, so no visitor's IP for the limit.
+	const production = ctx.production ?? isProductionBuild();
+	const ip = clientIp(request, ctx.clientAddress ?? (() => undefined), production);
+	if (ip === null) return text(503, NO_GATE_MESSAGE, {}, head);
+
 	// 4. The media variables.
 	const env = ctx.env ?? process.env;
 	const log = ctx.log ?? ((line: string) => console.error(line));
-	const config = readImagesConfig(env, ctx.production ?? isProductionBuild());
+	const config = readImagesConfig(env, production);
 	if (config.kind === 'unset') {
 		logOnce(log, `[caracms] files: /files/ answers 503: ${config.message}${config.missing.length ? ` (missing: ${config.missing.join(', ')})` : ''}`);
 		return text(503, UNAVAILABLE_TEXT, {}, head);
@@ -158,7 +163,7 @@ export async function handleFileRequest(request: Request, ctx: FileRouteContext
 
 	// 5. The visitor's allowance.
 	const limiter = ctx.limiter ?? filesLimiter(env);
-	if (await limiter.hit(clientIp(request, ctx.clientAddress ?? (() => undefined)))) {
+	if (await limiter.hit(ip)) {
 		return text(429, RATE_LIMITED_TEXT, { 'Retry-After': String(Math.ceil(FILES_LIMIT.windowMs / 1000)) }, head);
 	}
 

package/src/forms/endpoint.ts

@@ -37,8 +37,9 @@
  */
 import type { ResolvedSite } from '../config.ts';
 import { publicOrigin } from '../live/auth/index.ts';
-import { clientIp } from '../live/auth/request.ts';
+import { clientIp, NO_GATE_MESSAGE } from '../live/auth/request.ts';
 import { readCapped } from '../editor/server/media/upload.ts';
+import { isProductionBuild } from '../media.ts';
 import { readFormSettings, sendNotification, type FormSettings } from './email.ts';
 import { formLimiter, type FormRateLimiter } from './rate-limit.ts';
 import { cleanReturn, FILE_KINDS, FILE_TYPES, formsAcceptFiles, HONEYPOT, looksLikeEmail, MAX_FILE_BYTES, MAX_FILES, type ResolvedForm } from './rules.ts';
@@ -65,24 +66,14 @@ export const BAD_EMAIL_MESSAGE = "That email address doesn't look right.";
 export const TURNSTILE_VERIFY_URL = 'https://challenges.cloudflare.com/turnstile/v0/siteverify';
 const TURNSTILE_TIMEOUT_MS = 5_000;
 
-/** `SITE_URL` as an address (an http(s) origin), or undefined when it's unset or isn't one. */
-function siteUrlFromEnv(env: Env): URL | undefined {
-	const raw = env['SITE_URL']?.trim();
-	if (!raw) return undefined;
-	try {
-		const url = new URL(raw);
-		return url.protocol === 'https:' || url.protocol === 'http:' ? url : undefined;
-	} catch {
-		return undefined;
-	}
-}
-
 export { cleanReturn };
 
 export interface FormContext {
 	site: Pick<ResolvedSite, 'root' | 'forms' | 'timeZone'>;
-	/** The socket's address (Astro's `clientAddress`), read after `X-Real-IP`. */
+	/** The socket's address (Astro's `clientAddress`), read after `X-Real-IP` under `astro dev`. */
 	clientAddress?: () => string | undefined;
+	/** A production server: the IP comes from `caracms start`'s gate only (runs-anywhere Decision 8). Default: the build's define. */
+	production?: boolean;
 	env?: Env;
 	/** Astro's `site` (the route passes `context.site`): the public origin for the email's editor link. */
 	astroSite?: URL;
@@ -244,7 +235,11 @@ export async function handleForm(request: Request, ctx: FormContext): Promise<Re
 		return reply(405, { error: 'This address takes a form post.' }, { Allow: 'POST' });
 	}
 
-	const ip = clientIp(request, ctx.clientAddress ?? (() => undefined));
+	const ip = clientIp(request, ctx.clientAddress ?? (() => undefined), ctx.production ?? isProductionBuild());
+	if (ip === null) {
+		await request.body?.cancel().catch(() => {});
+		return reply(503, { error: NO_GATE_MESSAGE });
+	}
 	const takesFiles = formsAcceptFiles(ctx.site.forms);
 	const declared = Number(request.headers.get('content-length') ?? NaN);
 	const multipart = (request.headers.get('content-type') ?? '').toLowerCase().includes('multipart/form-data');
@@ -332,7 +327,7 @@ export async function handleForm(request: Request, ctx: FormContext): Promise<Re
 	let email;
 	try {
 		const settings = await (ctx.readSettings ?? (() => readFormSettings(ctx.site.root)))();
-		const siteUrl = publicOrigin(ctx.astroSite ?? siteUrlFromEnv(env), env);
+		const siteUrl = publicOrigin(ctx.astroSite, env);
 		email = await sendNotification({ submission, form, settings, siteUrl, timeZone: ctx.site.timeZone, env, fetch: ctx.fetch, now, log });
 	} catch (error) {
 		email = { status: 'failed' as const, at: now().toISOString(), to: [], error: `Could not read Site Settings: ${error instanceof Error ? error.message : String(error)}` };

package/src/forms/rules.ts

@@ -43,6 +43,8 @@ export interface FormFieldConfig {
 	 * Plain text, trimmed; blank is the same as leaving it out.
 	 */
 	prefix?: string;
+	/** A textarea's height in lines (`rows`), a whole number from 1 to 50. Default 6. Textarea only. */
+	rows?: number;
 }
 
 /** One form (Contracts → The forms config). Its key is its id: stored on submissions, keys `formRecipients`; never renamed once live. */
@@ -66,6 +68,7 @@ export interface ResolvedFormField {
 	error?: string;
 	placeholder?: string;
 	prefix?: string;
+	rows?: number;
 }
 
 /** A form as the package uses it: its fields as a list, in order, each with its type. Plain JSON. */
@@ -122,7 +125,7 @@ export const FILE_ACCEPT = Object.keys(FILE_TYPES)
 	.join(',');
 
 /** The types that take a placeholder: the ones a visitor types into. */
-const PLACEHOLDER_TYPES: readonly FormFieldType[] = ['text', 'email', 'tel', 'textarea'];
+export const PLACEHOLDER_TYPES: readonly FormFieldType[] = ['text', 'email', 'tel', 'textarea'];
 /** The types that take a prefix: a one-line box where a fixed lead-in reads naturally ("$", "+353"). */
 const PREFIX_TYPES: readonly FormFieldType[] = ['text', 'tel'];
 
@@ -188,6 +191,10 @@ export function checkForms(forms: unknown, fail: (message: string) => never): Re
 			if (placeholder && !PLACEHOLDER_TYPES.includes(type)) fail(`${at}: a ${type} field has no box to type in, so it can't take a placeholder (only ${PLACEHOLDER_TYPES.join(', ')} can).`);
 			const prefix = field.prefix?.trim() ?? '';
 			if (prefix && !PREFIX_TYPES.includes(type)) fail(`${at}: only a text or tel field takes a prefix (this one is ${type}).`);
+			if (field.rows !== undefined) {
+				if (type !== 'textarea') fail(`${at}: only a textarea takes rows (this one is ${type}).`);
+				if (!Number.isInteger(field.rows) || field.rows < 1 || field.rows > 50) fail(`${at}: rows must be a whole number from 1 to 50 (got ${JSON.stringify(field.rows)}).`);
+			}
 			fields.push({
 				name,
 				label: field.label!.trim(),
@@ -199,6 +206,7 @@ export function checkForms(forms: unknown, fail: (message: string) => never): Re
 				...(field.error ? { error: field.error } : {}),
 				...(placeholder ? { placeholder } : {}),
 				...(prefix ? { prefix } : {}),
+				...(field.rows !== undefined ? { rows: field.rows } : {}),
 			});
 		}
 		const email = fields.find((f) => f.name === 'email');

package/src/head.ts

@@ -4,7 +4,8 @@
  *
  * - **Title:** the page's `seo.title` as written; otherwise, for the home page, Site
  *   Settings' `seo.title`, then the brand's name; otherwise `<document title> · <brand name>`,
- *   where ` · ` is the config's `titleSeparator` (default ` · `, M8 trial round 2).
+ *   where ` · ` is the config's `titleSeparator` (default ` · `, M8 trial round 2). With the
+ *   config's `titleFallback: 'site'` (M9), every page falls back as the home page does.
  * - **Description and share image** fall back from the page's `seo` to Site Settings'.
  * - **Canonical link and `og:url`** only with the site's address (`SITE_URL`), and never
  *   in a preview.
@@ -13,7 +14,7 @@
  * - **The Google tag** is an ID, never a script: `GTM-…` loads Tag Manager, `G-…` loads
  *   gtag.js, anything else nothing. Only in a production build, never in a preview.
  */
-import { DEFAULT_TITLE_SEPARATOR } from './config.ts';
+import { DEFAULT_TITLE_SEPARATOR, type TitleFallback } from './config.ts';
 import { parseSettingsBrand, type PageDocument } from './document.ts';
 import { imageUrl, isResizable, type MediaConfig } from './media.ts';
 import { googleTagKind, parseGoogleTag, parseSeo, SHARE_IMAGE, type Seo, type SeoImage } from './seo.ts';
@@ -33,6 +34,8 @@ export interface HeadInput {
 	listPage?: number;
 	/** The config's `titleSeparator` (ResolvedSite), spaces included; ` · ` when left out. */
 	titleSeparator?: string;
+	/** The config's `titleFallback` (ResolvedSite); `'page-and-brand'` when left out. */
+	titleFallback?: TitleFallback;
 }
 
 export interface Head {
@@ -73,7 +76,8 @@ export function headOf(input: HeadInput): Head {
 	const docTitle = document.title.trim();
 	// Decision 16: " — page N" straight after the page's own part, before the brand, so ten pages don't share one title.
 	const paged = (text: string) => (input.listPage && input.listPage > 1 && text ? `${text} — page ${input.listPage}` : text);
-	const fallback = home ? paged(settings.seo.title || settings.brandName || docTitle) : [paged(docTitle), settings.brandName].filter(Boolean).join(input.titleSeparator ?? DEFAULT_TITLE_SEPARATOR);
+	const siteWide = home || input.titleFallback === 'site';
+	const fallback = siteWide ? paged(settings.seo.title || settings.brandName || docTitle) : [paged(docTitle), settings.brandName].filter(Boolean).join(input.titleSeparator ?? DEFAULT_TITLE_SEPARATOR);
 	const title = paged(own.title ?? '') || fallback;
 	const imageValue = own.image ?? settings.seo.image ?? null;
 	const image = imageValue ? shareImage(imageValue, input.media) : null;
@@ -100,12 +104,20 @@ export function googleTagSnippet(tag: NonNullable<Head['googleTag']>): string {
 	return `<script async src="https://www.googletagmanager.com/gtag/js?id=${encodeURIComponent(tag.id)}"></script><script>window.dataLayer=window.dataLayer||[];function gtag(){dataLayer.push(arguments);}gtag('js',new Date());gtag('config',${id});</script>`;
 }
 
+/**
+ * An address served from a `build.format: 'file'` prerender (`/about.html`, Home at
+ * `/index.html`) as the page's own address (`/about`, `/`): a document's address never ends in
+ * `.html` (Urban Return port). Others are kept as they are.
+ */
+export const withoutHtml = (path: string): string => path.replace(/(?:\/index)?\.html$/, '') || '/';
+
 /**
  * PageProps' `path` (MEC trial item 2): the document's address, the same in a public render
  * and in its preview. A preview's is `previewUrl`, its document's URL (content.ts →
  * documentUrl; null when it has no page). A public render's is the address it's served at,
  * decoded, with no trailing slash, and a paged listing's `/page/N` taken off (`listPage` > 1):
- * `/journal/page/2` is `/journal`'s page 2.
+ * `/journal/page/2` is `/journal`'s page 2. A `build.format: 'file'` prerender's `.html` comes
+ * off too (`withoutHtml`).
  */
 export function documentPath(input: { preview: boolean; previewUrl: string | null; pathname: string; listPage: number }): string | null {
 	if (input.preview) return input.previewUrl === null ? null : cleanPath(input.previewUrl) || '/';
@@ -116,6 +128,7 @@ export function documentPath(input: { preview: boolean; previewUrl: string | nul
 		// Not valid percent-encoding: kept as it came.
 	}
 	path = cleanPath(path) || '/';
+	path = withoutHtml(path);
 	if (input.listPage > 1) path = path.replace(new RegExp(`/page/${input.listPage}$`), '') || '/';
 	return path;
 }

package/src/index.ts

@@ -48,7 +48,8 @@
  */
 import type { AstroIntegration } from 'astro';
 import { fontProviders } from 'astro/config';
-import { readFileSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { isAbsolute, join, sep } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
@@ -59,6 +60,7 @@ import { writeSchemaFiles } from './cli/schemas.ts';
 import { configFile } from './cli/site.ts';
 import { readCodeRoutes } from './code-routes-disk.ts';
 import { GUARD_MIDDLEWARE, LOGIN_ROUTES } from './live/auth/routes.ts';
+import { HOST_COMMIT_VARIABLES } from './live/mode.ts';
 
 
 export type { SiteConfig, ResolvedSite } from './config.ts';
@@ -169,6 +171,25 @@ export function siteAddress(astroSite: string | undefined, env: Record<string, s
 	return { url: `${url.origin}${url.pathname}`.replace(/\/+$/, ''), problem: null };
 }
 
+/**
+ * Runs-anywhere Decision 9: the commit a build is made from, baked into the server.
+ * CARACMS_RUNNING_COMMIT or a host's commit variable at build, else `git rev-parse HEAD`
+ * when the build has a `.git` folder (Railway's and most Docker builds don't); null
+ * when neither. A value at run time wins over it (live/mode.ts → `runningCommitFrom`).
+ */
+export function buildCommit(root: string, env: Record<string, string | undefined> = process.env): string | null {
+	for (const name of ['CARACMS_RUNNING_COMMIT', ...HOST_COMMIT_VARIABLES]) {
+		const v = env[name]?.trim();
+		if (v) return v;
+	}
+	try {
+		const sha = execFileSync('git', ['rev-parse', 'HEAD'], { cwd: root, stdio: ['ignore', 'pipe', 'ignore'], timeout: 5000 }).toString().trim();
+		return /^[0-9a-f]{40}$/.test(sha) ? sha : null;
+	} catch {
+		return null;
+	}
+}
+
 /** Pre-M7 item 8: Site Settings' redirects, served as 301s on the public site. */
 export const REDIRECT_MIDDLEWARE = 'redirect-middleware.ts';
 
@@ -198,10 +219,11 @@ export function contentWatchIgnores(site: Pick<ResolvedSite, 'collections' | 'ro
 /**
  * The hosts Astro may take a request's address from (`security.allowedDomains`).
  * Without them, Astro ignores the Host header and every request reads as
- * `localhost:<port>`. Behind Railway's edge that breaks the same-origin checks on the
+ * `localhost:<port>`. Behind a host's proxy that breaks the same-origin checks on the
  * sign-in form and the editor's writes, and the addresses the pages show. Taken from
- * Astro's `site`, then Railway's public domain: the same sources as emailed links
- * (live/auth/index.ts → `publicOrigin`). A site's own `allowedDomains` wins.
+ * Astro's `site` (SITE_URL when the config sets none: `siteAddress`), then Railway's
+ * public domain: the same chain as emailed links (live/mode.ts → `addressFrom`;
+ * runs-anywhere Decision 7). A site's own `allowedDomains` wins.
  * Read at build time: Astro puts the list in the server's manifest.
  */
 export function trustedDomains(
@@ -301,8 +323,23 @@ async function loadSiteEnv(mode: string, root: string): Promise<Record<string, s
 	return loadEnv(mode, root, '');
 }
 
+/**
+ * Runs-anywhere Decisions 7 and 9: what a build baked in, also written beside the server's
+ * entry (`dist/server/caracms-build.json`) for `caracms start`'s gate, which can't import
+ * the site: `{ "site": "https://fernhill.ie" | null, "commit": "<sha>" | null }`. `site` is
+ * Astro's `site` as built (the config's, else SITE_URL's: `siteAddress`); `commit` is
+ * `buildCommit()`'s.
+ */
+export const BUILD_INFO_FILE = 'caracms-build.json';
+export interface BuildInfo {
+	site: string | null;
+	commit: string | null;
+}
+
 export default function caracms(config: SiteConfig): AstroIntegration {
 	let site: ResolvedSite;
+	let buildInfo: BuildInfo | null = null;
+	let serverDir: URL | null = null;
 	return {
 		name: 'caracms',
 		hooks: {
@@ -369,8 +406,10 @@ export default function caracms(config: SiteConfig): AstroIntegration {
 				const domains = trustedDomains(astroConfig.site ?? address.url ?? undefined, astroConfig.security?.allowedDomains);
 				if (command === 'build' && !astroConfig.security?.allowedDomains?.length) {
 					if (domains.length) logger.info(`trusting the Host header for ${domains.map((d) => d.hostname).join(', ')}`);
-					else logger.warn("the site's public address isn't known (set Astro's `site`, or build on Railway): behind a proxy, sign-in and the editor's saves will be refused as cross-origin.");
+					else logger.warn("the site's public address isn't known (set SITE_URL, at build and at run time): behind a proxy, sign-in and the editor's saves will be refused as cross-origin.");
 				}
+				const commit = dev ? null : buildCommit(site.root);
+				if (command === 'build') buildInfo = { site: address.url, commit };
 
 				updateConfig({
 					...(!astroConfig.site && address.url ? { site: address.url } : {}),
@@ -382,6 +421,9 @@ export default function caracms(config: SiteConfig): AstroIntegration {
 						define: {
 							__CARACMS_HARFBUZZ__: JSON.stringify(harfbuzz),
 							__CARACMS_PRODUCTION__: JSON.stringify(!dev),
+							// Runs-anywhere Decisions 7 and 9: the address and the commit the build was made with (editor/server/mode.ts → bakedAtBuild).
+							__CARACMS_SITE__: JSON.stringify(astroConfig.site ?? address.url ?? null),
+							__CARACMS_BUILD_COMMIT__: JSON.stringify(commit),
 							__CARACMS_TOKENS_CSS__: JSON.stringify(readFileSync(new URL('./editor/styles/tokens.css', import.meta.url), 'utf8')),
 						},
 						// Installed from npm, the package ships TypeScript and .astro source.
@@ -425,8 +467,12 @@ export default function caracms(config: SiteConfig): AstroIntegration {
 			},
 			// Posts and tags, Decision 15: a production build reads each document once (read.ts). Never in dev.
 			'astro:build:start': () => shareBuildReads(true),
-			'astro:build:done': () => shareBuildReads(false),
-			'astro:config:done': ({ injectTypes }) => {
+			'astro:build:done': () => {
+				shareBuildReads(false);
+				if (buildInfo && serverDir && existsSync(serverDir)) writeFileSync(new URL(BUILD_INFO_FILE, serverDir), `${JSON.stringify(buildInfo)}\n`);
+			},
+			'astro:config:done': ({ injectTypes, config: done }) => {
+				serverDir = done.build.server;
 				injectTypes({ filename: 'caracms.d.ts', content: '/// <reference types="caracms/virtual" />\n' });
 			},
 		},

package/src/links.ts

@@ -76,6 +76,41 @@ export function normaliseAddress(url: string): string {
  * `/`, `/about`, `/journal/my-first-post`), from the store's listing (Phase 2
  * wires it). Never an error: a warning the field shows.
  */
+/** M9 Decision 7: the hidden pages in a listing, as `WarningContext.hiddenPages` takes them (address → name). */
+export function hiddenPages(entries: Iterable<{ url: string | null; label: string; hidden?: true }>): Map<string, string> {
+	const out = new Map<string, string>();
+	for (const e of entries) if (e.hidden && e.url !== null) out.set(normaliseAddress(e.url), e.label);
+	return out;
+}
+
+/** M9 Decision 7: the hidden documents in a listing, as `WarningContext.hiddenDocuments` takes them (`collection/path` → name and address). */
+export function hiddenDocuments(entries: Iterable<{ collection: string; path: string; url: string | null; label: string; hidden?: true }>): Map<string, { label: string; url: string | null }> {
+	const out = new Map<string, { label: string; url: string | null }>();
+	for (const e of entries) if (e.hidden) out.set(`${e.collection}/${e.path}`, { label: e.label, url: e.url === null ? null : normaliseAddress(e.url) });
+	return out;
+}
+
+/**
+ * M9 Decision 7's warning for a reference (a `reference()` field) to a hidden page, worded as
+ * the link one is. Never an error: unhiding the page fixes it.
+ */
+export function hiddenReferenceTarget(collection: string, path: string, hidden: ReadonlyMap<string, { label: string; url: string | null }>): string | undefined {
+	const doc = hidden.get(`${collection}/${path}`);
+	if (!doc) return undefined;
+	return `Points at ${doc.url ?? path}, the ${doc.label || path} page, which is hidden from the site. Visitors get its 404 until it's shown again.`;
+}
+
+/**
+ * M9 Decision 7's warning: a link to a hidden page. `hidden` maps a hidden page's address
+ * (normalised) to its name. Never an error: unhiding the page fixes it.
+ */
+export function hiddenLinkTarget(href: unknown, hidden: ReadonlyMap<string, string>): string | undefined {
+	const path = internalLinkPath(href);
+	if (path === null) return undefined;
+	const name = hidden.get(path);
+	return name === undefined ? undefined : `Links to ${path}, the ${name} page, which is hidden from the site. Visitors get its 404 until it's shown again.`;
+}
+
 export function missingLinkTarget(href: unknown, addresses: Iterable<string | null | undefined>): string | undefined {
 	const path = internalLinkPath(href);
 	if (path === null) return undefined;

package/src/live/README.md

@@ -13,12 +13,15 @@ live drafts store, sweep, locks and status route, and Phase 3's sign-in, sit on
 | `merge.ts` | `mergeFile({ base, draft, other })`: the per-key three-way merge, pure and byte-preserving |
 | `messages.ts` | The commit-message contract (`draftMessage`, `mergeMessage`, `publishMessage`, `parseMessage`), `Person`, `displayName` |
 | `status.ts` | Pure: `waitingFromCommits()`, `publishState()`, `PublishRecord` |
-| `redis.ts` | `RedisClient`; `connectRedis(url)` (ioredis with M1 → R2's retry and idle close) and `memoryRedis()` (the stand-in, with `calls` and `flush()`) |
+| `redis.ts` | `RedisClient`; `connectRedis(url)` (ioredis with M1 → R2's retry and idle close) and `memoryRedis()` (the stand-in, with `calls` and `flush()`). Redis diet: `batch()`, a pipeline sent again whole only when every command in it is safe to send twice |
+| `status-cache.ts` | Redis diet. `StatusCache` (one per process, `git.statusCache`): what the status poll reads, by Redis key, re-read once 30 s old, refreshes single-flight; the modules that write Redis tell it what landed (`string`, `hash`, `add`, `drop`, `landed`) |
+| `notices.ts` | Redis diet. `Notices`: "published as it stood" notices and dismissed "draft kept" ones, written through the status cache |
 | `backend.ts` | `GitBackend`; `GitHubBackend`, `MemoryBackend` (test helpers: `seed`, `push`, `file`, `deployments`, `beforeRequest`); `StaleHeadError` |
+| `branches.ts` | `Branch` (a role: `main` or `drafts`), `BranchNames` (the refs behind them), `DEFAULT_BRANCHES`. `CARACMS_MAIN_BRANCH` and `CARACMS_DRAFTS_BRANCH` (read by `mode.ts`, M9 Decision 6) name the branch Publish commits to and the one autosaves land on; unset, `main` and `drafts`. They're set together or not at all: one alone is a problem, so the mode is unconfigured (`/admin` answers 503 saying both must be set; the public site still serves). Only the backends turn a role into a ref name, so with both set a branch called `main` is never read or moved. `MemoryBackend.refs` is keyed by name |
 | `github.ts` | The App's JWT, the installation token (one repo, refreshed early), `Tracker` (request counts) |
 | `webhook.ts` | `handleGithubWebhook()`, behind `POST /_caracms/github` (`../editor/routes/github.ts`) |
 | `autosaves.ts` | Phase 2. Autosaves in Redis (`caracms:autosave:<file>`, a week; stored compare-and-set, ordered per tab by `X-Caracms-Seq`), the session's last commit (the merge's ancestor) and who last changed a document (Decision 11; no expiry, and `known: false` when neither Redis nor git can say). M5a: a new document's autosave carries `created: { over }` (its ancestor until committed), a deletion is a "gone" autosave (`text` and `document` null, `gone: { title }`) |
-| `locks.ts` | Phase 2. `Locks`: taken by the first write, heartbeat on the poll, lapse only once committed, releasing, Edit here; presence |
+| `locks.ts` | Phase 2. `Locks`: taken by the first write, heartbeat on the poll (Redis diet: only when `needsBeat`), lapse only once committed, releasing, Edit here; presence, each record holding for twice its tab's poll interval plus 3 s |
 | `sweep.ts` | Phase 2. `Sweep`: one commit per tick for everything ready; ticks only while something is pending (no Redis call otherwise); `commitAll` fills `git.commitPending` |
 | `drafts-store.ts` | Phase 2. The live `DraftsStore`: the copy with autosaves on top (a gone one leaves the file out); `write` takes the lock and stores the autosave. M5a Phase 3: `create` (the lock, then the new document as an autosave) and `delete` (the lock, then a gone autosave, the lock released to drop once committed), with `editor/server/create.ts`'s rules. M5a: any kind of document; Site Settings' autosave is marked `sweepAtOnce` (the sweep commits it on its next tick, no idle wait); `source()` is the copy with every autosave on top (a preview's reads) |
 | `editor.ts` | Phase 2. `createLiveEditor(runtime)` / `liveEditor(site, settings)`: the store, sweep and locks, and the handlers for write, status, lock, publish, history, try-again, notice |

package/src/live/auth/auth.ts

@@ -65,6 +65,8 @@ export interface AuthOptions {
 
 export interface Auth {
 	readonly secure: boolean;
+	/** The site's public origin (`AuthOptions.siteOrigin`): the mismatch sentences name it (runs-anywhere Decision 7). */
+	readonly siteOrigin: string | null;
 	readonly cookieName: string;
 	readonly whitelist: Whitelist;
 	readonly links: LinkStore;
@@ -97,6 +99,7 @@ export function createAuth(options: AuthOptions): Auth {
 
 	return {
 		secure: options.secure,
+		siteOrigin: options.siteOrigin,
 		cookieName,
 		whitelist,
 		links,
@@ -136,7 +139,7 @@ export function createAuth(options: AuthOptions): Auth {
 					const emailing = options.env['NODE_ENV'] === 'production';
 					const origin = options.siteOrigin ?? (emailing ? null : requestOrigin);
 					if (!origin) {
-						log("no sign-in link sent: the site's public address isn't known (set Astro's `site`, or run on Railway, which sets RAILWAY_PUBLIC_DOMAIN).");
+						log("no sign-in link sent: the site's public address isn't known (set SITE_URL, when the site is built and when it runs).");
 						return 'not-sent';
 					}
 					const token = await links.issue(email, next);

package/src/live/auth/guard.ts

@@ -22,7 +22,7 @@
  */
 import type { Person } from '../messages.ts';
 import type { Auth, SignedOutReason } from './auth.ts';
-import { isRead, isSameOrigin } from './request.ts';
+import { addressMismatch, isRead, isSameOrigin } from './request.ts';
 import { cleanNext, LOGIN_PATH, loginHref } from './session.ts';
 
 /** Whether the guard looks at this path at all. */
@@ -93,7 +93,8 @@ export function guard(request: Request, auth: Auth): GuardResult {
 	const api = isApi(raw);
 
 	if (!isRead(request.method) && !isSameOrigin(request)) {
-		const error = 'This only takes requests from the editor on this site.';
+		// Runs-anywhere Decision 7: the editor's own write, refused because the site's address isn't the one in use.
+		const error = addressMismatch(request, auth.siteOrigin) ?? 'This only takes requests from the editor on this site.';
 		if (api) return { kind: 'respond', response: json(403, { error, code: 'cross-origin' } satisfies ForbiddenBody) };
 		return { kind: 'respond', response: new Response(error, { status: 403, headers: { 'Content-Type': 'text/plain; charset=utf-8', ...NO_STORE } }) };
 	}

package/src/live/auth/index.ts

@@ -19,7 +19,7 @@
  */
 import { SITE_SETTINGS_FILE, type ResolvedSite } from '../../config.ts';
 import { brandFrom } from '../../editor/brand.ts';
-import type { LiveSettings } from '../mode.ts';
+import { addressFrom, type LiveSettings } from '../mode.ts';
 import { liveRuntime } from '../runtime.ts';
 import { createAuth, type Auth } from './auth.ts';
 
@@ -27,13 +27,12 @@ const SHARED = Symbol.for('caracms.auth');
 type Shared = { [SHARED]?: Promise<Auth> };
 
 /**
- * The site's public origin for emailed links: Astro's `site`, else Railway's public
- * domain. Never a request's Host header (auth.ts → `siteOrigin`).
+ * The site's public origin for emailed links: Astro's `site`, then SITE_URL, then
+ * Railway's public domain (runs-anywhere Decision 7: the chain is mode.ts → `addressFrom`).
+ * Never a request's Host header (auth.ts → `siteOrigin`).
  */
 export function publicOrigin(astroSite: URL | undefined, env: Record<string, string | undefined> = process.env): string | null {
-	if (astroSite) return astroSite.origin;
-	const domain = env['RAILWAY_PUBLIC_DOMAIN']?.trim();
-	return domain ? `https://${domain}` : null;
+	return addressFrom(env, astroSite?.href);
 }
 
 /** The process's Auth, built on first use over the shared live runtime. */
@@ -50,7 +49,7 @@ export function authFor(site: ResolvedSite, settings: LiveSettings, astroSite?:
 				readSettings: () => rt.git.read(SITE_SETTINGS_FILE),
 				// M5a Decision 10: Site Settings' brand name as committed in `drafts`.
 				siteName: () => brandFrom(rt.git.read(SITE_SETTINGS_FILE), site).name,
-				siteOrigin: publicOrigin(astroSite),
+				siteOrigin: settings.address ?? publicOrigin(astroSite),
 				env: process.env,
 				now: rt.now,
 			}),

package/src/live/auth/login.ts

@@ -37,7 +37,7 @@
  */
 import type { Auth } from './auth.ts';
 import { normaliseEmail } from './allow.ts';
-import { clientIp, isRead, isSameOrigin } from './request.ts';
+import { addressMismatch, addressNotice, clientIp, isRead, isSameOrigin, NO_GATE_MESSAGE } from './request.ts';
 import { backupPerson, cleanNext, DEFAULT_NEXT, LOGIN_PATH, loginHref, safeEqual } from './session.ts';
 import {
 	backupView,
@@ -115,8 +115,17 @@ export async function handleLogin(request: Request, ctx: LoginContext): Promise<
 		extra.Allow = allow;
 		return page(405, 'Not allowed', messageView('Not allowed', 'Use the form on the sign-in page.'));
 	};
-	const crossOrigin = () => page(403, 'Not allowed', messageView('Not allowed', 'Send the form from the sign-in page.'));
+	// Runs-anywhere Decision 7: refused because the site's address isn't the one in use, the sentence says so, naming SITE_URL.
+	const mismatch = () => addressMismatch(request, auth.siteOrigin);
+	const crossOrigin = () => page(403, 'Not allowed', messageView('Not allowed', mismatch() ?? 'Send the form from the sign-in page.'));
 	const wantsJson = (request.headers.get('accept') ?? '').includes('application/json');
+	// Runs-anywhere Decision 8: on a production server (`auth.secure` is production), the IP
+	// comes from `caracms start`'s gate alone; without it, no sign-in at all (acceptance check 17).
+	const ip = clientIp(request, ctx.clientAddress, auth.secure);
+	if (ip === null) {
+		if (pathname === SIGNIN_PATH || wantsJson) return json(503, { error: NO_GATE_MESSAGE, reason: 'failed' });
+		return page(503, 'Sign-in is off', messageView('Sign-in is off', NO_GATE_MESSAGE));
+	}
 
 	try {
 		// ────────────────────────────────────────────────────────────── confirm
@@ -138,7 +147,7 @@ export async function handleLogin(request: Request, ctx: LoginContext): Promise<
 		// ─────────────────────────────────────────────────────────────── signin
 		if (pathname === SIGNIN_PATH) {
 			if (method !== 'POST') return notAllowed('POST');
-			if (!isSameOrigin(request)) return json(403, { error: 'Sign in from the sign-in page.', reason: 'failed' });
+			if (!isSameOrigin(request)) return json(403, { error: mismatch() ?? 'Sign in from the sign-in page.', reason: 'failed' });
 			let body: Record<string, unknown>;
 			try {
 				const parsed: unknown = JSON.parse(await readBody(request));
@@ -161,7 +170,7 @@ export async function handleLogin(request: Request, ctx: LoginContext): Promise<
 				// Every attempt counts, the right password included, so the limit can't confirm a guess.
 				let over = true;
 				try {
-					over = await auth.limits.backupAttemptOver(clientIp(request, ctx.clientAddress));
+					over = await auth.limits.backupAttemptOver(ip);
 				} catch (error) {
 					auth.log(`could not count a backup sign-in attempt, so it was refused: ${error instanceof Error ? error.message : String(error)}`);
 				}
@@ -179,7 +188,7 @@ export async function handleLogin(request: Request, ctx: LoginContext): Promise<
 		// ────────────────────────────────────────────────────────────── signout
 		if (pathname === SIGNOUT_PATH) {
 			if (method !== 'POST') return notAllowed('POST');
-			if (!isSameOrigin(request)) return wantsJson ? json(403, { error: 'Sign out from the editor.', reason: 'cross-origin' }) : crossOrigin();
+			if (!isSameOrigin(request)) return wantsJson ? json(403, { error: mismatch() ?? 'Sign out from the editor.', reason: 'cross-origin' }) : crossOrigin();
 			const location = loginHref({ signedout: '1' });
 			return wantsJson ? json(200, { ok: true, location }, auth.clearCookie()) : redirect(location, auth.clearCookie());
 		}
@@ -199,8 +208,9 @@ export async function handleLogin(request: Request, ctx: LoginContext): Promise<
 		const showBackup = query.get('backup') === '1' && auth.backup.enabled;
 		if (isRead(method)) {
 			const next = cleanNext(query.get('next'));
-			if (showBackup) return page(200, 'Backup account', backupView({ next }), { script: true });
-			return page(200, 'Sign in', emailView({ next, signedOut: query.get('signedout') === '1', backupEnabled: auth.backup.enabled }));
+			const notice = addressNotice(request, auth.siteOrigin);
+			if (showBackup) return page(200, 'Backup account', backupView({ next, notice }), { script: true });
+			return page(200, 'Sign in', emailView({ next, signedOut: query.get('signedout') === '1', backupEnabled: auth.backup.enabled, notice }));
 		}
 		if (method !== 'POST') return notAllowed('GET, HEAD, POST');
 		if (!isSameOrigin(request)) return crossOrigin();
@@ -221,7 +231,6 @@ export async function handleLogin(request: Request, ctx: LoginContext): Promise<
 		}
 
 		// Every address counts against the limits, allowed or not, so the time taken is the same.
-		const ip = clientIp(request, ctx.clientAddress);
 		let over = true;
 		try {
 			over = await auth.limits.linkRequestOver(email, ip);

package/src/live/auth/middleware.ts

@@ -8,7 +8,11 @@
  *   even building the runtime, so the public site never waits on GitHub or Redis.
  *   A guarded path that passes records the person (`setPerson`) for the route.
  * - **Unconfigured** never reaches here in a correct setup (Phase 2's middleware
- *   answers first); if it does, a guarded path gets a 503 rather than through.
+ *   answers first); if it does, a guarded path gets a 503 rather than through. The
+ *   public form endpoint's POST is the exception: Phase 2 lets it through, and so does this, since
+ *   a site's forms work without the editor (M6 Decision 5; the Urban Return port found it
+ *   answering 503 here until the GitHub App's variables were set). A GET to it is as
+ *   unavailable as any other guarded path, as live mode's let-through is POST-only too.
  *
  * The mode is Phase 2's `editorMode()`, so the two agree on live and local.
  */
@@ -16,7 +20,7 @@ import type { MiddlewareHandler } from 'astro';
 import { site } from 'virtual:caracms/config';
 import { editorMode } from '../../editor/server/mode.ts';
 import { setPerson } from '../locals.ts';
-import { guard, isGuardedPath } from './guard.ts';
+import { guard, isFormEndpoint, isGuardedPath } from './guard.ts';
 import { authFor } from './index.ts';
 
 const unavailable = (text: string) => new Response(text, { status: 503, headers: { 'Content-Type': 'text/plain; charset=utf-8', 'Cache-Control': 'private, no-store' } });
@@ -25,7 +29,7 @@ export const onRequest: MiddlewareHandler = async (context, next) => {
 	if (!isGuardedPath(context.url.pathname)) return next();
 	const mode = editorMode();
 	if (mode.kind === 'local') return next();
-	if (mode.kind !== 'live') return unavailable("The editor isn't set up on this server yet.");
+	if (mode.kind !== 'live') return isFormEndpoint(context.url.pathname) && context.request.method === 'POST' ? next() : unavailable("The editor isn't set up on this server yet.");
 
 	let auth;
 	try {