canopycms 0.0.68-int.98 → 0.1.0

package/dist/item-keys.js

@@ -0,0 +1,235 @@
+import { isPlainRecord, resolveBlockItem } from './validation/field-traversal.js';
+import { formatCanopyPath, parseCanopyPath } from './editor/canopy-path.js';
+/**
+ * The key each object-list item and block carries in content, naming that item among its list's
+ * items for as long as it exists: a move or an edit keeps it, a copy gets a new one. Field comment
+ * threads name the items on their path by it (`CommentThread.itemKeys`). Beside `template` on a
+ * block, never inside its `value`; a schema may not define a field of this name.
+ *
+ * Dependency-free: the editor and the server both use this module.
+ */
+export const ITEM_KEY = '_key';
+const ITEM_KEY_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/;
+/** A usable item key: 1-64 letters, digits, `_` or `-`, starting with a letter or digit. */
+export const isItemKey = (value) => typeof value === 'string' && ITEM_KEY_PATTERN.test(value);
+const BASE58 = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz';
+/** A new random item key: 12 Base58 characters. */
+export function mintItemKey() {
+    return Array.from(crypto.getRandomValues(new Uint8Array(12)), (b) => BASE58[b % 58]).join('');
+}
+/** cyrb53: a fast, well-mixed 53-bit string hash. Not cryptographic, and needn't be. */
+function hash53(text) {
+    let h1 = 0xdeadbeef;
+    let h2 = 0x41c6ce57;
+    for (let i = 0; i < text.length; i++) {
+        const c = text.charCodeAt(i);
+        h1 = Math.imul(h1 ^ c, 2654435761);
+        h2 = Math.imul(h2 ^ c, 1597334677);
+    }
+    h1 = Math.imul(h1 ^ (h1 >>> 16), 2246822507) ^ Math.imul(h2 ^ (h2 >>> 13), 3266489909);
+    h2 = Math.imul(h2 ^ (h2 >>> 16), 2246822507) ^ Math.imul(h1 ^ (h1 >>> 13), 3266489909);
+    return 4294967296 * (2097151 & h2) + (h1 >>> 0);
+}
+/** `h` and the Base58 hash of an item as it was read, before any key was added inside it. */
+function contentKey(item) {
+    let n = hash53(JSON.stringify(item));
+    let out = '';
+    do {
+        out = BASE58[n % 58] + out;
+        n = Math.floor(n / 58);
+    } while (n > 0);
+    return `h${out}`;
+}
+const isListField = (field) => field.type === 'block' || (field.type === 'object' && !!field.list);
+/**
+ * `data` with every object-list item and block keyed, each unique in its list, nested lists
+ * included; the same object when nothing needed a key. A usable key is kept unless `fill` is
+ * `fresh`.
+ */
+export function withItemKeys(fields, data, fill) {
+    let out = data;
+    for (const field of fields) {
+        if (field.type === 'group') {
+            out = withItemKeys(field.fields, out, fill);
+            continue;
+        }
+        const value = out[field.name];
+        let next = value;
+        if (isListField(field)) {
+            if (Array.isArray(value))
+                next = keyList(field, value, fill);
+        }
+        else if (field.type === 'object' && isPlainRecord(value)) {
+            next = withItemKeys(field.fields ?? [], value, fill);
+        }
+        if (next !== value)
+            out = { ...out, [field.name]: next };
+    }
+    return out;
+}
+/** `item`, a copy about to join `field`'s list, with fresh keys for it and every item inside it. */
+export function withFreshItemKeys(field, item) {
+    return keyList(field, [item], 'fresh')[0];
+}
+function keyList(field, items, fill) {
+    const held = new Set();
+    if (fill !== 'fresh') {
+        for (const item of items) {
+            if (isPlainRecord(item) && isItemKey(item[ITEM_KEY]))
+                held.add(item[ITEM_KEY]);
+        }
+    }
+    const kept = new Set();
+    let changed = false;
+    const out = items.map((item) => {
+        if (!isPlainRecord(item))
+            return item;
+        let next = keyInside(field, item, fill);
+        const own = item[ITEM_KEY];
+        if (fill !== 'fresh' && isItemKey(own) && !kept.has(own)) {
+            kept.add(own);
+        }
+        else {
+            const key = fill === 'content' ? unheld(contentKey(item), held) : mintItemKey();
+            held.add(key);
+            kept.add(key);
+            next = { ...next, [ITEM_KEY]: key };
+        }
+        if (next !== item)
+            changed = true;
+        return next;
+    });
+    return changed ? out : items;
+}
+/** `key`, or with a suffix when another item of the list already holds it (identical items). */
+function unheld(key, held) {
+    let out = key;
+    for (let n = 2; held.has(out); n++)
+        out = `${key}-${n}`;
+    return out;
+}
+/** The item with the lists inside it keyed. */
+function keyInside(field, item, fill) {
+    if (field.type !== 'block') {
+        return withItemKeys(field.fields ?? [], item, fill);
+    }
+    const resolved = resolveBlockItem(field, item);
+    if (!resolved)
+        return item;
+    const data = withItemKeys(resolved.fields, resolved.data, fill);
+    if (data === resolved.data)
+        return item;
+    return resolved.data === item ? data : { ...item, value: data };
+}
+const findField = (fields, name) => {
+    for (const field of fields) {
+        if (field.type === 'group') {
+            const inGroup = findField(field.fields, name);
+            if (inGroup)
+                return inGroup;
+        }
+        else if (field.name === name) {
+            return field;
+        }
+    }
+    return undefined;
+};
+/**
+ * Walks `canopyPath` through `value` by schema, calling `atIndex` with each list index on the path
+ * and that list's items; it returns the index to continue with, or undefined to stop. Returns the
+ * path walked, or undefined when the walk stopped or the value has no such path.
+ */
+function walkPath(fields, value, canopyPath, atIndex) {
+    const segments = parseCanopyPath(canopyPath);
+    const out = [];
+    let scope = fields;
+    let record = value;
+    let depth = 0;
+    for (let i = 0; i < segments.length; i++) {
+        const name = segments[i];
+        if (typeof name !== 'string')
+            return undefined;
+        const field = findField(scope, name);
+        out.push(name);
+        if (!field || i === segments.length - 1) {
+            if (!field)
+                return undefined;
+            continue;
+        }
+        const node = record?.[name];
+        if (isListField(field)) {
+            const index = segments[i + 1];
+            if (typeof index !== 'number' || !Array.isArray(node))
+                return undefined;
+            const at = atIndex(index, node, depth);
+            if (at === undefined)
+                return undefined;
+            depth += 1;
+            out.push(at);
+            i += 1;
+            const item = node[at];
+            if (!isPlainRecord(item))
+                return undefined;
+            if (field.type === 'block') {
+                const resolved = resolveBlockItem(field, item);
+                if (!resolved)
+                    return undefined;
+                scope = resolved.fields;
+                record = resolved.data;
+            }
+            else {
+                scope = field.fields ?? [];
+                record = item;
+            }
+        }
+        else if (field.type === 'object') {
+            scope = field.fields ?? [];
+            record = isPlainRecord(node) ? node : undefined;
+        }
+        else {
+            return undefined;
+        }
+    }
+    return out;
+}
+/**
+ * The keys of the list items on `canopyPath` in `value`, outermost first: what a new field thread
+ * stores to name them. Undefined when an item on the path has no usable key or the path isn't
+ * there.
+ */
+export function itemKeysOnPath(fields, value, canopyPath) {
+    const keys = [];
+    const walked = walkPath(fields, value, canopyPath, (index, items) => {
+        const item = items[index];
+        const key = isPlainRecord(item) ? item[ITEM_KEY] : undefined;
+        if (!isItemKey(key))
+            return undefined;
+        keys.push(key);
+        return index;
+    });
+    return walked ? keys : undefined;
+}
+/**
+ * Where a field thread made at `canopyPath` on the items named by `itemKeys` is in `value` now:
+ * its path with each index replaced by that item's current one, or `null` when one of the items
+ * is gone. A path with no keys (one through no list) is returned as it is.
+ */
+export function resolveThreadPath(fields, value, canopyPath, itemKeys) {
+    if (!itemKeys || itemKeys.length === 0)
+        return canopyPath;
+    let missing = false;
+    const walked = walkPath(fields, value, canopyPath, (_index, items, depth) => {
+        const key = itemKeys[depth];
+        const at = items.findIndex((item) => isPlainRecord(item) && item[ITEM_KEY] === key);
+        if (key === undefined || at === -1) {
+            missing = true;
+            return undefined;
+        }
+        return at;
+    });
+    // A walk that can't reach an item, its enclosing object cleared or its block's template gone,
+    // has lost it just as surely as a removal.
+    if (missing || !walked)
+        return null;
+    return formatCanopyPath(walked);
+}

package/dist/operating-mode/editor-mode-check.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The run-time check that the editor bundle and its server agree on `mode` (see mode-env.ts).
+ * Without it, a dev bundle against a prod server fails only as a sign-in that never succeeds. The
+ * generated client sends its mode in `EDITOR_MODE_HEADER`, and the request handler refuses a
+ * mismatch with `EDITOR_MODE_MISMATCH_STATUS` before auth, naming only the editor's value (with
+ * two modes, that still tells the editor the server's). A request without the header is not
+ * checked; only the editor's client sends it. Dependency-free: it reaches the browser bundle.
+ */
+import type { OperatingMode } from './types.js';
+export declare const EDITOR_MODE_HEADER = "x-canopy-editor-mode";
+/** Not 409, which the editor reads as a save conflict to reload past. */
+export declare const EDITOR_MODE_MISMATCH_STATUS = 412;
+/** The header's value, or undefined for an absent or unrecognized one, which is not checked. */
+export declare function parseEditorModeHeader(value: string | null): OperatingMode | undefined;
+export declare function editorModeMismatchMessage(editorMode: OperatingMode): string;

package/dist/operating-mode/editor-mode-check.js

@@ -0,0 +1,24 @@
+/**
+ * The run-time check that the editor bundle and its server agree on `mode` (see mode-env.ts).
+ * Without it, a dev bundle against a prod server fails only as a sign-in that never succeeds. The
+ * generated client sends its mode in `EDITOR_MODE_HEADER`, and the request handler refuses a
+ * mismatch with `EDITOR_MODE_MISMATCH_STATUS` before auth, naming only the editor's value (with
+ * two modes, that still tells the editor the server's). A request without the header is not
+ * checked; only the editor's client sends it. Dependency-free: it reaches the browser bundle.
+ */
+export const EDITOR_MODE_HEADER = 'x-canopy-editor-mode';
+/** Not 409, which the editor reads as a save conflict to reload past. */
+export const EDITOR_MODE_MISMATCH_STATUS = 412;
+function otherOperatingMode(mode) {
+    return mode === 'prod' ? 'dev' : 'prod';
+}
+/** The header's value, or undefined for an absent or unrecognized one, which is not checked. */
+export function parseEditorModeHeader(value) {
+    return value === 'prod' || value === 'dev' ? value : undefined;
+}
+export function editorModeMismatchMessage(editorMode) {
+    const serverMode = otherOperatingMode(editorMode);
+    return (`This editor was built for "${editorMode}" mode, but the CMS server runs in "${serverMode}" ` +
+        `mode, so signing in cannot work. Whoever deploys this site needs to rebuild the editor with ` +
+        `NEXT_PUBLIC_CANOPY_MODE=${serverMode} set at build time. Reloading this page will not help.`);
+}

package/dist/operating-mode/mode-env.d.ts

@@ -8,24 +8,23 @@
  *   - `next dev` and `next build` are both `dev`. Build-time reads come from
  *     the working tree in either mode (`readsFromCheckout` in build-mode.ts),
  *     while prod would hold the image builder to checks it has no reason to
- *     meet: `gitBotAuthorName`/`gitBotAuthorEmail` (the prod strategy's
- *     `validateConfig`) and a credential-verifying auth plugin
- *     (`assertAuthPluginAllowedForMode`). See Dockerfile.cms.template.
+ *     meet: the prod strategy's `validateConfig` (`gitBotAuthorName`, `gitBotAuthorEmail`)
+ *     and `assertAuthPluginAllowedForMode`. See Dockerfile.cms.template.
  *   - The Lambda is `prod`: dev resolves the workspace to `<cwd>/.canopy-dev`,
- *     and Lambda's filesystem is read-only outside /tmp, so the first write
- *     fails with EROFS.
+ *     and Lambda's filesystem is read-only outside /tmp (EROFS).
  *
  * Two variable names, on purpose. Server code reads `CANOPY_MODE`, stamped on
- * the Lambda by `CanopyCmsService` and deliberately NOT set during
- * `next build`. Browser code has no runtime environment — the editor page
- * imports the config directly (`config.client()`), so its `mode` is whatever
- * was inlined at build time, and Next inlines only `NEXT_PUBLIC_*`. Both names
- * MUST appear as literal `process.env.X` member expressions here or the
- * bundler cannot substitute them.
+ * the Lambda by `CanopyCmsService` and NOT set during `next build`. The editor
+ * page imports the config directly, so the browser's `mode` is inlined at
+ * build, and Next inlines only `NEXT_PUBLIC_*`. Both names MUST appear as
+ * literal `process.env.X` member expressions here or the bundler cannot
+ * substitute them. The two MUST agree at run time: editor-mode-check.ts refuses
+ * editor requests where they do not. A prerendered `/edit` resolves the
+ * build's mode on the server, which is harmless: NextCanopyEditorPage's
+ * `<Suspense>` makes that prerender bail out to client rendering.
  *
- * An unrecognized value throws rather than falling back: falling back would
- * turn a typo (`CANOPY_MODE=production`) into a silent dev-mode deployment
- * running header-trusting dev auth semantics.
+ * An unrecognized value throws rather than falling back: a typo
+ * (`CANOPY_MODE=production`) would otherwise deploy dev auth semantics silently.
  */
 import type { OperatingMode } from './types.js';
 /**

package/dist/operating-mode/mode-env.js

@@ -8,24 +8,23 @@
  *   - `next dev` and `next build` are both `dev`. Build-time reads come from
  *     the working tree in either mode (`readsFromCheckout` in build-mode.ts),
  *     while prod would hold the image builder to checks it has no reason to
- *     meet: `gitBotAuthorName`/`gitBotAuthorEmail` (the prod strategy's
- *     `validateConfig`) and a credential-verifying auth plugin
- *     (`assertAuthPluginAllowedForMode`). See Dockerfile.cms.template.
+ *     meet: the prod strategy's `validateConfig` (`gitBotAuthorName`, `gitBotAuthorEmail`)
+ *     and `assertAuthPluginAllowedForMode`. See Dockerfile.cms.template.
  *   - The Lambda is `prod`: dev resolves the workspace to `<cwd>/.canopy-dev`,
- *     and Lambda's filesystem is read-only outside /tmp, so the first write
- *     fails with EROFS.
+ *     and Lambda's filesystem is read-only outside /tmp (EROFS).
  *
  * Two variable names, on purpose. Server code reads `CANOPY_MODE`, stamped on
- * the Lambda by `CanopyCmsService` and deliberately NOT set during
- * `next build`. Browser code has no runtime environment — the editor page
- * imports the config directly (`config.client()`), so its `mode` is whatever
- * was inlined at build time, and Next inlines only `NEXT_PUBLIC_*`. Both names
- * MUST appear as literal `process.env.X` member expressions here or the
- * bundler cannot substitute them.
+ * the Lambda by `CanopyCmsService` and NOT set during `next build`. The editor
+ * page imports the config directly, so the browser's `mode` is inlined at
+ * build, and Next inlines only `NEXT_PUBLIC_*`. Both names MUST appear as
+ * literal `process.env.X` member expressions here or the bundler cannot
+ * substitute them. The two MUST agree at run time: editor-mode-check.ts refuses
+ * editor requests where they do not. A prerendered `/edit` resolves the
+ * build's mode on the server, which is harmless: NextCanopyEditorPage's
+ * `<Suspense>` makes that prerender bail out to client rendering.
  *
- * An unrecognized value throws rather than falling back: falling back would
- * turn a typo (`CANOPY_MODE=production`) into a silent dev-mode deployment
- * running header-trusting dev auth semantics.
+ * An unrecognized value throws rather than falling back: a typo
+ * (`CANOPY_MODE=production`) would otherwise deploy dev auth semantics silently.
  */
 import { canopyLogWarn } from '../utils/logger.js';
 const SERVER_MODE_ENV_VAR = 'CANOPY_MODE';

package/dist/operating-mode/types.d.ts

@@ -2,7 +2,7 @@
 import type { OperatingMode as OM } from './index.js';
 import type { CanopyConfig } from '../config/index.js';
 export type OperatingMode = OM;
-/** @internal No importer; deletion candidate in knip-no-importer-deletion-candidates.md. */
+/** @internal No importer; deletion candidate in safeinsights/canopycms#725. */
 export interface ResolveRemoteUrlOptions {
     mode: OperatingMode;
     remoteUrl?: string;
@@ -47,7 +47,7 @@ export interface ClientSafeStrategy {
 export interface ClientUnsafeStrategy extends ClientSafeStrategy {
     /**
      * The mode's workspace root; content-branches, settings and .cache all live
-     * under it. prod: CANOPYCMS_WORKSPACE_ROOT ?? /mnt/efs/workspace.
+     * under it. prod: CANOPYCMS_WORKSPACE_ROOT ?? /mnt/efs.
      * dev: {sourceRoot ?? cwd}/.canopy-dev.
      */
     getWorkspaceRoot(sourceRoot?: string): string;

package/dist/paths/branch.d.ts

@@ -24,6 +24,5 @@ import { sanitizeBranchName } from './branch-name.js';
 export { sanitizeBranchName };
 /** Resolve a branch name to workspace paths, rejecting traversal and settings-branch names. */
 export declare function resolveBranchPath(options: BranchPathOptions): BranchPathResult;
-export declare function ensureBranchRoot(options: BranchPathOptions): Promise<BranchPathResult>;
 export declare function getDefaultBranchBase(mode: OperatingMode, override?: string): string;
 export declare function resolveBranchPaths(branchContext: BranchContext, mode: OperatingMode, basePathOverride?: string): BranchPathResult;

package/dist/paths/branch.js

@@ -1,5 +1,4 @@
 /** Branch path resolution utilities. */
-import fs from 'node:fs/promises';
 import path from 'node:path';
 import { operatingStrategy } from '../operating-mode/index.js';
 import { isNodeError } from '../utils/error.js';
@@ -15,8 +14,7 @@ export function namesNoWorkspace(err) {
         return true;
     return isNodeError(err) && (err.code === 'ENAMETOOLONG' || err.code === 'ENOTDIR');
 }
-// Lives in ./branch-name (dependency-free); re-exported here for server-side
-// importers, who may safely reach this module's node:fs imports.
+// Lives in ./branch-name (dependency-free); re-exported for server-side importers.
 import { sanitizeBranchName, isSettingsBranchName } from './branch-name.js';
 /** @internal Exported for tests. */
 export { sanitizeBranchName };
@@ -48,11 +46,6 @@ export function resolveBranchPath(options) {
     }
     return { branchRoot, baseRoot: normalizedBase, branchName: safeBranch };
 }
-export async function ensureBranchRoot(options) {
-    const result = resolveBranchPath(options);
-    await fs.mkdir(result.branchRoot, { recursive: true });
-    return result;
-}
 export function getDefaultBranchBase(mode, override) {
     return resolveContentBranchesRoot(mode, override);
 }

package/dist/paths/index.d.ts

@@ -7,5 +7,5 @@ export { normalizeFilesystemPath, normalizeCollectionPath, hasTraversalSequence,
 export { validateAndNormalizePath } from './normalize-server.js';
 export { validateContentPath, isValidCollectionPath, sanitizeForPath, hasEmbeddedContentId, looksLikePhysicalPath, looksLikeLogicalPath, parseLogicalPath, parsePhysicalPath, isValidContentId, parseContentId, parseBranchName, parseSlug, } from './validation.js';
 export { resolveLogicalPath } from './resolve.js';
-export { resolveBranchPath, ensureBranchRoot, getDefaultBranchBase, resolveBranchPaths, BranchPathError, namesNoWorkspace, type BranchPathOptions, type BranchPathResult, } from './branch.js';
+export { resolveBranchPath, getDefaultBranchBase, resolveBranchPaths, BranchPathError, namesNoWorkspace, type BranchPathOptions, type BranchPathResult, } from './branch.js';
 export { sanitizeBranchName, RESERVED_SETTINGS_BRANCH_PREFIX, RESERVED_ROUTE_BRANCH_NAMES, isSettingsBranchName, } from './branch-name.js';

package/dist/paths/index.js

@@ -8,5 +8,5 @@ export { normalizeFilesystemPath, normalizeCollectionPath, hasTraversalSequence,
 export { validateAndNormalizePath } from './normalize-server.js';
 export { validateContentPath, isValidCollectionPath, sanitizeForPath, hasEmbeddedContentId, looksLikePhysicalPath, looksLikeLogicalPath, parseLogicalPath, parsePhysicalPath, isValidContentId, parseContentId, parseBranchName, parseSlug, } from './validation.js';
 export { resolveLogicalPath } from './resolve.js';
-export { resolveBranchPath, ensureBranchRoot, getDefaultBranchBase, resolveBranchPaths, BranchPathError, namesNoWorkspace, } from './branch.js';
+export { resolveBranchPath, getDefaultBranchBase, resolveBranchPaths, BranchPathError, namesNoWorkspace, } from './branch.js';
 export { sanitizeBranchName, RESERVED_SETTINGS_BRANCH_PREFIX, RESERVED_ROUTE_BRANCH_NAMES, isSettingsBranchName, } from './branch-name.js';

package/dist/paths/validation.js

@@ -186,7 +186,6 @@ export function parseSlug(slug) {
             error: 'Slug is required',
         };
     }
-    // Check length (filesystem path safety)
     if (slug.length > 64) {
         return { ok: false, error: 'Slug too long (max 64 characters)' };
     }
@@ -202,7 +201,6 @@ export function parseSlug(slug) {
             error: 'Slug cannot be a traversal sequence',
         };
     }
-    // Normalize to lowercase for case-insensitive matching
     const normalized = slug.toLowerCase();
     if (!/^[a-z0-9][a-z0-9-]*$/.test(normalized)) {
         return {

package/dist/preview.d.ts

@@ -0,0 +1,8 @@
+/**
+ * What a host page needs from the preview bridge. Everything reachable from here stays free of
+ * CSS, `@mantine/*` and editor UI (`pnpm lint:bundle`): a page that imports it renders in the
+ * adopter's own styles inside the editor's preview, and ships no editor code to the public.
+ */
+export { CANOPY_PREVIEW_ERROR, CANOPY_PREVIEW_FOCUS, CANOPY_PREVIEW_HIGHLIGHT, CANOPY_PREVIEW_MESSAGE, CANOPY_PREVIEW_READY, isTrustedEditorMessage, resolveMessageOrigin, useCanopyPreview, usePreviewAssetBaseGate, usePreviewData, usePreviewFocusEmitter, usePreviewHighlight, } from './editor/preview-bridge.js';
+export type { DraftUpdateMessage, HighlightMessage, PreviewErrorMessage, PreviewFocusMessage, PreviewLoadingState, } from './editor/preview-bridge.js';
+export type { CanopyPathSegment } from './editor/canopy-path.js';

package/dist/preview.js

@@ -0,0 +1,7 @@
+'use client';
+/**
+ * What a host page needs from the preview bridge. Everything reachable from here stays free of
+ * CSS, `@mantine/*` and editor UI (`pnpm lint:bundle`): a page that imports it renders in the
+ * adopter's own styles inside the editor's preview, and ships no editor code to the public.
+ */
+export { CANOPY_PREVIEW_ERROR, CANOPY_PREVIEW_FOCUS, CANOPY_PREVIEW_HIGHLIGHT, CANOPY_PREVIEW_MESSAGE, CANOPY_PREVIEW_READY, isTrustedEditorMessage, resolveMessageOrigin, useCanopyPreview, usePreviewAssetBaseGate, usePreviewData, usePreviewFocusEmitter, usePreviewHighlight, } from './editor/preview-bridge.js';

package/dist/reference-resolver.js

@@ -54,6 +54,7 @@ export class ReferenceResolver {
                 // Only the label is read, so the candidate's own references stay unresolved.
                 const doc = await this.store.read(location.collection, normalizedSlug, {
                     resolveReferences: false,
+                    allowUnavailableEntryType: true,
                 });
                 const label = String(doc.data[displayField] || doc.data.title || normalizedSlug);
                 if (search && !label.toLowerCase().includes(search.toLowerCase())) {

package/dist/resolve-canopy-user.d.ts

@@ -3,7 +3,7 @@ import type { CanopyUser } from './user.js';
 import type { OperatingMode } from './operating-mode/index.js';
 /**
  * Test-only: reset the once-per-process "no admins configured" warning latch.
- * @internal No importer; deletion candidate in knip-no-importer-deletion-candidates.md.
+ * @internal No importer; deletion candidate in safeinsights/canopycms#725.
  */
 export declare function resetResolveCanopyUserWarningForTests(): void;
 export interface ResolveCanopyUserDeps {

package/dist/resolve-canopy-user.js

@@ -17,7 +17,7 @@ import { timeRequestPhase } from './utils/request-timing.js';
 let warnedNoAdmins = false;
 /**
  * Test-only: reset the once-per-process "no admins configured" warning latch.
- * @internal No importer; deletion candidate in knip-no-importer-deletion-candidates.md.
+ * @internal No importer; deletion candidate in safeinsights/canopycms#725.
  */
 export function resetResolveCanopyUserWarningForTests() {
     warnedNoAdmins = false;

package/dist/schema/meta-loader.d.ts

@@ -1,6 +1,6 @@
 import type { RootCollectionConfig } from '../config/index.js';
 import type { ContentId } from '../paths/types.js';
-import type { EntrySchemaRegistry } from './types.js';
+import type { EntrySchemaRegistry, SchemaIssue, UnknownSchemaPolicy } from './types.js';
 type EntryTypeMeta = {
     name: string;
     format: 'md' | 'mdx' | 'json' | 'yaml';
@@ -38,6 +38,13 @@ export declare function loadCollectionMetaFiles(contentRoot: string): Promise<{
         contentId?: ContentId;
     }>;
 }>;
+type LoadedMetaFiles = {
+    root: RootCollectionMeta | null;
+    collections: Array<CollectionMeta & {
+        path: string;
+        contentId?: ContentId;
+    }>;
+};
 /**
  * Resolve schema references for root collection and all collections.
  *
@@ -49,12 +56,15 @@ export declare function loadCollectionMetaFiles(contentRoot: string): Promise<{
  * @returns Fully resolved root collection config ready for use by CanopyCMS
  * @throws Error if any schema reference doesn't exist in registry (with helpful suggestions)
  */
-export declare function resolveCollectionReferences(metaFiles: {
-    root: RootCollectionMeta | null;
-    collections: Array<CollectionMeta & {
-        path: string;
-        contentId?: ContentId;
-    }>;
-}, entrySchemaRegistry: EntrySchemaRegistry): RootCollectionConfig;
+export declare function resolveCollectionReferences(metaFiles: LoadedMetaFiles, entrySchemaRegistry: EntrySchemaRegistry): RootCollectionConfig;
+/**
+ * {@link resolveCollectionReferences} under an explicit {@link UnknownSchemaPolicy}: 'degrade'
+ * marks an entry type naming an unregistered schema `unavailable` and reports it in `issues`
+ * instead of throwing, so the rest of the schema still resolves.
+ */
+export declare function resolveCollectionMetaFiles(metaFiles: LoadedMetaFiles, entrySchemaRegistry: EntrySchemaRegistry, policy: UnknownSchemaPolicy): {
+    schema: RootCollectionConfig;
+    issues: SchemaIssue[];
+};
 export declare function watchCollectionMetaFiles(contentRoot: string, onChange: () => void): () => void;
 export {};

package/dist/schema/meta-loader.js

@@ -154,12 +154,36 @@ export async function loadCollectionMetaFiles(contentRoot) {
     const collections = await scanForCollectionMeta(contentRoot);
     return { root, collections };
 }
-function resolveEntryTypes(entryTypes, entrySchemaRegistry, contextName) {
+function resolveEntryTypes(entryTypes, entrySchemaRegistry, contextName, location, resolution) {
     return entryTypes.map((entryType) => {
         const resolvedSchema = entrySchemaRegistry[entryType.schema];
         if (!resolvedSchema) {
-            throw new Error(`Schema reference "${entryType.schema}" in entry type "${entryType.name}" (${contextName}) not found in registry. ` +
-                `Available schemas: ${Object.keys(entrySchemaRegistry).join(', ')}`);
+            const message = `Schema reference "${entryType.schema}" in entry type "${entryType.name}" (${contextName}) not found in registry.`;
+            if (resolution.policy === 'throw') {
+                throw new Error(`${message} Available schemas: ${Object.keys(entrySchemaRegistry).join(', ')}`);
+            }
+            resolution.issues.push({
+                kind: 'unknown-schema',
+                collectionPath: location.collectionPath,
+                entryType: entryType.name,
+                schemaRef: entryType.schema,
+                metaFile: location.metaFile,
+                message,
+            });
+            return {
+                name: entryType.name,
+                label: entryType.label,
+                format: entryType.format,
+                schema: [],
+                schemaRef: entryType.schema,
+                default: entryType.default,
+                maxItems: entryType.maxItems,
+                unavailable: {
+                    reason: 'unknown-schema',
+                    schemaRef: entryType.schema,
+                    metaFile: location.metaFile,
+                },
+            };
         }
         // Note: "body" field name validation for md/mdx formats is handled by the
         // entry schema registry (isBody constraints). Not checked here because
@@ -175,9 +199,9 @@ function resolveEntryTypes(entryTypes, entrySchemaRegistry, contextName) {
         };
     });
 }
-function resolveCollectionMeta(meta, entrySchemaRegistry, allCollections) {
+function resolveCollectionMeta(meta, entrySchemaRegistry, allCollections, resolution) {
     const entries = meta.entries && meta.entries.length > 0
-        ? resolveEntryTypes(meta.entries, entrySchemaRegistry, `collection "${meta.name}"`)
+        ? resolveEntryTypes(meta.entries, entrySchemaRegistry, `collection "${meta.name}"`, { collectionPath: meta.path, metaFile: `${meta.path}/.collection.json` }, resolution)
         : undefined;
     // Find nested collections (subfolders with .collection.json)
     const nestedCollections = allCollections.filter((col) => {
@@ -185,7 +209,7 @@ function resolveCollectionMeta(meta, entrySchemaRegistry, allCollections) {
             col.path.split('/').length === meta.path.split('/').length + 1);
     });
     const collections = nestedCollections.length > 0
-        ? nestedCollections.map((nestedMeta) => resolveCollectionMeta(nestedMeta, entrySchemaRegistry, allCollections))
+        ? nestedCollections.map((nestedMeta) => resolveCollectionMeta(nestedMeta, entrySchemaRegistry, allCollections, resolution))
         : undefined;
     return {
         name: meta.name,
@@ -209,13 +233,22 @@ function resolveCollectionMeta(meta, entrySchemaRegistry, allCollections) {
  * @throws Error if any schema reference doesn't exist in registry (with helpful suggestions)
  */
 export function resolveCollectionReferences(metaFiles, entrySchemaRegistry) {
+    return resolveCollectionMetaFiles(metaFiles, entrySchemaRegistry, 'throw').schema;
+}
+/**
+ * {@link resolveCollectionReferences} under an explicit {@link UnknownSchemaPolicy}: 'degrade'
+ * marks an entry type naming an unregistered schema `unavailable` and reports it in `issues`
+ * instead of throwing, so the rest of the schema still resolves.
+ */
+export function resolveCollectionMetaFiles(metaFiles, entrySchemaRegistry, policy) {
+    const resolution = { policy, issues: [] };
     // Build result object dynamically to avoid readonly conflicts
     const result = {};
     if (metaFiles.root?.label) {
         result.label = metaFiles.root.label;
     }
     if (metaFiles.root?.entries && metaFiles.root.entries.length > 0) {
-        result.entries = resolveEntryTypes(metaFiles.root.entries, entrySchemaRegistry, 'root collection');
+        result.entries = resolveEntryTypes(metaFiles.root.entries, entrySchemaRegistry, 'root collection', { collectionPath: '', metaFile: '.collection.json' }, resolution);
     }
     if (metaFiles.root?.order) {
         result.order = metaFiles.root.order;
@@ -223,9 +256,9 @@ export function resolveCollectionReferences(metaFiles, entrySchemaRegistry) {
     // Resolve top-level collections (no slashes in path)
     const topLevelCollections = metaFiles.collections.filter((meta) => !meta.path.includes('/'));
     if (topLevelCollections.length > 0) {
-        result.collections = topLevelCollections.map((meta) => resolveCollectionMeta(meta, entrySchemaRegistry, metaFiles.collections));
+        result.collections = topLevelCollections.map((meta) => resolveCollectionMeta(meta, entrySchemaRegistry, metaFiles.collections, resolution));
     }
-    return result;
+    return { schema: result, issues: resolution.issues };
 }
 export function watchCollectionMetaFiles(contentRoot, onChange) {
     const watcher = chokidar.watch(`${contentRoot}/**/.collection.json`, {