@glw907/cairn-cms 0.41.0 → 0.51.0

package/src/lib/content/types.ts

@@ -154,6 +154,33 @@ export interface NavMenuConfig {
   maxDepth?: number;
 }
 
+/**
+ * How the edit page's preview frame reproduces the live site's content styling. The admin
+ * deliberately never loads the site's CSS (chrome isolation), so a design-accurate preview needs
+ * the site to name its stylesheets for the preview frame; without this knob the preview renders
+ * unstyled markup. The frame's srcdoc pins a white body background as a deliberately overridable
+ * default, so a site whose ground is not white should state its body background in its own
+ * stylesheet.
+ */
+export interface PreviewConfig {
+  /** Absolute or root-relative URLs of the site's compiled stylesheets, linked inside the
+   *  preview document. A Vite `?url` import of the site's CSS resolves the hashed asset URL. */
+  stylesheets: string[];
+  /** Class list applied to the preview document's body, for theme or typography roots. */
+  bodyClass?: string;
+  /** Class list for a wrapper element around the rendered content, reproducing the site's
+   *  content container (a prose or measure class). Omitted renders the content bare. */
+  containerClass?: string;
+  /** Per-concept overrides of bodyClass and containerClass, keyed by concept id. An entry's
+   *  preview resolves the override for its concept over the top-level values; stylesheets are
+   *  always shared. */
+  byConcept?: Record<string, { bodyClass?: string; containerClass?: string }>;
+}
+
+/** The flat preview shape `editLoad` ships to the edit page: the top-level `PreviewConfig`
+ *  values with the entry's concept override applied, and no `byConcept` map. */
+export type ResolvedPreview = Omit<PreviewConfig, 'byConcept'>;
+
 /** Reserved asset slot (seam 4). Typed and unused in the rebuild; R7/R9 read it later with no contract change. */
 export interface AssetConfig {
   /** Repo-relative asset roots, e.g. ["static/images"]. */
@@ -176,8 +203,8 @@ export interface CairnAdapter {
   backend: BackendConfig;
   sender: SenderConfig;
   /** The site's one renderer: the editor preview and every public page call it (design decision 4).
-   *  `resolve` rewrites cairn: links to live permalinks; the build passes a site-index resolver, the
-   *  preview a manifest one. */
+   *  `resolve` rewrites cairn: links to live permalinks; the build passes a site-resolver-backed
+   *  one, the preview a manifest one. */
   render(md: string, opts?: { stagger?: boolean; resolve?: LinkResolve }): string | Promise<string>;
   /** Repo-relative path to the committed content manifest. Defaults to src/content/.cairn/index.json
    *  in composeRuntime. It sits outside any concept directory, so content enumeration never globs it. */
@@ -187,6 +214,9 @@ export interface CairnAdapter {
   /** The site's glyph name to SVG path-data map, for the admin icon picker and the renderer. */
   icons?: IconSet;
   navMenu?: NavMenuConfig;
+  /** The live site's content styling for the preview frame. The admin's chrome isolation keeps
+   *  the site's CSS out of the admin document, so the preview frame links these instead. */
+  preview?: PreviewConfig;
   assets?: AssetConfig;
 }
 
@@ -285,6 +315,8 @@ export interface CairnRuntime {
   /** The site's glyph name to SVG path-data map, for the admin icon picker and the renderer. */
   icons?: IconSet;
   navMenu?: NavMenuConfig;
+  /** The live site's content styling for the preview frame; passed through from the adapter. */
+  preview?: PreviewConfig;
   assets?: AssetConfig;
   /** Admin panels contributed by extensions (Mode 2). Empty until Plan 09 wires the dispatch route. */
   adminPanels?: AdminPanel[];

package/src/lib/delivery/data.ts

@@ -3,8 +3,8 @@
 // the graph. The full ./delivery barrel re-exports this and adds the route loaders.
 export { createContentIndex, fromGlob } from './content-index.js';
 export type { RawFile, ContentSummary, ContentEntry, ContentIndex, ContentProblem } from './content-index.js';
-export { createSiteIndex } from './site-index.js';
-export type { SiteIndex, ConceptIndex } from './site-index.js';
+export { createSiteResolver, buildLinkResolver } from './site-resolver.js';
+export type { SiteResolver, ConceptIndex } from './site-resolver.js';
 export { createSiteIndexes } from './site-indexes.js';
 export type { SiteIndexes, SiteGlobs } from './site-indexes.js';
 export { siteDescriptors } from './site-descriptors.js';
@@ -18,9 +18,7 @@ export { buildSeoMeta } from './seo.js';
 export type { SeoInput, SeoMeta } from './seo.js';
 export { readSeoFields, resolveImageUrl } from './seo-fields.js';
 export type { SeoFields } from './seo-fields.js';
-export { paginate } from './paginate.js';
-export type { Page } from './paginate.js';
 export { rssResponse, jsonFeedResponse, sitemapResponse, robotsResponse } from './responses.js';
 export { jsonLdScript } from './json-ld.js';
 export { permalink } from '../content/permalink.js';
-export { buildSiteManifest, buildLinkResolver } from './manifest.js';
+export { buildSiteManifest } from './manifest.js';

package/src/lib/delivery/feeds.ts

@@ -2,6 +2,7 @@
 // channel and a list of items, so they unit-test without a render or a network. The caller
 // (a template +server.ts shim) assembles items from the content index and passes absolute
 // URLs built from PUBLIC_ORIGIN.
+import { escapeXml } from './xml.js';
 
 /** Feed channel metadata. URLs are absolute. */
 export interface FeedChannel {
@@ -24,14 +25,6 @@ export interface FeedItem {
   tags?: string[];
 }
 
-function escapeXml(value: string): string {
-  return value
-    .replace(/&/g, '&')
-    .replace(/</g, '&lt;')
-    .replace(/>/g, '&gt;')
-    .replace(/"/g, '&quot;');
-}
-
 /** Make a string safe inside a CDATA section by splitting any `]]>` across two sections. */
 function cdataSafe(value: string): string {
   return value.replace(/]]>/g, ']]]]><![CDATA[>');

package/src/lib/delivery/index.ts

@@ -3,11 +3,11 @@
 // lives at ./delivery/head. Importing this pulls @sveltejs/kit through the route loaders, so a
 // plain-Node tool imports from ./delivery/data instead.
 export * from './data.js';
-export { createPublicRoutes } from '../sveltekit/public-routes.js';
+export { createPublicRoutes } from './public-routes.js';
 export type {
   PublicRoutesDeps,
   ListData,
   TagData,
   TagIndexData,
   EntryData,
-} from '../sveltekit/public-routes.js';
+} from './public-routes.js';

package/src/lib/delivery/manifest.ts

@@ -1,15 +1,12 @@
-// cairn-cms: the build-side manifest builder and the build link resolver (content-graph design).
-// buildSiteManifest mirrors createSiteIndexes: it maps the site descriptors over the per-concept
-// globs and projects each file to a manifest row. buildLinkResolver reads the site index, which is
-// fresh from the files at build, and throws on a missing target so a dangling cairn: token fails
-// the build (the backstop). The admin preview uses manifestLinkResolver instead.
+// cairn-cms: the build-side manifest builder (content-graph design). buildSiteManifest mirrors
+// createSiteIndexes: it maps the site descriptors over the per-concept globs and projects each
+// file to a manifest row. The build-time cairn: link resolver lives beside the site resolver in
+// site-resolver.ts; the admin preview uses manifestLinkResolver instead.
 import { siteDescriptors } from './site-descriptors.js';
 import { fromGlob } from './content-index.js';
 import { parseMarkdown } from '../content/frontmatter.js';
 import { emptyManifest, manifestEntryFromFile } from '../content/manifest.js';
 import type { Manifest } from '../content/manifest.js';
-import type { LinkResolve } from '../content/links.js';
-import type { SiteIndex } from './site-index.js';
 import type { SiteConfig } from '../nav/site-config.js';
 import type { CairnAdapter } from '../content/types.js';
 import type { SiteGlobs } from './site-indexes.js';
@@ -22,7 +19,7 @@ export function buildSiteManifest<A extends CairnAdapter>(adapter: A, config: Si
   for (const descriptor of siteDescriptors(adapter, config)) {
     const record = globRecord[descriptor.id] ?? {};
     for (const file of fromGlob(record)) {
-      // Validate the same way createContentIndex does, so the manifest and the site index agree on
+      // Validate the same way createContentIndex does, so the manifest and the site resolver agree on
       // which entries exist. A validation failure is excluded from both; otherwise the preview would
       // resolve a link the build then rejects as a missing target.
       const { frontmatter, body } = parseMarkdown(file.raw);
@@ -32,13 +29,3 @@ export function buildSiteManifest<A extends CairnAdapter>(adapter: A, config: Si
   }
   return manifest;
 }
-
-/** A resolver backed by the site index, for the build. A miss throws, so a dangling cairn: token
- *  fails the prerender (the build backstop). The preview uses manifestLinkResolver, which marks. */
-export function buildLinkResolver(site: SiteIndex): LinkResolve {
-  return (ref) => {
-    const url = site.concept(ref.concept)?.byId(ref.id)?.permalink;
-    if (!url) throw new Error(`cairn link target not found: cairn:${ref.concept}/${ref.id}`);
-    return url;
-  };
-}

package/src/lib/{sveltekit → delivery}/public-routes.ts

@@ -1,20 +1,20 @@
-// cairn-cms: public route loaders (dated-slug design). The factory closes over the site-level
-// index, the runtime render, and the origin. entryLoad and entries are site-wide: one catch-all
+// cairn-cms: public route loaders (dated-slug design). The factory closes over the site
+// resolver, the runtime render, and the origin. entryLoad and entries are site-wide: one catch-all
 // `[...path]` route resolves any concept by request path through `byPermalink`. The archive, tag,
-// and tag-index loaders stay concept-scoped, keyed by concept id. The index is built in site code
-// from globs, so it stays in the prerender graph and out of the runtime Worker.
+// and tag-index loaders stay concept-scoped, keyed by concept id. The resolver is built in site
+// code from globs, so it stays in the prerender graph and out of the runtime Worker.
 import { error } from '@sveltejs/kit';
-import type { ContentSummary, ContentEntry } from '../delivery/content-index.js';
-import type { SiteIndex } from '../delivery/site-index.js';
-import { buildSeoMeta } from '../delivery/seo.js';
-import type { SeoMeta } from '../delivery/seo.js';
-import { readSeoFields, resolveImageUrl } from '../delivery/seo-fields.js';
-import { buildLinkResolver } from '../delivery/manifest.js';
+import type { ContentSummary, ContentEntry } from './content-index.js';
+import type { SiteResolver } from './site-resolver.js';
+import { buildSeoMeta } from './seo.js';
+import type { SeoMeta } from './seo.js';
+import { readSeoFields, resolveImageUrl } from './seo-fields.js';
+import { buildLinkResolver } from './site-resolver.js';
 import type { LinkResolve } from '../content/links.js';
 
 /** Injected dependencies for the public loaders. */
 export interface PublicRoutesDeps {
-  site: SiteIndex;
+  site: SiteResolver;
   render: (md: string, opts?: { stagger?: boolean; resolve?: LinkResolve }) => string | Promise<string>;
   origin: string;
   /** Site name for og:site_name and the SEO head. */

package/src/lib/delivery/site-indexes.ts

@@ -1,7 +1,7 @@
 // cairn-cms: the full-auto typed site index (schema-source-of-truth design). It maps over a
 // defineAdapter-typed adapter to give one typed per-concept index, with frontmatter typed as the
 // concept's inferred schema type, plus a site resolver for the catch-all route. It is the typed
-// convenience over createContentIndex and createSiteIndex, not a replacement: both stay the
+// convenience over createContentIndex and createSiteResolver, not a replacement: both stay the
 // lower-level escape hatch. It imports only pure content and delivery code, so the delivery
 // bundle stays backend-free.
 import type { CairnAdapter, ConceptConfig } from '../content/types.js';
@@ -9,9 +9,9 @@ import type { Infer } from '../content/schema.js';
 import type { SiteConfig } from '../nav/site-config.js';
 import { siteDescriptors } from './site-descriptors.js';
 import { createContentIndex, fromGlob } from './content-index.js';
-import { createSiteIndex } from './site-index.js';
+import { createSiteResolver } from './site-resolver.js';
 import type { ContentIndex } from './content-index.js';
-import type { ConceptIndex, SiteIndex } from './site-index.js';
+import type { ConceptIndex, SiteResolver } from './site-resolver.js';
 
 /** A per-concept raw glob record (`{ path: raw }`) keyed by concept id, from `import.meta.glob`. */
 export type SiteGlobs<A extends CairnAdapter> = {
@@ -24,13 +24,13 @@ export type SiteIndexes<A extends CairnAdapter> = {
   [K in keyof A['content']]: ContentIndex<
     NonNullable<A['content'][K]> extends ConceptConfig<infer S> ? Infer<S> : Record<string, unknown>
   >;
-} & { readonly site: SiteIndex };
+} & { readonly site: SiteResolver };
 
 /**
  * Build typed per-concept indexes and a site resolver from one adapter. Pass the per-concept raw
  * globs as `{ posts: import.meta.glob('...?raw', { eager: true }), ... }`; Vite needs the literal
  * glob at the call site, so the engine cannot glob on the site's behalf. `validate: false` opts out
- * of the build gate, exactly as on `createSiteIndex`.
+ * of the build gate, exactly as on `createSiteResolver`.
  */
 export function createSiteIndexes<const A extends CairnAdapter>(
   adapter: A,
@@ -59,6 +59,6 @@ export function createSiteIndexes<const A extends CairnAdapter>(
     byConcept[descriptor.id] = index;
     conceptIndexes.push({ descriptor, index });
   }
-  const site = createSiteIndex(conceptIndexes, opts);
+  const site = createSiteResolver(conceptIndexes, opts);
   return { ...byConcept, site } as SiteIndexes<A>;
 }

package/src/lib/delivery/{site-index.ts → site-resolver.ts}

@@ -1,9 +1,11 @@
-// cairn-cms: the site-level content index (dated-slug design). It unions every concept's
-// per-concept index into one cross-concept resolver: a single byPermalink map a catch-all route
-// matches a request path against, one entries() list the prerenderer walks, and the per-concept
-// indexes for concept-scoped archive, tag, and feed loaders. A duplicate permalink throws at build.
+// cairn-cms: the cross-concept site resolver (dated-slug design). It unions every concept's
+// per-concept index into one resolver: a single byPermalink map a catch-all route matches a
+// request path against, one entries() list the prerenderer walks, and the per-concept indexes
+// for concept-scoped archive, tag, and feed loaders. A duplicate permalink throws at build.
+// buildLinkResolver lives here too, since it closes over the resolver.
 import type { ConceptDescriptor } from '../content/types.js';
 import type { ContentEntry, ContentIndex, ContentSummary } from './content-index.js';
+import type { LinkResolve } from '../content/links.js';
 
 /** One concept's descriptor paired with its built index. */
 export interface ConceptIndex {
@@ -12,7 +14,7 @@ export interface ConceptIndex {
 }
 
 /** The cross-concept query surface a catch-all route and the sitemap read. */
-export interface SiteIndex {
+export interface SiteResolver {
   /** Resolve a request path (with or without a trailing slash) to its entry, or undefined. */
   byPermalink(path: string): ContentEntry | undefined;
   /** Newer/older neighbors within the entry's own concept, for prev/next links. */
@@ -49,11 +51,11 @@ function siteProblems(concepts: ConceptIndex[]): string[] {
  * unless `validate` is `false`, on any non-draft entry whose frontmatter fails its concept's
  * validator, so malformed content fails the build instead of shipping.
  */
-export function createSiteIndex(concepts: ConceptIndex[], opts: { validate?: boolean } = {}): SiteIndex {
+export function createSiteResolver(concepts: ConceptIndex[], opts: { validate?: boolean } = {}): SiteResolver {
   if (opts.validate !== false) {
     const problems = siteProblems(concepts);
     if (problems.length > 0) {
-      throw new Error(`site index: ${problems.length} invalid frontmatter field(s):\n  ${problems.join('\n  ')}`);
+      throw new Error(`site resolver: ${problems.length} invalid frontmatter field(s):\n  ${problems.join('\n  ')}`);
     }
   }
   const byPath = new Map<string, { index: ContentIndex; id: string }>();
@@ -64,7 +66,7 @@ export function createSiteIndex(concepts: ConceptIndex[], opts: { validate?: boo
       const existing = byPath.get(summary.permalink);
       if (existing) {
         throw new Error(
-          `site index: "${existing.id}" and "${summary.id}" both resolve to "${summary.permalink}"`,
+          `site resolver: "${existing.id}" and "${summary.id}" both resolve to "${summary.permalink}"`,
         );
       }
       byPath.set(summary.permalink, { index, id: summary.id });
@@ -90,3 +92,13 @@ export function createSiteIndex(concepts: ConceptIndex[], opts: { validate?: boo
     },
   };
 }
+
+/** A resolver backed by the site resolver, for the build. A miss throws, so a dangling cairn: token
+ *  fails the prerender (the build backstop). The preview uses manifestLinkResolver, which marks. */
+export function buildLinkResolver(site: SiteResolver): LinkResolve {
+  return (ref) => {
+    const url = site.concept(ref.concept)?.byId(ref.id)?.permalink;
+    if (!url) throw new Error(`cairn link target not found: cairn:${ref.concept}/${ref.id}`);
+    return url;
+  };
+}

package/src/lib/delivery/sitemap.ts

@@ -1,5 +1,6 @@
 // cairn-cms: sitemap builder (public-delivery design). Pure over a URL list; the caller
 // derives the list from the content index and the routable concepts.
+import { escapeXml } from './xml.js';
 
 /** One sitemap URL. `lastmod` is a YYYY-MM-DD date. */
 export interface SitemapUrl {
@@ -7,10 +8,6 @@ export interface SitemapUrl {
   lastmod?: string;
 }
 
-function escapeXml(value: string): string {
-  return value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
-}
-
 /** Build a sitemap XML document from a list of URLs. */
 export function buildSitemap(urls: SitemapUrl[]): string {
   const entries = urls

package/src/lib/delivery/xml.ts

@@ -0,0 +1,12 @@
+// cairn-cms: the one XML text escape the feed and sitemap builders share. The strongest of the
+// two copies it replaced (the old sitemap copy skipped quotes), so both documents stay safe in
+// element text and double-quoted attributes.
+
+/** Escape the XML-significant characters for element text and double-quoted attribute values. */
+export function escapeXml(value: string): string {
+  return value
+    .replaceAll('&', '&')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;');
+}

package/src/lib/diagnostics/conditions.ts

@@ -101,6 +101,14 @@ export const REGISTRY: Record<string, CairnCondition> = {
 		remediation: "Set csrf: { checkOrigin: false } in svelte.config.js and wire createAuthGuard into src/hooks.server.ts; cairn's guard owns the Origin and double-submit token checks.",
 		docsAnchor: 'cloudflare-readiness.md#hand-cairn-the-csrf-authority',
 	},
+	'config.public-origin-invalid': {
+		id: 'config.public-origin-invalid',
+		severity: 'blocker',
+		title: 'PUBLIC_ORIGIN is missing or invalid',
+		why: 'PUBLIC_ORIGIN is unset, does not parse as a URL, or uses http on a non-local host. The magic-link confirmation links and the absolute feed URLs derive from it, config-only so a forged Host header cannot redirect a link, and sign-in cannot mint a usable link without it.',
+		remediation: "Set PUBLIC_ORIGIN to the site's canonical https origin in the wrangler config vars (with .dev.vars carrying the local http override), then re-deploy; http passes only on localhost or 127.0.0.1.",
+		docsAnchor: 'cloudflare-readiness.md#set-the-public-origin',
+	},
 	'config.site-config-invalid': {
 		id: 'config.site-config-invalid',
 		severity: 'blocker',
@@ -109,6 +117,14 @@ export const REGISTRY: Record<string, CairnCondition> = {
 		remediation: 'Correct site.config.yaml; the parse or validation error names the failing field or URL-policy rule.',
 		docsAnchor: 'cloudflare-readiness.md#validate-the-site-config',
 	},
+	'config.dependency-floors-unmet': {
+		id: 'config.dependency-floors-unmet',
+		severity: 'blocker',
+		title: 'A framework dependency sits below the engine floor',
+		why: 'The lockfile resolves svelte or @sveltejs/kit below the range the engine declares as a peer. Consumer sites compile the shipped .svelte sources, so a below-floor compiler bites silently at build time; svelte 5.56.1 miscompiles parenthesized boolean groupings, which is why the svelte floor is ^5.56.3.',
+		remediation: "Raise the devDependency range in the site's package.json to the engine peer range and reinstall so the lockfile re-resolves, for example `npm install --save-dev svelte@^5.56.3`.",
+		docsAnchor: 'cloudflare-readiness.md#meet-the-dependency-floors',
+	},
 	'edge.hsts-off': {
 		id: 'edge.hsts-off',
 		severity: 'warning',
@@ -134,6 +150,14 @@ export const REGISTRY: Record<string, CairnCondition> = {
 		docsAnchor: 'cloudflare-readiness.md#install-the-github-app',
 		logEvent: 'github.unreachable',
 	},
+	'admin.login-probe-failed': {
+		id: 'admin.login-probe-failed',
+		severity: 'blocker',
+		title: 'Live admin login probe failed',
+		why: 'A live request to the deployed admin did not answer with the working sign-in envelope (the login page, its CSRF cookie and hidden field, and the request action), so a real editor cannot sign in either. A probe failure has many possible causes; the detail line names the assertion that failed.',
+		remediation: 'Read the failed assertion in the detail line, run the full doctor against the same site, and work through the deploy guide; the other checks narrow the cause.',
+		docsAnchor: 'cloudflare-readiness.md#probe-the-deployed-admin',
+	},
 };
 
 // The registry is shared identity, never working state; freeze every entry and the map itself.

package/src/lib/doctor/bin.ts

@@ -7,8 +7,17 @@
 // before the process ends.
 import { readFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
+import { liveProbeCheck } from './check-probe.js';
 import { liveSendCheck } from './check-send.js';
-import { contextFromEnv, defaultChecks, formatReport, parseArgs, runDoctor } from './index.js';
+import { readWranglerConfig } from './wrangler-config.js';
+import {
+	contextFromEnv,
+	defaultChecks,
+	deriveMissingInputs,
+	formatReport,
+	parseArgs,
+	runDoctor,
+} from './index.js';
 
 async function main(): Promise<void> {
 	let args: ReturnType<typeof parseArgs>;
@@ -21,21 +30,37 @@ async function main(): Promise<void> {
 	}
 
 	const cwd = process.cwd();
+	const readFileUnderCwd = async (relPath: string): Promise<string | null> => {
+		try {
+			return await readFile(resolve(cwd, relPath), 'utf8');
+		} catch (err) {
+			if ((err as NodeJS.ErrnoException).code === 'ENOENT') return null;
+			throw err;
+		}
+	};
+	// Fill inputs the flags and env left missing from the repo itself: from and repo off the
+	// adapter (through the vite arm, which exists only on this bin path, never in a Worker)
+	// and the account id off the wrangler config. The API token stays env-only.
+	const derived = await deriveMissingInputs(contextFromEnv(process.env, args, cwd), {
+		adapterFacts: async () => {
+			const { readAdapterFacts } = await import('../vite/index.js');
+			return readAdapterFacts(cwd);
+		},
+		wranglerAccountId: async () => (await readWranglerConfig(readFileUnderCwd))?.accountId,
+	});
 	const ctx = {
-		...contextFromEnv(process.env, args, cwd),
+		...derived,
 		fetch: globalThis.fetch,
-		readFile: async (relPath: string): Promise<string | null> => {
-			try {
-				return await readFile(resolve(cwd, relPath), 'utf8');
-			} catch (err) {
-				if ((err as NodeJS.ErrnoException).code === 'ENOENT') return null;
-				throw err;
-			}
-		},
+		readFile: readFileUnderCwd,
 	};
 
 	const checks = defaultChecks();
 	if (args.sendTest) checks.push(liveSendCheck(args.sendTest));
+	// The probe is an opt-in network POST against a live site, so it joins only on --probe;
+	// the bare flag hands the URL resolution (the PUBLIC_ORIGIN input) to the check itself.
+	if (args.probe !== undefined) {
+		checks.push(liveProbeCheck(args.probe === true ? undefined : args.probe));
+	}
 
 	const { results, failed } = await runDoctor(checks, ctx);
 	console.log(formatReport(results));

package/src/lib/doctor/check-floors.ts

@@ -0,0 +1,124 @@
+// The dependency-floors check. The engine's peer ranges have teeth only when something reads
+// the consumer's lockfile, where a transitively pinned svelte can sit below the floor while
+// package.json looks fine (the ecxc retrofit shipped svelte 5.56.0 that way). The check compares
+// the resolved svelte and @sveltejs/kit versions in package-lock.json against the peer ranges
+// the installed @glw907/cairn-cms declares, read at runtime so the floors live in one place.
+import { createRequire } from 'node:module';
+import { fail, pass, skip } from './types.js';
+import type { CheckResult, DoctorCheck, DoctorContext } from './types.js';
+
+interface Version {
+	major: number;
+	minor: number;
+	patch: number;
+}
+
+// Plain x.y.z only. A prerelease or build tag returns null, so the check skips rather than
+// guessing how a tagged build orders against the floor.
+function parseVersion(text: string): Version | null {
+	const m = text.match(/^(\d+)\.(\d+)\.(\d+)$/);
+	if (!m) return null;
+	return { major: Number(m[1]), minor: Number(m[2]), patch: Number(m[3]) };
+}
+
+// The engine's peers are simple caret ranges (^x.y.z, or ^x.y like the kit floor ^2.12), so
+// this handles the caret form only; anything else returns null and the check skips for that
+// dependency instead of approximating a full semver implementation.
+function caretFloor(range: string): Version | null {
+	const m = range.match(/^\^(\d+)(?:\.(\d+))?(?:\.(\d+))?$/);
+	if (!m) return null;
+	return { major: Number(m[1]), minor: Number(m[2] ?? 0), patch: Number(m[3] ?? 0) };
+}
+
+function compareVersions(a: Version, b: Version): number {
+	return a.major - b.major || a.minor - b.minor || a.patch - b.patch;
+}
+
+// A v2/v3 lockfile's packages map; v1 has none and the check skips.
+interface LockPackages {
+	packages?: Record<string, { version?: unknown } | undefined>;
+}
+
+function lockedVersion(lock: LockPackages, dep: string): string | undefined {
+	const version = lock.packages?.[`node_modules/${dep}`]?.version;
+	return typeof version === 'string' ? version : undefined;
+}
+
+/**
+ * Judge a lockfile's resolved framework versions against the engine's peer ranges. Pure, so the
+ * tests drive it table-style; the check object wires in the real lockfile and the real peers.
+ * A below-range version fails; a lockfile or entry the check cannot read skips, since a pnpm or
+ * yarn consumer carries no package-lock.json at all.
+ */
+export function dependencyFloorsResult(
+	lockText: string | null,
+	peers: Record<string, string>
+): CheckResult {
+	if (lockText === null) {
+		return skip('no package-lock.json found (a pnpm or yarn lockfile is not read)');
+	}
+	let lock: LockPackages;
+	try {
+		lock = JSON.parse(lockText) as LockPackages;
+	} catch {
+		// Like the wrangler reader: never echo file content into the report.
+		return fail('package-lock.json did not parse');
+	}
+	if (lock.packages === undefined) {
+		return skip('package-lock.json carries no packages map (lockfile v1; reinstall with a current npm)');
+	}
+	const failures: string[] = [];
+	const skips: string[] = [];
+	const passes: string[] = [];
+	for (const [dep, range] of Object.entries(peers)) {
+		const floor = caretFloor(range);
+		if (floor === null) {
+			skips.push(`${dep}: the engine range ${range} is not a simple caret range`);
+			continue;
+		}
+		const resolved = lockedVersion(lock, dep);
+		if (resolved === undefined) {
+			skips.push(`${dep}: no node_modules/${dep} entry in package-lock.json`);
+			continue;
+		}
+		const version = parseVersion(resolved);
+		if (version === null) {
+			skips.push(`${dep}: resolved ${resolved} is not a plain x.y.z version`);
+			continue;
+		}
+		// The caret bounds both ends: at or above the floor, same major. The engine's peers
+		// start at major 1 or higher, so the 0.x caret nuance never applies here.
+		if (compareVersions(version, floor) < 0) {
+			failures.push(`${dep} resolves to ${resolved}, below the engine floor ${range}`);
+		} else if (version.major !== floor.major) {
+			failures.push(`${dep} resolves to ${resolved}, outside the engine peer range ${range}`);
+		} else {
+			passes.push(`${dep} ${resolved}`);
+		}
+	}
+	if (failures.length > 0) return fail(failures.join('; '));
+	if (skips.length > 0) return skip(skips.join('; '));
+	return pass(`${passes.join(' and ')} satisfy the engine peer ranges`);
+}
+
+/**
+ * The engine's own declared peer ranges, read from the installed package.json at runtime so the
+ * floors are declared exactly once. The self-reference resolves through the consumer's
+ * node_modules in a real install and through the repo root during development.
+ */
+export function readEnginePeers(): Record<string, string> {
+	const require = createRequire(import.meta.url);
+	const pkg = require('@glw907/cairn-cms/package.json') as {
+		peerDependencies?: Record<string, string>;
+	};
+	return pkg.peerDependencies ?? {};
+}
+
+export const configDependencyFloors: DoctorCheck = {
+	id: 'config.dependency-floors',
+	conditionId: 'config.dependency-floors-unmet',
+	title: 'Dependency floors',
+	async run(ctx: DoctorContext): Promise<CheckResult> {
+		return dependencyFloorsResult(await ctx.readFile('package-lock.json'), readEnginePeers());
+	},
+};