@contentrain/types 1.29.0 → 1.31.0

package/dist/index.mjs

@@ -659,11 +659,32 @@ function isClaimOrigin(x) {
 	if (url.origin !== x || url.hostname.endsWith(".")) return false;
 	return url.protocol === "https:" || url.protocol === "http:" && LOCAL_HOSTS.has(url.hostname);
 }
+/** A compact JWS: three base64url segments, the signature non-empty. */
+function isCompactJws(x) {
+	return typeof x === "string" && x.length <= 2048 && /^[\w-]+\.[\w-]+\.[\w-]+$/.test(x);
+}
+/** A fetchable export address: https (http for localhost), no credentials, query or fragment — nowhere for a secret. */
+function isExportUrl(x) {
+	if (typeof x !== "string" || x.length > 2048) return false;
+	let url;
+	try {
+		url = new URL(x);
+	} catch {
+		return false;
+	}
+	if (url.username || url.password || url.search || url.hash || url.hostname.endsWith(".")) return false;
+	return url.protocol === "https:" || url.protocol === "http:" && LOCAL_HOSTS.has(url.hostname);
+}
 /**
 * Check a decoded, signature-verified payload against the contract. Pass
 * `now` (seconds since the epoch) to also check the validity window; without
 * it only the shape and the window's own bounds are checked. Returns every
 * problem found, as stable machine-readable strings (`field: problem`).
+*
+* A malformed `comments_export` does not fail the claim: it is an add-on, and
+* a Migrate still sending an older shape must not stop the trial. It is
+* dropped from `claim` and reported in `warnings`; Studio then offers the
+* file upload instead.
 */
 function validateMigrateStudioClaim(input, options = {}) {
 	const errors = [];
@@ -707,17 +728,42 @@ function validateMigrateStudioClaim(input, options = {}) {
 		else if (c.scale !== void 0 && c.scale !== null && typeof c.scale !== "string") errors.push(`capabilities[${i}].scale: invalid`);
 	});
 	if (x.origin !== void 0 && !isClaimOrigin(x.origin)) errors.push("origin: invalid");
-	return errors.length === 0 ? {
-		ok: true,
-		claim: x
-	} : {
+	const warnings = [];
+	if (x.comments_export !== void 0) {
+		const ce = x.comments_export;
+		if (!isObject(ce)) warnings.push("comments_export: invalid");
+		else {
+			if (!isExportUrl(ce.url)) warnings.push("comments_export.url: invalid");
+			if (!isCompactJws(ce.token)) warnings.push("comments_export.token: invalid");
+			if (!isSeconds(ce.expires_at)) warnings.push("comments_export.expires_at: invalid");
+			else if (isSeconds(x.iat) && ce.expires_at <= x.iat) warnings.push("comments_export.expires_at: not after iat");
+			if (typeof ce.comments !== "number" || !Number.isInteger(ce.comments) || ce.comments < 0) warnings.push("comments_export.comments: invalid");
+		}
+	}
+	if (errors.length > 0) return {
 		ok: false,
 		errors
 	};
+	if (warnings.length === 0) return {
+		ok: true,
+		claim: x
+	};
+	const { comments_export: _dropped, ...rest } = x;
+	return {
+		ok: true,
+		claim: rest,
+		warnings
+	};
 }
-/** Shape-only type guard (no clock check). The signature is the consumer's job. */
+/**
+* Shape-only type guard (no clock check). The signature is the consumer's job. Stricter than
+* `validateMigrateStudioClaim`: a claim whose `comments_export` would be dropped is `false` here,
+* since the guard narrows the input itself, malformed export included. To keep such a claim, use
+* `result.claim` from `validateMigrateStudioClaim`.
+*/
 function isMigrateStudioClaim(input) {
-	return validateMigrateStudioClaim(input).ok;
+	const result = validateMigrateStudioClaim(input);
+	return result.ok && !result.warnings;
 }
 //#endregion
 //#region src/project-plan.ts
@@ -784,6 +830,24 @@ function footerMenusOf(site) {
 }
 /** A font size the starter writes into a style: a length, or a `clamp()`/`calc()`/`min()`/`max()` of lengths (a theme's fluid size). */
 const CSS_LENGTH = /^(?!.*url\()(?:\d+(?:\.\d+)?(?:px|rem|em|%)|(?:clamp|calc|min|max)\([\d\s.,+*/()a-z%-]+\))$/;
+/**
+* How many object levels a field nests: 0 for a scalar or a list of scalars, 1 for an object of scalars,
+* 2 for an object holding a list of objects (`hero.actions[]`). A list adds no level of its own.
+*/
+function fieldDepth(field) {
+	const children = [...Object.values(field.fields ?? {}), ...typeof field.items === "object" ? [field.items] : []];
+	return (field.type === "object" ? 1 : 0) + Math.max(0, ...children.map(fieldDepth));
+}
+/**
+* Placement `rule`: a mapping table's section rule (`elementor:section:hero.split`) or element rule
+* (`gutenberg:element:core/details`, `gutenberg:element:core/template-part:header`), a site component
+* (`opus`), or the rich-text fallback.
+*/
+const PLAN_SECTION_RULE = /^(?:(?:gutenberg|elementor|divi|classic):(?:section:[a-z][\w.-]*|element:[a-z][\w./:-]*)|opus|prose)$/;
+/** A content prop's field name in a section object: the prop in snake_case (`ctaLabel` → `cta_label`). */
+function sectionFieldName(prop) {
+	return prop.replace(/[A-Z]/g, (c) => `_${c.toLowerCase()}`);
+}
 function validateProjectPlan(plan) {
 	const errors = [];
 	const warnings = [];
@@ -802,13 +866,18 @@ function validateProjectPlan(plan) {
 		].includes(part)) || new Set(parts).size !== parts.length) errors.push("site.post.header lists a part twice or one the starter does not have");
 		if (!Number.isSafeInteger(site.post.more) || site.post.more < 0 || site.post.more > 20) errors.push("site.post.more is not a count from 0 to 20");
 	}
-	if (site?.lists && !["cards", "full"].includes(site.lists.display)) errors.push(`site.lists.display ${site.lists.display} is not cards or full`);
+	if (site?.lists && ![
+		"cards",
+		"list",
+		"full"
+	].includes(site.lists.display)) errors.push(`site.lists.display ${site.lists.display} is not cards, list or full`);
 	if (site?.lists?.text !== void 0 && !CSS_LENGTH.test(site.lists.text)) errors.push(`site.lists.text ${site.lists.text} is not a CSS size`);
 	const chrome = site?.chrome;
 	if (chrome?.brand !== void 0 && !CSS_LENGTH.test(chrome.brand)) errors.push(`site.chrome.brand ${chrome.brand} is not a CSS size`);
 	if (chrome?.tagline !== void 0 && typeof chrome.tagline !== "boolean") errors.push("site.chrome.tagline is not a boolean");
 	if (chrome?.titleLinks !== void 0 && typeof chrome.titleLinks !== "boolean") errors.push("site.chrome.titleLinks is not a boolean");
 	if (chrome?.navLinks !== void 0 && typeof chrome.navLinks !== "boolean") errors.push("site.chrome.navLinks is not a boolean");
+	if (chrome?.footerAlign !== void 0 && !["start", "center"].includes(chrome.footerAlign)) errors.push(`site.chrome.footerAlign ${chrome.footerAlign} is not start or center`);
 	if (chrome?.copyright !== void 0 && (typeof chrome.copyright !== "string" || !chrome.copyright.trim() || chrome.copyright.length > 200 || /[<>]/.test(chrome.copyright))) errors.push("site.chrome.copyright is not a line of plain text (1–200 characters, no markup)");
 	const footer = site?.menus?.footer;
 	if (typeof footer === "string") {
@@ -839,11 +908,13 @@ function validateProjectPlan(plan) {
 		if (m.origin === "plan") {
 			if (!m.fields) errors.push(`plan model ${m.id} has no fields`);
 			if (!m.name || !m.domain) errors.push(`plan model ${m.id} needs name and domain`);
-			if (m.kind === "collection" || m.kind === "document") {
-				const title = m.title_field ? m.fields?.[m.title_field] : void 0;
-				if (!m.title_field) errors.push(`plan model ${m.id} has no title_field`);
-				else if (!title) errors.push(`plan model ${m.id}: title_field ${m.title_field} is not one of its fields`);
-				else if (!isTitleFieldType(title.type)) errors.push(`plan model ${m.id}: title_field ${m.title_field} is ${title.type}, not a text-like type`);
+			if (m.kind === "collection" || m.kind === "document" || m.kind === "singleton" && m.title_field) {
+				const title = m.title_field ? titleFieldTarget(m.fields, m.title_field) : void 0;
+				if (!m.title_field || !title) errors.push(`plan model ${m.id} has no title_field`);
+				else if (title.kind === "too-deep") errors.push(`plan model ${m.id}: title_field ${m.title_field} reaches more than one object deep`);
+				else if (title.kind === "not-object") errors.push(`plan model ${m.id}: title_field ${m.title_field} goes through ${title.at} (${title.type}), not an object field`);
+				else if (title.kind === "missing") errors.push(`plan model ${m.id}: title_field ${m.title_field} is not one of its fields`);
+				else if (!isTitleFieldType(title.def.type)) errors.push(`plan model ${m.id}: title_field ${m.title_field} is ${title.def.type}, not a text-like type`);
 			}
 			if (!m.extract?.length && !m.form) warnings.push(`plan model ${m.id} has no extraction — its entries start empty`);
 		}
@@ -856,9 +927,11 @@ function validateProjectPlan(plan) {
 		}
 		for (const x of m.extract ?? []) {
 			if (!x.rule && !x.fields) errors.push(`model ${m.id} extraction from ${x.from} has neither rule nor fields`);
+			if (x.field !== void 0 && m.fields && m.fields[x.field]?.type !== "object") errors.push(`model ${m.id} extraction from ${x.from} fills ${x.field}, which is not an object field`);
 			if (x.rule && !/^(gutenberg|elementor|divi|classic):[\w./:-]+$/.test(x.rule)) errors.push(`model ${m.id} extraction rule ${x.rule} is not <builder>:<match>`);
+			const target = x.field !== void 0 ? m.fields?.[x.field]?.fields : m.fields;
 			for (const [field, path] of Object.entries(x.fields ?? {})) {
-				if (m.fields && !m.fields[field]) errors.push(`model ${m.id} extraction fills unknown field ${field}`);
+				if (target && !target[field]) errors.push(`model ${m.id} extraction fills unknown field ${field}`);
 				if (!/^attr:[\w.-]+$|^[\d.]+\|(text|href|src|alt|datetime)$|^(?:dom|img|link|html):[^@]*(?:@[\w-]+)?$/.test(path)) errors.push(`model ${m.id} field ${field}: path ${path} is not "<path>|<prop>", "attr:<name>" or an element expression`);
 			}
 		}
@@ -883,6 +956,21 @@ function validateProjectPlan(plan) {
 		const b = s.bind;
 		if ("model" in b && !knownModel(b.model)) errors.push(`${at}: model ${b.model} is not declared`);
 		if (b.kind === "entry" && !route?.source) errors.push(`${at}: binds the route entry but ${route ? "the route has no source" : "layout has no entry"}`);
+		if (s.id !== void 0 && !/^[a-z][a-z0-9-]*$/.test(s.id)) errors.push(`${at}: id ${s.id} is not kebab-case`);
+		if (s.rule !== void 0 && !PLAN_SECTION_RULE.test(s.rule)) errors.push(`${at}: rule ${s.rule} is not <builder>:section:<id>, <builder>:element:<match>, opus or prose`);
+		if (b.kind === "section") {
+			const m = models.get(b.model);
+			const field = m?.fields?.[b.field];
+			const ownEntry = route?.page === b.model && route.source?.model === b.model;
+			if (m && m.origin === "plan" && m.kind !== "singleton" && b.entry === void 0 && !ownEntry) errors.push(`${at}: section of ${b.model} names no entry and ${b.model} is neither a singleton nor this route's page`);
+			if (m?.fields && !field) errors.push(`${at}: ${b.model} has no field ${b.field}`);
+			else if (field && field.type !== "object") errors.push(`${at}: ${b.model}.${b.field} is ${field.type}, not an object`);
+			else if (field && fieldDepth(field) > 2) errors.push(`${at}: ${b.model}.${b.field} nests deeper than 2 (an object inside a list item's object)`);
+			const fieldOf = new Map(Object.keys(c.props ?? {}).map((prop) => [sectionFieldName(prop), prop]));
+			if (c.props && field?.fields) {
+				for (const key of Object.keys(field.fields)) if (!fieldOf.has(key)) errors.push(`${at}: ${c.id} has no prop for field ${b.model}.${b.field}.${key} (fields are the props in snake_case)`);
+			}
+		}
 		const values = {
 			..."props" in b ? b.props : {},
 			...b.kind === "collection" && !b.into ? b.item : {}
@@ -892,8 +980,11 @@ function validateProjectPlan(plan) {
 			...b.kind === "collection" ? b.item : {}
 		})) if (!PLAN_VALUE_PATTERN.test(value)) errors.push(`${at}: ${prop} = ${value} is not a plan value (field: media: ref: href: term: ui: site: menu: page: const:)`);
 		if (c.props) {
+			const byField = new Map(Object.keys(c.props).map((prop) => [sectionFieldName(prop), prop]));
+			const spread = b.kind === "section" ? Object.keys(models.get(b.model)?.fields?.[b.field]?.fields ?? {}).flatMap((key) => byField.get(key) ?? []) : [];
 			const bound = new Set([
 				...Object.keys(values),
+				...spread,
 				...Object.keys(s.labels ?? {}),
 				..."into" in b && b.into ? [b.into] : b.kind === "menu" ? ["items"] : []
 			]);
@@ -914,6 +1005,18 @@ function validateProjectPlan(plan) {
 			(byModel.get(r.source.model) ?? byModel.set(r.source.model, []).get(r.source.model)).push(r);
 		}
 		if (r.body === "composed" && !r.sections.length) warnings.push(`route ${r.id} is composed but has no sections`);
+		if (r.page !== void 0) {
+			const page = models.get(r.page);
+			if (!page) errors.push(`route ${r.id}: page ${r.page} is not declared`);
+			else if (page.kind === "collection" ? r.source?.model !== r.page : page.kind !== "singleton") errors.push(`route ${r.id}: page ${r.page} is a ${page.kind}; a page is a singleton, or a collection that is the route's source`);
+			if (r.body !== "composed") errors.push(`route ${r.id}: a page model needs body composed`);
+		}
+		const sectionIds = /* @__PURE__ */ new Set();
+		for (const s of r.sections) {
+			if (s.id === void 0) continue;
+			if (sectionIds.has(s.id)) errors.push(`route ${r.id}: section id ${s.id} is used twice`);
+			sectionIds.add(s.id);
+		}
 		r.sections.forEach((s, i) => placement(s, `route ${r.id} section ${i}`, r));
 	}
 	const byPattern = /* @__PURE__ */ new Map();
@@ -1566,6 +1669,49 @@ const TITLE_FIELD_TYPE_SET = new Set(TITLE_FIELD_TYPES);
 function isTitleFieldType(type) {
 	return TITLE_FIELD_TYPE_SET.has(type);
 }
+/** Resolve a `title_field` path against a model's fields. A field named exactly `path` wins over splitting it. */
+function titleFieldTarget(fields, path) {
+	if (fields && Object.hasOwn(fields, path)) return {
+		kind: "field",
+		def: fields[path]
+	};
+	const segments = path.split(".");
+	if (segments.length > 2) return { kind: "too-deep" };
+	const [head, leaf] = segments;
+	const def = fields && Object.hasOwn(fields, head) ? fields[head] : void 0;
+	if (!def) return {
+		kind: "missing",
+		at: head
+	};
+	if (leaf === void 0) return {
+		kind: "field",
+		def
+	};
+	if (def.type !== "object") return {
+		kind: "not-object",
+		at: head,
+		type: def.type
+	};
+	const child = def.fields && Object.hasOwn(def.fields, leaf) ? def.fields[leaf] : void 0;
+	if (!child) return {
+		kind: "missing",
+		at: path
+	};
+	return {
+		kind: "field",
+		def: child,
+		parent: def
+	};
+}
+/** An entry's title value: `data[title_field]`, or one level into an object for a dotted path. */
+function titleFieldValue(data, path) {
+	if (data && Object.hasOwn(data, path)) return data[path];
+	const [head, leaf, ...rest] = path.split(".");
+	if (!data || head === void 0 || rest.length > 0) return void 0;
+	const value = data[head];
+	if (leaf === void 0) return value;
+	return value !== null && typeof value === "object" && !Array.isArray(value) ? value[leaf] : void 0;
+}
 /** Extensions we can name a MIME type for. Deliberately small — this is a sniff. */
 const EXTENSION_MIME = {
 	jpg: "image/jpeg",
@@ -1986,6 +2132,6 @@ function serializeMarkdownFrontmatter(data, body) {
 	return lines.join("\n");
 }
 //#endregion
-export { APPROVAL_GATES, APPROVAL_MODES, CANONICAL_JSON, CAPABILITY_KEYS, CHROME_BODY_SLOT, CHROME_COMPONENT_CLOSE, CHROME_COMPONENT_OPEN, CHROME_IF_CLOSE, CHROME_IF_OPEN, CHROME_REPEAT_CLOSE, CHROME_REPEAT_OPEN, COMMENTS_EXPORT_FORMAT, COMPONENT_TYPES, CONTENTRAIN_BRANCH, CONTENTRAIN_DIR, DEFAULT_APPROVAL_POLICY, DICTIONARY_TITLE_FIELD, ENTRY_ID_PATTERN, EXECUTION_CONTRACT_VERSION, INTEGRATION_CATEGORIES, INTEGRATION_EVIDENCE_KINDS, LEGACY_CSS_LAYER, LIST_ITEMS_SLOT, LOCALE_PATTERN, LOCAL_CAPABILITIES, MIGRATE_STUDIO_CLAIM_ALG, MIGRATE_STUDIO_CLAIM_AUDIENCE, MIGRATE_STUDIO_CLAIM_CLOCK_SKEW_SECONDS, MIGRATE_STUDIO_CLAIM_ISSUER, MIGRATE_STUDIO_CLAIM_MAX_TRIAL_DAYS, MIGRATE_STUDIO_CLAIM_MAX_TTL_SECONDS, MIGRATE_STUDIO_CLAIM_VERSION, MIGRATE_STUDIO_PLANS, MIGRATION_CONTRACT_VERSION, MODEL_EXTENSION_KEYS, MODEL_FIELD_ORDER, PAGE_BODY_KINDS, PATH_PATTERNS, PLAN_BEHAVIOR_REASON, PLAN_STARTER_FEATURES, PLAN_TOKEN_ROLES, PLAN_VALUE_PATTERN, PROJECT_PLAN_FORMAT, RAW_MARK_SUFFIX, RESERVED_PATHS, RISK_CLASSES, RUN_STATUSES, SCHEDULE_KINDS, SECRET_PATTERNS, SEO_PROVIDERS, SLUG_PATTERN, SOURCE_ACCESS_LADDER, SOURCE_DELTA_OPS, TERMINAL_RUN_STATUSES, TEXT_CANDIDATE_KINDS, TEXT_EXCLUDE_REASONS, TITLE_FIELD_TYPES, approversFor, canonicalStringify, commentsExportSource, componentSlot, computePlanHash, conflictId, describeModelLocaleScope, detectSecrets, effectiveRisk, evaluateApproval, footerMenusOf, generateEntryId, highestRisk, isMediaType, isMigrateStudioClaim, isRepoRelativePath, isReservedPath, isStoredMediaPath, isTerminalRunStatus, isTitleFieldType, looksLikeCredential, orderedFieldNames, parseFrontmatterScalar, parseFrontmatterScalarString, parseMarkdownFrontmatter, planHashPayload, requiredApprovals, resolveFieldLabel, resolveModelLocales, rewriteEntryMedia, rewriteFieldMedia, rewriteMarkdownMedia, rewriteMediaUrl, riskRank, serializeMarkdownFrontmatter, sortKeys, splitFrontmatterList, stableHash, toDeliveryUrl, validateAccept, validateEntryId, validateFieldValue, validateHandoffCommentsExport, validateLocale, validateMigrateStudioClaim, validateModelLocales, validateProjectPlan, validateSemanticType, validateSlug };
+export { APPROVAL_GATES, APPROVAL_MODES, CANONICAL_JSON, CAPABILITY_KEYS, CHROME_BODY_SLOT, CHROME_COMPONENT_CLOSE, CHROME_COMPONENT_OPEN, CHROME_IF_CLOSE, CHROME_IF_OPEN, CHROME_REPEAT_CLOSE, CHROME_REPEAT_OPEN, COMMENTS_EXPORT_FORMAT, COMPONENT_TYPES, CONTENTRAIN_BRANCH, CONTENTRAIN_DIR, DEFAULT_APPROVAL_POLICY, DICTIONARY_TITLE_FIELD, ENTRY_ID_PATTERN, EXECUTION_CONTRACT_VERSION, INTEGRATION_CATEGORIES, INTEGRATION_EVIDENCE_KINDS, LEGACY_CSS_LAYER, LIST_ITEMS_SLOT, LOCALE_PATTERN, LOCAL_CAPABILITIES, MIGRATE_STUDIO_CLAIM_ALG, MIGRATE_STUDIO_CLAIM_AUDIENCE, MIGRATE_STUDIO_CLAIM_CLOCK_SKEW_SECONDS, MIGRATE_STUDIO_CLAIM_ISSUER, MIGRATE_STUDIO_CLAIM_MAX_TRIAL_DAYS, MIGRATE_STUDIO_CLAIM_MAX_TTL_SECONDS, MIGRATE_STUDIO_CLAIM_VERSION, MIGRATE_STUDIO_PLANS, MIGRATION_CONTRACT_VERSION, MODEL_EXTENSION_KEYS, MODEL_FIELD_ORDER, PAGE_BODY_KINDS, PATH_PATTERNS, PLAN_BEHAVIOR_REASON, PLAN_SECTION_RULE, PLAN_STARTER_FEATURES, PLAN_TOKEN_ROLES, PLAN_VALUE_PATTERN, PROJECT_PLAN_FORMAT, RAW_MARK_SUFFIX, RESERVED_PATHS, RISK_CLASSES, RUN_STATUSES, SCHEDULE_KINDS, SECRET_PATTERNS, SEO_PROVIDERS, SLUG_PATTERN, SOURCE_ACCESS_LADDER, SOURCE_DELTA_OPS, TERMINAL_RUN_STATUSES, TEXT_CANDIDATE_KINDS, TEXT_EXCLUDE_REASONS, TITLE_FIELD_TYPES, approversFor, canonicalStringify, commentsExportSource, componentSlot, computePlanHash, conflictId, describeModelLocaleScope, detectSecrets, effectiveRisk, evaluateApproval, fieldDepth, footerMenusOf, generateEntryId, highestRisk, isMediaType, isMigrateStudioClaim, isRepoRelativePath, isReservedPath, isStoredMediaPath, isTerminalRunStatus, isTitleFieldType, looksLikeCredential, orderedFieldNames, parseFrontmatterScalar, parseFrontmatterScalarString, parseMarkdownFrontmatter, planHashPayload, requiredApprovals, resolveFieldLabel, resolveModelLocales, rewriteEntryMedia, rewriteFieldMedia, rewriteMarkdownMedia, rewriteMediaUrl, riskRank, sectionFieldName, serializeMarkdownFrontmatter, sortKeys, splitFrontmatterList, stableHash, titleFieldTarget, titleFieldValue, toDeliveryUrl, validateAccept, validateEntryId, validateFieldValue, validateHandoffCommentsExport, validateLocale, validateMigrateStudioClaim, validateModelLocales, validateProjectPlan, validateSemanticType, validateSlug };
 
 //# sourceMappingURL=index.mjs.map