@contentrain/types 1.21.0 → 1.23.0

package/dist/index.mjs

@@ -38,7 +38,8 @@ const SOURCE_ACCESS_LADDER = [
 const SEO_PROVIDERS = [
 	"yoast",
 	"rank_math",
-	"aioseo"
+	"aioseo",
+	"seopress"
 ];
 /** Where a candidate was found. */
 const TEXT_CANDIDATE_KINDS = [
@@ -701,6 +702,171 @@ function isMigrateStudioClaim(input) {
 	return validateMigrateStudioClaim(input).ok;
 }
 //#endregion
+//#region src/project-plan.ts
+const PROJECT_PLAN_FORMAT = "contentrain-project-plan@1";
+/** Semantic design roles the kit reads — the starter's `@theme` names without the `--` prefix. */
+const PLAN_TOKEN_ROLES = [
+	"color-surface",
+	"color-surface-muted",
+	"color-ink",
+	"color-ink-muted",
+	"color-line",
+	"color-accent",
+	"color-accent-ink",
+	"font-sans",
+	"font-serif",
+	"font-mono",
+	"container-prose",
+	"container-page",
+	"container-wide",
+	"radius-card"
+];
+const PLAN_VALUE_PATTERN = /^(?:field:[\w-]+|media:[\w-]+|ref:[\w-]+\.[\w-]+|href:(?:self|[\w-]+)|term:[\w-]+|ui:[\w.-]+|site:[\w-]+|menu:(?:primary|footer)|page:(?:base|current|total|breadcrumb)|const:(?:true|false|-?\d+(?:\.\d+)?|[a-z][a-z0-9_-]{0,31}))$/;
+const PERMALINK = /^\/(?:[^/\s]+\/)*$/;
+const IMPORTED_MODELS = new Set([
+	"posts",
+	"pages",
+	"categories",
+	"tags",
+	"authors",
+	"media",
+	"menus",
+	"menu-items",
+	"site",
+	"ui-strings"
+]);
+/**
+* Structural checks a plan must pass before anything is written: every reference resolves (routes →
+* components → models), permalinks are well-formed, kit components carry a kit id, plan models carry
+* their fields. Kit catalog and fact checks (does the kit id exist, does the template exist) belong to
+* the caller, which holds those documents.
+*/
+function validateProjectPlan(plan) {
+	const errors = [];
+	const warnings = [];
+	if (plan.format !== "contentrain-project-plan@1") errors.push(`format is not ${PROJECT_PLAN_FORMAT}`);
+	if (!/^https?:\/\/[^/]+$/.test(plan.source?.origin ?? "")) errors.push("source.origin is not an http(s) origin without a path");
+	const site = plan.site;
+	for (const [key, value] of Object.entries(site?.permalinks ?? {})) if (!PERMALINK.test(value)) errors.push(`site.permalinks.${key} must start and end with "/" (${value})`);
+	if (!Number.isSafeInteger(site?.postsPerPage) || site.postsPerPage < 1) errors.push("site.postsPerPage is not a positive integer");
+	for (const [from, to] of Object.entries(site?.redirects ?? {})) {
+		if (!from.startsWith("/")) errors.push(`redirect ${from} does not start with "/"`);
+		const status = typeof to === "string" ? 301 : to.status;
+		if (![
+			301,
+			302,
+			307,
+			308,
+			410
+		].includes(status)) errors.push(`redirect ${from} has status ${status}`);
+	}
+	for (const role of Object.keys(site?.tokens?.roles ?? {})) if (!PLAN_TOKEN_ROLES.includes(role)) errors.push(`tokens.roles.${role} is not a kit role`);
+	const models = /* @__PURE__ */ new Map();
+	for (const m of plan.models ?? []) {
+		if (models.has(m.id)) errors.push(`model ${m.id} is declared twice`);
+		models.set(m.id, m);
+		if (m.origin === "import" && !IMPORTED_MODELS.has(m.id)) warnings.push(`model ${m.id} is marked imported but wp-import does not write it`);
+		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.extract?.length) warnings.push(`plan model ${m.id} has no extraction — its entries start empty`);
+		}
+		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.rule && !/^(gutenberg|elementor|divi|classic):[\w./:-]+$/.test(x.rule)) errors.push(`model ${m.id} extraction rule ${x.rule} is not <builder>:<match>`);
+			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 (!/^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`);
+			}
+		}
+	}
+	const knownModel = (id) => models.has(id) || IMPORTED_MODELS.has(id);
+	const components = /* @__PURE__ */ new Map();
+	for (const c of plan.components ?? []) {
+		if (components.has(c.id)) errors.push(`component ${c.id} is declared twice`);
+		components.set(c.id, c);
+		if (!/^[A-Z][A-Za-z0-9]*$/.test(c.id)) errors.push(`component ${c.id} is not a PascalCase name`);
+		if (c.origin === "kit" && !c.kit?.id) errors.push(`kit component ${c.id} names no kit id`);
+		if (c.origin === "site" && !c.props) errors.push(`site component ${c.id} declares no props`);
+		if (c.origin === "site" && !c.brief) warnings.push(`site component ${c.id} has no brief for the writer`);
+	}
+	const placement = (s, at, route) => {
+		const c = components.get(s.component);
+		if (!c) {
+			errors.push(`${at}: component ${s.component} is not declared`);
+			return;
+		}
+		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"}`);
+		const values = {
+			..."props" in b ? b.props : {},
+			...b.kind === "collection" && !b.into ? b.item : {}
+		};
+		for (const [prop, value] of Object.entries({
+			...values,
+			...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 bound = new Set([
+				...Object.keys(values),
+				...Object.keys(s.labels ?? {}),
+				..."into" in b && b.into ? [b.into] : b.kind === "menu" ? ["items"] : []
+			]);
+			for (const prop of bound) if (!c.props[prop]) errors.push(`${at}: ${c.id} has no prop ${prop}`);
+			for (const [prop, def] of Object.entries(c.props)) if (def.required && !bound.has(prop)) errors.push(`${at}: required prop ${c.id}.${prop} is not bound`);
+		}
+	};
+	if (plan.layout?.header) placement(plan.layout.header, "layout header");
+	if (plan.layout?.footer) placement(plan.layout.footer, "layout footer");
+	const routeIds = /* @__PURE__ */ new Set();
+	const byModel = /* @__PURE__ */ new Map();
+	for (const r of plan.routes ?? []) {
+		if (routeIds.has(r.id)) errors.push(`route ${r.id} is declared twice`);
+		routeIds.add(r.id);
+		if (!PERMALINK.test(r.pattern)) errors.push(`route ${r.id}: pattern ${r.pattern} must start and end with "/"`);
+		if (r.source) {
+			if (!knownModel(r.source.model)) errors.push(`route ${r.id}: source model ${r.source.model} is not declared`);
+			(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`);
+		r.sections.forEach((s, i) => placement(s, `route ${r.id} section ${i}`, r));
+	}
+	const byPattern = /* @__PURE__ */ new Map();
+	for (const r of plan.routes ?? []) (byPattern.get(r.pattern) ?? byPattern.set(r.pattern, []).get(r.pattern)).push(r);
+	for (const [pattern, routes] of byPattern) {
+		if (routes.length < 2) continue;
+		const sources = new Set(routes.map((r) => r.source?.model ?? ""));
+		if (!(sources.size === 1 && !sources.has("") && routes.filter((r) => !r.source?.where).length <= 1)) warnings.push(`routes ${routes.map((r) => r.id).join(", ")} share the pattern ${pattern}`);
+	}
+	for (const [model, routes] of byModel) {
+		if (routes.length < 2) continue;
+		const catchAll = routes.filter((r) => !r.source?.where || Object.keys(r.source.where).length === 0);
+		if (catchAll.length > 1) errors.push(`model ${model}: routes ${catchAll.map((r) => r.id).join(", ")} are all catch-alls`);
+		const seen = /* @__PURE__ */ new Map();
+		for (const r of routes) {
+			const ids = r.source?.where?.wp_id;
+			if (r.source?.where && ids === void 0) warnings.push(`route ${r.id}: where without wp_id — overlap with other ${model} routes cannot be checked`);
+			for (const id of Array.isArray(ids) ? ids : ids === void 0 ? [] : [ids]) {
+				const other = seen.get(id);
+				if (other) errors.push(`model ${model}: entry ${String(id)} is in routes ${other} and ${r.id}`);
+				else seen.set(id, r.id);
+			}
+		}
+	}
+	if (!plan.routes?.some((r) => r.kind === "home")) errors.push("no home route");
+	return {
+		errors,
+		warnings
+	};
+}
+//#endregion
 //#region src/provider.ts
 /** Capability set for the LocalProvider (simple-git + worktree). */
 const LOCAL_CAPABILITIES = {
@@ -1725,6 +1891,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, 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, 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, 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_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, 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 };
 
 //# sourceMappingURL=index.mjs.map