mechanica 2.0.2 → 2.0.3

package/dist/cli.js

@@ -1,13 +1,13 @@
-import { B as readImageManifest, C as getPagePath, I as UPLOADS_PREFIX, J as hasSharp, L as assetFileOf, N as setPageCodec, R as isDerivedAsset, T as listPages, U as updateImageManifest, Y as isRasterImage, a as toBlockMeta, d as readFolderData, f as readFoldersData, i as composedBlockMeta, m as readSiteLocaleOverride, n as blockAssetLinks, p as readSiteData, q as analyzeImageBuffer, r as buildRichTextCodec, t as BLOCKS_MANIFEST_FILE } from "./chunks/page-assets-CM_MCuoa.js";
-import fs from "node:fs";
-import { dirname, join, parse, relative } from "node:path";
-import { applySeoTags, auditPageHtml, buildRobotsTxt, buildSitemap, findUnknownBlocks, generateProject, isPaginatedQuery, localePath, mergeTranslation, migrateContent, paginationVariantPath, registerFieldSchemas, resolveQueryKey, templateBlockIds, validateLinks, walkSchema, walkTree } from "mechanica-shared";
-import { parsePage } from "mechanica-shared/page-format";
-import { access, copyFile, cp, mkdir, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
+import { B as readImageManifest, J as hasSharp, R as isDerivedAsset, U as updateImageManifest, Y as isRasterImage, q as analyzeImageBuffer } from "./chunks/page-assets-CM_MCuoa.js";
+import { exportBuilt } from "./export.js";
+import fs, { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { chmod, mkdir, readFile, readdir, realpath, rm, writeFile } from "node:fs/promises";
 import { build } from "vite";
-import { pathToFileURL } from "node:url";
+import { fileURLToPath } from "node:url";
 import os from "node:os";
 import { spawn } from "node:child_process";
+import readline from "node:readline";
 //#region src/cli/args.ts
 /** Parse `argv` (without node/script) into a command, positionals and a `--flag[=value]` map. */
 function parseArgs(argv) {
@@ -74,562 +74,17 @@ async function runBuild() {
 	console.info("Build complete → dist/");
 }
 //#endregion
-//#region src/cli/export.ts
-/** A page filename stem ending in `@<locale>` is a translation, handled per-locale. */
-var VARIANT_STEM_RE = /@[A-Za-z][A-Za-z0-9_-]*$/;
-/** Set `<html lang>` unless the template already declares one (author wins). */
-function setHtmlLang(html, lang) {
-	if (/<html\b[^>]*\blang\s*=/i.test(html)) return html;
-	return html.replace(/<html\b([^>]*)>/i, `<html$1 lang="${lang}">`);
-}
-/** Read every page JSON under `<mech>/pages` as an exportable page. */
-async function readPages(pagesDir, foldersData = {}, richText) {
-	let entries;
-	try {
-		entries = await readdir(pagesDir, { recursive: true });
-	} catch {
-		return [];
-	}
-	const EXT = ".page.md";
-	const pages = [];
-	for (const relative of entries) {
-		if (!relative.endsWith(EXT)) continue;
-		const parsed = parse(relative);
-		const dir = parsed.dir.replace(/\\/g, "/");
-		const base = parsed.base.slice(0, -8);
-		if (VARIANT_STEM_RE.test(base)) continue;
-		const filePath = join(pagesDir, relative);
-		const file = parsePage(await readFile(filePath, "utf-8"), richText ? { richText } : void 0);
-		if (file.draft) continue;
-		const path = `/${dir}/${base === "index" ? "" : base}`.replace("//", "/").replace(/\/$/, "") || "/";
-		const data = {
-			...dir ? foldersData[dir] : void 0,
-			...file.data ?? {}
-		};
-		const lastmod = typeof file.meta?.lastmod === "string" ? file.meta.lastmod : await stat(filePath).then((s) => s.mtime.toISOString().slice(0, 10)).catch(() => void 0);
-		const meta = path === "/404" ? {
-			noindex: true,
-			...file.meta
-		} : file.meta;
-		pages.push({
-			path,
-			logicalPath: path,
-			content: file.content ?? [],
-			data,
-			name: file.name,
-			lastmod,
-			page: {
-				meta,
-				...file.layout ? { layout: file.layout } : {}
-			}
-		});
-	}
-	return pages;
-}
-/**
-* Read a page's translation for `locale`, returning an {@link ExportPage} at the
-* locale-prefixed path — or `null` when the translation file is missing or is a
-* per-locale draft. Content/data come from the variant file; folder-scoped data
-* merges the same as the base page.
-*/
-async function readTranslation(mechDir, base, locale, config, richText) {
-	const file = getPagePath(mechDir, base.logicalPath, locale);
-	let raw;
-	try {
-		raw = await readFile(file, "utf-8");
-	} catch {
-		return null;
-	}
-	const doc = parsePage(raw, richText ? { richText } : void 0);
-	if (doc.draft) return null;
-	const rel = relative(join(mechDir, "pages"), file).replace(/\\/g, "/");
-	const dir = dirname(rel) === "." ? "" : dirname(rel);
-	let content = doc.content ?? [];
-	let pageData = doc.data ?? {};
-	let pageMeta = doc.meta;
-	try {
-		const baseDoc = parsePage(await readFile(getPagePath(mechDir, base.logicalPath), "utf-8"), richText ? { richText } : void 0);
-		const merged = mergeTranslation({
-			content: baseDoc.content ?? [],
-			data: baseDoc.data ?? {},
-			meta: baseDoc.meta ?? {}
-		}, {
-			content: doc.content ?? [],
-			data: doc.data ?? {},
-			meta: doc.meta ?? {}
-		});
-		content = merged.content;
-		pageData = merged.data;
-		pageMeta = merged.meta;
-	} catch {}
-	const folderData = readFolderData(mechDir, dir || null, locale);
-	const data = {
-		...readSiteLocaleOverride(mechDir, locale),
-		...folderData,
-		...pageData
-	};
-	const lastmod = typeof doc.meta?.lastmod === "string" ? doc.meta.lastmod : await stat(file).then((s) => s.mtime.toISOString().slice(0, 10)).catch(() => void 0);
-	const meta = base.logicalPath === "/404" ? {
-		noindex: true,
-		...pageMeta
-	} : pageMeta;
-	return {
-		path: localePath(base.logicalPath, locale, config),
-		logicalPath: base.logicalPath,
-		locale,
-		content,
-		data,
-		name: doc.name ?? base.name,
-		lastmod,
-		page: {
-			meta,
-			locale,
-			path: base.logicalPath,
-			...base.page?.layout ? { layout: base.page.layout } : {}
-		}
-	};
-}
-/**
-* The breadcrumb trail for a path — every ancestor (root first, the page last)
-* that actually exists as a page, named by its editor label. Feeds the auto
-* BreadcrumbList JSON-LD.
-*/
-function breadcrumbsFor(path, names) {
-	if (path === "/") return [];
-	const trail = ["/"];
-	let current = "";
-	for (const segment of path.slice(1).split("/")) {
-		current += `/${segment}`;
-		trail.push(current);
-	}
-	return trail.filter((p) => names.has(p)).map((p) => ({
-		name: names.get(p),
-		path: p
-	}));
-}
-/**
-* Map a baked {@link VirtualPage} to an {@link ExportPage}. The provider emits
-* one per (logical page × locale) and self-declares `locale`/`locales`, so the
-* mapping just localizes the served `path` and carries the alternates — it never
-* goes through the file-based `readTranslation`.
-*/
-function virtualToExportPage(v, config) {
-	const isDefault = !config || !v.locale || v.locale === config.default;
-	const locale = config ? v.locale ?? config.default : void 0;
-	const path = isDefault ? v.path : localePath(v.path, v.locale, config);
-	const name = typeof v.meta?.title === "string" ? v.meta.title : void 0;
-	return {
-		path,
-		logicalPath: v.path,
-		locale,
-		translations: v.locales,
-		content: v.content ?? [],
-		data: v.data ?? {},
-		name,
-		lastmod: v.lastmod,
-		page: {
-			meta: v.meta ?? {},
-			locale,
-			locales: v.locales,
-			path: v.path,
-			...v.layout ? { layout: v.layout } : {}
-		}
-	};
-}
-/**
-* Load the pieces needed to preload per-page block chunks: the client build's
-* Vite manifest and the plugin's block map. Older builds (or builds outside
-* `mechanica build`) may not have them — links are simply skipped then.
-*/
-async function readBlockAssets(cwd) {
-	try {
-		const [manifest, blockFiles] = await Promise.all([readFile(join(cwd, "dist/.vite/manifest.json"), "utf-8").then(JSON.parse), readFile(join(cwd, "dist", BLOCKS_MANIFEST_FILE), "utf-8").then(JSON.parse)]);
-		return {
-			manifest,
-			blockFiles
-		};
-	} catch {
-		return null;
-	}
-}
-/** Where uploaded assets land in the static export. */
-var MEDIA_DIR = "media";
-/**
-* Rewrite the uploaded-asset URLs a composed-block template carries — a
-* `mech:image` node's `src`, any node's `bgImage` fill — through `onFile`, in
-* the base data and every `$bp` layer. Page data goes through `collectFiles`
-* (schema-driven); templates live in the block definition, so they need their
-* own pass. Mutates the defs in place: they are the same objects the SSR
-* runtime's registered components render from.
-*/
-function rewriteComposedAssets(defs, onFile) {
-	const isRecord = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
-	const rewriteLayer = (blockId, layer) => {
-		if (blockId === "mech:image" && typeof layer.src === "string") layer.src = onFile(layer.src);
-		const bg = layer.bgImage;
-		if (isRecord(bg)) {
-			if (typeof bg.src === "string") bg.src = onFile(bg.src);
-			if (typeof bg.croppedSrc === "string") bg.croppedSrc = onFile(bg.croppedSrc);
-		}
-	};
-	for (const def of defs) walkTree(def.template ?? [], (node) => {
-		if (!node.data) return;
-		rewriteLayer(node.blockId, node.data);
-		const bp = node.data.$bp;
-		if (isRecord(bp)) {
-			for (const layer of Object.values(bp)) if (isRecord(layer)) rewriteLayer(node.blockId, layer);
-		}
-	});
-}
-/** Fill a value's missing preview/dimensions from a manifest entry. */
-function fillImageValue(value, entry) {
-	if (entry.previewSrc && (!value.previewSrc || value.previewSrc === value.src)) value.previewSrc = entry.previewSrc;
-	if (entry.width && !value.width) value.width = entry.width;
-	if (entry.height && !value.height) value.height = entry.height;
-}
-/**
-* Fill missing image metadata — LQIP `previewSrc` + intrinsic dimensions —
-* into the state being exported (page files are never touched). Sources, in
-* order: the `.mech/images.json` manifest (written by uploads, editor saves
-* and `mechanica images`), then the optional `sharp` dependency for anything
-* still missing — those computed entries are cached back into the manifest.
-* Without sharp, leftover gaps get a one-time hint.
-*/
-async function backfillImageMeta(pages, blocksMap, mechDir, warn) {
-	const manifest = readImageManifest(mechDir);
-	const incomplete = /* @__PURE__ */ new Map();
-	for (const page of pages) walkTree(page.content, (block) => {
-		const meta = blocksMap.get(block.blockId);
-		if (!meta) return;
-		walkSchema(block.data, meta.props, (value, schema) => {
-			if (schema.format !== "image") return;
-			const file = assetFileOf(value?.src);
-			if (!file) return;
-			const entry = manifest[file];
-			if (entry) fillImageValue(value, entry);
-			if (!value.previewSrc || value.previewSrc === value.src || !value.width || !value.height) incomplete.set(file, [...incomplete.get(file) ?? [], value]);
-		});
-	});
-	if (!incomplete.size) return;
-	if (!await hasSharp()) {
-		warn(`[mechanica] ${incomplete.size} image(s) lack a preview or dimensions — install the optional "sharp" dependency or run \`mechanica images\` to generate them`);
-		return;
-	}
-	const computed = {};
-	for (const [file, values] of incomplete) {
-		const buffer = await readFile(join(mechDir, "assets", file)).catch(() => null);
-		const info = buffer ? await analyzeImageBuffer(buffer) : null;
-		if (!info) continue;
-		computed[file] = info;
-		for (const value of values) fillImageValue(value, info);
-	}
-	updateImageManifest(mechDir, computed);
-}
+//#region src/cli/run-export.ts
 /**
-* Statically render every page of an already-built project into `export/`,
-* returning the generated page paths. This is the post-build core of
-* {@link runExport}, isolated so it can be tested without a Vite build: it
-* expects `<cwd>/dist` (index.html, assets, the loaded `ssr` bundle) and that
-* field schemas have been registered; it reads pages + scoped data from
-* `<cwd>/.mech`.
-*
-* Beyond the pages it also: rewrites + copies uploaded assets
-* (`/@mechanica/assets/…` → `/media/…`, or `<assetsUrl>/media/…` when a CDN
-* base is set), warns about dead internal links,
-* orphaned uploads and page-level SEO issues, emits `404.html` when a `/404`
-* page exists, and — when a site url is known (plugin `siteUrl` option or
-* `--site-url`) — injects the automatic SEO tags (canonical, `og:url`,
-* absolute social-image URLs, pagination prev/next, JSON-LD) and emits
-* `sitemap.xml` + `robots.txt`.
+* `mechanica export`: build the project, then statically render every page
+* into `export/`. Kept apart from `export.ts` so that module never imports
+* Vite — `mechanica/export` runs where only a built bundle exists.
 */
-async function exportProject(cwd, ssr, options = {}) {
-	const warn = options.onWarn ?? ((message) => console.warn(message));
-	const index = await readFile(join(cwd, "dist/index.html"), "utf-8");
-	const siteUrl = options.siteUrl ?? ssr.site?.url;
-	const siteName = options.siteName ?? ssr.site?.name;
-	const assetsBase = (options.assetsUrl ?? ssr.assetsUrl ?? "").replace(/\/+$/, "");
-	const composedDefs = ssr.composedList ?? [];
-	const blocks = [...ssr.blocksList.map(toBlockMeta), ...composedDefs.map(composedBlockMeta)];
-	const blocksMap = new Map(blocks.map((block) => [block.id, block]));
-	const composedMap = new Map(composedDefs.map((def) => [def.id, def]));
-	const richText = buildRichTextCodec(ssr.blocksList);
-	const foldersData = readFoldersData(join(cwd, ".mech"));
-	const defaultPages = await readPages(join(cwd, ".mech/pages"), foldersData, richText);
-	const projectData = readSiteData(join(cwd, ".mech"));
-	const config = ssr.locales ?? null;
-	const mechDir = join(cwd, ".mech");
-	const pages = [...defaultPages];
-	if (config) {
-		const missing = {};
-		for (const base of defaultPages) {
-			const present = [config.default];
-			for (const locale of config.all) {
-				if (locale === config.default) continue;
-				const translation = await readTranslation(mechDir, base, locale, config, richText);
-				if (translation) {
-					present.push(locale);
-					pages.push(translation);
-				} else if (!base.page?.meta?.noindex) (missing[locale] ??= []).push(base.logicalPath);
-			}
-			base.translations = present;
-			if (base.page) base.locale = config.default;
-			base.page = {
-				...base.page,
-				locale: config.default,
-				locales: present
-			};
-		}
-		const translationsByLogical = new Map(defaultPages.map((p) => [p.logicalPath, p.translations]));
-		for (const page of pages) if (page.locale && page.locale !== config.default) {
-			const present = translationsByLogical.get(page.logicalPath);
-			page.translations = present;
-			page.page = {
-				...page.page,
-				locales: present
-			};
-		}
-		for (const [locale, paths] of Object.entries(missing)) if (paths.length) warn(`[mechanica] locale "${locale}" is missing ${paths.length} translation(s) (rendered only in ${config.default}): ${paths.join(", ")}`);
-	}
-	if (ssr.generatedPages?.length) {
-		const taken = new Set(pages.map((page) => page.path));
-		for (const vp of ssr.generatedPages) {
-			const generated = virtualToExportPage(vp, config);
-			if (taken.has(generated.path)) throw new Error(`[mechanica] generatePages produced "${generated.path}", but a page already exists there — change the generated path or remove the conflicting page.`);
-			taken.add(generated.path);
-			pages.push(generated);
-		}
-	}
-	setPageCodec(richText);
-	const querySource = {
-		listPages: (opts) => listPages(join(cwd, ".mech"), {
-			...opts,
-			generated: ssr.generatedPages
-		}),
-		fetchJson: async ({ url, ...init }) => {
-			const res = await fetch(url, init);
-			if (!res.ok) throw new Error(`${url} responded ${res.status}`);
-			return res.json();
-		}
-	};
-	const queryCache = /* @__PURE__ */ new Map();
-	const resolveForPage = (pageNumber, pageLocale) => (key) => {
-		const locale = config && pageLocale && pageLocale !== config.default ? pageLocale : void 0;
-		const cacheKey = `${pageNumber} ${locale ?? ""} ${key}`;
-		let hit = queryCache.get(cacheKey);
-		if (!hit) {
-			hit = resolveQueryKey(querySource, key, {
-				page: pageNumber,
-				locale
-			});
-			queryCache.set(cacheKey, hit);
-		}
-		return hit;
-	};
-	for (const page of pages) {
-		migrateContent(page.content, blocksMap);
-		for (const id of findUnknownBlocks(page.content, blocksMap)) warn(`[mechanica] Page ${page.path} references unknown block "${id}" — it renders as nothing`);
-	}
-	if (ssr.layoutNames) {
-		const layoutNames = ssr.layoutNames;
-		const seen = /* @__PURE__ */ new Set();
-		for (const page of pages) {
-			const layout = page.page?.layout;
-			if (!layout || layoutNames.includes(layout) || seen.has(page.logicalPath)) continue;
-			seen.add(page.logicalPath);
-			warn(layoutNames.length === 0 ? `[mechanica] Page ${page.logicalPath} sets layout "${layout}", but the app declares no layouts (defineMechanicaApp({ layouts }))` : `[mechanica] Page ${page.logicalPath} uses unknown layout "${layout}" — it falls back to "${layoutNames[0]}" (declared: ${layoutNames.join(", ")})`);
-		}
-	}
-	if (!pages.some((page) => page.logicalPath === "/404")) warn("[mechanica] No /404 page — the static host will show its own error page. Create a page at /404 (it exports as 404.html and is noindexed automatically).");
-	for (const issue of validateLinks(pages, blocksMap)) warn(`[mechanica] Broken link on ${issue.page}: ${issue.url} has no matching page`);
-	await backfillImageMeta(pages, blocksMap, join(cwd, ".mech"), warn);
-	const exportDir = join(cwd, "export");
-	await rm(exportDir, {
-		recursive: true,
-		force: true
-	});
-	await mkdir(exportDir, { recursive: true });
-	const DIST_PRIVATE = /* @__PURE__ */ new Set([
-		"index.html",
-		"ssr.js",
-		"ssr.js.map",
-		".vite",
-		BLOCKS_MANIFEST_FILE
-	]);
-	const distEntries = await readdir(join(cwd, "dist")).catch(() => []);
-	for (const entry of distEntries) {
-		if (DIST_PRIVATE.has(entry)) continue;
-		await cp(join(cwd, "dist", entry), join(exportDir, entry), { recursive: true });
-	}
-	const referenced = /* @__PURE__ */ new Set();
-	const onFile = (src) => {
-		if (typeof src !== "string" || !src.startsWith("/@mechanica/assets/")) return src;
-		const relative = decodeURIComponent(src.slice(UPLOADS_PREFIX.length));
-		referenced.add(relative);
-		return `${assetsBase}/${MEDIA_DIR}/${relative}`;
-	};
-	rewriteComposedAssets(composedDefs, onFile);
-	const blockAssets = await readBlockAssets(cwd);
-	const pageLinks = blockAssets ? (content) => {
-		const blockIds = /* @__PURE__ */ new Set();
-		const add = (id) => {
-			if (blockIds.has(id)) return;
-			blockIds.add(id);
-			const def = composedMap.get(id);
-			if (def) for (const inner of templateBlockIds(def)) add(inner);
-		};
-		walkTree(content, (block) => add(block.blockId));
-		return blockAssetLinks({
-			blockIds,
-			...blockAssets,
-			base: assetsBase || void 0,
-			alreadyLinked: (file) => index.includes(file)
-		});
-	} : void 0;
-	const projectOptions = {
-		index,
-		blocksMap,
-		dataEntries: ssr.dataEntries ?? [],
-		projectData,
-		site: {
-			url: siteUrl,
-			name: siteName
-		},
-		assetsUrl: assetsBase || void 0,
-		locales: config ?? void 0,
-		render: (state) => ssr.render(state, { resolveQuery: resolveForPage(state.page?.pagination?.page ?? 1, state.page?.locale) }),
-		onFile,
-		pageLinks
-	};
-	const written = [];
-	const writePage = async (path, html) => {
-		const dir = path === "/" ? exportDir : join(exportDir, path);
-		await mkdir(dir, { recursive: true });
-		await writeFile(join(dir, "index.html"), html);
-		written.push(path);
-	};
-	const templateHandlesPagination = index.includes("page.pagination");
-	const pageNames = new Map(defaultPages.map((page) => [page.logicalPath, page.name ?? (page.logicalPath === "/" ? "Home" : page.logicalPath.split("/").pop())]));
-	for (const vp of ssr.generatedPages ?? []) pageNames.set(vp.path, typeof vp.meta?.title === "string" ? vp.meta.title : vp.path.split("/").pop());
-	/** hreflang alternates for a translated page (each locale + x-default), at page N. */
-	const alternatesFor = (source, pageNum = 1) => {
-		if (!config || !source.translations || source.translations.length < 2) return void 0;
-		const at = (loc) => paginationVariantPath(localePath(source.logicalPath, loc, config), pageNum);
-		return [{
-			hreflang: "x-default",
-			path: at(config.default)
-		}, ...source.translations.map((loc) => ({
-			hreflang: loc,
-			path: at(loc)
-		}))];
-	};
-	const finishPage = (html, path, source, pagination) => {
-		let out = applySeoTags(html, {
-			siteUrl,
-			siteName,
-			path,
-			noindex: source.page?.meta?.noindex === true,
-			pagination,
-			templateHandlesPagination,
-			breadcrumbs: breadcrumbsFor(source.logicalPath, pageNames),
-			alternates: alternatesFor(source, pagination?.page ?? 1)
-		});
-		if (config) out = setHtmlLang(out, source.locale ?? config.default);
-		return out;
-	};
-	const sitemapEntries = [];
-	const recordSitemap = (path, source, pageNum = 1) => {
-		if (path === "/404" || source.page?.meta?.noindex === true) return;
-		sitemapEntries.push({
-			path,
-			lastmod: source.lastmod,
-			alternates: alternatesFor(source, pageNum)
-		});
-	};
-	const knownPaths = new Set(pages.map((page) => page.path));
-	const pageByPath = new Map(pages.map((page) => [page.path, page]));
-	const variants = [];
-	const titlePages = /* @__PURE__ */ new Map();
-	for await (const { html, path, query } of generateProject({
-		...projectOptions,
-		pages
-	})) {
-		const source = pageByPath.get(path);
-		let pageCount = 1;
-		for (const [key, result] of Object.entries(query)) {
-			if (!isPaginatedQuery(key)) continue;
-			pageCount = Math.max(pageCount, result?.pageCount ?? 1);
-		}
-		const pagination = pageCount > 1 ? {
-			page: 1,
-			pageCount,
-			basePath: path
-		} : void 0;
-		const finished = finishPage(html, path, source, pagination);
-		await writePage(path, finished);
-		recordSitemap(path, source);
-		for (const issue of auditPageHtml(finished)) warn(`[mechanica] SEO on ${path}: ${issue}`);
-		const title = finished.match(/<title[^>]*>([\s\S]*?)<\/title>/i)?.[1]?.trim();
-		if (title) titlePages.set(title, [...titlePages.get(title) ?? [], path]);
-		if (!pagination) continue;
-		const base = path === "/" ? "" : path;
-		for (let n = 2; n <= pageCount; n++) {
-			const variantPath = `${base}/${n}`;
-			if (knownPaths.has(variantPath)) throw new Error(`[mechanica] Paginated page ${path} needs ${variantPath}, but a real page already exists at that path — rename that page or adjust the pagination.`);
-			variants.push({
-				...source,
-				path: variantPath,
-				page: {
-					...source.page,
-					pagination: {
-						page: n,
-						pageCount
-					}
-				}
-			});
-		}
-	}
-	for (const [title, paths] of titlePages) if (paths.length > 1) warn(`[mechanica] SEO: ${paths.length} pages share the title "${title}": ${paths.join(", ")}`);
-	for await (const { html, path } of generateProject({
-		...projectOptions,
-		pages: variants
-	})) {
-		const source = variants.find((page) => page.path === path);
-		const basePath = path.replace(/\/\d+$/, "") || "/";
-		await writePage(path, finishPage(html, path, source, {
-			...source.page.pagination,
-			basePath
-		}));
-		recordSitemap(path, source, source.page.pagination.page);
-	}
-	await copyUploads(join(cwd, ".mech/assets"), join(exportDir, MEDIA_DIR), referenced, warn);
-	if (written.includes("/404")) await copyFile(join(exportDir, "404/index.html"), join(exportDir, "404.html"));
-	if (siteUrl) {
-		await writeFile(join(exportDir, "sitemap.xml"), buildSitemap(siteUrl, sitemapEntries));
-		const robotsPath = join(exportDir, "robots.txt");
-		if (!await access(robotsPath).then(() => true, () => false)) await writeFile(robotsPath, buildRobotsTxt(siteUrl));
-	}
-	return written;
-}
-/** Copy referenced uploads into the export; warn about missing + orphaned files. */
-async function copyUploads(assetsDir, outDir, referenced, warn) {
-	for (const relative of referenced) {
-		const target = join(outDir, relative);
-		await mkdir(dirname(target), { recursive: true });
-		await copyFile(join(assetsDir, relative), target).catch(() => {
-			warn(`[mechanica] Missing upload: ${relative} is referenced by a page but not in .mech/assets`);
-		});
-	}
-	const orphans = (await readdir(assetsDir, { recursive: true }).catch(() => [])).map((entry) => entry.replace(/\\/g, "/")).filter((entry) => /\.\w+$/.test(entry) && !referenced.has(entry) && !isDerivedAsset(entry));
-	if (orphans.length) warn(`[mechanica] ${orphans.length} unused upload(s) in .mech/assets (not exported): ${orphans.join(", ")}`);
-}
-/** Build the project, then statically render every page into `export/`. */
 async function runExport(options = {}) {
 	await runBuild();
-	registerFieldSchemas();
-	const cwd = process.cwd();
-	const written = await exportProject(cwd, await import(pathToFileURL(join(cwd, "dist/ssr.js")).href), options);
-	for (const path of written) console.info("Generated", path);
-	console.info(`Exported ${written.length} page(s) → export/`);
+	const { pages } = await exportBuilt(process.cwd(), options);
+	for (const path of pages) console.info("Generated", path);
+	console.info(`Exported ${pages.length} page(s) → ${options.outDir ?? "export"}/`);
 }
 //#endregion
 //#region src/cli/images.ts
@@ -673,71 +128,433 @@ async function runImages(options = {}) {
 	const summary = skipped ? `, ${skipped} already complete` : "";
 	console.info(`Analyzed ${Object.keys(computed).length} image(s)${summary} → .mech/images.json`);
 }
+/** Normalize a host argument to an origin (`https://example.com`, no trailing slash or path). */
+function hostOrigin(host) {
+	const value = host ?? process.env.MECHANICA_HOST ?? "https://mechanica.jt3.ru";
+	return new URL(/^https?:\/\//.test(value) ? value : `https://${value}`).origin;
+}
+/** Where access tokens are kept: one file per user, outside any project. */
+function credentialsFile() {
+	return join(process.env.MECHANICA_CONFIG_DIR ?? join(os.homedir(), ".mechanica"), "credentials.json");
+}
+async function readAll() {
+	try {
+		const parsed = JSON.parse(await readFile(credentialsFile(), "utf-8"));
+		return parsed && typeof parsed === "object" ? parsed : {};
+	} catch {
+		return {};
+	}
+}
+/**
+* The access token for a platform origin: `MECHANICA_TOKEN` (CI) wins over the
+* one `mechanica login` saved.
+*/
+async function getToken(origin) {
+	if (process.env.MECHANICA_TOKEN) return process.env.MECHANICA_TOKEN;
+	return (await readAll())[origin] ?? null;
+}
+/** Remember the token for an origin, in a file only the user can read. */
+async function saveToken(origin, token) {
+	const file = credentialsFile();
+	const all = await readAll();
+	all[origin] = token;
+	await mkdir(join(file, ".."), { recursive: true });
+	await writeFile(file, JSON.stringify(all, null, 2) + "\n", { mode: 384 });
+	await chmod(file, 384).catch(() => {});
+	return file;
+}
 //#endregion
-//#region src/cli/push.ts
+//#region src/cli/platform/api.ts
+/** A failed platform request: the HTTP status plus the message the platform gave. */
+var PlatformError = class extends Error {
+	status;
+	constructor(status, message) {
+		super(message);
+		this.status = status;
+	}
+};
+/** The platform answers errors as plain text or as `{ error: { field: { message } } }`. */
+function errorMessage(status, text) {
+	try {
+		const error = JSON.parse(text)?.error;
+		if (typeof error === "string") return error;
+		if (error && typeof error === "object") {
+			const messages = Object.values(error).map((item) => item?.message).filter((message) => typeof message === "string");
+			if (messages.length) return messages.join("; ");
+		}
+	} catch {}
+	return text.trim() || `Request failed (${status})`;
+}
+/** One request to the platform API; resolves with the parsed JSON body (or null). */
+async function request(origin, method, path, options = {}) {
+	const headers = {};
+	if (options.token) headers.authorization = `Bearer ${options.token}`;
+	if (options.raw) headers["content-type"] = "application/octet-stream";
+	else if (options.body !== void 0) headers["content-type"] = "application/json";
+	let response;
+	try {
+		response = await fetch(origin + path, {
+			method,
+			headers,
+			body: options.raw ?? (options.body !== void 0 ? JSON.stringify(options.body) : void 0)
+		});
+	} catch (error) {
+		throw new PlatformError(0, `Could not reach ${origin} (${error.message})`);
+	}
+	const text = await response.text();
+	if (!response.ok) throw new PlatformError(response.status, errorMessage(response.status, text));
+	return text ? JSON.parse(text) : null;
+}
+/** The saved token for `origin`, or an error telling the user to log in. */
+async function requireToken(origin) {
+	const token = await getToken(origin);
+	if (!token) throw new Error(`Not logged in to ${origin} — run \`mechanica login\` first`);
+	return token;
+}
+/** The name of the git remote `mechanica link` manages. */
+var REMOTE_NAME = "mechanica";
 /**
-* Upload a built project to a backend. Preserves v1's binary body format
-* (a JSON tree header + concatenated file buffers) so the existing backend
-* keeps working; the contract is redesigned later with the SAAS service.
+* Split a site's git remote URL (`https://host/git/<slug>.git`) into the
+* platform origin and the slug; null for a URL that is not one of ours.
 */
-async function runPush(options) {
-	const apiKey = options.key ?? process.env.BUILDER_API_KEY;
-	const host = options.host ?? process.env.BUILDER_HOST ?? "https://builder.jt3.ru";
-	if (!apiKey) {
-		console.error("[mechanica push] missing --key (or BUILDER_API_KEY)");
-		process.exitCode = 1;
-		return;
+function parseRemoteUrl(url) {
+	try {
+		const parsed = new URL(url);
+		const match = /^\/git\/([a-z0-9][a-z0-9-]*[a-z0-9])\.git\/?$/.exec(parsed.pathname);
+		if (!match || !/^https?:$/.test(parsed.protocol)) return null;
+		return {
+			origin: parsed.origin,
+			slug: match[1]
+		};
+	} catch {
+		return null;
 	}
-	const root = join(process.cwd(), options.dir ?? "dist");
-	const buffers = [];
-	let written = 0;
-	const walk = async (dir) => {
-		const result = [];
-		for (const name of await readdir(dir)) {
-			const full = join(dir, name);
-			const info = await stat(full);
-			if (info.isDirectory()) result.push({
-				type: "folder",
-				name,
-				mtime: info.mtimeMs,
-				children: await walk(full)
+}
+//#endregion
+//#region src/cli/platform/git.ts
+/**
+* Environment that makes git send the access token to one origin only, as HTTP
+* Basic credentials. Passed through `GIT_CONFIG_*` variables so the token never
+* appears on a command line (visible to other processes) or in the repo config.
+*/
+function gitAuthEnv(origin, token) {
+	const basic = Buffer.from(`mechanica:${token}`).toString("base64");
+	return {
+		GIT_CONFIG_COUNT: "1",
+		GIT_CONFIG_KEY_0: `http.${origin}/.extraHeader`,
+		GIT_CONFIG_VALUE_0: `Authorization: Basic ${basic}`,
+		GIT_TERMINAL_PROMPT: "0"
+	};
+}
+/** Run git in `cwd` and collect its output; never throws on a non-zero exit. */
+function git(cwd, args, env = {}) {
+	return new Promise((resolve, reject) => {
+		const child = spawn("git", args, {
+			cwd,
+			env: {
+				...process.env,
+				...env
+			},
+			windowsHide: true
+		});
+		let stdout = "";
+		let stderr = "";
+		child.stdout.on("data", (chunk) => stdout += chunk);
+		child.stderr.on("data", (chunk) => stderr += chunk);
+		child.on("error", (error) => reject(error.code === "ENOENT" ? /* @__PURE__ */ new Error("git is not installed (or not on PATH)") : error));
+		child.on("close", (code) => resolve({
+			code: code ?? 1,
+			stdout: stdout.trim(),
+			stderr: stderr.trim()
+		}));
+	});
+}
+/** Like {@link git}, but a non-zero exit throws with git's own message. */
+async function gitOk(cwd, args, env = {}) {
+	const result = await git(cwd, args, env);
+	if (result.code !== 0) throw new Error(result.stderr || result.stdout || `git ${args[0]} failed`);
+	return result.stdout;
+}
+//#endregion
+//#region src/cli/platform/link.ts
+/**
+* `mechanica link <slug>`: attach this project to a site on the platform by
+* pointing the `mechanica` git remote at it. With `--create` the site is made
+* first. The remote is the whole link — `mechanica push` reads the platform
+* origin and the site from its URL, so there is no extra config file.
+*/
+async function runLink(slug, options) {
+	if (!slug) throw new Error("Usage: mechanica link <slug> [--create] [--name \"Site name\"]");
+	const cwd = process.cwd();
+	const origin = hostOrigin(options.host);
+	const token = await requireToken(origin);
+	if ((await git(cwd, ["rev-parse", "--is-inside-work-tree"])).code !== 0) throw new Error("This folder is not a git repository — run `git init` first");
+	const sites = await request(origin, "GET", "/api/sites", { token });
+	let site = sites.find((item) => item.slug === slug);
+	if (!site) {
+		if (!options.create) {
+			const known = sites.length ? `Your sites: ${sites.map((item) => item.slug).join(", ")}.` : "You have no sites yet.";
+			throw new Error(`No site "${slug}" on ${origin}. ${known} Pass --create to make it.`);
+		}
+		try {
+			site = await request(origin, "POST", "/api/sites", {
+				token,
+				body: {
+					slug,
+					name: options.name ?? slug
+				}
 			});
-			else {
-				const file = await readFile(full);
-				result.push({
-					type: "file",
-					name,
-					size: info.size,
-					mtime: info.mtimeMs,
-					offset: written,
-					length: file.byteLength
-				});
-				buffers.push(file);
-				written += file.byteLength;
-			}
+		} catch (error) {
+			if (error instanceof PlatformError) throw new Error(`Could not create "${slug}": ${error.message}`);
+			throw error;
 		}
-		return result;
-	};
-	const tree = await walk(root);
-	const header = Buffer.from(JSON.stringify(tree), "utf-8");
-	const controls = new Uint32Array([header.length, written]);
-	const body = Buffer.concat([
-		Buffer.from(controls.buffer),
-		header,
-		...buffers
+		console.info(`Created site ${site.slug}`);
+	}
+	if ((await git(cwd, [
+		"remote",
+		"get-url",
+		"mechanica"
+	])).code === 0) await gitOk(cwd, [
+		"remote",
+		"set-url",
+		REMOTE_NAME,
+		site.gitUrl
 	]);
-	console.info(`Pushing ${root} → ${host}…`);
-	const response = await fetch(`${host}/api/projects/push`, {
-		method: "POST",
-		headers: {
-			authorization: `Bearer ${apiKey}`,
-			"content-type": "application/octet-stream"
-		},
-		body
+	else await gitOk(cwd, [
+		"remote",
+		"add",
+		REMOTE_NAME,
+		site.gitUrl
+	]);
+	console.info(`Linked to ${site.slug} (${site.gitUrl})`);
+	console.info("Commit your work, then run `mechanica push` to deploy it.");
+}
+//#endregion
+//#region src/cli/platform/login.ts
+/** Ask one line on the terminal; with `hidden`, the typed characters are not echoed. */
+function prompt(question, hidden = false) {
+	return new Promise((resolve) => {
+		const rl = readline.createInterface({
+			input: process.stdin,
+			output: process.stdout,
+			terminal: true
+		});
+		if (hidden) {
+			const write = rl._writeToOutput.bind(rl);
+			let asked = false;
+			rl._writeToOutput = (text) => {
+				if (!asked) write(text);
+				asked = true;
+			};
+		}
+		rl.question(question, (answer) => {
+			rl.close();
+			if (hidden) process.stdout.write("\n");
+			resolve(answer.trim());
+		});
 	});
-	const text = await response.text();
-	if (!response.ok) throw new Error(`Push failed (${response.status}): ${text}`);
-	console.info("Project pushed successfully.", text);
+}
+/**
+* `mechanica login`: sign in to the platform and keep an access token for this
+* machine. With `--token` the given token is stored as is (CI, or a token made
+* in the dashboard); otherwise it asks for email + password and creates one.
+*/
+async function runLogin(options) {
+	const origin = hostOrigin(options.host);
+	let token = options.token;
+	if (!token) {
+		if (!process.stdin.isTTY) throw new Error("No terminal to ask for credentials — pass --token <access token>");
+		console.info(`Signing in to ${origin}`);
+		token = (await request(origin, "POST", "/api/account/tokens", {
+			token: (await request(origin, "POST", "/api/account/login", { body: {
+				login: await prompt("Email: "),
+				password: await prompt("Password: ", true)
+			} })).accessToken,
+			body: { name: `CLI on ${os.hostname()}` }
+		})).token;
+	}
+	const account = await request(origin, "GET", "/api/account", { token });
+	const file = await saveToken(origin, token);
+	console.info(`Logged in to ${origin} as ${account.email}`);
+	console.info(`Access token saved to ${file}`);
+}
+//#endregion
+//#region src/cli/platform/bundle-format.ts
+/**
+* The bundle `mechanica push` uploads: the built `dist/` for one commit, as one
+* request body.
+*
+*   "MCHB" | u32 LE header length | header JSON | the files' bytes, in header order
+*   header = { format: 1, commit, engine, files: [ { path, size } ] }
+*
+* `commit` ties the bundle to the source it was built from; `engine` (this
+* package's version) tells the platform which export code to render it with.
+* Paths are relative to `dist/`, forward-slashed, sorted — the same build always
+* produces the same header.
+*/
+var BUNDLE_MAGIC = "MCHB";
+/** Every file under `dir`, as forward-slashed paths relative to it, sorted. */
+async function listBundleFiles(dir) {
+	return (await readdir(dir, {
+		recursive: true,
+		withFileTypes: true
+	})).filter((entry) => entry.isFile()).map((entry) => join(entry.parentPath, entry.name).slice(dir.length + 1).replace(/\\/g, "/")).sort();
+}
+/** Serialize already-read files into a bundle body. */
+function encodeBundle(meta, files) {
+	const header = {
+		format: 1,
+		commit: meta.commit,
+		engine: meta.engine,
+		files: files.map((file) => ({
+			path: file.path,
+			size: file.data.length
+		}))
+	};
+	const head = new TextEncoder().encode(JSON.stringify(header));
+	const total = 8 + head.length + files.reduce((sum, file) => sum + file.data.length, 0);
+	const body = new Uint8Array(total);
+	body.set(new TextEncoder().encode(BUNDLE_MAGIC), 0);
+	new DataView(body.buffer).setUint32(4, head.length, true);
+	body.set(head, 8);
+	let offset = 8 + head.length;
+	for (const file of files) {
+		body.set(file.data, offset);
+		offset += file.data.length;
+	}
+	return body;
+}
+/** Read a built `dist/` and pack it for upload. */
+async function packBundle(distDir, meta) {
+	const paths = await listBundleFiles(distDir);
+	return encodeBundle(meta, await Promise.all(paths.map(async (path) => ({
+		path,
+		data: new Uint8Array(await readFile(join(distDir, path)))
+	}))));
+}
+//#endregion
+//#region src/cli/platform/engine-version.ts
+/**
+* This package's version, read from its own `package.json` — found by walking
+* up from this module, which sits at a different depth in `src/` and in the
+* built `dist/` (and its chunks).
+*/
+function engineVersion() {
+	let dir = dirname(fileURLToPath(import.meta.url));
+	for (let depth = 0; depth < 6; depth++) {
+		try {
+			const pkg = JSON.parse(readFileSync(join(dir, "package.json"), "utf-8"));
+			if (pkg.name === "mechanica" && typeof pkg.version === "string") return pkg.version;
+		} catch {}
+		dir = dirname(dir);
+	}
+	throw new Error("Could not determine the mechanica version");
+}
+//#endregion
+//#region src/cli/platform/push.ts
+var sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+var POLL_MS = 1e3;
+var DEPLOY_TIMEOUT_MS = 3e5;
+var AUTO_DEPLOY_WAIT_MS = 1e4;
+/**
+* `mechanica push`: publish the committed project to the platform.
+*
+*   1. bring in what was published online since the last pull (`pull --rebase`),
+*   2. `git push` the commits to the site's repository,
+*   3. if the code changed, build locally and upload the bundle for that commit
+*      (content-only pushes reuse the bundle already there — no build at all),
+*   4. wait for the deploy and report it.
+*
+* The build runs on this machine; the platform only ever renders the bundle.
+*/
+async function runPush() {
+	const cwd = process.cwd();
+	if ((await git(cwd, ["rev-parse", "--is-inside-work-tree"])).code !== 0) throw new Error("This folder is not a git repository — run `git init`, commit, then `mechanica link <slug>`");
+	const top = await realpath(await gitOk(cwd, ["rev-parse", "--show-toplevel"]));
+	if (top !== await realpath(cwd)) throw new Error(`Run \`mechanica push\` from the repository root (${top}) — the site must be the whole repository`);
+	const remote = await git(cwd, [
+		"remote",
+		"get-url",
+		REMOTE_NAME
+	]);
+	const link = remote.code === 0 ? parseRemoteUrl(remote.stdout) : null;
+	if (!link) throw new Error("This project is not linked to a site — run `mechanica link <slug>` first");
+	const token = await requireToken(link.origin);
+	const auth = gitAuthEnv(link.origin, token);
+	const site = (await request(link.origin, "GET", "/api/sites", { token })).find((item) => item.slug === link.slug);
+	if (!site) throw new Error(`You have no access to the site "${link.slug}" on ${link.origin}`);
+	if ((await git(cwd, [
+		"rev-parse",
+		"--verify",
+		"--quiet",
+		"HEAD"
+	])).code !== 0) throw new Error("Nothing to push yet — commit your project first");
+	const dirty = await gitOk(cwd, ["status", "--porcelain"]);
+	if (dirty) throw new Error(`Commit or stash your changes first — the working tree is not clean:\n${dirty}`);
+	if (await gitOk(cwd, [
+		"ls-remote",
+		"--heads",
+		"mechanica",
+		"main"
+	], auth)) {
+		console.info("Pulling changes from the platform…");
+		const pulled = await git(cwd, [
+			"pull",
+			"--rebase",
+			REMOTE_NAME,
+			"main"
+		], auth);
+		if (pulled.code !== 0) throw new Error(`Could not rebase onto the platform's changes:\n${pulled.stderr || pulled.stdout}\nResolve the conflict (\`git rebase --continue\`), then run \`mechanica push\` again.`);
+	}
+	const head = await gitOk(cwd, ["rev-parse", "HEAD"]);
+	console.info(`Pushing ${head.slice(0, 8)} to ${link.slug}…`);
+	const pushed = await git(cwd, [
+		"push",
+		REMOTE_NAME,
+		"HEAD:refs/heads/main"
+	], auth);
+	if (pushed.code !== 0) throw new Error(`git push failed:\n${pushed.stderr || pushed.stdout}`);
+	const statusPath = `/api/sites/${site.uuid}/status`;
+	let status = await request(link.origin, "GET", statusPath, { token });
+	let deployId = null;
+	if (status.needsBundle) {
+		await runBuild();
+		const body = await packBundle(join(cwd, "dist"), {
+			commit: head,
+			engine: engineVersion()
+		});
+		console.info(`Uploading the bundle (${(body.length / 1024 / 1024).toFixed(1)} MB)…`);
+		const uploaded = await request(link.origin, "POST", `/api/sites/${site.uuid}/bundles`, {
+			token,
+			raw: body
+		});
+		if (uploaded.deployId === null) throw new Error(`The bundle was not deployed: ${uploaded.reason}`);
+		deployId = uploaded.deployId;
+	} else {
+		console.info("Only content changed — the platform reuses the current bundle.");
+		const deadline = Date.now() + AUTO_DEPLOY_WAIT_MS;
+		while (status.latestDeploy?.contentCommit !== head && Date.now() < deadline) {
+			await sleep(POLL_MS / 2);
+			status = await request(link.origin, "GET", statusPath, { token });
+		}
+		if (status.latestDeploy?.contentCommit !== head) throw new Error("The platform did not start a deploy for this push — try `mechanica push` again");
+		deployId = status.latestDeploy.id;
+	}
+	const deployPath = `/api/sites/${site.uuid}/deploys/${deployId}`;
+	const deadline = Date.now() + DEPLOY_TIMEOUT_MS;
+	let deploy = await request(link.origin, "GET", deployPath, { token });
+	if (deploy.status === "rendering") console.info("Rendering…");
+	while (deploy.status === "rendering") {
+		if (Date.now() > deadline) throw new Error("Timed out waiting for the deploy — check the site later");
+		await sleep(POLL_MS);
+		deploy = await request(link.origin, "GET", deployPath, { token });
+	}
+	for (const warning of deploy.warnings ?? []) console.warn(warning);
+	if (deploy.status === "failed") {
+		if (deploy.log) console.error(`\n${deploy.log}\n`);
+		throw new Error(`Deploy failed: ${deploy.error ?? "unknown error"}. The previous version stays live.`);
+	}
+	console.info(`\nLive at ${deploy.url ?? status.url} — ${deploy.pages} page(s)`);
 }
 //#endregion
 //#region src/cli/headless.ts
@@ -1415,7 +1232,13 @@ Usage:
                              --site-name <name> adds WebSite JSON-LD;
                              --assets-url <origin> serves /assets and /media from
                              a CDN base — files still land in export/)
-  mechanica push [--key]    Upload dist/ to a backend (--key, --host, --dir)
+  mechanica login           Sign in to the Mechanica platform and save an access
+                            token for this machine (--host <url>, --token <token>)
+  mechanica link <slug>     Point this repository at a site on the platform
+                            (--create makes the site, --name "Site name")
+  mechanica push            Publish the committed project: pull what was edited
+                            online, git push, build + upload the bundle when the
+                            code changed, and wait for the deploy
   mechanica shot <blockId>  Screenshot one block via the dev preview route
   mechanica shot </path>    Screenshot a whole page (editor overlay stripped)
                             (--page </path>, --data <json|@file>, --width 1440,768,
@@ -1443,11 +1266,16 @@ async function run(argv) {
 			assetsUrl: str(flags["assets-url"])
 		});
 		case "images": return runImages({ force: flags.force === true });
-		case "push": return runPush({
-			key: str(flags.key),
+		case "login": return runLogin({
+			host: str(flags.host),
+			token: str(flags.token)
+		});
+		case "link": return runLink(args[0], {
 			host: str(flags.host),
-			dir: str(flags.dir)
+			create: flags.create === true,
+			name: str(flags.name)
 		});
+		case "push": return runPush();
 		case "shot": return runShot(args[0], {
 			page: str(flags.page),
 			data: str(flags.data),