canopycms 0.0.63 → 0.0.65

package/dist/services.d.ts

@@ -1,12 +1,12 @@
-import type { CanopyConfig } from './config';
-import type { EntrySchemaRegistry } from './schema/types';
-import type { BranchContext } from './types';
-import type { CanopyUser } from './user';
-import { createCheckBranchAccess, createCheckContentAccess, type ContentAccessChecker } from './authorization';
-import { GitManager } from './git-manager';
-import { BranchRegistry } from './branch-registry';
-import { type GitHubService } from './github-service';
-import { BranchSchemaCache } from './branch-schema-cache';
+import type { CanopyConfig } from './config/index.js';
+import type { EntrySchemaRegistry } from './schema/types.js';
+import type { BranchContext } from './types.js';
+import type { CanopyUser } from './user.js';
+import { createCheckBranchAccess, createCheckContentAccess, type ContentAccessChecker } from './authorization/index.js';
+import { GitManager } from './git-manager.js';
+import { BranchRegistry } from './branch-registry.js';
+import { type GitHubService } from './github-service.js';
+import { BranchSchemaCache } from './branch-schema-cache.js';
 /**
  * Parse bootstrap admin IDs from environment variable.
  * These users are always treated as Admins regardless of group membership.
@@ -23,7 +23,7 @@ export interface CanopyServices {
     /** Entry schema registry mapping entry schema names to field definitions */
     entrySchemaRegistry: EntrySchemaRegistry;
     /** Per-branch schema cache */
-    branchSchemaCache: import('./branch-schema-cache').BranchSchemaCache;
+    branchSchemaCache: import('./branch-schema-cache.js').BranchSchemaCache;
     checkBranchAccess: (context: BranchContext, user: CanopyUser) => ReturnType<ReturnType<typeof createCheckBranchAccess>>;
     checkContentAccess: ReturnType<typeof createCheckContentAccess>;
     /**
@@ -109,4 +109,3 @@ export declare const createCanopyServices: (config: CanopyConfig, options?: Crea
  * @param options - Optional settings including entry schema registry
  */
 export declare const createTestCanopyServices: (config: CanopyConfig, options?: CreateCanopyServicesOptions) => Promise<CanopyServices>;
-//# sourceMappingURL=services.d.ts.map

package/dist/services.js

@@ -396,4 +396,3 @@ async function _createCanopyServicesInternal(config, options) {
     };
     return services;
 }
-//# sourceMappingURL=services.js.map

package/dist/settings-workspace.d.ts

@@ -1,5 +1,5 @@
-import type { CanopyConfig } from './config';
-import type { OperatingMode } from './operating-mode';
+import type { CanopyConfig } from './config/index.js';
+import type { OperatingMode } from './operating-mode/index.js';
 /**
  * Directory the cross-process init lock is anchored on — a dedicated sibling of
  * the settings root, and NOT the settings root itself.
@@ -10,18 +10,16 @@ import type { OperatingMode } from './operating-mode';
  *    mkdir's its target, and `GitManager.initializeWorkspace` clones INTO the
  *    settings root — `git clone` refuses a destination that already has content
  *    in it. So the lock lives beside the settings root, never inside it.
- * 2. **It must not alias any other proper-lockfile target.** proper-lockfile
- *    keys its module-level bookkeeping (refresh timer + release function) by the
- *    TARGET path passed to `lock()`, not by `lockfilePath`, so two live locks in
- *    one process that share a target clobber each other's registry entry (see
- *    `.claude/future-tasks/proper-lockfile-hazards.md`). This target is a
- *    dedicated dot-directory, so it collides with none of the existing targets:
- *    the content-branches root and the bare remote's parent (provisioning locks
- *    — note the latter IS `path.dirname(settingsRoot)`, which is precisely why
- *    this cannot be anchored there: settings init calls into
- *    `ensureLocalSimulatedRemote` while holding this lock), `<branchRoot>/.canopy-meta`
- *    (content-write lock), `<workspaceRoot>/.tasks` (worker task lock), and the
- *    individual JSON file paths used by `withOccFileLock`.
+ * 2. **Its marker must not collide with another lock's marker.** Since
+ *    2026-08-20 `acquireProvisioningLock` anchors proper-lockfile on the lock
+ *    MARKER's own path rather than on the directory holding it, so its
+ *    in-process registry key is the on-disk lock identity and two live locks
+ *    can no longer clobber each other's bookkeeping (see docs/concurrency.md,
+ *    "Anchor path matters"). A dedicated dot-directory is still the right home
+ *    for this marker: `path.dirname(settingsRoot)` is where
+ *    `ensureLocalSimulatedRemote` puts `.remote-init.lock`, and settings init
+ *    calls into it while holding this lock, so keeping the two markers in
+ *    separate directories keeps that nesting obvious rather than incidental.
  */
 export declare function settingsInitLockTarget(settingsRoot: string): string;
 export interface EnsureSettingsWorkspaceOptions {
@@ -51,4 +49,3 @@ export declare class SettingsWorkspaceManager {
     constructor(config: CanopyConfig);
     ensureGitWorkspace(options: EnsureSettingsWorkspaceOptions): Promise<void>;
 }
-//# sourceMappingURL=settings-workspace.d.ts.map

package/dist/settings-workspace.js

@@ -21,18 +21,16 @@ const SETTINGS_INIT_LOCK_NAME = 'lock';
  *    mkdir's its target, and `GitManager.initializeWorkspace` clones INTO the
  *    settings root — `git clone` refuses a destination that already has content
  *    in it. So the lock lives beside the settings root, never inside it.
- * 2. **It must not alias any other proper-lockfile target.** proper-lockfile
- *    keys its module-level bookkeeping (refresh timer + release function) by the
- *    TARGET path passed to `lock()`, not by `lockfilePath`, so two live locks in
- *    one process that share a target clobber each other's registry entry (see
- *    `.claude/future-tasks/proper-lockfile-hazards.md`). This target is a
- *    dedicated dot-directory, so it collides with none of the existing targets:
- *    the content-branches root and the bare remote's parent (provisioning locks
- *    — note the latter IS `path.dirname(settingsRoot)`, which is precisely why
- *    this cannot be anchored there: settings init calls into
- *    `ensureLocalSimulatedRemote` while holding this lock), `<branchRoot>/.canopy-meta`
- *    (content-write lock), `<workspaceRoot>/.tasks` (worker task lock), and the
- *    individual JSON file paths used by `withOccFileLock`.
+ * 2. **Its marker must not collide with another lock's marker.** Since
+ *    2026-08-20 `acquireProvisioningLock` anchors proper-lockfile on the lock
+ *    MARKER's own path rather than on the directory holding it, so its
+ *    in-process registry key is the on-disk lock identity and two live locks
+ *    can no longer clobber each other's bookkeeping (see docs/concurrency.md,
+ *    "Anchor path matters"). A dedicated dot-directory is still the right home
+ *    for this marker: `path.dirname(settingsRoot)` is where
+ *    `ensureLocalSimulatedRemote` puts `.remote-init.lock`, and settings init
+ *    calls into it while holding this lock, so keeping the two markers in
+ *    separate directories keeps that nesting obvious rather than incidental.
  */
 export function settingsInitLockTarget(settingsRoot) {
     return path.join(path.dirname(path.resolve(settingsRoot)), SETTINGS_INIT_LOCK_DIR);
@@ -220,4 +218,3 @@ export class SettingsWorkspaceManager {
         });
     }
 }
-//# sourceMappingURL=settings-workspace.js.map

package/dist/static/index.d.ts

@@ -1,6 +1,6 @@
-import type { CanopyBuildContext } from '../context';
-import type { ListEntriesItem } from '../content-listing';
-import { type EntryFieldError } from '../validation/entry-validator';
+import type { CanopyBuildContext } from '../context.js';
+import type { ListEntriesItem } from '../content-listing.js';
+import { type EntryFieldError } from '../validation/entry-validator.js';
 /**
  * Framework-agnostic helpers for static-site generation. These produce neutral data structures
  * (no Next.js types) so that any framework adapter — e.g. canopycms-next — can map them to its own
@@ -11,7 +11,7 @@ import { type EntryFieldError } from '../validation/entry-validator';
  *   carried through, for surfaces that must inspect content (sitemap, feeds, search index).
  * - `./seo` — `extractSeoFields` / `isNoindexEntry` / URL shaping, re-exported below.
  */
-export { DEFAULT_SEO_FIELD_NAMES, extractSeoFields, isNoindexEntry, isAbsoluteUrl, withTrailingSlash, resolveSeoUrl, stripTrailingSlashes, type SeoFields, type SeoFieldNames, type SeoFieldLocation, type SeoOgType, type SeoTwitterCard, type ExtractSeoFieldsOptions, type ResolveSeoUrlOptions, } from './seo';
+export { DEFAULT_SEO_FIELD_NAMES, extractSeoFields, isNoindexEntry, isAbsoluteUrl, withTrailingSlash, resolveSeoUrl, stripTrailingSlashes, type SeoFields, type SeoFieldNames, type SeoFieldLocation, type SeoOgType, type SeoTwitterCard, type ExtractSeoFieldsOptions, type ResolveSeoUrlOptions, } from './seo.js';
 /** A routable content entry, reduced to what static path generation needs. */
 export interface StaticPathEntry {
     /**
@@ -66,13 +66,28 @@ export interface CollectRoutableEntriesOptions<T = Record<string, unknown>> {
     rootPath?: string;
     /** Keep only entries matching this predicate. Runs after `data` is attached, so it can read content. */
     filter?: (entry: RoutableEntry<T>) => boolean;
+    /**
+     * Resolve `reference` fields in each entry's `data`, the way `read()`/`readByUrlPath()` do.
+     * Defaults to `false`; see `ListEntriesOptions.resolveReferences` in content-listing.ts for
+     * the full rationale, cost and caveats.
+     *
+     * Turn this on for a surface that reads INSIDE an entry and must see referenced content —
+     * a search index over pages built from shared/referenced blocks is the case this exists
+     * for, since those blocks are otherwise indexed as an id string with no text in them.
+     * A sitemap needs `urlPath`/`updatedAt`/`noindex` only, so leave it off there.
+     *
+     * Not offered on `collectStaticPaths`, which discards `data` entirely — resolving
+     * references only to throw them away would be pure cost.
+     */
+    resolveReferences?: boolean;
 }
 /**
  * Enumerate routable content entries WITH their data — the input to any surface that must read
  * inside an entry to decide what to publish (sitemap, RSS, search index, index grids).
  *
  * Identical enumeration to `collectStaticPaths` (same single `listEntries` pass, same build-time
- * schema-validity guard); it simply keeps `data` and `updatedAt` instead of discarding them.
+ * schema-validity guard); it simply keeps `data` and `updatedAt` instead of discarding them, and
+ * can additionally opt into `reference` resolution, which a path-only enumeration has no use for.
  *
  * **Enumerates every entry type by default.** There is no allow-list of "publishable" types, and
  * that is deliberate: a sitemap built from a hand-maintained list of entry types silently omits
@@ -116,6 +131,12 @@ export interface InvalidBuildEntry {
  */
 type BuildScanItem = Pick<ListEntriesItem, 'entryPath' | 'schema'> & {
     data: unknown;
+    /**
+     * Only the unknown-key scan reads this, to recognise the md/mdx body key that `listEntries`
+     * merges into `data`. Optional so a caller assembling items by hand still typechecks; an
+     * absent format is treated as markdown-shaped, which errs toward under-reporting.
+     */
+    format?: ListEntriesItem['format'];
 };
 /**
  * Scan listEntries-shaped items for schema-invalid entries.
@@ -132,6 +153,34 @@ type BuildScanItem = Pick<ListEntriesItem, 'entryPath' | 'schema'> & {
  * different failure class, handled elsewhere.
  */
 export declare function findInvalidEntries(items: readonly BuildScanItem[]): InvalidBuildEntry[];
+/** An entry carrying data keys the schema no longer defines. */
+export interface EntryWithUnknownKeys {
+    entryPath: string;
+    /** Canonical field paths, e.g. `author.nickname` or `blocks[2].headline`. */
+    fieldPaths: string[];
+}
+/**
+ * Scan listEntries-shaped items for data keys with no schema counterpart.
+ *
+ * The inverse of `findInvalidEntries`, and non-fatal by design: an unknown key is stale data,
+ * not broken data. A build must not go red for it — the page still renders, it is just quietly
+ * missing whatever the renamed field used to supply. `warnUnknownEntryKeys` is the reporting
+ * half. Both sit at module scope alongside `findInvalidEntries`/`assertBuildEntriesValid` and
+ * are deliberately NOT on `canopycms/server`, matching those two — the build wires them itself.
+ *
+ * Skips items with no resolved schema, and items whose schema is empty — "no schema" is not
+ * "every key is unknown". Same `normalizeDatesDeep` pass as the validity scan, so a hand-authored
+ * `date: 2024-01-15` is a plain value here too.
+ */
+export declare function findEntriesWithUnknownKeys(items: readonly BuildScanItem[]): EntryWithUnknownKeys[];
+/**
+ * Warn — never throw — about entries carrying keys the schema no longer defines.
+ *
+ * A production build is the one place that sees every entry at once, which makes it the only
+ * place a schema reshape's leftovers show up as a list rather than one mysteriously undefined
+ * value at a time.
+ */
+export declare function warnUnknownEntryKeys(items: readonly BuildScanItem[], phaseLabel: string): void;
 /**
  * Throw a single, descriptive Error if any item is schema-invalid.
  *
@@ -140,4 +189,113 @@ export declare function findInvalidEntries(items: readonly BuildScanItem[]): Inv
  * offending entry so one build catches every abandoned scaffold, not just the first.
  */
 export declare function assertBuildEntriesValid(items: readonly BuildScanItem[], phaseLabel: string): void;
-//# sourceMappingURL=index.d.ts.map
+/**
+ * One URL claimed by more than one entry.
+ */
+export interface DuplicateUrlPath {
+    /** The contested URL path, exactly as `listEntries` computed it. */
+    urlPath: string;
+    /** Logical paths of every entry claiming it, sorted. Always length >= 2. */
+    entryPaths: string[];
+}
+/** What the duplicate-URL scan needs off a listing item. */
+type UrlScanItem = Pick<ListEntriesItem, 'entryPath' | 'urlPath'>;
+/**
+ * Find every `urlPath` claimed by two or more entries.
+ *
+ * `listEntries` assigns each entry exactly one `urlPath` and documents it as round-trip safe with
+ * `readByUrlPath`. That guarantee is per-entry, not per-URL: nothing stops two DIFFERENT entries
+ * computing the same one, and when they do exactly one of them is reachable while the other
+ * silently has no route at all. The known ways to get there:
+ *
+ * - An entry whose slug matches a sibling collection that also has an `index` entry — the index
+ *   collapses onto the collection's path, which is the entry's path too. The write boundary now
+ *   refuses to author this too (url-collision.ts), so reaching it means the content arrived some
+ *   other way — the same merge/PR/retrofit routes as the same-slug case below. (An entry beside a
+ *   sibling collection with NO index entry is a different, legitimate shape: a landing page plus
+ *   a folder of children, nothing contested.)
+ * - Two entries whose slugs differ only by case, since `urlPath` is lowercased.
+ * - Two entries with the same slug in one collection. The write boundary already refuses this
+ *   (`ContentStore.buildPaths` resolves by slug across entry types, and the create-intent guard
+ *   turns a hit into a conflict), but content also arrives by merge, by PR, and by adopters
+ *   retrofitting an existing repo — none of which pass through that boundary.
+ *
+ * Exported so adopters can assert on it directly instead of hand-rolling a content-integrity
+ * test; `assertNoDuplicateUrlPaths` is what the build itself uses.
+ *
+ * Pure. Results are sorted by `urlPath`, with each `entryPaths` sorted too, so messages are
+ * stable across runs (`listEntries` resolves collections in parallel, so its own order is not).
+ */
+export declare function findDuplicateUrlPaths(items: readonly UrlScanItem[]): DuplicateUrlPath[];
+/**
+ * Throw a single, descriptive Error if any URL is claimed by more than one entry.
+ *
+ * Fails the build for the same reason its sibling `assertBuildEntriesValid` does: a page that
+ * silently disappears from a static build is a worse failure mode than a red build, and that is
+ * precisely what a contested URL produces — `generateStaticParams` emits the path once, one entry
+ * renders, and the other never appears anywhere with no error to notice.
+ *
+ * Runs on the RAW listing, before the caller's `filter`, and that will produce the first "why is
+ * my build red, that entry isn't even routed?" question — so: a contested `urlPath` is a real
+ * collision at RESOLUTION time regardless of routing. `readByUrlPath` picks one of the two
+ * whatever any `generateStaticParams` filter says, so the un-routed entry is not innocent; it is
+ * shadowing (or being shadowed by) the routed one at the same URL. `rootPath` narrows the scan
+ * because it narrows what was loaded at all; `filter` deliberately does not.
+ *
+ * Related but not redundant: `canopycms-next`'s `dedupeSitemapItems` warns on the same collision
+ * at the sitemap. It stays, because it also covers entry-vs-`extraUrls` collisions (adopter-supplied
+ * paths this content enumeration never sees) and non-build-mode calls, where this guard is silent.
+ */
+export declare function assertNoDuplicateUrlPaths(items: readonly UrlScanItem[], phaseLabel: string): void;
+/** An entry whose slug cannot round-trip through `readByUrlPath`. */
+export interface UnroutableSlugEntry {
+    entryPath: string;
+    urlPath: string;
+    slug: string;
+    /** Why `parseSlug` rejected it, e.g. "Slug must start with a letter or number...". */
+    error: string;
+}
+/** What the slug-routability scan needs off a listing item. */
+type SlugScanItem = Pick<ListEntriesItem, 'entryPath' | 'urlPath' | 'slug'>;
+/**
+ * Find every listed entry whose `slug` cannot pass `parseSlug` — the validation `readByUrlPath`
+ * runs on every URL-resolution candidate it tries (`context.ts`).
+ *
+ * The filename grammar `parseTypedFilename` parses (`{type}.{slug}.{id}.{ext}`) deliberately
+ * allows a slug to contain dots, anchoring the split on the type and ID instead (see that
+ * function's doc comment) — and it does not run the parsed slug through `parseSlug` before
+ * handing it back, by design: recovering `{type, slug, id}` structurally, without validating
+ * every part, is its whole contract. `listCollectionEntries` inherits that: it lists the file and
+ * computes a `urlPath` for it, same as any other entry.
+ *
+ * But `parseSlug` requires `^[a-z0-9][a-z0-9-]*$` — no dots — so a listed entry whose slug
+ * contains one is unreachable through the one path everything else assumes works:
+ * `readByUrlPath` tries the URL's last segment as a candidate slug and skips any candidate that
+ * fails `parseSlug` (treating it as a miss, not an error) before it ever calls `read()`. The
+ * entry still builds, still gets a `generateStaticParams` entry, still gets a sitemap `<loc>` —
+ * and 404s the moment anything actually visits it. That breaks the `Round-trip safe` contract
+ * `content-listing.ts` documents on `urlPath` (`readByUrlPath(item.urlPath)` resolves to the same
+ * entry) and is exactly the silent-page-loss failure mode this guard's siblings
+ * (`assertBuildEntriesValid`, `assertNoDuplicateUrlPaths`) exist to make loud instead.
+ *
+ * The write boundary refuses to MINT such a slug: `api/content.ts` and `ContentStore.write()`
+ * both run `parseSlug` on a create, and `renameEntry()` runs it on the new slug (the [SLUG]
+ * guards). That enforcement is deliberately create-only — an entry that already carries a
+ * non-conforming slug stays saveable and renameable, because renaming it is the only way to fix
+ * this build failure, and refusing reads or edits would turn a red build into unreachable data.
+ *
+ * So this guard still fires, and is still needed, for every slug the write boundary never saw:
+ * hand-authored files, scripted migrations, content merged in over git, a repo being retrofitted
+ * onto CanopyCMS (this guard's intended audience, same as its siblings), and entries created
+ * before the write-time rule existed.
+ */
+export declare function findUnroutableSlugs(items: readonly SlugScanItem[]): UnroutableSlugEntry[];
+/**
+ * Throw a single, descriptive Error if any listed entry's slug cannot round-trip through
+ * `readByUrlPath`.
+ *
+ * Fails the build for the same reason its siblings do: an entry that builds and gets advertised
+ * (sitemap, `generateStaticParams`) but 404s on every actual visit is a worse failure mode than a
+ * red build.
+ */
+export declare function assertRoutableSlugs(items: readonly SlugScanItem[], phaseLabel: string): void;

package/dist/static/index.js

@@ -1,5 +1,8 @@
 import { isBuildMode } from '../build-mode.js';
-import { validateEntryData } from '../validation/entry-validator.js';
+import { findUnknownKeys, validateEntryData, } from '../validation/entry-validator.js';
+import { findBodyFieldName } from '../utils/body-field.js';
+import { isDataOnlyFormat } from '../utils/format.js';
+import { parseSlug } from '../paths/index.js';
 /**
  * Framework-agnostic helpers for static-site generation. These produce neutral data structures
  * (no Next.js types) so that any framework adapter — e.g. canopycms-next — can map them to its own
@@ -17,14 +20,33 @@ export { DEFAULT_SEO_FIELD_NAMES, extractSeoFields, isNoindexEntry, isAbsoluteUr
  * `phaseLabel` only names the phase in the build-guard error, but it is threaded through rather
  * than fixed so the message points at the surface that actually failed.
  */
-async function enumerateRoutableEntries(ctx, rootPath, phaseLabel) {
-    const entries = await ctx.listEntries({ rootPath });
+async function enumerateRoutableEntries(ctx, rootPath, phaseLabel, resolveReferences) {
+    const entries = await ctx.listEntries({ rootPath, resolveReferences });
     // Build-time only: `next dev` runs generateStaticParams against the live working tree, where
     // fresh create-scaffolds legitimately exist mid-edit. Only fail the actual production build —
     // an abandoned schema-invalid scaffold shipping into a static build silently drops that page's
     // route (or worse, renders broken), which is worse than a red build.
-    if (isBuildMode())
+    //
+    // The unknown-key warning runs BEFORE all three throwing guards, so a build about to go red
+    // still prints everything it found rather than dying on the first problem.
+    //
+    // All four run on the RAW listing, before the caller's `filter` — a filtered-out entry still
+    // occupies its URL as far as every other route is concerned. `rootPath` scoping does narrow
+    // them, since that happens inside `listEntries`; that is the intended escape hatch, `filter`
+    // is not.
+    //
+    // Slug routability is asserted first, ahead of schema validity and duplicate URLs: an entry
+    // whose slug cannot round-trip through `readByUrlPath` has no URL at all as far as any OTHER
+    // guard is concerned, so it is the most fundamental of the three problems a listed entry can
+    // have. Schema validity is asserted before duplicate URLs for the same reason one level down:
+    // a schema-invalid entry is the more fundamental problem, and an adopter fixing it may remove
+    // the duplicate on the way.
+    if (isBuildMode()) {
+        warnUnknownEntryKeys(entries, phaseLabel);
+        assertRoutableSlugs(entries, phaseLabel);
         assertBuildEntriesValid(entries, phaseLabel);
+        assertNoDuplicateUrlPaths(entries, phaseLabel);
+    }
     return entries.map((entry) => ({
         urlPath: entry.urlPath,
         segments: entry.urlPath === '/' ? [] : entry.urlPath.replace(/^\//, '').split('/'),
@@ -39,7 +61,8 @@ async function enumerateRoutableEntries(ctx, rootPath, phaseLabel) {
  * inside an entry to decide what to publish (sitemap, RSS, search index, index grids).
  *
  * Identical enumeration to `collectStaticPaths` (same single `listEntries` pass, same build-time
- * schema-validity guard); it simply keeps `data` and `updatedAt` instead of discarding them.
+ * schema-validity guard); it simply keeps `data` and `updatedAt` instead of discarding them, and
+ * can additionally opt into `reference` resolution, which a path-only enumeration has no use for.
  *
  * **Enumerates every entry type by default.** There is no allow-list of "publishable" types, and
  * that is deliberate: a sitemap built from a hand-maintained list of entry types silently omits
@@ -54,7 +77,7 @@ async function enumerateRoutableEntries(ctx, rootPath, phaseLabel) {
  * const published = entries.filter((e) => !isNoindexEntry(e.data))
  */
 export async function collectRoutableEntries(ctx, options = {}) {
-    const entries = await enumerateRoutableEntries(ctx, options.rootPath, 'routable entry enumeration');
+    const entries = await enumerateRoutableEntries(ctx, options.rootPath, 'routable entry enumeration', options.resolveReferences);
     return options.filter ? entries.filter(options.filter) : entries;
 }
 /**
@@ -142,6 +165,70 @@ export function findInvalidEntries(items) {
     }
     return invalid;
 }
+/**
+ * How many offending entries `warnUnknownEntryKeys` lists before summarising the rest. Bounds CI
+ * output for a schema-wide rename across a large content tree; the reported COUNT is never capped.
+ */
+const UNKNOWN_KEY_REPORT_LIMIT = 20;
+/**
+ * Scan listEntries-shaped items for data keys with no schema counterpart.
+ *
+ * The inverse of `findInvalidEntries`, and non-fatal by design: an unknown key is stale data,
+ * not broken data. A build must not go red for it — the page still renders, it is just quietly
+ * missing whatever the renamed field used to supply. `warnUnknownEntryKeys` is the reporting
+ * half. Both sit at module scope alongside `findInvalidEntries`/`assertBuildEntriesValid` and
+ * are deliberately NOT on `canopycms/server`, matching those two — the build wires them itself.
+ *
+ * Skips items with no resolved schema, and items whose schema is empty — "no schema" is not
+ * "every key is unknown". Same `normalizeDatesDeep` pass as the validity scan, so a hand-authored
+ * `date: 2024-01-15` is a plain value here too.
+ */
+export function findEntriesWithUnknownKeys(items) {
+    const found = [];
+    for (const item of items) {
+        if (!item.schema || item.schema.length === 0)
+            continue;
+        const data = normalizeDatesDeep(item.data);
+        // For md/mdx, `listEntries` merges the file's body into `data` under
+        // `findBodyFieldName(schema)` (readEntryData in content-listing.ts). When the schema declares
+        // an `isBody` field that name IS a schema field and this is a no-op -- but declaring one is
+        // optional, and with none the merge key falls back to the literal 'body', which the schema
+        // legitimately does not define. Without this the scan told every adopter whose md entry types
+        // omit `isBody` that their prose was a stale key to delete.
+        const bodyKey = isDataOnlyFormat(item.format ?? 'md')
+            ? undefined
+            : findBodyFieldName(item.schema);
+        const fieldPaths = findUnknownKeys(item.schema, data).filter((path) => path !== bodyKey);
+        if (fieldPaths.length > 0) {
+            found.push({ entryPath: item.entryPath, fieldPaths });
+        }
+    }
+    return found;
+}
+/**
+ * Warn — never throw — about entries carrying keys the schema no longer defines.
+ *
+ * A production build is the one place that sees every entry at once, which makes it the only
+ * place a schema reshape's leftovers show up as a list rather than one mysteriously undefined
+ * value at a time.
+ */
+export function warnUnknownEntryKeys(items, phaseLabel) {
+    const found = findEntriesWithUnknownKeys(items);
+    if (found.length === 0)
+        return;
+    // Capped, unlike the sibling assert. That one throws, so it prints once and the build stops;
+    // this one returns, and a Next build runs the enumeration several times (every catch-all route
+    // plus the sitemap). A schema-wide rename across a large tree would otherwise bury CI output
+    // under the same thousands of lines two or three times over. The count is always exact.
+    const shown = found.slice(0, UNKNOWN_KEY_REPORT_LIMIT);
+    const lines = shown.map(({ entryPath, fieldPaths }) => `  - ${entryPath} — ${fieldPaths.join(', ')}`);
+    if (found.length > shown.length) {
+        lines.push(`  …and ${found.length - shown.length} more`);
+    }
+    console.warn(`CanopyCMS static build: ${found.length} ${found.length === 1 ? 'entry has' : 'entries have'} content keys not defined in their schema during ${phaseLabel}:\n${lines.join('\n')}\n` +
+        `These are usually left over from a renamed or reshaped field. Nothing reads them, and they are kept in the file on every save. ` +
+        `Add them to the schema or remove them from the content.`);
+}
 /**
  * Throw a single, descriptive Error if any item is schema-invalid.
  *
@@ -164,4 +251,152 @@ export function assertBuildEntriesValid(items, phaseLabel) {
         `These are likely abandoned create-scaffolds (empty entries left behind when a create was started but never finished). ` +
         `Finish editing the entry (fill in its required fields) or delete the abandoned draft, then rebuild.`);
 }
-//# sourceMappingURL=index.js.map
+/**
+ * Find every `urlPath` claimed by two or more entries.
+ *
+ * `listEntries` assigns each entry exactly one `urlPath` and documents it as round-trip safe with
+ * `readByUrlPath`. That guarantee is per-entry, not per-URL: nothing stops two DIFFERENT entries
+ * computing the same one, and when they do exactly one of them is reachable while the other
+ * silently has no route at all. The known ways to get there:
+ *
+ * - An entry whose slug matches a sibling collection that also has an `index` entry — the index
+ *   collapses onto the collection's path, which is the entry's path too. The write boundary now
+ *   refuses to author this too (url-collision.ts), so reaching it means the content arrived some
+ *   other way — the same merge/PR/retrofit routes as the same-slug case below. (An entry beside a
+ *   sibling collection with NO index entry is a different, legitimate shape: a landing page plus
+ *   a folder of children, nothing contested.)
+ * - Two entries whose slugs differ only by case, since `urlPath` is lowercased.
+ * - Two entries with the same slug in one collection. The write boundary already refuses this
+ *   (`ContentStore.buildPaths` resolves by slug across entry types, and the create-intent guard
+ *   turns a hit into a conflict), but content also arrives by merge, by PR, and by adopters
+ *   retrofitting an existing repo — none of which pass through that boundary.
+ *
+ * Exported so adopters can assert on it directly instead of hand-rolling a content-integrity
+ * test; `assertNoDuplicateUrlPaths` is what the build itself uses.
+ *
+ * Pure. Results are sorted by `urlPath`, with each `entryPaths` sorted too, so messages are
+ * stable across runs (`listEntries` resolves collections in parallel, so its own order is not).
+ */
+export function findDuplicateUrlPaths(items) {
+    const byUrl = new Map();
+    for (const item of items) {
+        const existing = byUrl.get(item.urlPath);
+        if (existing)
+            existing.push(item.entryPath);
+        else
+            byUrl.set(item.urlPath, [item.entryPath]);
+    }
+    const duplicates = [];
+    for (const [urlPath, entryPaths] of byUrl) {
+        if (entryPaths.length > 1) {
+            duplicates.push({ urlPath, entryPaths: [...entryPaths].sort() });
+        }
+    }
+    return duplicates.sort((a, b) => a.urlPath.localeCompare(b.urlPath));
+}
+/**
+ * Throw a single, descriptive Error if any URL is claimed by more than one entry.
+ *
+ * Fails the build for the same reason its sibling `assertBuildEntriesValid` does: a page that
+ * silently disappears from a static build is a worse failure mode than a red build, and that is
+ * precisely what a contested URL produces — `generateStaticParams` emits the path once, one entry
+ * renders, and the other never appears anywhere with no error to notice.
+ *
+ * Runs on the RAW listing, before the caller's `filter`, and that will produce the first "why is
+ * my build red, that entry isn't even routed?" question — so: a contested `urlPath` is a real
+ * collision at RESOLUTION time regardless of routing. `readByUrlPath` picks one of the two
+ * whatever any `generateStaticParams` filter says, so the un-routed entry is not innocent; it is
+ * shadowing (or being shadowed by) the routed one at the same URL. `rootPath` narrows the scan
+ * because it narrows what was loaded at all; `filter` deliberately does not.
+ *
+ * Related but not redundant: `canopycms-next`'s `dedupeSitemapItems` warns on the same collision
+ * at the sitemap. It stays, because it also covers entry-vs-`extraUrls` collisions (adopter-supplied
+ * paths this content enumeration never sees) and non-build-mode calls, where this guard is silent.
+ */
+export function assertNoDuplicateUrlPaths(items, phaseLabel) {
+    const duplicates = findDuplicateUrlPaths(items);
+    if (duplicates.length === 0)
+        return;
+    const lines = duplicates.map(({ urlPath, entryPaths }) => {
+        // Identical entryPaths means ONE entry was enumerated more than once, not two entries
+        // colliding — the remedy below ("rename or remove one of them") is unfollowable, since
+        // there is only one file. The known cause is two sibling collections sharing a name: both
+        // resolve to the same directory, so its entries are listed once per sibling.
+        const selfCollision = entryPaths.every((entryPath) => entryPath === entryPaths[0]);
+        return selfCollision
+            ? `  - ${urlPath} — ${entryPaths.length}x ${entryPaths[0]} (the same entry, enumerated more than once — usually two sibling collections sharing one name)`
+            : `  - ${urlPath} — claimed by ${entryPaths.join(', ')}`;
+    });
+    throw new Error(`CanopyCMS static build: found ${duplicates.length} ${duplicates.length === 1 ? 'URL' : 'URLs'} claimed by more than one entry during ${phaseLabel}:\n${lines.join('\n')}\n` +
+        'Only one entry can be served at each URL, so the rest have no route at all. This usually means ' +
+        "an entry whose slug matches a sibling collection that also has an 'index' entry (the index " +
+        "collapses onto the collection's path), or two slugs differing only by case (URL paths are " +
+        'lowercased). Rename or remove one of the colliding entries, then rebuild.');
+}
+/**
+ * Find every listed entry whose `slug` cannot pass `parseSlug` — the validation `readByUrlPath`
+ * runs on every URL-resolution candidate it tries (`context.ts`).
+ *
+ * The filename grammar `parseTypedFilename` parses (`{type}.{slug}.{id}.{ext}`) deliberately
+ * allows a slug to contain dots, anchoring the split on the type and ID instead (see that
+ * function's doc comment) — and it does not run the parsed slug through `parseSlug` before
+ * handing it back, by design: recovering `{type, slug, id}` structurally, without validating
+ * every part, is its whole contract. `listCollectionEntries` inherits that: it lists the file and
+ * computes a `urlPath` for it, same as any other entry.
+ *
+ * But `parseSlug` requires `^[a-z0-9][a-z0-9-]*$` — no dots — so a listed entry whose slug
+ * contains one is unreachable through the one path everything else assumes works:
+ * `readByUrlPath` tries the URL's last segment as a candidate slug and skips any candidate that
+ * fails `parseSlug` (treating it as a miss, not an error) before it ever calls `read()`. The
+ * entry still builds, still gets a `generateStaticParams` entry, still gets a sitemap `<loc>` —
+ * and 404s the moment anything actually visits it. That breaks the `Round-trip safe` contract
+ * `content-listing.ts` documents on `urlPath` (`readByUrlPath(item.urlPath)` resolves to the same
+ * entry) and is exactly the silent-page-loss failure mode this guard's siblings
+ * (`assertBuildEntriesValid`, `assertNoDuplicateUrlPaths`) exist to make loud instead.
+ *
+ * The write boundary refuses to MINT such a slug: `api/content.ts` and `ContentStore.write()`
+ * both run `parseSlug` on a create, and `renameEntry()` runs it on the new slug (the [SLUG]
+ * guards). That enforcement is deliberately create-only — an entry that already carries a
+ * non-conforming slug stays saveable and renameable, because renaming it is the only way to fix
+ * this build failure, and refusing reads or edits would turn a red build into unreachable data.
+ *
+ * So this guard still fires, and is still needed, for every slug the write boundary never saw:
+ * hand-authored files, scripted migrations, content merged in over git, a repo being retrofitted
+ * onto CanopyCMS (this guard's intended audience, same as its siblings), and entries created
+ * before the write-time rule existed.
+ */
+export function findUnroutableSlugs(items) {
+    const found = [];
+    for (const item of items) {
+        const result = parseSlug(item.slug);
+        if (!result.ok) {
+            found.push({
+                entryPath: item.entryPath,
+                urlPath: item.urlPath,
+                slug: item.slug,
+                error: result.error,
+            });
+        }
+    }
+    return found;
+}
+/**
+ * Throw a single, descriptive Error if any listed entry's slug cannot round-trip through
+ * `readByUrlPath`.
+ *
+ * Fails the build for the same reason its siblings do: an entry that builds and gets advertised
+ * (sitemap, `generateStaticParams`) but 404s on every actual visit is a worse failure mode than a
+ * red build.
+ */
+export function assertRoutableSlugs(items, phaseLabel) {
+    const unroutable = findUnroutableSlugs(items);
+    if (unroutable.length === 0)
+        return;
+    const lines = unroutable.map(({ entryPath, urlPath, slug }) => `  - ${entryPath} (slug "${slug}", urlPath "${urlPath}")`);
+    throw new Error(`CanopyCMS static build: found ${unroutable.length} ${unroutable.length === 1 ? 'entry' : 'entries'} whose slug cannot resolve back through a URL during ${phaseLabel}:\n${lines.join('\n')}\n` +
+        'The filename grammar allows a slug to contain characters readByUrlPath cannot accept back ' +
+        "(most commonly a dot, e.g. a slug of 'getting.started.guide') — a valid slug for parseSlug is " +
+        'lowercase letters, numbers and hyphens only, starting with a letter or number. Each entry ' +
+        'above would build, appear in generateStaticParams and any sitemap, and then 404 on every ' +
+        'visit. Rename the slug (the file itself, not just its content), then rebuild.');
+}