canopycms 0.0.63 → 0.0.64

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.');
+}

package/dist/static/seo.d.ts

@@ -9,6 +9,14 @@
  * entry-schema.ts, which builds a schema group from these same names so the schema side and
  * the read side cannot drift.
  */
+import { isAbsoluteUrl, stripTrailingSlashes } from '../utils/url-prefix.js';
+/**
+ * Re-exported so this module's public surface (and `canopycms/server`'s, via `static/index.ts`)
+ * is unchanged by their move to `utils/url-prefix.ts` — where they now sit beside
+ * `joinUrlPrefix`, the shared join that `assets/asset-url.ts` also needs and that must not
+ * import anything under `static/`.
+ */
+export { isAbsoluteUrl, stripTrailingSlashes };
 /** og:type values covered by the recommended group. */
 export type SeoOgType = 'website' | 'article' | 'profile';
 /** twitter:card values covered by the recommended group. */
@@ -79,35 +87,6 @@ export declare function extractSeoFields(entryData: unknown, opts?: ExtractSeoFi
  * resolves for anyone holding the link.
  */
 export declare function isNoindexEntry(entryData: unknown, opts?: SeoFieldLocation): boolean;
-/**
- * An off-site URL: either scheme-qualified (`https://…`) or LITERAL protocol-relative
- * (`//cdn…`). Both name a host we don't control, so neither may be rewritten against the site
- * origin — `resolveSeoUrl` passes a `true` result through verbatim.
- *
- * Deliberately narrower than "resolves off-origin": a WHATWG-backslash-equivalent spelling
- * (`/\evil.com`, `\\evil.com`, `\/evil.com` — see `utils/sanitize-href.ts`'s
- * `isImplicitlyOffOrigin`) also resolves off-origin in a browser, but is NOT recognized here as
- * an intentional off-site pointer the way a literal `//cdn…` is. `resolveSeoUrl` handles that
- * case separately, by neutralizing (`neutralizeImplicitOffOrigin`) rather than passing through: a
- * `false` result here isn't a guarantee the value is a safe site-relative path on its own, only
- * that it isn't a *declared* off-site one.
- */
-export declare function isAbsoluteUrl(url: string): boolean;
-/**
- * Strip trailing slashes without a regex.
- *
- * The obvious `replace(/\/+$/, '')` is a polynomial-ReDoS shape (CodeQL
- * `js/polynomial-redos`, flagged high): on a value that is mostly slashes but does not end in
- * one, the engine retries `\/+` from every position and the match cost is quadratic in the
- * input length. `siteUrl` is adopter-supplied and can reach here from config or an env var, so
- * it counts as uncontrolled. A character scan is linear and needs no reasoning about
- * backtracking.
- *
- * Exported (from `canopycms/server`) so adopter code normalizing its own site-origin env var —
- * e.g. a `SITE_URL` constant built from `NEXT_PUBLIC_SITE_URL` — has a package-provided linear
- * way to do it instead of reaching for the same regex this function replaced.
- */
-export declare function stripTrailingSlashes(value: string): string;
 /**
  * Append a trailing slash to a site-relative path, matching a site that serves `/contact/`.
  *
@@ -147,4 +126,3 @@ export interface ResolveSeoUrlOptions {
  * "absolute" (see its doc) can't still be read by a browser as protocol-relative once emitted.
  */
 export declare function resolveSeoUrl(pathOrUrl: string, opts?: ResolveSeoUrlOptions): string;
-//# sourceMappingURL=seo.d.ts.map

package/dist/static/seo.js

@@ -9,7 +9,14 @@
  * entry-schema.ts, which builds a schema group from these same names so the schema side and
  * the read side cannot drift.
  */
-import { neutralizeImplicitOffOrigin } from '../utils/sanitize-href.js';
+import { isAbsoluteUrl, joinUrlPrefix, stripTrailingSlashes, toSameOriginPath, } from '../utils/url-prefix.js';
+/**
+ * Re-exported so this module's public surface (and `canopycms/server`'s, via `static/index.ts`)
+ * is unchanged by their move to `utils/url-prefix.ts` — where they now sit beside
+ * `joinUrlPrefix`, the shared join that `assets/asset-url.ts` also needs and that must not
+ * import anything under `static/`.
+ */
+export { isAbsoluteUrl, stripTrailingSlashes };
 /**
  * The recommended SEO field names. `defineSeoFieldGroup()` emits a schema group using exactly
  * these names, so an adopter who uses both ends needs no configuration at all.
@@ -99,42 +106,6 @@ export function extractSeoFields(entryData, opts = {}) {
 export function isNoindexEntry(entryData, opts = {}) {
     return extractSeoFields(entryData, opts).noindex === true;
 }
-/**
- * An off-site URL: either scheme-qualified (`https://…`) or LITERAL protocol-relative
- * (`//cdn…`). Both name a host we don't control, so neither may be rewritten against the site
- * origin — `resolveSeoUrl` passes a `true` result through verbatim.
- *
- * Deliberately narrower than "resolves off-origin": a WHATWG-backslash-equivalent spelling
- * (`/\evil.com`, `\\evil.com`, `\/evil.com` — see `utils/sanitize-href.ts`'s
- * `isImplicitlyOffOrigin`) also resolves off-origin in a browser, but is NOT recognized here as
- * an intentional off-site pointer the way a literal `//cdn…` is. `resolveSeoUrl` handles that
- * case separately, by neutralizing (`neutralizeImplicitOffOrigin`) rather than passing through: a
- * `false` result here isn't a guarantee the value is a safe site-relative path on its own, only
- * that it isn't a *declared* off-site one.
- */
-export function isAbsoluteUrl(url) {
-    return /^[a-z][a-z0-9+.-]*:\/\//i.test(url) || url.startsWith('//');
-}
-/**
- * Strip trailing slashes without a regex.
- *
- * The obvious `replace(/\/+$/, '')` is a polynomial-ReDoS shape (CodeQL
- * `js/polynomial-redos`, flagged high): on a value that is mostly slashes but does not end in
- * one, the engine retries `\/+` from every position and the match cost is quadratic in the
- * input length. `siteUrl` is adopter-supplied and can reach here from config or an env var, so
- * it counts as uncontrolled. A character scan is linear and needs no reasoning about
- * backtracking.
- *
- * Exported (from `canopycms/server`) so adopter code normalizing its own site-origin env var —
- * e.g. a `SITE_URL` constant built from `NEXT_PUBLIC_SITE_URL` — has a package-provided linear
- * way to do it instead of reaching for the same regex this function replaced.
- */
-export function stripTrailingSlashes(value) {
-    let end = value.length;
-    while (end > 0 && value.charCodeAt(end - 1) === 47 /* '/' */)
-        end--;
-    return value.slice(0, end);
-}
 /**
  * Append a trailing slash to a site-relative path, matching a site that serves `/contact/`.
  *
@@ -177,13 +148,15 @@ export function withTrailingSlash(path) {
 export function resolveSeoUrl(pathOrUrl, opts = {}) {
     if (isAbsoluteUrl(pathOrUrl))
         return pathOrUrl;
-    const safePathOrUrl = neutralizeImplicitOffOrigin(pathOrUrl);
-    const normalized = opts.trailingSlash
-        ? withTrailingSlash(safePathOrUrl)
-        : safePathOrUrl.startsWith('/')
-            ? safePathOrUrl
-            : `/${safePathOrUrl}`;
-    const origin = opts.siteUrl === undefined ? undefined : stripTrailingSlashes(opts.siteUrl);
-    return origin ? origin + normalized : normalized;
+    // Neutralize BEFORE the trailing-slash step, which is the order this has always run in:
+    // `withTrailingSlash` inspects the last path segment, and a backslash-equivalent spelling
+    // changes what that segment is.
+    //
+    // `toSameOriginPath`, not a bare `neutralizeImplicitOffOrigin`: neutralizing `/\evil.com//a`
+    // yields `//a`, and handing THAT to `joinUrlPrefix` means its absolute-URL check reads it as a
+    // protocol-relative pointer and returns it verbatim — dropping `siteUrl` and emitting an
+    // off-origin canonical. See `toSameOriginPath`'s doc.
+    const safePathOrUrl = toSameOriginPath(pathOrUrl);
+    const normalized = opts.trailingSlash ? withTrailingSlash(safePathOrUrl) : safePathOrUrl;
+    return joinUrlPrefix(opts.siteUrl, normalized);
 }
-//# sourceMappingURL=seo.js.map

package/dist/sync-core.d.ts

@@ -54,4 +54,3 @@ export interface PushContentToWorkspaceOptions {
 export declare function pushContentToWorkspace(options: PushContentToWorkspaceOptions): Promise<{
     fileCount: number;
 }>;
-//# sourceMappingURL=sync-core.d.ts.map

package/dist/sync-core.js

@@ -176,4 +176,3 @@ export async function pushContentToWorkspace(options) {
         await invalidateBranchContentCaches(branchPath);
     }
 }
-//# sourceMappingURL=sync-core.js.map