@homepages/template-cli 0.1.0

package/dist/cli/check/stages/validate/list-scalar-contract.js

@@ -0,0 +1,22 @@
+//#region src/cli/check/stages/validate/list-scalar-contract.ts
+const SCALAR_ELEMENT_TYPES = /* @__PURE__ */ new Set(["text", "number"]);
+function checkListSlot(slot, label, sectionKey) {
+	if (slot.element == null) throw new Error(`Section "${sectionKey}": ${label} must declare \`element\` (a scalar Slot, text|number).`);
+	if (!SCALAR_ELEMENT_TYPES.has(slot.element.type ?? "")) throw new Error(`Section "${sectionKey}": ${label} element must be a scalar Slot (text|number), got "${slot.element.type}".`);
+}
+function assertListScalarContract(schema, sectionKey) {
+	for (const [slotId, slotUnknown] of Object.entries(schema.slots)) {
+		const slot = slotUnknown;
+		if (slot.type === "list") {
+			checkListSlot(slot, `list "${slotId}"`, sectionKey);
+			continue;
+		}
+		if (slot.type === "object_list" && slot.item != null) for (const [childId, child] of Object.entries(slot.item)) {
+			if (child.type !== "list") continue;
+			checkListSlot(child, `object_list "${slotId}" field "${childId}"`, sectionKey);
+		}
+	}
+}
+
+//#endregion
+export { assertListScalarContract };

package/dist/cli/check/stages/validate/nav-contract.js

@@ -0,0 +1,89 @@
+import { loadSection } from "../../loader.js";
+import { materializeSection } from "./orchestrator.js";
+import { FixtureModuleShape, TemplateManifest, buildFixtureSet } from "@homepages/template-kit";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { renderSectionHtml, resolveAnchorMap, resolveFixtureSetMedia, resolveSectionRef } from "@homepages/template-kit/ssr";
+
+//#region src/cli/check/stages/validate/nav-contract.ts
+const ALLOWED_EXTERNAL_ANCHORS = ["#privacy-policy"];
+function guardedAnchors(anchors, templateKey) {
+	return new Proxy(anchors, { get(target, prop, receiver) {
+		if (typeof prop === "string" && !(prop in target)) throw new Error(`Template "${templateKey}": section renderer referenced nav.anchors["${prop}"], but no composed section resolves to that key (dangling cross-section link).`);
+		return Reflect.get(target, prop, receiver);
+	} });
+}
+function collectNavViolations(html, allow) {
+	const ids = /* @__PURE__ */ new Set();
+	for (const m of html.matchAll(/\sid="([^"]*)"/g)) ids.add(m[1]);
+	const allowSet = new Set(allow);
+	const violations = /* @__PURE__ */ new Set();
+	for (const m of html.matchAll(/\shref="(#[^"]*)"/g)) {
+		const href = m[1];
+		if (allowSet.has(href)) continue;
+		if (!ids.has(href.slice(1))) violations.add(href);
+	}
+	return [...violations];
+}
+/**
+* Loads the template's manifest.json, resolves every composed section
+* (via resolveSectionRef — bare refs qualify to `<templateKey>/<name>`; the
+* kit does not yet model a `shared/` library, so those never match a local
+* section), builds the ONE composed anchor map keyed by bare section name
+* (the namespace renderers actually read via `nav.anchors[bareName]`),
+* renders each instance's "typical" fixture with that composed nav, and
+* throws naming the template + every dangling in-page link.
+*/
+async function assertNavContract(workspaceRoot, template) {
+	const raw = JSON.parse(await readFile(join(template.dir, "manifest.json"), "utf8"));
+	const manifest = TemplateManifest.parse(raw);
+	const sectionByName = new Map(template.sections.map((s) => [s.name, s]));
+	const composed = manifest.sections.map((inst) => {
+		const resolvedKey = resolveSectionRef(manifest.key, inst.section);
+		const bareName = resolvedKey.split("/").pop();
+		const target = resolvedKey === `${manifest.key}/${bareName}` ? sectionByName.get(bareName) : void 0;
+		if (!target) throw new Error(`Template "${template.key}": section instance "${inst.instance_id}" references unknown section "${inst.section}" (resolved "${resolvedKey}").`);
+		return target;
+	});
+	const materializedByName = /* @__PURE__ */ new Map();
+	const rendererByName = /* @__PURE__ */ new Map();
+	const fixturesByName = /* @__PURE__ */ new Map();
+	for (const section of composed) {
+		const loaded = await loadSection(workspaceRoot, section);
+		const materialized = materializeSection(section.name, loaded);
+		materializedByName.set(section.name, {
+			anchor: materialized.schema.anchor,
+			schema: materialized.schema
+		});
+		rendererByName.set(section.name, loaded.Renderer);
+		fixturesByName.set(section.name, loaded.fixtures);
+	}
+	const anchors = guardedAnchors(resolveAnchorMap(composed.map((s) => ({
+		key: s.name,
+		anchor: materializedByName.get(s.name).anchor
+	}))), template.key);
+	let html = "";
+	for (const section of composed) {
+		const { anchor, schema } = materializedByName.get(section.name);
+		const base = resolveFixtureSetMedia(buildFixtureSet({
+			schema,
+			module: FixtureModuleShape.parse(fixturesByName.get(section.name)),
+			selfAnchor: anchor
+		})).find((f) => f.id === "typical");
+		if (!base) throw new Error(`Template "${template.key}": section "${section.name}" has no "typical" base fixture.`);
+		html += renderSectionHtml(rendererByName.get(section.name), {
+			slots: base.props.slots,
+			options: base.props.options,
+			nav: {
+				selfAnchor: anchor,
+				anchors
+			},
+			variants: base.props.variants
+		});
+	}
+	const violations = collectNavViolations(html, ALLOWED_EXTERNAL_ANCHORS);
+	if (violations.length > 0) throw new Error(`Template "${template.key}": nav link(s) resolve to no composed section id: ${violations.join(", ")}.`);
+}
+
+//#endregion
+export { assertNavContract, collectNavViolations, guardedAnchors };

package/dist/cli/check/stages/validate/nested-slot-contract.js

@@ -0,0 +1,12 @@
+import { SLOT_TYPES } from "@homepages/template-kit";
+
+//#region src/cli/check/stages/validate/nested-slot-contract.ts
+function assertNestedSlotTypes(schema, sectionKey) {
+	for (const [slotId, slot] of Object.entries(schema.slots)) {
+		if (slot.type !== "object_list" || !slot.item) continue;
+		for (const [childId, child] of Object.entries(slot.item)) if (child.type != null && !SLOT_TYPES.includes(child.type)) throw new Error(`Section "${sectionKey}": object_list "${slotId}" item "${childId}" has unknown nested slot type "${child.type}".`);
+	}
+}
+
+//#endregion
+export { assertNestedSlotTypes };

package/dist/cli/check/stages/validate/object-list-contract.js

@@ -0,0 +1,31 @@
+import { COLLECTIONS, collectionForSlot } from "@homepages/template-kit";
+
+//#region src/cli/check/stages/validate/object-list-contract.ts
+const SCALAR_SLOT_TYPES = /* @__PURE__ */ new Set([
+	"text",
+	"number",
+	"select"
+]);
+function assertObjectListContract(schema, sectionKey) {
+	for (const [slotId, slotUnknown] of Object.entries(schema.slots)) {
+		const slot = slotUnknown;
+		if (slot.type !== "object_list") continue;
+		const source = slot.source;
+		if (source?.kind === "direct") {
+			const collection = collectionForSlot({
+				type: "object_list",
+				source
+			});
+			if (collection === null) throw new Error(`Section "${sectionKey}": object_list "${slotId}" source.field "${source.field ?? "?"}" is not a known collection (COLLECTIONS in platform/contracts/slot-catalog.ts).`);
+			if (!COLLECTIONS[collection].ownership) throw new Error(`Section "${sectionKey}": object_list "${slotId}" collection "${collection}" declares no ownership in COLLECTIONS (platform/contracts/slot-catalog.ts).`);
+		}
+		const itemSlots = slot.item;
+		if (itemSlots == null) throw new Error(`Section "${sectionKey}": object_list "${slotId}" must declare \`item\` (a record of nested slots).`);
+		const childIds = Object.keys(itemSlots);
+		if (childIds.length === 1 && SCALAR_SLOT_TYPES.has(itemSlots[childIds[0]].type ?? "")) throw new Error(`Section "${sectionKey}": object_list "${slotId}" has a single scalar slot "${childIds[0]}" — use a \`list\` slot instead.`);
+		for (const [childId, child] of Object.entries(itemSlots)) if (child.type === "object_list") throw new Error(`Section "${sectionKey}": object_list "${slotId}" item "${childId}" is itself an object_list — object_list is depth-1 (a scalar \`list\` is allowed).`);
+	}
+}
+
+//#endregion
+export { assertObjectListContract };

package/dist/cli/check/stages/validate/orchestrator.js

@@ -0,0 +1,236 @@
+import { loadSection } from "../../loader.js";
+import { assertCatalogExhaustiveness } from "./catalog-exhaustiveness.js";
+import { FACTS_ARRAY_FIELDS, FACTS_READABLE } from "./facts.js";
+import { assertFormatterContract } from "./formatter-contract.js";
+import { assertGroupContract } from "./group-contract.js";
+import { assertListScalarContract } from "./list-scalar-contract.js";
+import { assertNestedSlotTypes } from "./nested-slot-contract.js";
+import { assertObjectListContract } from "./object-list-contract.js";
+import { assertProducedByContract } from "./produced-by-contract.js";
+import { assertRowContract } from "./row-contract.js";
+import { assertSelectContract } from "./select-contract.js";
+import { assertSourceContract } from "./source-contract.js";
+import { assertVariantContract } from "./variant-contract.js";
+import { isDeepStrictEqual } from "node:util";
+import { FillSpec, FixtureModuleShape, SectionSchema, TemplateManifest } from "@homepages/template-kit";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { flattenLayout, parseTreatment, resolveSectionRef } from "@homepages/template-kit/ssr";
+
+//#region src/cli/check/stages/validate/orchestrator.ts
+function serializeVariants(variants) {
+	const out = {};
+	for (const [axis, def] of Object.entries(variants)) out[axis] = {
+		cases: def.cases,
+		default: def.default
+	};
+	return out;
+}
+function flattenMeta(authored, sectionName) {
+	const { meta, ...rest } = authored;
+	return {
+		...rest,
+		anchor: meta.anchor ?? sectionName,
+		...meta.variants ? { variants: serializeVariants(meta.variants) } : {},
+		...meta.groups ? { groups: meta.groups } : {}
+	};
+}
+/**
+* Zod-parses a loaded section's schema + fill-spec and materializes the
+* bookkeeping fields (slot_order, item_order, flattened meta) every contract
+* and consumer expects. Throws on the first parse/shape failure — there is no
+* schema to check contracts against until this succeeds.
+*/
+function materializeSection(key, loaded) {
+	const authored = SectionSchema.parse(loaded.schema);
+	authored.slot_order = Object.keys(authored.slots);
+	for (const slot of Object.values(authored.slots)) if (slot.type === "object_list" && slot.item) slot.item_order = slot.item_layout ? flattenLayout(slot.item_layout) : Object.keys(slot.item);
+	return {
+		key,
+		schema: flattenMeta(authored, key),
+		fillSpec: FillSpec.parse(loaded.fillSpec),
+		displayName: authored.meta.displayName
+	};
+}
+/**
+* Zod-parses the section's fixtures module against the fixture meta-schema,
+* collecting one message per violation. Its own gate (template-kit/fixtures-invalid)
+* because it is a different authored artifact from the schema: the render stage
+* consumes this module, and until it was parsed here an invalid one surfaced only
+* as a raw crash mid-render.
+*/
+function validateFixtureModule(key, loaded) {
+	const parsed = FixtureModuleShape.safeParse(loaded.fixtures);
+	if (parsed.success) return [];
+	return parsed.error.issues.map((issue) => {
+		const path = issue.path.join(".");
+		return `Section "${key}": fixtures.ts — ${path === "" ? "the fixture module" : `"${path}"`}: ${issue.message}.`;
+	});
+}
+/** Runs `fn`, pushing its thrown message onto `messages` instead of propagating. */
+function guard(messages, fn) {
+	try {
+		fn();
+	} catch (cause) {
+		messages.push(cause instanceof Error ? cause.message : String(cause));
+	}
+}
+/**
+* Runs every cross-reference + contract check against an already-loaded
+* section, collecting each violation's message rather than stopping at the
+* first. Returns an empty array when the section is clean.
+*/
+function validateOneSection(key, loaded) {
+	const messages = [];
+	let materialized;
+	try {
+		materialized = materializeSection(key, loaded);
+	} catch (cause) {
+		messages.push(cause instanceof Error ? cause.message : String(cause));
+		return messages;
+	}
+	const { schema, fillSpec } = materialized;
+	guard(messages, () => {
+		assertCatalogExhaustiveness();
+	});
+	for (const r of fillSpec.reads ?? []) guard(messages, () => {
+		const base = r.split(".")[0];
+		if (!FACTS_READABLE.has(base)) throw new Error(`Section "${key}": fill-spec reads "${r}" is not an author-declarable facts key (allowed: ${[...FACTS_READABLE].join(", ")}).`);
+	});
+	for (const d of fillSpec.decisions) {
+		for (const produced of d.produces) guard(messages, () => {
+			if (!(produced in schema.slots)) throw new Error(`Section "${key}": fill-spec decision "${d.id}" produces unknown slot "${produced}".`);
+		});
+		if (d.type === "list-extract" || d.type === "structured-list") {
+			const decisionType = d.type;
+			const decisionId = d.id;
+			const iterate = d.iterate;
+			const itemCount = d.item_count;
+			guard(messages, () => {
+				if (typeof iterate === "string" === (itemCount !== void 0)) throw new Error(`Section "${key}": ${decisionType} decision "${decisionId}" must specify exactly one of \`iterate\` or \`item_count\`.`);
+			});
+			if (typeof iterate === "string") guard(messages, () => {
+				if (!FACTS_ARRAY_FIELDS.has(iterate)) throw new Error(`Section "${key}": ${decisionType} decision "${decisionId}" iterate="${iterate}" is not an iterable facts array (allowed: ${[...FACTS_ARRAY_FIELDS].join(", ")}).`);
+			});
+			if (d.type === "structured-list") {
+				const itemFields = d.item_fields;
+				for (const [field, raw] of Object.entries(itemFields)) guard(messages, () => {
+					if (parseTreatment(raw) === null) throw new Error(`Section "${key}": decision "${decisionId}" item_field "${field}" has invalid treatment "${raw}".`);
+				});
+				const routeBy = d.route_by;
+				const catalog = d.catalog;
+				if (typeof routeBy === "string") {
+					const slots = new Set((catalog ?? []).map((event) => event.slot).filter((s) => typeof s === "string"));
+					for (const p of d.produces) guard(messages, () => {
+						if (!slots.has(p)) throw new Error(`Section "${key}": decision "${decisionId}" routes to slot "${p}" but no catalog entry declares slot="${p}".`);
+					});
+				}
+			}
+		}
+	}
+	guard(messages, () => {
+		assertProducedByContract(schema, fillSpec, key);
+	});
+	guard(messages, () => {
+		assertVariantContract(schema, key);
+	});
+	const decisionIds = new Set(fillSpec.decisions.map((d) => d.id));
+	guard(messages, () => {
+		assertSourceContract({
+			key,
+			slots: schema.slots
+		});
+	});
+	guard(messages, () => {
+		assertFormatterContract({
+			key,
+			slots: schema.slots
+		});
+	});
+	guard(messages, () => {
+		assertObjectListContract(schema, key);
+	});
+	guard(messages, () => {
+		assertNestedSlotTypes(schema, key);
+	});
+	guard(messages, () => {
+		assertListScalarContract(schema, key);
+	});
+	guard(messages, () => {
+		assertSelectContract(schema, key);
+	});
+	guard(messages, () => {
+		assertGroupContract(schema, key);
+	});
+	guard(messages, () => {
+		assertRowContract(schema, key);
+	});
+	for (const [optName, opt] of Object.entries(schema.options)) {
+		for (const dId of opt.affects_decisions) guard(messages, () => {
+			if (!decisionIds.has(dId)) throw new Error(`Section "${key}": option "${optName}" affects_decisions contains unknown decision "${dId}".`);
+		});
+		for (const slotId of opt.affects_slots) guard(messages, () => {
+			if (!(slotId in schema.slots)) throw new Error(`Section "${key}": option "${optName}" affects_slots contains unknown slot "${slotId}".`);
+		});
+	}
+	return messages;
+}
+/**
+* Re-materializes every section a template composes (loadSection is
+* memoized, so this is cheap) and resolves + cross-checks the template's
+* manifest.json: the manifest key matches the folder name, every section
+* reference resolves to a real (locally-authored, per resolveSectionRef's D3
+* rule) section, every overridden option exists and is template_overridable,
+* and no override merely restates the section's own default. Finishes with
+* the whole-composition nav contract (nav-contract.ts). Collects every
+* violation rather than stopping at the first.
+*/
+async function validateTemplateManifest(workspaceRoot, template) {
+	const messages = [];
+	let manifest;
+	try {
+		const raw = JSON.parse(await readFile(join(template.dir, "manifest.json"), "utf8"));
+		manifest = TemplateManifest.parse(raw);
+	} catch (cause) {
+		messages.push(cause instanceof Error ? cause.message : String(cause));
+		return messages;
+	}
+	guard(messages, () => {
+		if (manifest.key !== template.key) throw new Error(`Template "${template.key}": manifest key "${manifest.key}" does not match the template folder name "${template.key}".`);
+	});
+	const sectionByName = /* @__PURE__ */ new Map();
+	for (const section of template.sections) try {
+		const loaded = await loadSection(workspaceRoot, section);
+		sectionByName.set(section.name, materializeSection(section.name, loaded));
+	} catch {}
+	for (const inst of manifest.sections) {
+		const resolvedKey = resolveSectionRef(manifest.key, inst.section);
+		const bareName = resolvedKey.split("/").pop();
+		const target = resolvedKey === `${manifest.key}/${bareName}` ? sectionByName.get(bareName) : void 0;
+		if (!target) {
+			guard(messages, () => {
+				throw new Error(`Template "${manifest.key}": section instance "${inst.instance_id}" references unknown section "${inst.section}" (resolved "${resolvedKey}").`);
+			});
+			continue;
+		}
+		for (const [optName, overrideVal] of Object.entries(inst.options)) guard(messages, () => {
+			const sectOpt = target.schema.options[optName];
+			if (!sectOpt) throw new Error(`Template "${manifest.key}": section instance "${inst.instance_id}" overrides option "${optName}", which the section "${inst.section}" does not declare.`);
+			if (sectOpt.template_overridable === false) throw new Error(`Template "${manifest.key}": section instance "${inst.instance_id}" overrides option "${optName}", but the section declares template_overridable: false.`);
+			if (isDeepStrictEqual(overrideVal, sectOpt.default)) throw new Error(`Template "${manifest.key}": section instance "${inst.instance_id}" overrides option "${optName}" with a value equal to the section default — drop it (only genuine overrides belong in the manifest).`);
+		});
+	}
+	const { assertNavContract } = await import("./nav-contract.js");
+	await guardAsync(messages, () => assertNavContract(workspaceRoot, template));
+	return [...new Set(messages)];
+}
+async function guardAsync(messages, fn) {
+	try {
+		await fn();
+	} catch (cause) {
+		messages.push(cause instanceof Error ? cause.message : String(cause));
+	}
+}
+
+//#endregion
+export { flattenMeta, materializeSection, validateFixtureModule, validateOneSection, validateTemplateManifest };

package/dist/cli/check/stages/validate/produced-by-contract.js

@@ -0,0 +1,18 @@
+//#region src/cli/check/stages/validate/produced-by-contract.ts
+function assertProducedByContract(schema, fillSpec, sectionKey) {
+	const decisionIds = new Set(fillSpec.decisions.map((d) => d.id));
+	for (const [slotId, slot] of Object.entries(schema.slots)) {
+		const srcKind = slot.source?.kind;
+		if (srcKind === "direct" || srcKind === "derived") {
+			if (slot.produced_by) throw new Error(`Section "${sectionKey}": slot "${slotId}" is source-bound; remove the redundant produced_by="${slot.produced_by}".`);
+			continue;
+		}
+		if (!slot.produced_by) throw new Error(`Section "${sectionKey}": slot "${slotId}" of type ${slot.type} must declare a \`source\` binding or a \`produced_by\` decision.`);
+		if (!decisionIds.has(slot.produced_by)) throw new Error(`Section "${sectionKey}": slot "${slotId}" produced_by="${slot.produced_by}" does not match any decision id.`);
+		const producer = fillSpec.decisions.find((d) => d.id === slot.produced_by);
+		if (producer && !producer.produces.includes(slotId)) throw new Error(`Section "${sectionKey}": slot "${slotId}" declares produced_by="${slot.produced_by}", but decision "${slot.produced_by}" does not list "${slotId}" in its produces [${producer.produces.join(", ")}].`);
+	}
+}
+
+//#endregion
+export { assertProducedByContract };

package/dist/cli/check/stages/validate/row-contract.js

@@ -0,0 +1,31 @@
+import { flattenLayout, isShortSlot } from "@homepages/template-kit/ssr";
+
+//#region src/cli/check/stages/validate/row-contract.ts
+function assertRowContract(schema, sectionKey) {
+	for (const group of schema.groups ?? []) assertRowPairs(group.members, schema.slots, `group "${group.id}"`, sectionKey);
+	for (const [slotId, slot] of Object.entries(schema.slots)) {
+		if (slot.type !== "object_list" || !slot.item_layout) continue;
+		const itemFields = slot.item ?? {};
+		assertRowPairs(slot.item_layout, itemFields, `object_list "${slotId}"`, sectionKey);
+		const flat = flattenLayout(slot.item_layout);
+		const dup = flat.find((id, i) => flat.indexOf(id) !== i);
+		if (dup) throw new Error(`Section "${sectionKey}": object_list "${slotId}" item_layout lists "${dup}" more than once.`);
+		for (const id of flat) if (!(id in itemFields)) throw new Error(`Section "${sectionKey}": object_list "${slotId}" item_layout names unknown field "${id}".`);
+		for (const key of Object.keys(itemFields)) if (!flat.includes(key)) throw new Error(`Section "${sectionKey}": object_list "${slotId}" item_layout omits field "${key}".`);
+	}
+}
+function assertRowPairs(layout, slots, ctx, sectionKey) {
+	const order = Object.keys(slots);
+	for (const entry of layout) {
+		if (typeof entry === "string") continue;
+		const [a, b] = entry;
+		for (const id of [a, b]) {
+			if (!(id in slots)) throw new Error(`Section "${sectionKey}": ${ctx} row names unknown slot "${id}".`);
+			if (!isShortSlot(slots[id])) throw new Error(`Section "${sectionKey}": ${ctx} row pairs non-short slot "${id}" (type "${slots[id].type}"); only number/short-text slots may share a row.`);
+		}
+		if (order.indexOf(b) !== order.indexOf(a) + 1) throw new Error(`Section "${sectionKey}": ${ctx} row [${a}, ${b}] must be adjacent and in order; reorder the declaration so "${b}" immediately follows "${a}".`);
+	}
+}
+
+//#endregion
+export { assertRowContract };

package/dist/cli/check/stages/validate/select-contract.js

@@ -0,0 +1,13 @@
+//#region src/cli/check/stages/validate/select-contract.ts
+function assertSelectContract(schema, sectionKey) {
+	for (const [slotId, slotUnknown] of Object.entries(schema.slots)) {
+		const slot = slotUnknown;
+		if (slot.type !== "select") continue;
+		const hasValues = slot.values != null;
+		const hasOptions = slot.options != null;
+		if (!(slot.catalog != null) && hasValues === hasOptions) throw new Error(`Section "${sectionKey}": select "${slotId}" needs exactly one of \`values\` or \`options\` (or a \`catalog\`).`);
+	}
+}
+
+//#endregion
+export { assertSelectContract };

package/dist/cli/check/stages/validate/source-contract.js

@@ -0,0 +1,20 @@
+import { SOURCE_FIELDS, TRANSFORMS } from "@homepages/template-kit";
+
+//#region src/cli/check/stages/validate/source-contract.ts
+function assertSourceContract(schema) {
+	for (const [name, slot] of Object.entries(schema.slots)) {
+		const src = slot.source;
+		if (!src) continue;
+		if (src.kind === "direct") {
+			const def = SOURCE_FIELDS[src.field ?? ""];
+			if (!def) throw new Error(`${schema.key}.${name}: unknown direct source field "${String(src.field)}"`);
+			if (def.image && slot.type !== "image" && slot.type !== "object_list") throw new Error(`${schema.key}.${name}: image source field "${src.field}" must sit on an image slot`);
+			continue;
+		}
+		if (src.kind !== "derived") continue;
+		if (!(src.transform !== void 0 && Object.hasOwn(TRANSFORMS, src.transform))) throw new Error(`${schema.key}.${name}: unknown transform "${String(src.transform)}" (add it to platform/contracts/transforms.ts)`);
+	}
+}
+
+//#endregion
+export { assertSourceContract };

package/dist/cli/check/stages/validate/variant-contract.js

@@ -0,0 +1,15 @@
+//#region src/cli/check/stages/validate/variant-contract.ts
+function assertVariantContract(schema, sectionKey) {
+	const axes = schema.variants ?? {};
+	for (const [axisName, axis] of Object.entries(axes)) if (!axis.cases.includes(axis.default)) throw new Error(`Section "${sectionKey}": variant axis "${axisName}" default "${axis.default}" is not one of its cases.`);
+	for (const [slotId, slot] of Object.entries(schema.slots)) {
+		const v = slot.variant;
+		if (v == null) continue;
+		const axis = axes[v.axis];
+		if (!axis) throw new Error(`Section "${sectionKey}": slot "${slotId}" gates on unknown axis "${v.axis}".`);
+		for (const c of v.cases) if (!axis.cases.includes(c)) throw new Error(`Section "${sectionKey}": slot "${slotId}" gates on case "${c}" not declared by axis "${v.axis}".`);
+	}
+}
+
+//#endregion
+export { assertVariantContract };

package/dist/cli/check/workspace.js

@@ -0,0 +1,99 @@
+import { readFile, readdir, stat } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+
+//#region src/cli/check/workspace.ts
+const isDir = async (p) => {
+	try {
+		return (await stat(p)).isDirectory();
+	} catch {
+		return false;
+	}
+};
+const isFile = async (p) => {
+	try {
+		return (await stat(p)).isFile();
+	} catch {
+		return false;
+	}
+};
+/** Nearest ancestor holding both a package.json and a templates/ dir. Throws if there is none. */
+async function findWorkspaceRoot(from) {
+	let dir = resolve(from);
+	for (;;) {
+		if (await isFile(join(dir, "package.json")) && await isDir(join(dir, "templates"))) return dir;
+		const parent = dirname(dir);
+		if (parent === dir) throw new Error("not inside a workspace — no parent directory has both a package.json and a templates/ folder.\nRun this from your workspace root, or create one with `npm create @homepages/workspace`.");
+		dir = parent;
+	}
+}
+/**
+* The kit version the workspace DECLARES in package.json — deliberately not what is
+* installed. The link overlay never touches package.json, so declared-vs-installed is
+* precisely the gap the check warning exists to surface.
+*/
+async function declaredKitPin(root) {
+	try {
+		const raw = await readFile(join(root, "package.json"), "utf8");
+		return JSON.parse(raw).dependencies?.["@homepages/template-kit"] ?? "unknown";
+	} catch {
+		return "unknown";
+	}
+}
+async function discoverTemplates(root) {
+	const templatesDir = join(root, "templates");
+	const entries = await readdir(templatesDir, { withFileTypes: true });
+	const templates = [];
+	for (const entry of entries) {
+		if (!entry.isDirectory()) continue;
+		const dir = join(templatesDir, entry.name);
+		const sectionsDir = join(dir, "sections");
+		const sections = [];
+		if (await isDir(sectionsDir)) {
+			for (const s of await readdir(sectionsDir, { withFileTypes: true })) if (s.isDirectory()) sections.push({
+				name: s.name,
+				dir: join(sectionsDir, s.name)
+			});
+		}
+		sections.sort((a, b) => a.name.localeCompare(b.name));
+		templates.push({
+			key: entry.name,
+			dir,
+			sections
+		});
+	}
+	templates.sort((a, b) => a.key.localeCompare(b.key));
+	return templates;
+}
+/**
+* Which templates this invocation gates. A bare invocation inside a template folder
+* infers that template; at the root with several templates it asks for a name.
+* `command` is the invoking subcommand (`check`/`theme`), named back in the
+* "several templates" guidance so it points at the command the author actually ran.
+*/
+async function selectTemplates(root, named, all, command) {
+	const templates = await discoverTemplates(root);
+	const keys = templates.map((t) => t.key);
+	if (all) return templates;
+	if (named !== void 0) {
+		const found = templates.find((t) => t.key === named);
+		if (!found) throw new Error(`unknown template "${named}". This workspace has: ${keys.join(", ") || "(none)"}`);
+		return [found];
+	}
+	if (templates.length === 1) return templates;
+	if (templates.length === 0) return [];
+	throw new Error(`this workspace has several templates (${keys.join(", ")}).\nName one — \`template-kit ${command} <template>\` — or run them all with \`template-kit ${command} --all\`.`);
+}
+/**
+* The key of the template whose folder `cwd` sits inside (`<root>/templates/<key>/…`),
+* or `undefined` when `cwd` is not under any template. Lets a bare `check`/`theme`
+* infer its target from the current directory.
+*/
+function templateFromCwd(root, cwd) {
+	const prefix = `${root}/templates/`;
+	if (!cwd.startsWith(prefix)) return void 0;
+	const [key] = cwd.slice(prefix.length).split("/");
+	return key === "" ? void 0 : key;
+}
+
+//#endregion
+export { declaredKitPin, discoverTemplates, findWorkspaceRoot, selectTemplates, templateFromCwd };