caracms 0.3.3 → 0.4.0

package/src/live/mode.ts

@@ -1,13 +1,15 @@
 /**
  * Which mode the editor runs in, read from the environment (M4 Decision 1).
  *
- * - **Local mode**: `astro dev` with no GitHub credentials (`GITHUB_APP_ID` or
- *   `CARACMS_GITHUB_TOKEN`). M3's editor, files on disk.
+ * - **Local mode**: `astro dev` with no GitHub credentials (`CARACMS_CLOUD_KEY`,
+ *   `GITHUB_APP_ID` or `CARACMS_GITHUB_TOKEN`). M3's editor, files on disk.
  * - **Live mode**: whenever a credential is configured, and **always on a production
  *   server**. It needs one GitHub credential (a fine-grained token, or the App's
  *   `GITHUB_APP_ID` and `GITHUB_APP_PRIVATE_KEY`; runs-anywhere Decisions 3–4), the repo
  *   (`GITHUB_REPO=owner/name`, or Railway's `RAILWAY_GIT_REPO_OWNER` and
- *   `RAILWAY_GIT_REPO_NAME`; Decision 6), `CARACMS_SECRET`, `REDIS_URL` and the site's
+ *   `RAILWAY_GIT_REPO_NAME`; Decision 6), or CaraCMS Cloud's site key instead of both
+ *   (`CARACMS_CLOUD_KEY`, with `CARACMS_CLOUD_URL` for another deployment than
+ *   production; caracms-cloud M2 Decision 11: the repo comes from the cloud at start), `CARACMS_SECRET`, `REDIS_URL` and the site's
  *   `https://` address in production (dev may use the stand-in Redis). A production
  *   server missing any of them still serves the public site; `/admin` answers 503
  *   naming them (Phase 2 builds that from `missing`).
@@ -18,6 +20,7 @@
  * This only reads; it doesn't wire anything (Phase 2 switches the routes on it,
  * Phase 3 guards with it).
  */
+import { CLOUD_KEY_SHAPE, DEFAULT_CLOUD_URL } from './cloud.ts';
 import { DEFAULT_BRANCHES, type BranchNames } from './branches.ts';
 import { DEFAULT_TIMINGS, type LiveTimings } from './timings.ts';
 
@@ -26,6 +29,8 @@ export interface LiveSettings {
 	github:
 		| { kind: 'app'; appId: string; privateKey: string; owner: string; repo: string }
 		| { kind: 'token'; token: string; owner: string; repo: string }
+		/** CARACMS_CLOUD_KEY (caracms-cloud M2 Decision 11): the repo comes from the cloud when the runtime starts. */
+		| { kind: 'cloud'; key: string; url: string }
 		| { kind: 'memory' };
 	/** Null in dev without REDIS_URL: the in-memory stand-in. */
 	redisUrl: string | null;
@@ -88,6 +93,13 @@ export const NO_ADDRESS_PROBLEM =
 	"The site's public address isn't known: set SITE_URL to it, like https://fernhill.ie, both when the site is built and when it runs. Without it, sign-in links can't be sent and the editor's saves are refused.";
 export const HTTP_ADDRESS_PROBLEM = (address: string) =>
 	`The site's address (${address}) is http://, but signing in needs https://: the session cookie is only ever sent over https. Set SITE_URL to the https:// address (http:// works for localhost only).`;
+export const CLOUD_KEY_PROBLEM =
+	"CARACMS_CLOUD_KEY isn't a CaraCMS Cloud site key: a key is cck_ followed by 43 letters, digits, - and _. Copy it again from app.caracms.com.";
+export const CLOUD_AND_GITHUB_PROBLEM = (other: string) =>
+	`Both CARACMS_CLOUD_KEY and ${other} are set: a site uses one GitHub credential, so remove ${other}.`;
+export const CLOUD_REPO_PROBLEM = 'CARACMS_CLOUD_KEY is set, so the repo comes from CaraCMS Cloud; remove GITHUB_REPO.';
+export const CLOUD_URL_PROBLEM = (url: string) =>
+	`CARACMS_CLOUD_URL must be the cloud's https:// address (http:// works for localhost only; got "${url}"). Leave it unset for CaraCMS Cloud itself.`;
 export const BOTH_REDEPLOYERS_PROBLEM =
 	'Both CARACMS_DEPLOY_HOOK_URL and CARACMS_RAILWAY_TOKEN are set: Try again redeploys through one of them, so set only one.';
 
@@ -153,7 +165,8 @@ export function readMode(env: Env = process.env, production = env.NODE_ENV === '
 	const memory = get('CARACMS_GITHUB') === 'memory';
 	// Never GITHUB_TOKEN (Decision 4): the gh CLI and GitHub Actions export it.
 	const ghToken = get('CARACMS_GITHUB_TOKEN');
-	if (!production && !memory && !get('GITHUB_APP_ID') && !ghToken) return { kind: 'local' };
+	const cloudKey = get('CARACMS_CLOUD_KEY');
+	if (!production && !memory && !get('GITHUB_APP_ID') && !ghToken && !cloudKey) return { kind: 'local' };
 
 	const missing: string[] = [];
 	const problems: string[] = [];
@@ -168,7 +181,14 @@ export function readMode(env: Env = process.env, production = env.NODE_ENV === '
 	if (other && other !== 'memory') problems.push(`CARACMS_GITHUB must be "memory" or unset (got "${other}").`);
 
 	let github: LiveSettings['github'] = { kind: 'memory' };
-	if (!memory || production) {
+	if (cloudKey && (!memory || production)) {
+		// The cloud names the repo (Decision 13), so GITHUB_REPO is a mistake and Railway's own variables are ignored.
+		if (!CLOUD_KEY_SHAPE.test(cloudKey)) problems.push(CLOUD_KEY_PROBLEM);
+		if (ghToken) problems.push(CLOUD_AND_GITHUB_PROBLEM('CARACMS_GITHUB_TOKEN'));
+		if (get('GITHUB_APP_ID')) problems.push(CLOUD_AND_GITHUB_PROBLEM('GITHUB_APP_ID'));
+		if (get('GITHUB_REPO')) problems.push(CLOUD_REPO_PROBLEM);
+		github = { kind: 'cloud', key: cloudKey, url: readCloudUrl(get('CARACMS_CLOUD_URL'), problems) };
+	} else if (!memory || production) {
 		const appId = get('GITHUB_APP_ID');
 		const repo = readRepo(env, problems);
 		const owner = repo?.owner ?? '';
@@ -181,7 +201,7 @@ export function readMode(env: Env = process.env, production = env.NODE_ENV === '
 		} else if (appId) {
 			github = { kind: 'app', appId, privateKey: need('GITHUB_APP_PRIVATE_KEY'), owner, repo: name };
 		} else {
-			missing.push('CARACMS_GITHUB_TOKEN (or GITHUB_APP_ID and GITHUB_APP_PRIVATE_KEY)');
+			missing.push('CARACMS_CLOUD_KEY (or CARACMS_GITHUB_TOKEN, or GITHUB_APP_ID and GITHUB_APP_PRIVATE_KEY)');
 		}
 		if (!repo && !problems.some((p) => p.startsWith('GITHUB_REPO'))) {
 			missing.push(onRailway(env) ? 'RAILWAY_GIT_REPO_OWNER and RAILWAY_GIT_REPO_NAME (or GITHUB_REPO)' : 'GITHUB_REPO');
@@ -277,6 +297,22 @@ function isBranchName(name: string): boolean {
 	);
 }
 
+/** CARACMS_CLOUD_URL, without a trailing slash: https://, or http:// on localhost. Unset, the production address. */
+function readCloudUrl(raw: string | null, problems: string[]): string {
+	if (!raw) return DEFAULT_CLOUD_URL;
+	let url: URL | null = null;
+	try {
+		url = new URL(raw);
+	} catch {
+		/* a problem, below */
+	}
+	if (!url || !(url.protocol === 'https:' || (url.protocol === 'http:' && isLocalhost(url.hostname)))) {
+		problems.push(CLOUD_URL_PROBLEM(raw));
+		return raw;
+	}
+	return `${url.origin}${url.pathname}`.replace(/\/+$/, '');
+}
+
 /** The repo: GITHUB_REPO overrides Railway's own variables (M4 Decision 3; runs-anywhere Decision 6). */
 function readRepo(env: Env, problems: string[]): { owner: string; repo: string } | null {
 	const override = env.GITHUB_REPO?.trim();

package/src/live/runtime.ts

@@ -20,6 +20,7 @@ import { join, relative, sep } from 'node:path';
 import { repoPrefix, type ResolvedSite } from '../config.ts';
 import { GitHubBackend, MemoryBackend, type FileWrite, type GitBackend } from './backend.ts';
 import { DEFAULT_BRANCHES } from './branches.ts';
+import { cloudSettings } from './cloud.ts';
 import { GitHubClient, Tracker } from './github.ts';
 import { LiveGit, SITE_SETTINGS_FILE } from './git.ts';
 import type { LiveSettings } from './mode.ts';
@@ -52,6 +53,8 @@ export interface RuntimeOptions {
 	railwayFetch?: typeof fetch;
 	/** Tests: the deploy hook's fetch. */
 	deployHookFetch?: typeof fetch;
+	/** Tests: the fetch GitHub and CaraCMS Cloud are reached through. */
+	fetch?: typeof fetch;
 }
 
 /** Build and start a runtime (not shared: tests make their own). */
@@ -72,8 +75,21 @@ export async function createLiveRuntime(options: RuntimeOptions): Promise<LiveRu
 		} else {
 			const tracker = new Tracker(now);
 			const gh = settings.github;
-			const connection = gh.kind === 'token' ? { token: gh.token, owner: gh.owner, repo: gh.repo, now } : { appId: gh.appId, privateKey: gh.privateKey, owner: gh.owner, repo: gh.repo, now };
-			backend = new GitHubBackend(new GitHubClient(connection, tracker), settings.branches);
+			const fetch = options.fetch;
+			let client: GitHubClient;
+			if (gh.kind === 'cloud') {
+				// caracms-cloud M2 Decision 13: the repo from the cloud's settings, then the first
+				// token, so a refusal of either stops the start (the sign-in guard shows its sentence).
+				const { owner, repo } = await cloudSettings({ key: gh.key, url: gh.url, fetch });
+				client = new GitHubClient({ cloudKey: gh.key, cloudUrl: gh.url, owner, repo, now, fetch }, tracker);
+				await client.ready();
+				log(`live mode on ${owner}/${repo} through CaraCMS Cloud`);
+			} else {
+				const connection =
+					gh.kind === 'token' ? { token: gh.token, owner: gh.owner, repo: gh.repo, now, fetch } : { appId: gh.appId, privateKey: gh.privateKey, owner: gh.owner, repo: gh.repo, now, fetch };
+				client = new GitHubClient(connection, tracker);
+			}
+			backend = new GitHubBackend(client, settings.branches);
 		}
 	}
 	const { main, drafts } = backend.branches;

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';

package/src/redirects.ts

@@ -1,11 +1,12 @@
 /**
  * Redirects (pre-M7 item 8): Site Settings' `redirects`, a list of `{ from, to }`
  * site addresses. Changing a document's address adds one, from the old address to
- * the new; the package serves them as 301s on the public site (redirect-middleware.ts).
+ * the new, unless it's asked not to (move.ts); the package serves them as 301s on the public site (redirect-middleware.ts).
  * Browser-safe (no imports beyond links.ts): the Redirects section reads them too.
  *
  *   parseRedirects(raw)                        the list as the file holds it, cleaned
  *   redirectsAfterMove(list, from, to, add)    the list once a document moves
+ *   redirectsAfterMoves(list, moves)           the list once several move at once (swaps, chains)
  *   redirectFor(list, pathname)                where a request for `pathname` goes, or null
  *
  * - **Both ends are `/paths`**, without a trailing slash (`/` stays `/`). An entry that
@@ -64,6 +65,36 @@ export function redirectsAfterMove(list: readonly Redirect[], from: string, to:
 	return next;
 }
 
+/**
+ * The list once several documents move at once (the many-move engine): every move is
+ * taken against the list before the plan, so a swap or a chain comes out as its
+ * documents end up. Entries to an old address go to that document's new one (chains
+ * collapse, one step: `X → A` becomes `X → B` when A moves to B); an entry from an
+ * address a document now occupies goes (a page is there); and, per move with `add`,
+ * `from → to` is added, unless another document now sits at `from` (in a swap neither
+ * is added). With no address both vacated and taken, this is `redirectsAfterMove` per
+ * move, in order.
+ */
+export function redirectsAfterMoves(list: readonly Redirect[], moves: readonly { from: string; to: string; add: boolean }[]): Redirect[] {
+	const taken = (address: string) => moves.some((m) => same(m.to, address));
+	const replaced = (address: string) => moves.some((m) => m.add && same(m.from, address));
+	const next = list
+		.filter((r) => !taken(r.from) && !replaced(r.from))
+		.map((r) => {
+			const m = moves.find((m) => same(r.to, m.from));
+			return m ? { from: r.from, to: m.to } : r;
+		})
+		.filter((r) => !same(r.from, r.to));
+	for (const m of moves) if (m.add && !same(m.from, m.to) && !taken(m.from)) next.push({ from: m.from, to: m.to });
+	return next;
+}
+
+/** The redirects a plan adds (`redirectsAfterMoves`): one per move with `add`, unless another document now sits at its old address. */
+export function redirectsAddedBy(moves: readonly { from: string; to: string; add: boolean }[]): Redirect[] {
+	const taken = (address: string) => moves.some((m) => same(m.to, address));
+	return moves.filter((m) => m.add && !same(m.from, m.to) && !taken(m.from)).map((m) => ({ from: m.from, to: m.to }));
+}
+
 /** Where a request for `pathname` goes, or null. Matched without a trailing slash; letter case counts, as it does for pages. */
 export function redirectFor(list: readonly Redirect[], pathname: string): string | null {
 	let path: string;

package/src/relink.ts

@@ -145,17 +145,47 @@ function fieldAt(site: Pick<ResolvedSite, 'blocks'>, collection: Pick<ResolvedCo
 	return field ? { field, rest } : null;
 }
 
-/** A string at `rest` inside a field's value, with its links to the old address rewritten; null when it isn't a link there or doesn't point there. */
-function relinkIn(field: Field, rest: Segment[], value: string, move: AddressMove): string | null {
+/**
+ * Several moves at once (collections under pages, Decision 9: a page and everything under
+ * it): each link is matched against the addresses as they were, once, so a swap stays a
+ * swap and a link is never moved twice.
+ */
+interface MoveIndex {
+	href: HrefRewrite;
+	ref: (collection: string, path: string) => string | null;
+}
+
+function indexMoves(moves: readonly AddressMove[]): MoveIndex {
+	const byUrl = new Map<string, AddressMove>();
+	const byPath = new Map<string, AddressMove>();
+	for (const m of moves) {
+		const url = normaliseAddress(m.fromUrl);
+		if (m.fromUrl !== m.toUrl && !byUrl.has(url)) byUrl.set(url, m);
+		// A held document keeps its path when its holder moves (check 18: references to it never change).
+		const key = `${m.collection}\u0000${m.fromPath}`;
+		if (m.fromPath !== m.toPath && !byPath.has(key)) byPath.set(key, m);
+	}
+	return {
+		href: (href) => {
+			const path = internalLinkPath(href);
+			const move = path === null ? undefined : byUrl.get(path);
+			return move ? relinkHref(href, move) : null;
+		},
+		ref: (collection, path) => byPath.get(`${collection}\u0000${path}`)?.toPath ?? null,
+	};
+}
+
+/** A string at `rest` inside a field's value, with its links to the old addresses rewritten; null when it isn't a link there or doesn't point at one. */
+function relinkIn(field: Field, rest: Segment[], value: string, moves: MoveIndex): string | null {
 	switch (field.kind) {
 		case 'link':
-			return rest.length === 1 && rest[0] === 'href' ? relinkHref(value, move) : null;
+			return rest.length === 1 && rest[0] === 'href' ? moves.href(value) : null;
 		case 'buttons':
-			return rest.length === 2 && typeof rest[0] === 'number' && rest[1] === 'href' ? relinkHref(value, move) : null;
+			return rest.length === 2 && typeof rest[0] === 'number' && rest[1] === 'href' ? moves.href(value) : null;
 		case 'richText':
-			return relinkRichText(value, move);
+			return rewriteRichText(value, moves.href)?.text ?? null;
 		case 'reference':
-			return rest.length === 0 && field.to === move.collection && value.trim() === move.fromPath ? move.toPath : null;
+			return rest.length === 0 && field.to ? moves.ref(field.to, value.trim()) : null;
 		default:
 			return null;
 	}
@@ -217,17 +247,18 @@ function splice(text: string, edits: { start: number; end: number; text: string
 /**
  * The file's text with every link and reference to the moved document pointing at
  * its new address (or path); `text` itself when nothing points there. `collection` is
- * the file's own collection (for its schema).
+ * the file's own collection (for its schema). Several moves are applied at once.
  */
 export function relinkText(
 	text: string,
-	move: AddressMove,
+	move: AddressMove | readonly AddressMove[],
 	site: Pick<ResolvedSite, 'blocks'>,
 	collection: Pick<ResolvedCollection, 'kind' | 'fields'>,
 ): { text: string; links: number } {
 	const edits: { start: number; end: number; text: string }[] = [];
+	const moves = indexMoves(Array.isArray(move) ? move : [move as AddressMove]);
 	const ok = fieldStrings(text, site, collection, (field, rest, value, node) => {
-		const next = relinkIn(field, rest, value, move);
+		const next = relinkIn(field, rest, value, moves);
 		if (next !== null && next !== value) edits.push({ start: node.start, end: node.end, text: JSON.stringify(next) });
 	});
 	if (!ok || edits.length === 0) return { text, links: 0 };

package/src/serialize.ts

@@ -242,7 +242,7 @@ export function applyEdits(base: string | null, edited: SiteDocument, site: Pick
 	}
 	if (fieldTexts.size) {
 		const next = parseSource(out);
-		if (next.root.kind === 'object') out = spliceKeys(next, next.root, fieldTexts, ['title', 'hidden', ...Object.keys(fields)]);
+		if (next.root.kind === 'object') out = spliceKeys(next, next.root, fieldTexts, ['title', 'hidden', 'holds', ...Object.keys(fields)]);
 	}
 	return withTrailingNewline(out);
 }

package/src/slug.ts

@@ -17,7 +17,9 @@
  *   or null: under the editor's own `/admin` or `/_caracms`, or the library's files'
  *   `/files` (M6c Decision 3, served by files-route.ts); strictly below another
  *   collection's non-root `urlBase` (exactly at it is allowed: the Work page at
- *   `/work`); or another document's address already, in any collection.
+ *   `/work`), unless a page holds that collection (collections under pages, Decision 6:
+ *   pages may sit under a holder beside its documents); or another document's address
+ *   already, in any collection, held documents included (Decision 8), naming it.
  */
 import { codeRouteAt, codeRouteMessage, type CodeRoute } from './code-routes.ts';
 
@@ -56,8 +58,10 @@ export const INDEX_MESSAGE = '"index" is kept for Home, so it can\'t be an addre
 export interface AddressCollection {
 	name: string;
 	label: string;
-	/** Starts and ends with `/`; null for collections with no pages (shared blocks, Site Settings). */
+	/** Starts and ends with `/`; null for collections with no pages (shared blocks, Site Settings). A held collection's is its resolved base (held.ts). */
 	urlBase: string | null;
+	/** Collections under pages: set on a collection a page holds, whose base doesn't refuse pages below it (Decision 6). */
+	heldBy?: string | null;
 }
 
 /** What `addressProblem` needs of a document. */
@@ -65,6 +69,8 @@ export interface AddressDocument {
 	collection: string;
 	path: string;
 	url: string | null;
+	/** What the editor lists it as: `address-taken` names a document of another collection by it (Decision 8). */
+	label?: string;
 }
 
 export type AddressProblemCode = 'reserved-address' | 'below-collection' | 'address-taken';
@@ -105,7 +111,7 @@ export function addressProblem(
 	const route = codeRouteAt(url, codeRoutes);
 	if (route) return { code: 'reserved-address', message: codeRouteMessage(url, route) };
 	for (const other of collections) {
-		if (other.name === collection || other.urlBase === null) continue;
+		if (other.name === collection || other.urlBase === null || other.heldBy) continue;
 		const base = sameAddress(other.urlBase);
 		if (base === '/') continue;
 		if (at.startsWith(`${base}/`)) {
@@ -116,6 +122,11 @@ export function addressProblem(
 		}
 	}
 	const taken = documents.find((d) => d.url !== null && sameAddress(d.url) === at);
-	if (taken) return { code: 'address-taken', message: `There's already a page at ${url}.` };
+	if (taken) {
+		// Decision 8: a held document and a page can't share an address either way; the other is named.
+		const other = taken.collection !== collection ? collections.find((c) => c.name === taken.collection) : undefined;
+		const named = other && taken.label ? `: “${taken.label}” in ${other.label}` : '';
+		return { code: 'address-taken', message: `There's already a page at ${url}${named}.` };
+	}
 	return null;
 }