@postedin/cms-client 0.1.0

package/README.md

@@ -0,0 +1,66 @@
+# @postedin/cms-client
+
+Everything a postedin Astro site reads from Payload CMS, and the form proxy it
+writes through: documents in, render inputs out.
+
+```ts
+import { createClient } from '@postedin/cms-client';
+
+export const client = createClient({
+	apiUrl: import.meta.env.API_BASE_URL,
+	apiKey: import.meta.env.CMS_API_KEY,
+	projectSlug: import.meta.env.PROJECT_SLUG,
+	uploadsBaseUrl: import.meta.env.S3_PUBLIC_URL,
+	protectionBypassSecret: process.env.CMS_VERCEL_AUTOMATION_BYPASS_SECRET,
+	isDev: import.meta.env.DEV,
+	appearance: __APPEARANCE__, // fetched at config time
+	project: __PROJECT__, // fetched at config time
+	locales: ['es', 'en'],
+	defaultLocale: 'es',
+	localePrefix: { es: '', en: '/en' },
+});
+
+const cms = client.cms('en');
+const posts = await cms.posts.all();
+const routes = client.routes('en', await client.getHomePageRef('en'));
+```
+
+The package reads no environment. The site builds the client from its own
+`import.meta.env`, because Astro externalises an installed package and would
+leave `import.meta.env` empty inside it.
+
+## Entry points
+
+- `@postedin/cms-client` — `createClient` and everything server-side.
+- `@postedin/cms-client/browser` — `defineLocales`, `defineRoutes`,
+  `defineCmsToHref` and the link types. No credential, no fetch: safe in a
+  hydrated island.
+- `@postedin/cms-client/upload-policy` — the CMS's upload limits, read by the
+  form islands and the proxy alike.
+- `@postedin/cms-client/payload-types` — the CMS's generated types.
+
+## Options a site may need
+
+- `resolveUploadUrl(media, use)` — the site's own rule for where an upload is
+  served from, asked in every production build; return `undefined` to use
+  the bucket, or the CMS's own URL when there is none.
+- `extensions` — collections only this site reads. Each is built per locale
+  from `{ api, locale, cms, createCollectionLoader, createGlobalLoader }` and
+  appears on `client.cms(locale)` under its key.
+- `appearanceFallbacks` — what a blank Appearance colour falls back to.
+- `pageConcurrency` — collection pages fetched at a time (default 4).
+
+## Binaries
+
+Run from a site's directory:
+
+- `cms-profile-build`, `cms-profile-report`, `cms-profile-interference` — see
+  the template's `docs/performance/README.md`.
+- `cms-dissect-build-log` — a Vercel build log split into phases and page
+  groups; `--deployment <id> --team <id>` reads the full log with
+  `VERCEL_TOKEN`, `--labels labels.json` names the groups.
+
+## Versioning
+
+Minor for an additive schema change, major for a removal. Sites in this
+repository use `workspace:*`; a client's own repository pins an exact version.

package/bin/dissect/cli.mjs

@@ -0,0 +1,138 @@
+#!/usr/bin/env node
+/**
+ * Dissects a Vercel build log.
+ *
+ *   cms-dissect-build-log build.log                  # `vercel inspect --logs` output
+ *   cms-dissect-build-log events.json                # `/v3/deployments/{id}/events`
+ *   cms-dissect-build-log --deployment dpl_… --team team_…
+ *   … --labels labels.json --out report.md --json summary.json
+ *
+ * `--deployment` reads the whole log from the Vercel API with `VERCEL_TOKEN`.
+ * Both other routes to it are capped: `vercel inspect --logs` prints the last
+ * 10,000 lines and the events endpoint answers at most 10,000 per request, so
+ * this pages backwards until it has every line. It also reads the deployment's
+ * `buildingAt`, which is what every time in the report is measured from.
+ *
+ * `--labels` names page groups; see `dissect.mjs` for the shape.
+ */
+
+import { readFileSync, realpathSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { dissect, parseLog, renderMarkdown } from './dissect.mjs';
+
+const API = 'https://api.vercel.com';
+
+function parseArgs(argv) {
+	const args = { file: null };
+	for (let i = 0; i < argv.length; i++) {
+		const arg = argv[i];
+		if (arg.startsWith('--')) {
+			args[arg.slice(2)] = argv[++i];
+		} else {
+			args.file = arg;
+		}
+	}
+	return args;
+}
+
+async function vercel(path, token) {
+	const res = await fetch(`${API}${path}`, {
+		headers: { Authorization: `Bearer ${token}` },
+	});
+	if (!res.ok) {
+		throw new Error(`${res.status} from ${path}: ${await res.text()}`);
+	}
+	return await res.json();
+}
+
+/** Every event of a deployment's build, oldest first. */
+export async function fetchDeploymentLog(deployment, team, token) {
+	const scope = team ? `&teamId=${encodeURIComponent(team)}` : '';
+	const byId = new Map();
+	let until = null;
+
+	for (;;) {
+		const page = await vercel(
+			`/v3/deployments/${deployment}/events?builds=1&limit=-1&direction=backward${scope}${until ? `&until=${until}` : ''}`,
+			token,
+		);
+		const fresh = page.filter((event) => !byId.has(event.id));
+		for (const event of page) {
+			byId.set(event.id, event);
+		}
+		if (fresh.length === 0) {
+			break;
+		}
+		until = Math.min(...page.map((event) => event.created));
+	}
+
+	const events = [...byId.values()].sort(
+		(a, b) =>
+			a.created - b.created || (a.serial ?? '').localeCompare(b.serial ?? ''),
+	);
+	const { buildingAt } = await vercel(
+		`/v13/deployments/${deployment}?${scope.slice(1)}`,
+		token,
+	);
+
+	return { events, buildingAt };
+}
+
+async function main(argv) {
+	const args = parseArgs(argv);
+	let input;
+	let origin = args.origin ? Number(args.origin) : undefined;
+
+	if (args.deployment) {
+		const token = process.env.VERCEL_TOKEN;
+		if (!token) {
+			throw new Error(
+				'--deployment reads the Vercel API and needs VERCEL_TOKEN.',
+			);
+		}
+		const { events, buildingAt } = await fetchDeploymentLog(
+			args.deployment,
+			args.team,
+			token,
+		);
+		input = events;
+		origin ??= buildingAt;
+		if (args['save-log']) {
+			writeFileSync(args['save-log'], JSON.stringify(events));
+		}
+	} else if (args.file) {
+		const raw = readFileSync(args.file, 'utf-8');
+		input = raw.trimStart().startsWith('[') ? JSON.parse(raw) : raw;
+	} else {
+		throw new Error('Give a log file, or --deployment <id> [--team <id>].');
+	}
+
+	const labels = args.labels
+		? JSON.parse(readFileSync(args.labels, 'utf-8'))
+		: {};
+	const summary = dissect(parseLog(input), { origin, labels });
+	const markdown = renderMarkdown(summary, {
+		title: args.deployment ? `Build ${args.deployment}, dissected` : undefined,
+	});
+
+	if (args.json) {
+		writeFileSync(args.json, `${JSON.stringify(summary, null, '\t')}\n`);
+	}
+	if (args.out) {
+		writeFileSync(args.out, markdown);
+		console.log(args.out);
+	} else {
+		console.log(markdown);
+	}
+}
+
+if (
+	process.argv[1] &&
+	realpathSync(resolve(process.argv[1])) === fileURLToPath(import.meta.url)
+) {
+	main(process.argv.slice(2)).catch((error) => {
+		console.error(error.message);
+		process.exit(1);
+	});
+}

package/bin/dissect/dissect.mjs

@@ -0,0 +1,290 @@
+/**
+ * Dissects a Vercel build log of an Astro site: where the build's time went,
+ * phase by phase, and within prerendering, page group by page group.
+ *
+ * Pure: a list of `{ t, text }` lines in, a summary out. Reading the log from a
+ * file or from the Vercel API is `cli.mjs`'s job, so everything here can be
+ * tested against a fixture.
+ */
+
+// Colour codes, which the events API keeps and `vercel inspect` strips.
+// biome-ignore lint/suspicious/noControlCharactersInRegex: that is what they are
+const ANSI = /\x1b\[[0-9;]*m/g;
+
+/**
+ * The lines that end each phase, in order. A phase runs from the end of the
+ * one before it (or the start of the log) to the first line matching its
+ * marker. Where a phase names more than one, the first is preferred and the
+ * rest are fallbacks for a log that lacks it. A phase whose markers never
+ * appear is left out and hands its time to the next one.
+ *
+ * Prerendering ends where Astro starts waiting on `astro:build:done`, so the
+ * adapter's rearranging and bundling after the last page count towards it.
+ */
+export const PHASES = [
+	{ name: 'Clone, restore build cache', until: [/^Running "vercel build"/] },
+	{
+		name: 'Install dependencies',
+		until: [/^Running "(pnpm|npm|yarn|bun) run build"/],
+	},
+	{
+		name: '`astro build` to the start of prerendering',
+		until: [/prerendering static routes/],
+	},
+	{
+		name: 'Prerendering static routes',
+		until: [/hook "astro:build:done"/, /\[build\] Rearranging server assets/],
+		prerender: true,
+	},
+	{
+		name: '`astro:build:done`',
+		until: [/\[build\] Server built in/, /\[build\] Complete!/],
+	},
+	{ name: 'Packaging the output', until: [/^Build Completed in /] },
+	{ name: 'Deploying outputs', until: [/^Deployment completed/] },
+];
+
+const ROUTE_HEADER = /[▶λ] (\S.*?)\s*$/;
+const PAGE_LINE = /[├└]─\s+(\S+)\s+\(\+([\d.]+)(ms|s)\)/;
+
+/** Normalises either input format to `{ t, text }` in log order. */
+export function parseLog(input) {
+	if (Array.isArray(input)) {
+		// Events from `/v3/deployments/{id}/events`.
+		return input
+			.filter((event) => typeof event.text === 'string')
+			.map((event) => ({
+				t: event.created,
+				text: event.text.replace(ANSI, ''),
+			}));
+	}
+
+	// `vercel inspect --logs`: `2026-09-18T22:22:50.810Z  <text>`.
+	return String(input)
+		.split(/\r?\n/)
+		.map((line) => {
+			const match = line.match(/^(\d{4}-\d\d-\d\dT[\d:.]+Z)\s{2}(.*)$/);
+			return match
+				? { t: Date.parse(match[1]), text: match[2].replace(ANSI, '') }
+				: null;
+		})
+		.filter(Boolean);
+}
+
+function renderMs(value, unit) {
+	const n = Number(value);
+	return unit === 's' ? Math.round(n * 1000) : n;
+}
+
+/**
+ * A label for every page, from the route that rendered it and the locale its
+ * path is in. `labels.routes` maps a route (`src/pages/...`) to a group name,
+ * or to `{ label, locale: false }` for a group that is not split by locale.
+ * A route it does not name is grouped under its own path. Redirects — Astro
+ * prints them as a header naming the URL rather than a source file — are one
+ * group.
+ */
+function groupOf(route, path, labels) {
+	if (route === null || !route.startsWith('src/')) {
+		return labels.redirects ?? 'Redirects';
+	}
+
+	const entry = labels.routes?.[route];
+	const label = typeof entry === 'string' ? entry : (entry?.label ?? route);
+	const split = typeof entry === 'object' ? entry.locale !== false : true;
+
+	if (!split) {
+		return label;
+	}
+
+	const prefixes = Object.entries(
+		labels.locales ?? { '': 'default', '/en': 'en' },
+	).sort(([a], [b]) => b.length - a.length);
+	const [, locale] = prefixes.find(
+		([prefix]) => prefix && path.startsWith(`${prefix}/`),
+	) ??
+		prefixes.find(([prefix]) => prefix === '') ?? ['', ''];
+
+	return locale ? `${label}, ${locale}` : label;
+}
+
+function median(sorted) {
+	if (sorted.length === 0) {
+		return 0;
+	}
+	const mid = Math.floor(sorted.length / 2);
+	return sorted.length % 2 ? sorted[mid] : (sorted[mid - 1] + sorted[mid]) / 2;
+}
+
+/**
+ * @param {{ t: number, text: string }[]} lines
+ * @param {{ origin?: number, labels?: object, pauses?: number }} options
+ *   `origin` is what every time is measured from — the deployment's
+ *   `buildingAt`, so the phases sum to the build time the deployments API
+ *   reports. Defaults to the first line.
+ */
+export function dissect(lines, options = {}) {
+	const origin = options.origin ?? lines[0]?.t ?? 0;
+	const labels = options.labels ?? {};
+	const at = (t) => (t - origin) / 1000;
+
+	// Phases.
+	const phases = [];
+	let from = origin;
+	let cursor = 0;
+	let prerenderSpan = null;
+	for (const phase of PHASES) {
+		let index = -1;
+		for (const marker of phase.until) {
+			index = lines.findIndex(
+				(line, i) => i >= cursor && marker.test(line.text.trim()),
+			);
+			if (index !== -1) {
+				break;
+			}
+		}
+		if (index === -1) {
+			continue;
+		}
+		const to = lines[index].t;
+		phases.push({
+			name: phase.name,
+			from: at(from),
+			to: at(to),
+			seconds: at(to) - at(from),
+		});
+		if (phase.prerender) {
+			prerenderSpan = { from, to, startIndex: cursor, endIndex: index };
+		}
+		from = to;
+		cursor = index;
+	}
+
+	// Pages, and the gaps between them, inside prerendering only.
+	const groups = new Map();
+	const pauses = [];
+	let renderMsTotal = 0;
+	let pageCount = 0;
+	let gapMs = 0;
+	let tailMs = 0;
+
+	if (prerenderSpan) {
+		let route = null;
+		let previous = prerenderSpan.from;
+		let previousLabel = 'the start of prerendering';
+
+		for (let i = prerenderSpan.startIndex; i < prerenderSpan.endIndex; i++) {
+			const { t, text } = lines[i];
+			const page = text.match(PAGE_LINE);
+
+			if (!page) {
+				const header = text.match(ROUTE_HEADER);
+				if (header) {
+					route = header[1];
+				}
+				continue;
+			}
+
+			const ms = renderMs(page[2], page[3]);
+			const label = groupOf(route, page[1], labels);
+			const group = groups.get(label) ?? { label, pages: 0, ms: 0, each: [] };
+			group.pages++;
+			group.ms += ms;
+			group.each.push(ms);
+			groups.set(label, group);
+
+			// What the log does not account for between this page line and the
+			// one before it: time spent outside any page, which is where each
+			// route's `getStaticPaths` — its CMS fetches — runs.
+			const gap = t - previous - ms;
+			gapMs += gap;
+			pauses.push({ ms: gap, before: route ?? page[1], after: previousLabel });
+			previous = t;
+			previousLabel = route ?? page[1];
+			renderMsTotal += ms;
+			pageCount++;
+		}
+
+		tailMs = prerenderSpan.to - previous;
+	}
+
+	const byGroup = [...groups.values()]
+		.map((group) => {
+			const each = [...group.each].sort((a, b) => a - b);
+			return {
+				label: group.label,
+				pages: group.pages,
+				seconds: group.ms / 1000,
+				meanMs: group.ms / group.pages,
+				medianMs: median(each),
+			};
+		})
+		.sort((a, b) => b.seconds - a.seconds);
+
+	return {
+		totalSeconds: lines.length ? at(lines.at(-1).t) : 0,
+		phases,
+		prerender: prerenderSpan
+			? {
+					seconds: (prerenderSpan.to - prerenderSpan.from) / 1000,
+					renderSeconds: renderMsTotal / 1000,
+					gapSeconds: gapMs / 1000,
+					tailSeconds: tailMs / 1000,
+					pages: pageCount,
+				}
+			: null,
+		pauses: pauses
+			.sort((a, b) => b.ms - a.ms)
+			.slice(0, options.pauses ?? 5)
+			.map((pause) => ({ ...pause, seconds: pause.ms / 1000 })),
+		byGroup,
+	};
+}
+
+const s1 = (n) => `${n.toFixed(1)} s`;
+const ms1 = (n) => `${n.toFixed(1)} ms`;
+
+export function renderMarkdown(
+	summary,
+	{ title = 'Build log, dissected' } = {},
+) {
+	const out = [`# ${title}`, ''];
+
+	out.push('| Phase | Span | Cost |', '| --- | --- | --- |');
+	for (const phase of summary.phases) {
+		out.push(
+			`| ${phase.name} | ${phase.from.toFixed(1)} – ${phase.to.toFixed(1)} | ${s1(phase.seconds)} |`,
+		);
+	}
+	out.push('');
+
+	if (summary.prerender) {
+		const p = summary.prerender;
+		out.push(
+			'| Prerendering | Cost |',
+			'| --- | --- |',
+			`| Rendering, summed from ${p.pages.toLocaleString('en')} page lines | ${s1(p.renderSeconds)} |`,
+			`| Gaps between page lines — each route's \`getStaticPaths\` | ${s1(p.gapSeconds)} |`,
+			`| After the last page line | ${s1(p.tailSeconds)} |`,
+			'',
+			'Largest gaps:',
+			'',
+			...summary.pauses.map(
+				(pause) => `- ${s1(pause.seconds)} before \`${pause.before}\``,
+			),
+			'',
+		);
+	}
+
+	out.push(
+		'| Group | Pages | Total | Mean | Median |',
+		'| --- | --- | --- | --- | --- |',
+		...summary.byGroup.map(
+			(g) =>
+				`| ${g.label} | ${g.pages.toLocaleString('en')} | ${s1(g.seconds)} | ${ms1(g.meanMs)} | ${Math.round(g.medianMs)} ms |`,
+		),
+		'',
+	);
+
+	return out.join('\n');
+}

package/bin/profile/build.mjs

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+/**
+ * Runs one profiled build: `pnpm build:profile` in a site, which runs the
+ * package's `cms-profile-build` from the site's directory.
+ *
+ * Astro is spawned exactly as `pnpm build` spawns it, plus a `--import` that
+ * loads `fetch-log.mjs` into the process. `pnpm build` itself is untouched —
+ * the profiler is only ever present in a build started from here.
+ *
+ * This is also where the log's name and the CMS origin are decided, rather than
+ * in the preload, because `--import` applies to worker threads too: a name
+ * chosen in the preload would give every thread a file of its own, and the
+ * report would see a fraction of the build. One name in the environment means
+ * every thread appends to the same log.
+ */
+
+import { spawn } from 'node:child_process';
+import { existsSync, mkdirSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { LOG_DIR, writeReport } from './report.mjs';
+import { loadSiteEnv } from './site-env.mjs';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const preload = pathToFileURL(join(here, 'fetch-log.mjs')).href;
+
+// Resolved in the mode the build about to be spawned will resolve it in:
+// `astro build` runs Vite in `production`, so an `.env.production` would be in
+// play for the site's own `import.meta.env.API_BASE_URL` and has to be in play
+// here too. Otherwise the profiler would classify requests against one origin
+// while the build talked to another.
+const { API_BASE_URL } = await loadSiteEnv(
+	process.env.NODE_ENV ?? 'production',
+);
+
+// A caller profiling a build against something other than what the env files
+// say — a tunnel, a local CMS, a preview deployment — names the origin itself.
+const cmsOrigin = process.env.PROFILE_CMS_ORIGIN || API_BASE_URL || '';
+
+// Every request is classified by comparing its origin to this one, so an
+// unresolved value does not fail anything — it quietly moves the whole CMS
+// into "other hosts" and the report reads as a build that never called the CMS.
+if (!cmsOrigin) {
+	console.warn(
+		'API_BASE_URL did not resolve, so no request can be recognised as the CMS and the report will say there were none. Check .env / .env.local, or set PROFILE_CMS_ORIGIN.\n',
+	);
+}
+
+// A caller that needs to read this log itself — the interference harness joins
+// it against its own polls — names it up front. Otherwise it is named here.
+const logPath = resolve(
+	process.env.PROFILE_FETCH_LOG || join(LOG_DIR, `build-${stamp()}.ndjson`),
+);
+
+mkdirSync(dirname(logPath), { recursive: true });
+
+console.log(`Profiling this build into ${logPath}\n`);
+
+// Astro 5 shipped its CLI as `astro/astro.js`; Astro 7 ships it as
+// `astro/bin/astro.mjs` and nothing at the old path, so try both rather than
+// tying the profiler to one major.
+const astro = [
+	resolve('node_modules', 'astro', 'bin', 'astro.mjs'),
+	resolve('node_modules', 'astro', 'astro.js'),
+].find((candidate) => existsSync(candidate));
+
+if (!astro) {
+	console.error(
+		'Cannot find the Astro CLI under node_modules/astro. Run `pnpm install` first.',
+	);
+	process.exit(1);
+}
+
+const build = spawn(
+	process.execPath,
+	[astro, 'build', ...process.argv.slice(2)],
+	{
+		stdio: 'inherit',
+		env: {
+			...process.env,
+			PROFILE_FETCH_LOG: logPath,
+			PROFILE_CMS_ORIGIN: cmsOrigin,
+			NODE_OPTIONS: [process.env.NODE_OPTIONS, `--import ${preload}`]
+				.filter(Boolean)
+				.join(' '),
+		},
+	},
+);
+
+build.on('exit', (code, signal) => {
+	// A build that failed part-way still logged everything it managed to ask
+	// for, and that is often the interesting part, so report either way.
+	if (existsSync(logPath)) {
+		console.log(`\nFetch log:  ${logPath}`);
+		console.log(`Report:     ${writeReport(logPath)}`);
+	} else {
+		console.error(`\nNo fetch log was written to ${logPath}.`);
+	}
+
+	process.exit(signal ? 1 : (code ?? 0));
+});
+
+/** `2026-09-03T14-22-05`: sorts chronologically, survives a file system. */
+function stamp() {
+	return new Date().toISOString().slice(0, 19).replaceAll(':', '-');
+}