canopycms 0.0.63 → 0.0.64

package/dist/utils/entry-url.js

@@ -5,6 +5,25 @@
  * so it can be safely imported into browser bundles.
  */
 import { trimSlashes } from '../paths/normalize.js';
+/**
+ * Is this slug the collection-index slug?
+ *
+ * The shared home for that decision. Six sites route through here: `computeEntryUrl` below,
+ * `content-tree.ts`'s `defaultBuildPath`, `content-reader.ts`'s `buildEntryPath` and the
+ * editor's `buildPreviewSrc` (the four forward-rule implementations), the reverse
+ * `resolveUrlPathCandidates`, and `canopycms-next`'s `collectStaticParams`, which skips index
+ * entries for a single-segment route. Re-exported from `canopycms/server` for adopters. (`content-tree.ts`'s `indexEntry` lookup still does its own
+ * `slug === 'index'`; it is fed slugs already lowercased by the listing, so it is safe rather
+ * than shared.) Slug matching is case-insensitive throughout
+ * CanopyCMS (`parseSlug` lowercases, and `ContentStore` resolves slugs by a lowercased
+ * directory scan), so this compares lowercased — a bare `slug === 'index'` is correct only
+ * for callers whose input was already normalized, and silently wrong for the ones handling
+ * raw URL segments or on-disk names. `resolveUrlPathCandidates` was exactly that case: its
+ * strict compare left `/x/Index` resolving the index entry after `/x/index` stopped.
+ */
+export function isIndexSlug(slug) {
+    return slug?.toLowerCase() === 'index';
+}
 /**
  * Compute a URL path from an entry's collection path and slug.
  *
@@ -30,12 +49,11 @@ export function computeEntryUrl(collection, slug, contentRoot) {
     }
     // Build URL segments
     const segments = stripped.split('/').filter(Boolean);
-    // Append slug unless it's "index" (index entries collapse to parent)
-    if (slug && slug !== 'index') {
+    // Append slug unless it's an index slug (index entries collapse to parent)
+    if (slug && !isIndexSlug(slug)) {
         segments.push(slug);
     }
     const path = segments.length > 0 ? `/${segments.join('/')}` : '/';
     // Lowercase to match content-listing.ts and content-tree.ts URL conventions
     return path.toLowerCase();
 }
-//# sourceMappingURL=entry-url.js.map

package/dist/utils/error.d.ts

@@ -84,4 +84,3 @@ export declare function isPermissionError(err: unknown): boolean;
  * @returns True if the error is EEXIST (file already exists)
  */
 export declare function isFileExistsError(err: unknown): boolean;
-//# sourceMappingURL=error.d.ts.map

package/dist/utils/error.js

@@ -150,4 +150,3 @@ export function isPermissionError(err) {
 export function isFileExistsError(err) {
     return isNodeError(err) && err.code === 'EEXIST';
 }
-//# sourceMappingURL=error.js.map

package/dist/utils/flatten-group-fields.d.ts

@@ -1,4 +1,4 @@
-import type { FieldConfig } from '../config';
+import type { FieldConfig } from '../config/index.js';
 /**
  * Recursively flatten inline groups out of a field array.
  * Group children are inlined at the parent level — groups are transparent to data.
@@ -10,4 +10,3 @@ import type { FieldConfig } from '../config';
  * Not needed when using traverseFields() — that already handles groups transparently.
  */
 export declare function flattenGroupFields(fields: readonly FieldConfig[]): FieldConfig[];
-//# sourceMappingURL=flatten-group-fields.d.ts.map

package/dist/utils/flatten-group-fields.js

@@ -20,4 +20,3 @@ export function flattenGroupFields(fields) {
     }
     return result;
 }
-//# sourceMappingURL=flatten-group-fields.js.map

package/dist/utils/format.d.ts

@@ -1,4 +1,4 @@
-import type { ContentFormat } from '../config';
+import type { ContentFormat } from '../config/index.js';
 /**
  * Get the file extension for a content format
  * @param format - The content format (md, mdx, json, yaml)
@@ -9,4 +9,3 @@ export declare const getFormatExtension: (format: ContentFormat) => string;
 export declare const isDataOnlyFormat: (format: ContentFormat) => boolean;
 /** Safely coerce a parsed value to a record, returning {} for non-object values */
 export declare const asRecord: (value: unknown) => Record<string, unknown>;
-//# sourceMappingURL=format.d.ts.map

package/dist/utils/format.js

@@ -18,4 +18,3 @@ export const isDataOnlyFormat = (format) => format === 'json' || format === 'yam
 export const asRecord = (value) => value && typeof value === 'object' && !Array.isArray(value)
     ? value
     : {};
-//# sourceMappingURL=format.js.map

package/dist/utils/fs.d.ts

@@ -1,3 +1,9 @@
 /** Check if a path exists on disk. */
 export declare function filePathExists(filePath: string): Promise<boolean>;
-//# sourceMappingURL=fs.d.ts.map
+/**
+ * Read a UTF-8 file, or return undefined if it does not exist.
+ *
+ * Only ENOENT is swallowed — a permissions or I/O failure still throws, so a caller cannot
+ * mistake "unreadable" for "not there yet".
+ */
+export declare function readFileIfExists(filePath: string): Promise<string | undefined>;

package/dist/utils/fs.js

@@ -12,4 +12,19 @@ export async function filePathExists(filePath) {
         throw err;
     }
 }
-//# sourceMappingURL=fs.js.map
+/**
+ * Read a UTF-8 file, or return undefined if it does not exist.
+ *
+ * Only ENOENT is swallowed — a permissions or I/O failure still throws, so a caller cannot
+ * mistake "unreadable" for "not there yet".
+ */
+export async function readFileIfExists(filePath) {
+    try {
+        return await fs.readFile(filePath, 'utf8');
+    }
+    catch (err) {
+        if (isNotFoundError(err))
+            return undefined;
+        throw err;
+    }
+}

package/dist/utils/git.d.ts

@@ -1,4 +1,4 @@
-import type { OperatingMode } from '../operating-mode';
+import type { OperatingMode } from '../operating-mode/index.js';
 /**
  * Whether a git remote URL points at a network location — http(s)://,
  * ssh://, git://, scp-like `[user@]host:path`, a transport-helper `scheme::`
@@ -98,4 +98,3 @@ export declare function resolveBaseBranch(options: {
     /** Repo root used for dev-mode HEAD detection. Defaults to process.cwd(). */
     detectFrom?: string;
 }): Promise<string>;
-//# sourceMappingURL=git.d.ts.map

package/dist/utils/git.js

@@ -174,4 +174,3 @@ export async function resolveBaseBranch(options) {
     }
     return 'main';
 }
-//# sourceMappingURL=git.js.map

package/dist/utils/logger.d.ts

@@ -68,4 +68,3 @@ export declare function canopyLog(...args: unknown[]): void;
 export declare function canopyLogWarn(...args: unknown[]): void;
 /** Failure worth alerting on. Routes to stderr. */
 export declare function canopyLogError(...args: unknown[]): void;
-//# sourceMappingURL=logger.d.ts.map

package/dist/utils/logger.js

@@ -82,4 +82,3 @@ export function canopyLogWarn(...args) {
 export function canopyLogError(...args) {
     active.error(...args);
 }
-//# sourceMappingURL=logger.js.map

package/dist/utils/occ-json-write.d.ts

@@ -97,4 +97,3 @@ export declare function withOccRetry<T>(operation: () => Promise<T>, options?: W
  * legitimately take many seconds.
  */
 export declare function withOccFileLock<T>(filePath: string, fn: () => Promise<T>): Promise<T>;
-//# sourceMappingURL=occ-json-write.d.ts.map

package/dist/utils/occ-json-write.js

@@ -238,4 +238,3 @@ export async function withOccFileLock(filePath, fn) {
         });
     }
 }
-//# sourceMappingURL=occ-json-write.js.map

package/dist/utils/provisioning-lock.d.ts

@@ -1,3 +1,16 @@
+/**
+ * Called when proper-lockfile reports the lock was lost mid-hold (its directory
+ * vanished, or a refresh failed and another holder may have taken over).
+ *
+ * Every call site must decide what that means for ITS critical section, which
+ * is why this is a parameter rather than a fixed policy: a compromise during
+ * idempotent provisioning is survivable, but a compromise during the worker's
+ * rebase means a second writer may be live and the next destructive git step
+ * must not run. What is NOT negotiable is that it must not throw --
+ * proper-lockfile invokes it from inside the refresh timer, so a throw is an
+ * uncaught exception that kills the process.
+ */
+export type OnLockCompromised = (err: Error) => void;
 /**
  * Acquire a cross-process filesystem lock for content provisioning.
  *
@@ -11,10 +24,11 @@
  *
  * Returns a release function — always call it in a `finally`.
  *
- * @param lockTargetDir directory the lock is anchored on (created if missing)
+ * @param lockTargetDir directory the lock marker lives in (created if missing)
  * @param lockName name of the on-disk lock marker, created inside lockTargetDir
+ * @param onCompromised see {@link OnLockCompromised}; defaults to log-and-continue
  */
-export declare function acquireProvisioningLock(lockTargetDir: string, lockName: string): Promise<() => Promise<void>>;
+export declare function acquireProvisioningLock(lockTargetDir: string, lockName: string, onCompromised?: OnLockCompromised): Promise<() => Promise<void>>;
 /**
  * Zero-retry variant of {@link acquireProvisioningLock}, for admin actions
  * running inside a synchronous request/response cycle (e.g. a Lambda-backed
@@ -33,5 +47,4 @@ export declare function acquireProvisioningLock(lockTargetDir: string, lockName:
  * Throws with `err.code === 'ELOCKED'` on contention (a live, non-stale
  * holder) -- callers should translate that into a 409.
  */
-export declare function tryAcquireProvisioningLock(lockTargetDir: string, lockName: string): Promise<() => Promise<void>>;
-//# sourceMappingURL=provisioning-lock.d.ts.map
+export declare function tryAcquireProvisioningLock(lockTargetDir: string, lockName: string, onCompromised?: OnLockCompromised): Promise<() => Promise<void>>;

package/dist/utils/provisioning-lock.js

@@ -1,6 +1,90 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import lockfile from 'proper-lockfile';
+import { getErrorMessage, isNodeError } from './error.js';
+import { canopyLogWarn } from './logger.js';
+/**
+ * Shared option set for both provisioning-lock variants.
+ *
+ * **The lock is anchored on the lock file's own path, not its directory.**
+ * proper-lockfile keys its module-level `locks{}` bookkeeping (refresh timer,
+ * release fn) by the TARGET path passed to `lock()` — not by `lockfilePath`.
+ * Passing the shared branches directory made every branch under one root alias
+ * a single registry entry: acquiring `.b.init.lock` overwrote `.a.init.lock`'s
+ * entry, so releasing A tore down B's refresh timer, made B's own release fail
+ * with `ERELEASED`, and leaked B's lock directory on disk until `stale`
+ * expired. The orphaned refresh timer then `stat`ed a path its owner had
+ * already deleted, raising `ECOMPROMISED`. Anchoring here makes the registry
+ * key identical to the on-disk lock identity, so two live locks can never
+ * share a key. `realpath: false` because the anchor path is the lock marker
+ * itself and does not exist before we create it (realpath would ENOENT).
+ * See docs/concurrency.md ("Anchor path matters").
+ */
+function provisioningLockOptions(lockPath, retries, onCompromised) {
+    return {
+        lockfilePath: lockPath,
+        realpath: false,
+        retries,
+        stale: 30_000,
+        // proper-lockfile invokes this from inside its refresh timer, so ANY throw
+        // escaping here is an uncaught exception that kills the process -- the very
+        // failure the handler exists to prevent. Call sites are told not to throw
+        // (see OnLockCompromised); this makes it structural rather than a
+        // convention, and also covers the LOGGER throwing: under `CI=true`,
+        // vitest's `onConsoleLog` turns any console write into a throw.
+        onCompromised: (err) => {
+            try {
+                if (onCompromised) {
+                    onCompromised(err);
+                    return;
+                }
+                // Default: log and let the holder finish. proper-lockfile's own default
+                // rethrows from the refresh timer, which protects nothing -- by the time
+                // a compromise is reported the mutual exclusion is already gone.
+                // `canopyLogWarn` (not the debug logger) because this means "two
+                // holders may now be live": it must be visible without CANOPYCMS_DEBUG.
+                canopyLogWarn(`[canopy] Provisioning lock compromised mid-hold for ${lockPath}:`, getErrorMessage(err));
+            }
+            catch {
+                // Last resort: a raw stderr write goes around both a replaced logger
+                // and vitest's console interception, so the compromise still leaves a
+                // trace. Guarded in turn, because nothing above this line is allowed
+                // to throw out of a refresh timer.
+                try {
+                    process.stderr.write(`[canopy] lock compromised for ${lockPath}; its handler or logger threw\n`);
+                }
+                catch {
+                    // Nothing further is safe to attempt.
+                }
+            }
+        },
+    };
+}
+/**
+ * proper-lockfile's release rejects with `ERELEASED` once the lock has been
+ * marked compromised (`setLockAsCompromised` sets `released = true` before the
+ * caller ever gets to release). Callers hold this in a `finally`, so letting
+ * that escape would convert a COMPLETED operation into a spurious failure.
+ * There is nothing left to release in that state, so swallow just that code and
+ * let every other release error propagate to the caller that asked for it.
+ */
+function releaseIgnoringAlreadyReleased(release, lockPath) {
+    return async () => {
+        try {
+            await release();
+        }
+        catch (err) {
+            if (isNodeError(err) && err.code === 'ERELEASED') {
+                // Deliberately does not name a cause: ERELEASED is raised both by a
+                // lock compromised mid-hold AND by a plain double-release bug, and
+                // from here the two are indistinguishable.
+                canopyLogWarn(`[canopy] Lock at ${lockPath} was already released (compromised mid-hold, or released twice); nothing to release`);
+                return;
+            }
+            throw err;
+        }
+    };
+}
 /**
  * Acquire a cross-process filesystem lock for content provisioning.
  *
@@ -14,22 +98,21 @@ import lockfile from 'proper-lockfile';
  *
  * Returns a release function — always call it in a `finally`.
  *
- * @param lockTargetDir directory the lock is anchored on (created if missing)
+ * @param lockTargetDir directory the lock marker lives in (created if missing)
  * @param lockName name of the on-disk lock marker, created inside lockTargetDir
+ * @param onCompromised see {@link OnLockCompromised}; defaults to log-and-continue
  */
-export async function acquireProvisioningLock(lockTargetDir, lockName) {
+export async function acquireProvisioningLock(lockTargetDir, lockName, onCompromised) {
     await fs.mkdir(lockTargetDir, { recursive: true });
+    const lockPath = path.join(lockTargetDir, lockName);
     // Generous, jittered retries: many waiters (one per build worker process, each
     // prerendering several pages) may contend, and the holder can take several
     // seconds to init + clone/push. `randomize` de-syncs the herd so a waiter isn't
     // perpetually colliding on the same tick. `stale` stays modest because proper-
     // lockfile auto-refreshes a live holder's lock, so it only expires when a
     // process actually dies.
-    return lockfile.lock(lockTargetDir, {
-        lockfilePath: path.join(lockTargetDir, lockName),
-        retries: { retries: 600, factor: 1, minTimeout: 300, maxTimeout: 800, randomize: true },
-        stale: 30_000,
-    });
+    const release = await lockfile.lock(lockPath, provisioningLockOptions(lockPath, { retries: 600, factor: 1, minTimeout: 300, maxTimeout: 800, randomize: true }, onCompromised));
+    return releaseIgnoringAlreadyReleased(release, lockPath);
 }
 /**
  * Zero-retry variant of {@link acquireProvisioningLock}, for admin actions
@@ -49,12 +132,9 @@ export async function acquireProvisioningLock(lockTargetDir, lockName) {
  * Throws with `err.code === 'ELOCKED'` on contention (a live, non-stale
  * holder) -- callers should translate that into a 409.
  */
-export async function tryAcquireProvisioningLock(lockTargetDir, lockName) {
+export async function tryAcquireProvisioningLock(lockTargetDir, lockName, onCompromised) {
     await fs.mkdir(lockTargetDir, { recursive: true });
-    return lockfile.lock(lockTargetDir, {
-        lockfilePath: path.join(lockTargetDir, lockName),
-        retries: 0,
-        stale: 30_000,
-    });
+    const lockPath = path.join(lockTargetDir, lockName);
+    const release = await lockfile.lock(lockPath, provisioningLockOptions(lockPath, 0, onCompromised));
+    return releaseIgnoringAlreadyReleased(release, lockPath);
 }
-//# sourceMappingURL=provisioning-lock.js.map

package/dist/utils/sanitize-href.d.ts

@@ -7,7 +7,7 @@
  * equivalent to forward slash for special schemes, so `/\evil.com`, `\\evil.com` and `\/evil.com`
  * are all protocol-relative in effect despite declaring no scheme). Exported so every "is this
  * URL off-site" check in the package shares one answer instead of re-deriving it -- see
- * `isImplicitlyOffOrigin` below and `static/seo.ts`'s `isAbsoluteUrl`.
+ * `isImplicitlyOffOrigin` below and `utils/url-prefix.ts`'s `isAbsoluteUrl`.
  */
 export declare function declaresScheme(url: string): boolean;
 /**
@@ -22,7 +22,7 @@ export declare function declaresScheme(url: string): boolean;
  * (`declaresScheme` already identifies those as intentionally off-site on their own).
  *
  * Callers that want to treat a LITERAL `//host` as an intentionally-supported off-site pointer
- * (e.g. `static/seo.ts`'s `isAbsoluteUrl`, for a CDN-hosted `ogImage`) should check that
+ * (e.g. `utils/url-prefix.ts`'s `isAbsoluteUrl`, for a CDN-hosted `ogImage`) should check that
  * separately and only fall back to this function to catch the spellings that slip past a
  * `startsWith('//')` check.
  */
@@ -87,4 +87,3 @@ export declare function neutralizeImplicitOffOrigin(url: string): string;
  * ```
  */
 export declare function sanitizeHref(url: string, fallback?: string): string;
-//# sourceMappingURL=sanitize-href.d.ts.map

package/dist/utils/sanitize-href.js

@@ -11,7 +11,7 @@ const SENTINEL_BASE = 'https://relative.invalid';
  * equivalent to forward slash for special schemes, so `/\evil.com`, `\\evil.com` and `\/evil.com`
  * are all protocol-relative in effect despite declaring no scheme). Exported so every "is this
  * URL off-site" check in the package shares one answer instead of re-deriving it -- see
- * `isImplicitlyOffOrigin` below and `static/seo.ts`'s `isAbsoluteUrl`.
+ * `isImplicitlyOffOrigin` below and `utils/url-prefix.ts`'s `isAbsoluteUrl`.
  */
 export function declaresScheme(url) {
     return /^[a-z][a-z0-9+.-]*:/i.test(url.trim());
@@ -28,7 +28,7 @@ export function declaresScheme(url) {
  * (`declaresScheme` already identifies those as intentionally off-site on their own).
  *
  * Callers that want to treat a LITERAL `//host` as an intentionally-supported off-site pointer
- * (e.g. `static/seo.ts`'s `isAbsoluteUrl`, for a CDN-hosted `ogImage`) should check that
+ * (e.g. `utils/url-prefix.ts`'s `isAbsoluteUrl`, for a CDN-hosted `ogImage`) should check that
  * separately and only fall back to this function to catch the spellings that slip past a
  * `startsWith('//')` check.
  */
@@ -146,4 +146,3 @@ export function sanitizeHref(url, fallback = '#') {
     }
     return fallback;
 }
-//# sourceMappingURL=sanitize-href.js.map

package/dist/utils/title-field.d.ts

@@ -1,4 +1,4 @@
-import type { FieldConfig } from '../config';
+import type { FieldConfig } from '../config/index.js';
 /**
  * Find the field marked `isTitle: true` in a schema and extract its value from data.
  * Recurses into object fields to support nested title fields (e.g., hero.title).
@@ -37,4 +37,3 @@ export declare function findInvalidTitleFields(fields: readonly FieldConfig[], p
  * Returns dotted paths of such fields.
  */
 export declare function findTitleFieldsInLists(fields: readonly FieldConfig[], parentPath?: string): string[];
-//# sourceMappingURL=title-field.d.ts.map

package/dist/utils/title-field.js

@@ -154,4 +154,3 @@ function collectAllTitleFields(fields, parentPath) {
     }
     return found;
 }
-//# sourceMappingURL=title-field.js.map

package/dist/utils/typed-filename.d.ts

@@ -0,0 +1,61 @@
+import type { EntryTypeConfig } from '../config/index.js';
+import type { ContentId, Slug } from '../paths/types.js';
+/**
+ * Parse a Canopy content filename into its `{type}.{slug}.{id}.{ext}` parts.
+ *
+ * ## Filename grammar
+ *
+ * Every entry file on disk is named `{type}.{slug}.{id}.{ext}`:
+ * - `type` — the entry type name (a key in the collection's `entries` config).
+ * - `slug` — the entry's URL slug. May itself contain dots (e.g. a slug of
+ *   `getting.started.guide`), so the type and ID anchor the split: the ID is
+ *   always the second-to-last dot-separated segment, and the slug is
+ *   everything between the type and the ID. The returned `slug` is
+ *   lowercased.
+ * - `id` — a 12-character Base58 content ID (`generateId()`/`isValidId()`).
+ *   Base58 excludes the ambiguous characters `0`, `O`, `I`, `l` so IDs are
+ *   unambiguous when read aloud or hand-transcribed. A filename whose
+ *   would-be ID segment doesn't pass `isValidId` is rejected — the whole
+ *   parse returns `null`, even if the rest of the shape looks right.
+ * - `ext` — the format extension (`.md`, `.mdx`, `.json`, `.yaml`), stripped
+ *   before parsing and not part of the returned result.
+ *
+ * @param filename - The bare filename (no directory component). **This precondition is
+ *   not enforced.** The parser splits purely on `.`, so a `/` or `\` you pass in is not
+ *   rejected and is not treated as special — it becomes part of whichever segment it
+ *   falls in, most often the `type` segment (e.g. `'foo/bar.slug.<validId>.md'` parses
+ *   to `type: 'foo/bar'`). Strip any directory component yourself (e.g.
+ *   `path.basename(filePath)`) before calling this — every internal caller already does.
+ * @param entryTypes - When provided, the parsed `type` segment must match one
+ *   of these entry types by name, or the parse is rejected (this is how
+ *   `listCollectionEntries` filters out files that don't belong to the
+ *   collection's configured entry types). Omit this argument to parse
+ *   structurally without validating the type against a known list — useful
+ *   for adopter code that needs to recover `{type, slug, id}` from a
+ *   filename without having a schema/entry-types list on hand (e.g. a
+ *   filesystem walk over content for tooling or diagnostics). Even without
+ *   `entryTypes`, a leading-dot filename (dotfile, editor swap/backup file)
+ *   is always rejected — an empty string is never a legal type, matching the
+ *   `filename.startsWith('.')` guard `extractEntryTypeFromFilename` in
+ *   `content-id-index.ts` already applies.
+ * @returns `{ type, slug, id }`, or `null` if `filename` doesn't match the
+ *   `{type}.{slug}.{id}.{ext}` shape (too few segments, no extension, a
+ *   leading dot, an invalid ID, or — when `entryTypes` is given — an
+ *   unrecognized type). `id` is validated (`isValidId`) and safe to trust. **`slug` is
+ *   not** — it is the raw dot-joined middle segment(s), lowercased, cast to the branded
+ *   `Slug` type without running `parseSlug`'s validation. A filename with an
+ *   unconventional slug segment (e.g. containing a space, or a dot) still parses and still
+ *   receives the `Slug` brand. Callers that need a validated slug must run the result
+ *   through `parseSlug` themselves; this function's contract is "split the filename
+ *   grammar apart," not "validate every part." `listCollectionEntries` (content-listing.ts)
+ *   is exactly such a caller that does NOT re-validate — it lists the file and computes a
+ *   `urlPath` for it regardless — so a dotted slug listed this way builds and gets
+ *   advertised (sitemap, `generateStaticParams`) but can never be read back through
+ *   `readByUrlPath`, which does run every URL-resolution candidate through `parseSlug`.
+ *   `static/index.ts`'s `assertRoutableSlugs` is the build-time guard that catches this.
+ */
+export declare const parseTypedFilename: (filename: string, entryTypes?: readonly EntryTypeConfig[]) => {
+    type: string;
+    slug: Slug;
+    id: ContentId;
+} | null;

package/dist/utils/typed-filename.js

@@ -0,0 +1,92 @@
+import { isValidId } from '../id.js';
+// Lives here rather than in content-listing.ts, where it was born, purely so dependency-light
+// modules can use it: content-listing imports ContentStore, so anything content-store itself
+// imports (url-collision.ts) cannot reach back into it without a cycle. content-listing
+// re-exports this and `canopycms/server` re-exports it from there, so the public surface is
+// unchanged.
+/**
+ * Parse a Canopy content filename into its `{type}.{slug}.{id}.{ext}` parts.
+ *
+ * ## Filename grammar
+ *
+ * Every entry file on disk is named `{type}.{slug}.{id}.{ext}`:
+ * - `type` — the entry type name (a key in the collection's `entries` config).
+ * - `slug` — the entry's URL slug. May itself contain dots (e.g. a slug of
+ *   `getting.started.guide`), so the type and ID anchor the split: the ID is
+ *   always the second-to-last dot-separated segment, and the slug is
+ *   everything between the type and the ID. The returned `slug` is
+ *   lowercased.
+ * - `id` — a 12-character Base58 content ID (`generateId()`/`isValidId()`).
+ *   Base58 excludes the ambiguous characters `0`, `O`, `I`, `l` so IDs are
+ *   unambiguous when read aloud or hand-transcribed. A filename whose
+ *   would-be ID segment doesn't pass `isValidId` is rejected — the whole
+ *   parse returns `null`, even if the rest of the shape looks right.
+ * - `ext` — the format extension (`.md`, `.mdx`, `.json`, `.yaml`), stripped
+ *   before parsing and not part of the returned result.
+ *
+ * @param filename - The bare filename (no directory component). **This precondition is
+ *   not enforced.** The parser splits purely on `.`, so a `/` or `\` you pass in is not
+ *   rejected and is not treated as special — it becomes part of whichever segment it
+ *   falls in, most often the `type` segment (e.g. `'foo/bar.slug.<validId>.md'` parses
+ *   to `type: 'foo/bar'`). Strip any directory component yourself (e.g.
+ *   `path.basename(filePath)`) before calling this — every internal caller already does.
+ * @param entryTypes - When provided, the parsed `type` segment must match one
+ *   of these entry types by name, or the parse is rejected (this is how
+ *   `listCollectionEntries` filters out files that don't belong to the
+ *   collection's configured entry types). Omit this argument to parse
+ *   structurally without validating the type against a known list — useful
+ *   for adopter code that needs to recover `{type, slug, id}` from a
+ *   filename without having a schema/entry-types list on hand (e.g. a
+ *   filesystem walk over content for tooling or diagnostics). Even without
+ *   `entryTypes`, a leading-dot filename (dotfile, editor swap/backup file)
+ *   is always rejected — an empty string is never a legal type, matching the
+ *   `filename.startsWith('.')` guard `extractEntryTypeFromFilename` in
+ *   `content-id-index.ts` already applies.
+ * @returns `{ type, slug, id }`, or `null` if `filename` doesn't match the
+ *   `{type}.{slug}.{id}.{ext}` shape (too few segments, no extension, a
+ *   leading dot, an invalid ID, or — when `entryTypes` is given — an
+ *   unrecognized type). `id` is validated (`isValidId`) and safe to trust. **`slug` is
+ *   not** — it is the raw dot-joined middle segment(s), lowercased, cast to the branded
+ *   `Slug` type without running `parseSlug`'s validation. A filename with an
+ *   unconventional slug segment (e.g. containing a space, or a dot) still parses and still
+ *   receives the `Slug` brand. Callers that need a validated slug must run the result
+ *   through `parseSlug` themselves; this function's contract is "split the filename
+ *   grammar apart," not "validate every part." `listCollectionEntries` (content-listing.ts)
+ *   is exactly such a caller that does NOT re-validate — it lists the file and computes a
+ *   `urlPath` for it regardless — so a dotted slug listed this way builds and gets
+ *   advertised (sitemap, `generateStaticParams`) but can never be read back through
+ *   `readByUrlPath`, which does run every URL-resolution candidate through `parseSlug`.
+ *   `static/index.ts`'s `assertRoutableSlugs` is the build-time guard that catches this.
+ */
+export const parseTypedFilename = (filename, entryTypes) => {
+    // Reject dotfiles outright (matching extractEntryTypeFromFilename's guard in
+    // content-id-index.ts): a leading dot can never be a legal entry type, and this
+    // is exactly the shape of the files a structural (no-entryTypes) parse would
+    // otherwise misparse -- e.g. '.hidden.file.aB3cD4eF5gH6.md' -> potentialType ''.
+    if (filename.startsWith('.'))
+        return null;
+    // Remove extension
+    const lastDot = filename.lastIndexOf('.');
+    if (lastDot === -1)
+        return null;
+    const nameWithoutExt = filename.slice(0, lastDot);
+    // Parse: {type}.{slug}.{id}
+    const parts = nameWithoutExt.split('.');
+    if (parts.length < 3)
+        return null;
+    const potentialType = parts[0];
+    // When a known-types list is supplied, the first segment must match one of
+    // them. Without it, any non-empty first segment is accepted as the type.
+    if (entryTypes && !entryTypes.some((e) => e.name === potentialType)) {
+        return null;
+    }
+    const id = parts[parts.length - 1];
+    if (!isValidId(id))
+        return null;
+    const slug = parts.slice(1, -1).join('.').toLowerCase();
+    return {
+        type: potentialType,
+        slug: slug,
+        id: id,
+    };
+};