canopycms 0.0.62 → 0.0.64

package/dist/static/seo.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Framework-agnostic SEO field extraction and URL shaping.
+ *
+ * This module is pure: it maps an entry's raw data onto a neutral `SeoFields` shape and
+ * resolves URLs. Framework adapters (e.g. canopycms-next's `entryToMetadata`) turn that shape
+ * into their own metadata objects; nothing here imports a framework or a node built-in.
+ *
+ * The field names default to the recommended SEO field group — see `defineSeoFieldGroup` in
+ * 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. */
+export type SeoTwitterCard = 'summary' | 'summary_large_image';
+/** The neutral, framework-agnostic SEO shape. */
+export interface SeoFields {
+    title?: string;
+    description?: string;
+    ogImage?: string;
+    ogType?: SeoOgType;
+    canonical?: string;
+    noindex?: boolean;
+    twitterCard?: SeoTwitterCard;
+}
+/** Entry field names backing each neutral field. */
+export type SeoFieldNames = Record<keyof SeoFields, string>;
+/**
+ * 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.
+ */
+export declare const DEFAULT_SEO_FIELD_NAMES: {
+    readonly title: "metaTitle";
+    readonly description: "metaDescription";
+    readonly ogImage: "ogImage";
+    readonly ogType: "ogType";
+    readonly canonical: "canonical";
+    readonly noindex: "noindex";
+    readonly twitterCard: "twitterCard";
+};
+export interface ExtractSeoFieldsOptions {
+    /** Per-field name overrides (e.g. `{ title: 'seoTitle' }`). */
+    fields?: Partial<SeoFieldNames>;
+    /**
+     * Read the fields from a nested object under this key instead of from flat entry fields.
+     * Pair with `defineSeoFieldGroup({ group: 'seo' })`, which nests the same fields under that
+     * key in the content file. Omit for the flat (inline-group) convention, which is the default
+     * on both ends.
+     */
+    group?: string;
+    /** Used when the entry has no meta title (typically the entry's own title/heading). */
+    fallbackTitle?: string;
+    /** Used when the entry has no meta description. */
+    fallbackDescription?: string;
+}
+/** Just the parts of `ExtractSeoFieldsOptions` that locate the fields, with no fallbacks. */
+export type SeoFieldLocation = Pick<ExtractSeoFieldsOptions, 'fields' | 'group'>;
+/**
+ * Map an entry's SEO fields onto the neutral shape.
+ *
+ * Entry data is `unknown` — every read is guarded, unknown enum values are dropped rather than
+ * passed through, and non-object data (null, a string, an array) yields an all-undefined result
+ * rather than throwing.
+ */
+export declare function extractSeoFields(entryData: unknown, opts?: ExtractSeoFieldsOptions): SeoFields;
+/**
+ * THE `noindex` predicate. Every surface that suppresses an entry must route through this one
+ * function rather than re-deriving the flag:
+ *
+ * - the page's own `robots: { index: false }` (canopycms-next's `entryToMetadata`), and
+ * - exclusion from the sitemap (canopycms-next's `generateContentSitemap`).
+ *
+ * Those two shipping from one predicate is the point of shipping them together. Where they were
+ * derived separately, a `noindex` entry stayed advertised in one surface while correctly absent
+ * from the other, and nothing warned.
+ *
+ * NOT applied to enumeration: `noindex` means "don't advertise this", not "don't build this".
+ * `collectRoutableEntries` and `generateStaticParams` must still emit the entry, so its URL
+ * resolves for anyone holding the link.
+ */
+export declare function isNoindexEntry(entryData: unknown, opts?: SeoFieldLocation): boolean;
+/**
+ * Append a trailing slash to a site-relative path, matching a site that serves `/contact/`.
+ *
+ * Leaves the root (`/`) and file-like paths (a last segment containing a dot, e.g.
+ * `/blog/rss.xml`) alone, and never doubles an existing slash.
+ *
+ * A query string and/or fragment (`?page=2`, `#section`) is split off BEFORE the slash decision
+ * and placement, then reattached after — so `/blog?page=2` becomes `/blog/?page=2`, never
+ * `/blog?page=2/` (a literal trailing slash inside the query string, which is not what "serve
+ * with a trailing slash" means and breaks the URL).
+ */
+export declare function withTrailingSlash(path: string): string;
+export interface ResolveSeoUrlOptions {
+    /** Site origin (e.g. `https://example.com`). Trailing slashes are stripped. */
+    siteUrl?: string;
+    /**
+     * Emit site-relative paths with a trailing slash. CanopyCMS has no knowledge of your
+     * framework's routing config, so this must be stated explicitly — see the note on
+     * `generateContentSitemap`.
+     */
+    trailingSlash?: boolean;
+}
+/**
+ * Resolve a possibly-relative URL for public emission (canonical tag, sitemap URL, OG image).
+ *
+ * ORDER MATTERS — the absolute check runs FIRST. An absolute or protocol-relative value is a
+ * deliberate off-site pointer (syndication, a partner-hosted copy, a CDN image) and passes
+ * through verbatim; only a site-relative path gets trailing-slash normalization and the site
+ * origin. Normalizing first turns `https://other.org/page` into
+ * `<siteUrl>/https://other.org/page/`.
+ *
+ * With no `siteUrl`, a site-relative path is returned still relative (normalized), which is
+ * what you want when the framework resolves relative metadata URLs itself.
+ *
+ * A NOT-absolute value is also run through `neutralizeImplicitOffOrigin` before normalization,
+ * so a WHATWG-backslash-equivalent spelling that `isAbsoluteUrl` correctly declines to call
+ * "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;

package/dist/static/seo.js

@@ -0,0 +1,162 @@
+/**
+ * Framework-agnostic SEO field extraction and URL shaping.
+ *
+ * This module is pure: it maps an entry's raw data onto a neutral `SeoFields` shape and
+ * resolves URLs. Framework adapters (e.g. canopycms-next's `entryToMetadata`) turn that shape
+ * into their own metadata objects; nothing here imports a framework or a node built-in.
+ *
+ * The field names default to the recommended SEO field group — see `defineSeoFieldGroup` in
+ * entry-schema.ts, which builds a schema group from these same names so the schema side and
+ * the read side cannot drift.
+ */
+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.
+ */
+export const DEFAULT_SEO_FIELD_NAMES = {
+    title: 'metaTitle',
+    description: 'metaDescription',
+    ogImage: 'ogImage',
+    ogType: 'ogType',
+    canonical: 'canonical',
+    noindex: 'noindex',
+    twitterCard: 'twitterCard',
+};
+const asRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value)
+    ? value
+    : undefined;
+/**
+ * A non-empty trimmed string, or undefined.
+ *
+ * Empty is treated as UNSET, deliberately: CanopyCMS writes optional fields present-but-empty
+ * rather than omitting them, so `metaTitle: ''` is what an untouched SEO group looks like on
+ * disk. Treating it as a value would let a blank field beat the fallback title on every entry
+ * whose author never opened the SEO section.
+ */
+const asText = (value) => {
+    if (typeof value !== 'string')
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed === '' ? undefined : trimmed;
+};
+const asFlag = (value) => typeof value === 'boolean' ? value : undefined;
+/**
+ * An image URL from either convention: a plain string field, or an `image` field, whose value
+ * is a structured `{ src, alt, ... }` object. Supporting both means switching the recommended
+ * `ogImage` field to `type: 'image'` doesn't silently drop every OG image.
+ */
+const asImageUrl = (value) => {
+    const text = asText(value);
+    if (text)
+        return text;
+    return asText(asRecord(value)?.src);
+};
+const asOgType = (value) => {
+    const text = asText(value);
+    return text === 'website' || text === 'article' || text === 'profile' ? text : undefined;
+};
+const asTwitterCard = (value) => {
+    const text = asText(value);
+    return text === 'summary' || text === 'summary_large_image' ? text : undefined;
+};
+/**
+ * Map an entry's SEO fields onto the neutral shape.
+ *
+ * Entry data is `unknown` — every read is guarded, unknown enum values are dropped rather than
+ * passed through, and non-object data (null, a string, an array) yields an all-undefined result
+ * rather than throwing.
+ */
+export function extractSeoFields(entryData, opts = {}) {
+    const names = { ...DEFAULT_SEO_FIELD_NAMES, ...opts.fields };
+    const entry = asRecord(entryData);
+    const source = opts.group ? asRecord(entry?.[opts.group]) : entry;
+    return {
+        title: asText(source?.[names.title]) ?? asText(opts.fallbackTitle),
+        description: asText(source?.[names.description]) ?? asText(opts.fallbackDescription),
+        ogImage: asImageUrl(source?.[names.ogImage]),
+        ogType: asOgType(source?.[names.ogType]),
+        canonical: asText(source?.[names.canonical]),
+        noindex: asFlag(source?.[names.noindex]),
+        twitterCard: asTwitterCard(source?.[names.twitterCard]),
+    };
+}
+/**
+ * THE `noindex` predicate. Every surface that suppresses an entry must route through this one
+ * function rather than re-deriving the flag:
+ *
+ * - the page's own `robots: { index: false }` (canopycms-next's `entryToMetadata`), and
+ * - exclusion from the sitemap (canopycms-next's `generateContentSitemap`).
+ *
+ * Those two shipping from one predicate is the point of shipping them together. Where they were
+ * derived separately, a `noindex` entry stayed advertised in one surface while correctly absent
+ * from the other, and nothing warned.
+ *
+ * NOT applied to enumeration: `noindex` means "don't advertise this", not "don't build this".
+ * `collectRoutableEntries` and `generateStaticParams` must still emit the entry, so its URL
+ * resolves for anyone holding the link.
+ */
+export function isNoindexEntry(entryData, opts = {}) {
+    return extractSeoFields(entryData, opts).noindex === true;
+}
+/**
+ * Append a trailing slash to a site-relative path, matching a site that serves `/contact/`.
+ *
+ * Leaves the root (`/`) and file-like paths (a last segment containing a dot, e.g.
+ * `/blog/rss.xml`) alone, and never doubles an existing slash.
+ *
+ * A query string and/or fragment (`?page=2`, `#section`) is split off BEFORE the slash decision
+ * and placement, then reattached after — so `/blog?page=2` becomes `/blog/?page=2`, never
+ * `/blog?page=2/` (a literal trailing slash inside the query string, which is not what "serve
+ * with a trailing slash" means and breaks the URL).
+ */
+export function withTrailingSlash(path) {
+    const splitIndex = path.search(/[?#]/);
+    const base = splitIndex === -1 ? path : path.slice(0, splitIndex);
+    const suffix = splitIndex === -1 ? '' : path.slice(splitIndex);
+    const withLeading = base.startsWith('/') ? base : `/${base}`;
+    if (withLeading === '/' || withLeading.endsWith('/'))
+        return withLeading + suffix;
+    const lastSegment = withLeading.slice(withLeading.lastIndexOf('/') + 1);
+    if (lastSegment.includes('.'))
+        return withLeading + suffix;
+    return `${withLeading}/${suffix}`;
+}
+/**
+ * Resolve a possibly-relative URL for public emission (canonical tag, sitemap URL, OG image).
+ *
+ * ORDER MATTERS — the absolute check runs FIRST. An absolute or protocol-relative value is a
+ * deliberate off-site pointer (syndication, a partner-hosted copy, a CDN image) and passes
+ * through verbatim; only a site-relative path gets trailing-slash normalization and the site
+ * origin. Normalizing first turns `https://other.org/page` into
+ * `<siteUrl>/https://other.org/page/`.
+ *
+ * With no `siteUrl`, a site-relative path is returned still relative (normalized), which is
+ * what you want when the framework resolves relative metadata URLs itself.
+ *
+ * A NOT-absolute value is also run through `neutralizeImplicitOffOrigin` before normalization,
+ * so a WHATWG-backslash-equivalent spelling that `isAbsoluteUrl` correctly declines to call
+ * "absolute" (see its doc) can't still be read by a browser as protocol-relative once emitted.
+ */
+export function resolveSeoUrl(pathOrUrl, opts = {}) {
+    if (isAbsoluteUrl(pathOrUrl))
+        return pathOrUrl;
+    // 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);
+}

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

package/dist/task-queue/index.d.ts

@@ -1,3 +1,2 @@
-export type { Task, TaskStatus, QueueStats, TaskQueueLogger, CorruptTaskFile } from './types';
-export { enqueueTask, dequeueTask, completeTask, failTask, retryTask, requeueFailedTask, recoverOrphanedTasks, cleanupOldTasks, getTask, listTasks, getQueueStats, listCorruptTaskFiles, } from './task-queue';
-//# sourceMappingURL=index.d.ts.map
+export type { Task, TaskStatus, QueueStats, TaskQueueLogger, CorruptTaskFile } from './types.js';
+export { enqueueTask, dequeueTask, completeTask, failTask, retryTask, requeueFailedTask, recoverOrphanedTasks, cleanupOldTasks, getTask, listTasks, getQueueStats, listCorruptTaskFiles, } from './task-queue.js';

package/dist/task-queue/index.js

@@ -1,2 +1 @@
 export { enqueueTask, dequeueTask, completeTask, failTask, retryTask, requeueFailedTask, recoverOrphanedTasks, cleanupOldTasks, getTask, listTasks, getQueueStats, listCorruptTaskFiles, } from './task-queue.js';
-//# sourceMappingURL=index.js.map

package/dist/task-queue/task-queue.d.ts

@@ -15,7 +15,7 @@
  * processes — the worker lock (acquireLock) ensures only one consumer runs at
  * a time. Do not run multiple dequeue consumers concurrently.
  */
-import type { Task, TaskStatus, QueueStats, TaskQueueLogger, CorruptTaskFile } from './types';
+import type { Task, TaskStatus, QueueStats, TaskQueueLogger, CorruptTaskFile } from './types.js';
 /**
  * Enqueue a task. Writes a JSON file to pending/{id}.json.
  * Returns the generated task ID.
@@ -114,4 +114,3 @@ export declare function getQueueStats(taskDir: string): Promise<QueueStats>;
  * dir (returns []). Sorted newest-mtime first, capped at `limit`.
  */
 export declare function listCorruptTaskFiles(taskDir: string, limit?: number, logger?: TaskQueueLogger): Promise<CorruptTaskFile[]>;
-//# sourceMappingURL=task-queue.d.ts.map

package/dist/task-queue/task-queue.js

@@ -531,4 +531,3 @@ async function moveToCorrupt(taskDir, sourceDir, fileName, reason, logger) {
         await fs.unlink(path.join(sourceDir, fileName)).catch(() => { });
     }
 }
-//# sourceMappingURL=task-queue.js.map

package/dist/task-queue/types.d.ts

@@ -47,4 +47,3 @@ export interface CorruptTaskFile {
     mtime: string;
     rawSnippet: string;
 }
-//# sourceMappingURL=types.d.ts.map

package/dist/task-queue/types.js

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=types.js.map

package/dist/types.d.ts

@@ -1,4 +1,4 @@
-import type { ContentId } from './paths/types';
+import type { ContentId } from './paths/types.js';
 export type CanopyUserId = string;
 export type CanopyGroupId = string;
 /**
@@ -98,11 +98,11 @@ export interface BranchPaths {
 export interface BranchContext extends BranchPaths {
     branch: BranchMetadata;
     /** Per-branch flattened schema (lazy-loaded via getBranchContext with loadSchema: true) */
-    flatSchema?: import('./config').FlatSchemaItem[];
+    flatSchema?: import('./config/index.js').FlatSchemaItem[];
 }
 /** BranchContext with guaranteed flatSchema (loaded via schema guard or loadSchema: true) */
 export interface BranchContextWithSchema extends BranchContext {
-    flatSchema: import('./config').FlatSchemaItem[];
+    flatSchema: import('./config/index.js').FlatSchemaItem[];
 }
 /**
  * Wire shape of the worker's self-reported status file (worker-status.json,
@@ -170,4 +170,3 @@ export interface WorkerStatusReport {
         phase: 'startup' | 'run';
     };
 }
-//# sourceMappingURL=types.d.ts.map

package/dist/types.js

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=types.js.map

package/dist/url-collision.d.ts

@@ -0,0 +1,86 @@
+/**
+ * The WRITE-BOUNDARY half of the invariant "no two entries may claim the same `urlPath`".
+ *
+ * The build-time half (`assertNoDuplicateUrlPaths`, static/index.ts) detects the state; this
+ * refuses to create it. Neither replaces the other: content is git-backed, so it also arrives by
+ * merge, by PR, by direct commit and by adopters retrofitting an existing repo — none of which
+ * pass through this boundary — while the build guard cannot help an editor who is about to author
+ * the collision right now.
+ *
+ * A SCHEMA edit alone can also create one, with no content write at all: `updateEntryType`
+ * changing a format changes the listing's `validExts`, which can flip a previously-unlisted
+ * `guide.index.{id}.json` into a published entry and so into a contested pair. Another reason
+ * neither half of this invariant subsumes the other.
+ *
+ * Deliberately formulated on `urlPath`, not on names. An entry whose slug matches a sibling
+ * collection is only a problem when that collection ALSO has an index entry:
+ *
+ *   content/docs/page.guides.{id}.json + content/docs/guides.{id}/  (no index)  -> fine.
+ *     A landing page plus a folder of children. Both are reachable; nothing is contested.
+ *
+ *   content/docs/page.guides.{id}.json + content/docs/guides.{id}/doc.index.{id}.md
+ *     -> contested. Both compute /docs/guides, so exactly one of them is reachable and the
+ *        other silently has no route.
+ *
+ * A name-collision rule would forbid the first, which is a shape adopters legitimately build.
+ *
+ * Everything here works on PHYSICAL directories, because that is what the write path holds when
+ * it needs the answer, and because the on-disk names carry the content IDs that logical paths
+ * hide (`guides.{id}/`, `doc.index.{id}.md`).
+ *
+ * SCOPE, and do not widen it by accident: this guards the URL an ENTRY claims -- the `urlPath`
+ * that `computeEntryUrl` derives and `listEntries` publishes. It is NOT "every URL the site
+ * serves", and the two are not the same set. A framework adapter can route an entry somewhere
+ * else — adopters add hand-written routes Canopy knows nothing about, and a framework adapter can
+ * rewrite a sitemap `<loc>` after enumeration (`generateContentSitemap`'s `pathFor` option, in
+ * `canopycms-next/src/static.ts`, does exactly that). Those URLs are
+ * invisible here by design -- there is no filesystem state to check them against at write time.
+ * A future change that tries to make this the authority on "the set of URLs this site claims"
+ * would be reaching past what the write boundary can actually see.
+ */
+/** One entry that already claims the `urlPath` a pending write would produce. */
+export interface UrlPathClaimant {
+    /**
+     * Which of the two shapes was found. Callers word their own message from this, because the
+     * actionable advice differs: for `sibling-collection-index` the author should rename their new
+     * entry, for `parent-entry` they are adding the index entry that makes an existing pair
+     * contested.
+     */
+    kind: 'sibling-collection-index' | 'parent-entry';
+    /** Absolute path of the file already claiming that URL. */
+    physicalPath: string;
+    /** The contested logical name — the sibling collection's name, or the parent entry's slug. */
+    name: string;
+}
+/**
+ * The index entry file directly inside `dir`, or null.
+ *
+ * Slug extraction is entry-type-agnostic (each candidate's own type is read out of its filename),
+ * so an index entry of ANY entry type counts — same reasoning as the existing same-slug guard,
+ * which is deliberately cross-type because the URL does not care what type serves it.
+ */
+export declare function findIndexEntryIn(dir: string): Promise<string | null>;
+/** The entry file directly inside `dir` whose slug is `slug`, or null. */
+export declare function findEntryBySlugIn(dir: string, slug: string): Promise<string | null>;
+/**
+ * Would an entry at `collectionDir` with slug `slug` land on a `urlPath` some OTHER entry already
+ * claims? Returns the offender, or null when the write is clear.
+ *
+ * Only the cross-collection shapes are checked here. An entry colliding with another entry in the
+ * SAME collection is already refused upstream (`ContentStore.buildPaths` resolves a write by a
+ * type-agnostic slug scan, and the `expectedVersion: null` create-intent guard turns that into a
+ * conflict), so re-checking it would be duplicate work and a second source of truth.
+ *
+ * Two directory reads at worst, and only on create/rename — an ordinary save of an existing entry
+ * never calls this, because the entry's URL is not changing and the collision (if any) predates
+ * the write.
+ *
+ * @param contentRoot Absolute path of the content root. A root-level index entry claims `/`, which
+ *   nothing above it can contest, so the `parent-entry` check stops here rather than walking out
+ *   of the content tree.
+ */
+export declare function findUrlPathClaimant(opts: {
+    collectionDir: string;
+    slug: string;
+    contentRoot: string;
+}): Promise<UrlPathClaimant | null>;

package/dist/url-collision.js

@@ -0,0 +1,186 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { extractSlugFromFilename } from './content-id-index.js';
+import { isIndexSlug } from './utils/entry-url.js';
+import { isNotFoundError } from './utils/error.js';
+import { parseTypedFilename } from './utils/typed-filename.js';
+/**
+ * Every extension `getFormatExtension` can return.
+ *
+ * Compared CASE-SENSITIVELY, deliberately, because `listCollectionEntries` compares
+ * case-sensitively (`d.name.endsWith(ext)` against lowercase extensions). Lowercasing here made
+ * the guard looser than the listing: a `doc.index.{id}.MD` file counted as a claimant while the
+ * listing skipped it silently — publishing no URL, tripping no build error, and blocking a write
+ * the build would have accepted.
+ *
+ * KNOWN RESIDUAL LOOSENESS, stated because the alternative is a comment that overclaims: the
+ * listing accepts only the extensions of a collection's OWN configured entry-type formats, while
+ * this accepts all four. A hand-authored `doc.index.{id}.json` inside an md-only collection
+ * therefore claims no URL yet still blocks a sibling write. Closing that means threading each
+ * collection's configured formats into a module that is deliberately schema-free, across three
+ * call sites, and going from a physical directory back to a schema item to do it — a change with
+ * more room to introduce a new defect than the narrow one it fixes. Tracked in
+ * .claude/future-tasks/url-collision-guard-superset-of-listing.md.
+ *
+ * A literal rather than derived: deriving it needs the `ContentFormat` union this module has no
+ * reason to import. `url-collision.test.ts` carries the drift tripwire — a compile-time
+ * exhaustiveness check plus a fixture per format — so adding a format fails there rather than
+ * silently under-blocking here.
+ */
+const CONTENT_EXTENSIONS = ['.md', '.mdx', '.json', '.yaml'];
+/** Read a directory, treating "missing" as empty. Anything else is a real error and propagates. */
+async function readDirSafe(dir) {
+    try {
+        return await fs.readdir(dir, { withFileTypes: true });
+    }
+    catch (err) {
+        if (isNotFoundError(err))
+            return [];
+        throw err;
+    }
+}
+/** The child directory of `dir` whose logical name is `name`, or null. */
+async function findChildCollectionDir(dir, name) {
+    const wanted = name.toLowerCase();
+    for (const entry of await readDirSafe(dir)) {
+        if (!entry.isDirectory())
+            continue;
+        if (extractSlugFromFilename(entry.name) === wanted)
+            return path.join(dir, entry.name);
+    }
+    return null;
+}
+/**
+ * The slug a file CLAIMS A URL AT, or null when the file claims none.
+ *
+ * This must recognise the set `listEntries` recognises, as closely as a schema-free module can,
+ * because the invariant is defined over the `urlPath`s `listEntries` publishes and the build-time
+ * half checks those. (One documented gap remains — see `CONTENT_EXTENSIONS`.) Hence
+ * `parseTypedFilename` — the same `{type}.{slug}.{id}.{ext}` grammar `listCollectionEntries` uses
+ * — rather than `extractSlugFromFilename`, which answers a different and much looser question
+ * ("what would I call this file?") and happily names a slug for things that are not entries.
+ *
+ * Getting this wrong OVER-BLOCKS, which is worse here than under-blocking: a hand-authored
+ * `index.md` with no content ID, an `index.md~` editor backup, or a colocated `guides.png` are all
+ * non-entries that claim no URL, so the build guard ignores them — but a looser scan counted them
+ * as claimants and refused a legitimate write, telling the author to "remove that collection's
+ * index entry" about a file Canopy does not consider an entry. That lands hardest on repos being
+ * retrofitted onto CanopyCMS, which is precisely the audience this guard's migration note
+ * addresses.
+ *
+ * Parsed structurally (no `entryTypes` list), which is the SECOND of three known ways this
+ * claimant set is a strict superset of the listing's — all of them over-blocks, all of them
+ * tracked together in .claude/future-tasks/url-collision-guard-superset-of-listing.md:
+ *
+ *   1. extension — see `CONTENT_EXTENSIONS` above;
+ *   2. entry TYPE — a file whose type is not in the collection's config is skipped by the
+ *      listing but counted here. An earlier version of this comment dismissed that as "already
+ *      reported by the listing's malformed-file guard". That is true only in BUILD mode; in the
+ *      editor, where this guard actually runs, `listCollectionEntries` skips such a file with a
+ *      debug-gated warning and nothing surfaces. Reached by the accident
+ *      `looksLikeMalformedEntry` itself names as most common: renaming an entry type in
+ *      `.collection.json` without renaming the files;
+ *   3. collection-hood — `findChildCollectionDir` matches any child directory by name, but a
+ *      directory with no `.collection.json` is not a collection, so nothing inside it publishes
+ *      a URL. Narrow (the file inside still needs valid entry grammar) but the same direction.
+ *
+ * All three need the same fix — the schema this module deliberately does not have — so they are
+ * one task, not three.
+ */
+function entrySlugOf(filename) {
+    // `parseTypedFilename` strips the extension without checking it, so an editor backup
+    // (`doc.index.{id}.md~`) parses exactly like the entry it shadows. `listCollectionEntries`
+    // additionally requires a CONFIGURED format extension, so it skips those -- and this must skip
+    // them too, or the guard refuses a write over a file the build guard never counted.
+    if (!CONTENT_EXTENSIONS.some((ext) => filename.endsWith(ext)))
+        return null;
+    return parseTypedFilename(filename)?.slug ?? null;
+}
+/**
+ * The index entry file directly inside `dir`, or null.
+ *
+ * Slug extraction is entry-type-agnostic (each candidate's own type is read out of its filename),
+ * so an index entry of ANY entry type counts — same reasoning as the existing same-slug guard,
+ * which is deliberately cross-type because the URL does not care what type serves it.
+ */
+export async function findIndexEntryIn(dir) {
+    for (const entry of await readDirSafe(dir)) {
+        if (entry.isDirectory())
+            continue;
+        if (isIndexSlug(entrySlugOf(entry.name) ?? undefined))
+            return path.join(dir, entry.name);
+    }
+    return null;
+}
+/** The entry file directly inside `dir` whose slug is `slug`, or null. */
+export async function findEntryBySlugIn(dir, slug) {
+    const wanted = slug.toLowerCase();
+    for (const entry of await readDirSafe(dir)) {
+        if (entry.isDirectory())
+            continue;
+        if (entrySlugOf(entry.name) === wanted)
+            return path.join(dir, entry.name);
+    }
+    return null;
+}
+/**
+ * Would an entry at `collectionDir` with slug `slug` land on a `urlPath` some OTHER entry already
+ * claims? Returns the offender, or null when the write is clear.
+ *
+ * Only the cross-collection shapes are checked here. An entry colliding with another entry in the
+ * SAME collection is already refused upstream (`ContentStore.buildPaths` resolves a write by a
+ * type-agnostic slug scan, and the `expectedVersion: null` create-intent guard turns that into a
+ * conflict), so re-checking it would be duplicate work and a second source of truth.
+ *
+ * Two directory reads at worst, and only on create/rename — an ordinary save of an existing entry
+ * never calls this, because the entry's URL is not changing and the collision (if any) predates
+ * the write.
+ *
+ * @param contentRoot Absolute path of the content root. A root-level index entry claims `/`, which
+ *   nothing above it can contest, so the `parent-entry` check stops here rather than walking out
+ *   of the content tree.
+ */
+export async function findUrlPathClaimant(opts) {
+    const { collectionDir, slug, contentRoot } = opts;
+    if (isIndexSlug(slug)) {
+        // Adding an index entry collapses this collection onto its own path, which an entry sitting
+        // beside the collection in the PARENT may already hold.
+        const resolvedRoot = path.resolve(contentRoot);
+        if (path.resolve(collectionDir) === resolvedRoot)
+            return null; // a root index claims '/', uncontestable
+        const parentDir = path.dirname(collectionDir);
+        const ownName = extractSlugFromFilename(path.basename(collectionDir));
+        // A collection literally NAMED "index" collapses onto ITS OWN path (`<parentPath>/index`),
+        // not onto `<parentPath>` -- see `computeEntryUrl`. So the only thing that could contest it
+        // is another entry in the parent whose slug is ALSO the literal string "index" -- but per
+        // that same forward rule, such an entry IS the parent's own index/landing entry, which
+        // collapses onto `<parentPath>` itself, a different URL. Nothing in the parent can ever claim
+        // `<parentPath>/index`, so skip the lookup below rather than let it match the parent's own
+        // index entry and report a collision that does not exist. Without this, a collection named
+        // "index" could never have a landing page under any parent that has one of its own --
+        // ironic, since `resolveUrlPathCandidates`' candidate 2 was deliberately engineered to keep a
+        // collection named "index" addressable in the first place.
+        if (isIndexSlug(ownName))
+            return null;
+        const claimant = await findEntryBySlugIn(parentDir, ownName);
+        return claimant ? { kind: 'parent-entry', physicalPath: claimant, name: ownName } : null;
+    }
+    // A plain entry sits at the same URL as a same-named child collection's index entry.
+    //
+    // KNOWN DEPENDENCY: this resolves ONE child collection by name, and the index direction above
+    // likewise looks only for a parent ENTRY. Neither considers a second collection sharing the
+    // same name, because nothing currently stops one being created -- `createCollectionInner` does
+    // not check sibling names at all (tracked in collection-sibling-name-uniqueness.md). With two
+    // `guides.{id}` directories side by side you can write an index entry into each, and both
+    // writes pass this guard while two entries end up claiming one URL. The build guard still
+    // catches it. Fixing sibling-name uniqueness closes this without changing anything here --
+    // which is why that task is a prerequisite for this guard being complete, not an unrelated
+    // tidy-up.
+    const childDir = await findChildCollectionDir(collectionDir, slug);
+    if (!childDir)
+        return null;
+    const indexEntry = await findIndexEntryIn(childDir);
+    return indexEntry
+        ? { kind: 'sibling-collection-index', physicalPath: indexEntry, name: slug }
+        : null;
+}