canopycms 0.0.68-int.98 → 0.1.0

package/dist/settings-workspace.js

@@ -1,8 +1,11 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { GitManager } from './git-manager.js';
+import { removeLeftoverDir, settingsStagingDirName, settingsTrashDirName, } from './branch-provisioning.js';
 import { createDebugLogger } from './utils/debug.js';
-import { getErrorMessage } from './utils/error.js';
+import { getErrorMessage, isNodeError } from './utils/error.js';
+import { canopyLogWarn } from './utils/logger.js';
+import { ProvisionLog } from './utils/provision-log.js';
 import { acquireProvisioningLock } from './utils/provisioning-lock.js';
 import { RESERVED_SETTINGS_BRANCH_PREFIX } from './paths/index.js';
 const log = createDebugLogger({ prefix: 'SettingsWorkspace' });
@@ -30,13 +33,27 @@ const ensuredSettingsWorkspaces = new Set();
 function ensuredKey(options) {
     return `${path.resolve(options.settingsRoot)}\0${options.branchName}`;
 }
+async function headBranch(settingsRoot) {
+    try {
+        const head = (await fs.readFile(path.join(settingsRoot, '.git', 'HEAD'), 'utf-8')).trim();
+        return head.startsWith('ref: refs/heads/') ? head.slice('ref: refs/heads/'.length) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 async function checkedOutOn(settingsRoot, branchName) {
+    return (await headBranch(settingsRoot)) === branchName;
+}
+async function hasLocalBranch(settingsRoot, branchName) {
+    const gitDir = path.join(settingsRoot, '.git');
     try {
-        const head = await fs.readFile(path.join(settingsRoot, '.git', 'HEAD'), 'utf-8');
-        return head.trim() === `ref: refs/heads/${branchName}`;
+        await fs.access(path.join(gitDir, 'refs', 'heads', branchName));
+        return true;
     }
     catch {
-        return false;
+        const packed = await fs.readFile(path.join(gitDir, 'packed-refs'), 'utf-8').catch(() => '');
+        return packed.split('\n').some((line) => line.endsWith(` refs/heads/${branchName}`));
     }
 }
 const SETTINGS_INIT_LOCK_DIR = '.settings-init';
@@ -49,8 +66,8 @@ const SETTINGS_INIT_LOCK_NAME = 'lock';
  * its target, and `GitManager.initializeWorkspace` clones INTO the settings
  * root, which `git clone` refuses if anything is already there. A dedicated
  * dot-directory also keeps this marker out of `path.dirname(settingsRoot)`,
- * where `ensureLocalSimulatedRemote` puts `.remote-init.lock` — settings init
- * calls into that while holding this lock, so separate directories make the
+ * where `ensureLocalSimulatedRemote` puts `.remote-init.lock` — an in-place
+ * settings re-init calls into that while holding this lock, so separate directories make the
  * nesting obvious rather than incidental. For how a lock's anchor path is
  * chosen, see utils/provisioning-lock.ts and docs/concurrency.md.
  * @internal Exported for tests.
@@ -78,6 +95,41 @@ async function settingsFilesPresent(settingsRoot) {
     }
     return false;
 }
+/**
+ * What occupies the settings root.
+ *
+ * `interrupted` is a first init that died before its settings branch existed: not on this
+ * deployment's settings branch or any `canopycms-settings-*` one, no local ref for it, and no
+ * settings files -- what the rename guard lets through, minus a local settings branch that could
+ * hold unpushed commits. A clone killed in place leaves this behind, often with a stale
+ * `config.lock` that fails every later git config write.
+ */
+async function settingsRootState(options) {
+    let entries;
+    try {
+        entries = await fs.readdir(options.settingsRoot);
+    }
+    catch (err) {
+        if (isNodeError(err) && err.code === 'ENOENT')
+            return 'vacant';
+        if (isNodeError(err) && err.code === 'ENOTDIR')
+            return 'interrupted';
+        throw err;
+    }
+    if (entries.length === 0)
+        return 'vacant';
+    if (await settingsFilesPresent(options.settingsRoot))
+        return 'in-use';
+    if (!(await GitManager.repoExistsAt(options.settingsRoot)))
+        return 'interrupted';
+    const head = await headBranch(options.settingsRoot);
+    if (head === options.branchName || head?.startsWith(RESERVED_SETTINGS_BRANCH_PREFIX)) {
+        return 'in-use';
+    }
+    if (await hasLocalBranch(options.settingsRoot, options.branchName))
+        return 'in-use';
+    return 'interrupted';
+}
 /**
  * Rename guard (settings-branch protection): refuse to boot when an
  * ALREADY-POPULATED settings workspace would be re-orphaned under a different
@@ -144,9 +196,14 @@ async function assertSettingsWorkspaceIdentity(options) {
  * BranchWorkspaceManager this writes no metadata files and never touches the
  * branch registry.
  *
+ * A first clone follows [PROV-1] (branch-provisioning.ts): it is built in a
+ * staging sibling and renamed into place, so a process killed mid-clone never
+ * leaves a half-made workspace at the settings root. Never sparse: the orphan
+ * init's `git rm -rf .` would leave out-of-cone base files in the tree.
+ *
  * Two locking layers, mirroring BranchWorkspaceManager: an in-memory promise
  * lock within the process, and `acquireProvisioningLock` (proper-lockfile)
- * across processes and hosts.
+ * across processes and hosts around the publish and every in-place init.
  */
 export class SettingsWorkspaceManager {
     constructor(config) {
@@ -178,45 +235,11 @@ export class SettingsWorkspaceManager {
                     // Running it here also means no path reaches initializeWorkspace
                     // without the guard having run in THIS process.
                     await assertSettingsWorkspaceIdentity(options);
-                    // Layer 2: cross-process/cross-host lock around the init itself
-                    // (proper-lockfile: heartbeat-refreshed while the holder lives, so a
-                    // slow EFS clone is not mistaken for a crash, and patient retries so a
-                    // loser WAITS instead of racing into a concurrent clone).
-                    const releaseLock = await acquireProvisioningLock(settingsInitLockTarget(options.settingsRoot), SETTINGS_INIT_LOCK_NAME);
-                    try {
-                        // Re-run the guard on the now-stable state: a previous holder may
-                        // have created the workspace, or moved it onto its own settings
-                        // branch, after we sampled it above, and acting on that stale
-                        // sample is the destructive path the guard exists to stop. Not
-                        // gated on any "did I win the race" flag — by design there is none;
-                        // every process here either holds the lock or has already thrown.
-                        await assertSettingsWorkspaceIdentity(options);
-                        // initializeWorkspace is idempotent (it checks for .git), so this
-                        // is safe even if another process just finished init.
-                        await GitManager.initializeWorkspace({
-                            workspacePath: options.settingsRoot,
-                            branchName: options.branchName,
-                            mode: options.mode,
-                            baseBranch: this.config.defaultBaseBranch,
-                            sourceRoot: this.config.sourceRoot,
-                            defaultRemoteUrl: this.config.defaultRemoteUrl,
-                            remoteUrl: options.remoteUrl,
-                            remoteName: this.config.defaultRemoteName,
-                            allowNetworkRemoteInProd: this.config.allowNetworkRemoteInProd,
-                            branchType: 'orphan', // Key difference: orphan branch for settings
-                            gitBotAuthorName: this.config.gitBotAuthorName,
-                            gitBotAuthorEmail: this.config.gitBotAuthorEmail,
-                        });
-                        ensuredSettingsWorkspaces.add(key);
-                    }
-                    finally {
-                        try {
-                            await releaseLock();
-                        }
-                        catch (err) {
-                            log.debug('workspace', 'Failed to release settings-init lock', { err });
-                        }
+                    if ((await settingsRootState(options)) !== 'in-use' ||
+                        !(await this.ensureInPlace(options))) {
+                        await this.provisionStaged(options);
                     }
+                    ensuredSettingsWorkspaces.add(key);
                 }
                 finally {
                     settingsInitLock = null;
@@ -225,4 +248,95 @@ export class SettingsWorkspaceManager {
             await settingsInitLock;
         });
     }
+    initOptions(options, workspacePath) {
+        return {
+            workspacePath,
+            branchName: options.branchName,
+            mode: options.mode,
+            baseBranch: this.config.defaultBaseBranch,
+            sourceRoot: this.config.sourceRoot,
+            defaultRemoteUrl: this.config.defaultRemoteUrl,
+            remoteUrl: options.remoteUrl,
+            remoteName: this.config.defaultRemoteName,
+            allowNetworkRemoteInProd: this.config.allowNetworkRemoteInProd,
+            branchType: 'orphan',
+            gitBotAuthorName: this.config.gitBotAuthorName,
+            gitBotAuthorEmail: this.config.gitBotAuthorEmail,
+        };
+    }
+    /**
+     * Layer 2 around the init itself (proper-lockfile: heartbeat-refreshed while the holder lives,
+     * so a slow EFS operation is not mistaken for a crash, and patient retries so a loser WAITS
+     * instead of racing into a concurrent init).
+     */
+    async withInitLock(options, run) {
+        const releaseLock = await acquireProvisioningLock(settingsInitLockTarget(options.settingsRoot), SETTINGS_INIT_LOCK_NAME);
+        try {
+            // Re-run the guard on the now-stable state: a previous holder may
+            // have created the workspace, or moved it onto its own settings
+            // branch, after we sampled it above, and acting on that stale
+            // sample is the destructive path the guard exists to stop. Not
+            // gated on any "did I win the race" flag — by design there is none;
+            // every process here either holds the lock or has already thrown.
+            await assertSettingsWorkspaceIdentity(options);
+            return await run();
+        }
+        finally {
+            try {
+                await releaseLock();
+            }
+            catch (err) {
+                log.debug('workspace', 'Failed to release settings-init lock', { err });
+            }
+        }
+    }
+    /** Re-init an existing workspace where it is; false when, under the lock, there is none. */
+    async ensureInPlace(options) {
+        return this.withInitLock(options, async () => {
+            if ((await settingsRootState(options)) !== 'in-use')
+                return false;
+            await GitManager.initializeWorkspace(this.initOptions(options, options.settingsRoot));
+            return true;
+        });
+    }
+    /**
+     * Clone and set up the settings branch in a staging sibling, then publish it under the init
+     * lock, moving an interrupted first init aside to `.trash-settings-*`. A workspace someone
+     * else published meanwhile wins and the staging copy is dropped.
+     */
+    async provisionStaged(options) {
+        const settingsRoot = path.resolve(options.settingsRoot);
+        const workspaceRoot = path.dirname(settingsRoot);
+        await fs.mkdir(workspaceRoot, { recursive: true });
+        const stagingPath = path.join(workspaceRoot, settingsStagingDirName());
+        const provisionLog = new ProvisionLog('settings');
+        let published = false;
+        try {
+            await GitManager.initializeWorkspace({
+                ...this.initOptions(options, stagingPath),
+                provisionLog,
+            });
+            published = await provisionLog.step('publish', () => this.withInitLock(options, async () => {
+                const state = await settingsRootState(options);
+                if (state === 'in-use')
+                    return false;
+                if (state === 'interrupted') {
+                    const trashName = settingsTrashDirName();
+                    await fs.rename(settingsRoot, path.join(workspaceRoot, trashName));
+                    canopyLogWarn(`[canopy] Moved an unfinished settings workspace clone aside as ${trashName}`);
+                }
+                await fs.rename(stagingPath, settingsRoot);
+                return true;
+            }));
+        }
+        catch (err) {
+            provisionLog.finish('error');
+            throw err;
+        }
+        finally {
+            if (!published)
+                await removeLeftoverDir(stagingPath);
+        }
+        provisionLog.finish(published ? 'ok' : 'exists');
+    }
 }

package/dist/stamp-on-publish.d.ts

@@ -0,0 +1,36 @@
+import type { FlatSchemaItem } from './config/index.js';
+import type { ContentStore } from './content-store.js';
+import type { GitManager } from './git-manager.js';
+import type { ContentId } from './paths/types.js';
+/**
+ * One entry a submit stamped: the editor moves its loaded value, draft and OCC token from
+ * `previousVersion` onto `version` with these fields set, instead of finding its next save refused.
+ */
+export interface StampedEntry {
+    contentId: ContentId;
+    /** Stamp field name to the value written. */
+    fields: Record<string, string>;
+    /** The file's version (`read()`'s mtime) before the stamp. */
+    previousVersion: number;
+    /** The file's version after the stamp. */
+    version: number;
+}
+/**
+ * Fill every empty stamp field of every entry the base lacks with `stampedAt`, never
+ * overwriting a value, and return the entries written. Lists the base only when the schema has
+ * a stamp field, and reads only the entry files the base lacks. Rejects when the base cannot be
+ * fetched or listed; a single entry that cannot be written is reported through `warn` and
+ * skipped.
+ *
+ * The caller holds the branch's content-write lock, as `store.fillEmptyFieldWhileHoldingWriteLock`
+ * requires.
+ */
+export declare function stampNewEntries(options: {
+    git: Pick<GitManager, 'listBaseFiles'>;
+    store: ContentStore;
+    branchRoot: string;
+    flatSchema: readonly FlatSchemaItem[];
+    contentRoot: string;
+    stampedAt: string;
+    warn: (message: string) => void;
+}): Promise<StampedEntry[]>;

package/dist/stamp-on-publish.js

@@ -0,0 +1,71 @@
+/**
+ * `stampOnPublish` (config/types.ts): at submit, each entry new to the base branch gets the
+ * submit's time in its empty stamp fields. Canopy never merges and never writes the base branch,
+ * and adopters build from the merged tree, so its own submit is the last point it can put the
+ * date into the content. An entry counts as new when neither the base tip nor the fork point
+ * holds a file with its ContentId, so a renamed or moved entry, which keeps its ID, is never
+ * stamped.
+ */
+import path from 'node:path';
+import { listCollectionEntries } from './content-listing.js';
+import { getErrorMessage } from './utils/error.js';
+import { flattenGroupFields } from './utils/flatten-group-fields.js';
+import { parseTypedFilename } from './utils/typed-filename.js';
+/** The names of `schema`'s top-level fields that carry `stampOnPublish`. */
+const stampFieldNames = (schema) => flattenGroupFields(schema)
+    .filter((f) => f.type === 'datetime' && 'stampOnPublish' in f && f.stampOnPublish === true)
+    .map((f) => f.name);
+const isEmpty = (value) => value === undefined || value === null || value === '';
+/** `contentRoot` as a repo-relative directory, or undefined when it is the repository root. */
+const contentRootDir = (contentRoot) => contentRoot
+    .split('/')
+    .filter((segment) => segment && segment !== '.')
+    .join('/') || undefined;
+/**
+ * Fill every empty stamp field of every entry the base lacks with `stampedAt`, never
+ * overwriting a value, and return the entries written. Lists the base only when the schema has
+ * a stamp field, and reads only the entry files the base lacks. Rejects when the base cannot be
+ * fetched or listed; a single entry that cannot be written is reported through `warn` and
+ * skipped.
+ *
+ * The caller holds the branch's content-write lock, as `store.fillEmptyFieldWhileHoldingWriteLock`
+ * requires.
+ */
+export async function stampNewEntries(options) {
+    const collections = options.flatSchema.filter((item) => item.type === 'collection' &&
+        (item.entries ?? []).some((entryType) => stampFieldNames(entryType.schema).length > 0));
+    if (collections.length === 0)
+        return [];
+    const baseIds = new Set();
+    for (const file of await options.git.listBaseFiles(contentRootDir(options.contentRoot))) {
+        const id = parseTypedFilename(path.posix.basename(file))?.id;
+        if (id)
+            baseIds.add(id);
+    }
+    const stamped = [];
+    for (const collection of collections) {
+        const entries = await listCollectionEntries(options.branchRoot, collection, undefined, (id) => !baseIds.has(id));
+        for (const entry of entries) {
+            const schema = collection.entries?.find((e) => e.name === entry.entryType)?.schema ?? [];
+            const empty = stampFieldNames(schema).filter((name) => isEmpty(entry.data[name]));
+            let written;
+            for (const field of empty) {
+                try {
+                    const versions = await options.store.fillEmptyFieldWhileHoldingWriteLock(entry.physicalPath, entry.format, field, options.stampedAt);
+                    if (!versions)
+                        continue;
+                    written ??= { contentId: entry.contentId, fields: {}, ...versions };
+                    written.fields[field] = options.stampedAt;
+                    written.version = versions.version;
+                }
+                catch (err) {
+                    options.warn(`CanopyCMS: Could not stamp "${field}" on ${entry.physicalPath}; it is submitted ` +
+                        `without it: ${getErrorMessage(err)}`);
+                }
+            }
+            if (written)
+                stamped.push(written);
+        }
+    }
+    return stamped;
+}

package/dist/static/index.d.ts

@@ -1,3 +1,4 @@
+import type { MdxAllowlist } from '../config/index.js';
 import type { CanopyBuildContext } from '../context.js';
 import type { ListEntriesItem } from '../content-listing.js';
 import { type EntryFieldError } from '../validation/entry-validator.js';
@@ -81,6 +82,11 @@ export interface CollectRoutableEntriesOptions<T = Record<string, unknown>> {
      */
     resolveReferences?: boolean;
 }
+/**
+ * What the enumeration helpers take: a listing, plus the services whose config sets
+ * `danglingReferences`. A context without `services` gets the default, `'error'`.
+ */
+type StaticBuildContext = Pick<CanopyBuildContext, 'listEntries'> & Partial<Pick<CanopyBuildContext, 'services'>>;
 /**
  * Enumerate routable content entries WITH their data — the input to any surface that must read
  * inside an entry to decide what to publish (sitemap, RSS, search index, index grids).
@@ -101,7 +107,7 @@ export interface CollectRoutableEntriesOptions<T = Record<string, unknown>> {
  * const entries = await collectRoutableEntries(await getCanopyForBuild())
  * const published = entries.filter((e) => !isNoindexEntry(e.data))
  */
-export declare function collectRoutableEntries<T = Record<string, unknown>>(ctx: Pick<CanopyBuildContext, 'listEntries'>, options?: CollectRoutableEntriesOptions<T>): Promise<RoutableEntry<T>[]>;
+export declare function collectRoutableEntries<T = Record<string, unknown>>(ctx: StaticBuildContext, options?: CollectRoutableEntriesOptions<T>): Promise<RoutableEntry<T>[]>;
 /**
  * Enumerate routable content entries as neutral path descriptors for static generation.
  *
@@ -115,7 +121,7 @@ export declare function collectRoutableEntries<T = Record<string, unknown>>(ctx:
  * // Single [slug] scoped to one collection:
  * const posts = await collectStaticPaths(await getCanopyForBuild(), { rootPath: 'content/posts' })
  */
-export declare function collectStaticPaths(ctx: Pick<CanopyBuildContext, 'listEntries'>, options?: CollectStaticPathsOptions): Promise<StaticPathEntry[]>;
+export declare function collectStaticPaths(ctx: StaticBuildContext, options?: CollectStaticPathsOptions): Promise<StaticPathEntry[]>;
 /**
  * One schema-invalid entry found during a build-time content scan.
  */
@@ -132,9 +138,10 @@ export interface InvalidBuildEntry {
 type BuildScanItem = Pick<ListEntriesItem, 'entryPath' | 'schema'> & {
     data: unknown;
     /**
-     * Only the unknown-key scan reads this, to recognise the md/mdx body key that `listEntries`
-     * merges into `data`. Optional so a caller assembling items by hand still typechecks; an
-     * absent format is treated as markdown-shaped, which errs toward under-reporting.
+     * The unknown-key and unsafe-markdown scans read this, to recognise the md/mdx body key that
+     * `listEntries` merges into `data`. Optional so a caller assembling items by hand still typechecks; an
+     * absent format errs toward under-reporting: the unknown-key scan treats it as markdown-shaped,
+     * and the unsafe-markdown scan checks no body.
      */
     format?: ListEntriesItem['format'];
 };
@@ -181,6 +188,19 @@ export declare function findEntriesWithUnknownKeys(items: readonly BuildScanItem
  * value at a time.
  */
 export declare function warnUnknownEntryKeys(items: readonly BuildScanItem[], phaseLabel: string): void;
+/** An entry holding code in a markdown or MDX field that is not `executable`. */
+export interface EntryWithUnsafeMarkdown {
+    entryPath: string;
+    fieldPaths: string[];
+}
+/**
+ * Scan listEntries-shaped items for markdown and MDX that runs code where the field is not
+ * `executable`. A save keeps such code only in a field saved unchanged, so the build is where it
+ * is listed. Non-fatal, like the unknown-key scan.
+ */
+export declare function findEntriesWithUnsafeMarkdown(items: readonly BuildScanItem[], siteAllow?: MdxAllowlist): EntryWithUnsafeMarkdown[];
+/** Warn — never throw — about entries holding markdown or MDX that a save of a changed field refuses. */
+export declare function warnUnsafeMarkdown(items: readonly BuildScanItem[], phaseLabel: string, siteAllow?: MdxAllowlist): void;
 /**
  * Throw a single, descriptive Error if any item is schema-invalid.
  *
@@ -273,3 +293,36 @@ export declare function findUnroutableSlugs(items: readonly SlugScanItem[]): Unr
  * red build.
  */
 export declare function assertRoutableSlugs(items: readonly SlugScanItem[], phaseLabel: string): void;
+/** A reference whose id names no listed entry. */
+export interface DanglingReference {
+    /** Logical path of the referring entry. */
+    entryPath: string;
+    /** Field path in `traverseFields`' format, e.g. `author`, `blocks[2].author`, `reviewers[1]`. */
+    fieldPath: string;
+    /** The id that names no entry. */
+    id: string;
+}
+/** What the dangling-reference scan needs off a listing item. */
+type ReferenceScanItem = Pick<ListEntriesItem, 'entryPath' | 'entryId' | 'schema'> & {
+    data: unknown;
+};
+/**
+ * Find every reference, at any depth (objects, lists, blocks), whose id names none of
+ * `knownIds`. `knownIds` defaults to the items' own ids, which is the whole id universe for an
+ * unscoped `listEntries()`.
+ *
+ * Reads ids through `referenceValueId`, so a listing that resolved its references scans the same
+ * as a raw one. An id naming a collection is dangling too, since it resolves to no entry.
+ * Exported for adopters to assert on directly; `assertNoDanglingReferences` is what the build
+ * uses. Sorted by entry, then field path.
+ */
+export declare function findDanglingReferences(items: readonly ReferenceScanItem[], knownIds?: ReadonlySet<string>): DanglingReference[];
+/**
+ * Fail the build (or, under `danglingReferences: 'warn'`, warn) when a reference names no entry.
+ *
+ * A dangling reference resolves to a `MissingReference`, so the page builds without whatever the
+ * reference supplied (a byline, its structured-data author) and nothing else notices. The save
+ * path refuses to introduce one, but a deleted target, a merge, a hand edit or a `sync pull`
+ * leaves one behind.
+ */
+export declare function assertNoDanglingReferences(items: readonly ReferenceScanItem[], knownIds: ReadonlySet<string>, phaseLabel: string, mode: 'error' | 'warn'): void;

package/dist/static/index.js

@@ -1,8 +1,11 @@
+import { createHash } from 'node:crypto';
 import { isBuildMode } from '../build-mode.js';
 import { findUnknownKeys, validateEntryData, } from '../validation/entry-validator.js';
 import { findBodyFieldName } from '../utils/body-field.js';
 import { isDataOnlyFormat } from '../utils/format.js';
 import { parseSlug } from '../paths/index.js';
+import { collectReferenceIds } from '../validation/field-traversal.js';
+import { findMarkdownSafetyIssues } from '../validation/markdown-safety.js';
 /**
  * Framework-agnostic helpers for static-site generation. These produce neutral data structures
  * (no Next.js types) so that any framework adapter — e.g. canopycms-next — can map them to its own
@@ -27,17 +30,20 @@ async function enumerateRoutableEntries(ctx, rootPath, phaseLabel, resolveRefere
     // an abandoned schema-invalid scaffold shipping into a static build silently drops that page's
     // route (or worse, renders broken), which is worse than a red build.
     //
-    // These four guards run in a fixed order on the RAW listing, before the caller's `filter` —
+    // These five guards run in a fixed order on the RAW listing, before the caller's `filter` —
     // `rootPath` narrows them, `filter` deliberately does not. The unknown-key warning runs first,
     // so a build about to go red still reports everything found. Slug routability runs next: an
-    // unroutable entry has no URL at all as far as the other three are concerned, the most
+    // unroutable entry has no URL at all as far as the other four are concerned, the most
     // fundamental problem a listed entry can have. Schema validity runs before duplicate URLs for
-    // the same "most fundamental first" reason, one level down.
+    // the same "most fundamental first" reason, one level down, and dangling references last: a
+    // page whose reference is broken still has its own route and data.
     if (isBuildMode()) {
         warnUnknownEntryKeys(entries, phaseLabel);
+        warnUnsafeMarkdown(entries, phaseLabel, ctx.services?.config.mdxAllow);
         assertRoutableSlugs(entries, phaseLabel);
         assertBuildEntriesValid(entries, phaseLabel);
         assertNoDuplicateUrlPaths(entries, phaseLabel);
+        assertNoDanglingReferences(entries, await knownEntryIds(ctx, entries, rootPath), phaseLabel, ctx.services?.config.danglingReferences ?? 'error');
     }
     return entries.map((entry) => ({
         urlPath: entry.urlPath,
@@ -221,6 +227,57 @@ export function warnUnknownEntryKeys(items, phaseLabel) {
         `These are usually left over from a renamed or reshaped field. Nothing reads them, and they are kept in the file on every save. ` +
         `Add them to the schema or remove them from the content.`);
 }
+/**
+ * Scan listEntries-shaped items for markdown and MDX that runs code where the field is not
+ * `executable`. A save keeps such code only in a field saved unchanged, so the build is where it
+ * is listed. Non-fatal, like the unknown-key scan.
+ */
+export function findEntriesWithUnsafeMarkdown(items, siteAllow) {
+    const found = [];
+    for (const item of items) {
+        if (!item.schema || typeof item.data !== 'object' || item.data === null)
+            continue;
+        const fieldPaths = unsafeFieldPaths(item.schema, item.format, item.data, siteAllow);
+        if (fieldPaths.length > 0)
+            found.push({ entryPath: item.entryPath, fieldPaths });
+    }
+    return found;
+}
+/**
+ * A build lists its entries several times (every catch-all route, the sitemap), and parsing each
+ * body costs milliseconds, so results are kept per schema object and hash of an entry's content.
+ */
+const unsafeFieldPathsMemo = new WeakMap();
+function unsafeFieldPaths(schema, format, data, siteAllow) {
+    let bySchema = unsafeFieldPathsMemo.get(schema);
+    if (bySchema === undefined) {
+        bySchema = new Map();
+        unsafeFieldPathsMemo.set(schema, bySchema);
+    }
+    const key = createHash('sha256')
+        .update(`${format ?? ''}\0${JSON.stringify(siteAllow ?? null)}\0${JSON.stringify(data)}`)
+        .digest('hex');
+    let fieldPaths = bySchema.get(key);
+    if (fieldPaths === undefined) {
+        fieldPaths = findMarkdownSafetyIssues(schema, format, data, siteAllow).map((f) => f.fieldPath);
+        bySchema.set(key, fieldPaths);
+    }
+    return fieldPaths;
+}
+/** Warn — never throw — about entries holding markdown or MDX that a save of a changed field refuses. */
+export function warnUnsafeMarkdown(items, phaseLabel, siteAllow) {
+    const found = findEntriesWithUnsafeMarkdown(items, siteAllow);
+    if (found.length === 0)
+        return;
+    // Capped and counted for the reason `warnUnknownEntryKeys` gives.
+    const shown = found.slice(0, UNKNOWN_KEY_REPORT_LIMIT);
+    const lines = shown.map(({ entryPath, fieldPaths }) => `  - ${entryPath} — ${fieldPaths.join(', ')}`);
+    if (found.length > shown.length) {
+        lines.push(`  …and ${found.length - shown.length} more`);
+    }
+    console.warn(`CanopyCMS static build: ${found.length} ${found.length === 1 ? 'entry holds' : 'entries hold'} markdown or MDX that runs code, or that \`mdxAllow\` excludes, during ${phaseLabel}:\n${lines.join('\n')}\n` +
+        `A save keeps it but refuses adding more. Move code into a component, allow a component or tag in \`mdxAllow\`, or set \`executable: true\` on a field whose editors you trust as code authors.`);
+}
 /**
  * Throw a single, descriptive Error if any item is schema-invalid.
  *
@@ -366,3 +423,76 @@ export function assertRoutableSlugs(items, phaseLabel) {
         'above would build, appear in generateStaticParams and any sitemap, and then 404 on every ' +
         'visit. Rename the slug (the file itself, not just its content), then rebuild.');
 }
+/**
+ * How many dangling references the warning lists before summarising the rest; the error lists
+ * every one, for the reason `warnUnknownEntryKeys` gives.
+ */
+const DANGLING_REFERENCE_REPORT_LIMIT = 20;
+/**
+ * Find every reference, at any depth (objects, lists, blocks), whose id names none of
+ * `knownIds`. `knownIds` defaults to the items' own ids, which is the whole id universe for an
+ * unscoped `listEntries()`.
+ *
+ * Reads ids through `referenceValueId`, so a listing that resolved its references scans the same
+ * as a raw one. An id naming a collection is dangling too, since it resolves to no entry.
+ * Exported for adopters to assert on directly; `assertNoDanglingReferences` is what the build
+ * uses. Sorted by entry, then field path.
+ */
+export function findDanglingReferences(items, knownIds = new Set(items.map((item) => item.entryId))) {
+    const found = [];
+    for (const item of items) {
+        if (!item.schema || typeof item.data !== 'object' || item.data === null)
+            continue;
+        const data = item.data;
+        for (const { id, path } of collectReferenceIds(item.schema, data)) {
+            if (id && !knownIds.has(id))
+                found.push({ entryPath: item.entryPath, fieldPath: path, id });
+        }
+    }
+    return found.sort((a, b) => a.entryPath.localeCompare(b.entryPath) || a.fieldPath.localeCompare(b.fieldPath));
+}
+/**
+ * Fail the build (or, under `danglingReferences: 'warn'`, warn) when a reference names no entry.
+ *
+ * A dangling reference resolves to a `MissingReference`, so the page builds without whatever the
+ * reference supplied (a byline, its structured-data author) and nothing else notices. The save
+ * path refuses to introduce one, but a deleted target, a merge, a hand edit or a `sync pull`
+ * leaves one behind.
+ */
+export function assertNoDanglingReferences(items, knownIds, phaseLabel, mode) {
+    const found = findDanglingReferences(items, knownIds);
+    if (found.length === 0)
+        return;
+    const shown = mode === 'warn' ? found.slice(0, DANGLING_REFERENCE_REPORT_LIMIT) : found;
+    const lines = shown.map(({ entryPath, fieldPath, id }) => `  - ${entryPath} — ${fieldPath} → ${id}`);
+    if (found.length > shown.length)
+        lines.push(`  …and ${found.length - shown.length} more`);
+    const message = `CanopyCMS static build: found ${found.length} ${found.length === 1 ? 'reference' : 'references'} to a missing entry during ${phaseLabel}:\n${lines.join('\n')}\n` +
+        'Each resolves as unavailable, so the page renders without what it references. Repoint or ' +
+        'clear each reference, or restore the entry it names, then rebuild.';
+    if (mode === 'warn')
+        console.warn(message);
+    else
+        throw new Error(message + " Set `danglingReferences: 'warn'` to build anyway.");
+}
+/**
+ * Every entry id a build context can resolve a reference to, computed at most once per context.
+ *
+ * Targets live anywhere in the content tree, so a `rootPath`-scoped listing is not the id
+ * universe; that case lists the whole tree once and keeps the result for the context's lifetime.
+ * Safe to keep, unlike a request-time memo, because these guards run only in build mode, which
+ * reads a checkout that does not change mid-build (`build-mode.ts`, `readsFromCheckout`). Keyed weakly on the context, so it lives
+ * exactly as long as the context does; a rejected listing is forgotten so the next call retries.
+ */
+const entryIdUniverse = new WeakMap();
+async function knownEntryIds(ctx, listed, rootPath) {
+    const cached = entryIdUniverse.get(ctx);
+    if (cached)
+        return cached;
+    const universe = rootPath === undefined
+        ? Promise.resolve(new Set(listed.map((item) => item.entryId)))
+        : ctx.listEntries().then((all) => new Set(all.map((item) => item.entryId)));
+    entryIdUniverse.set(ctx, universe);
+    universe.catch(() => entryIdUniverse.delete(ctx));
+    return universe;
+}

package/dist/static/seo.d.ts

@@ -75,12 +75,12 @@ export declare function extractSeoFields(entryData: unknown, opts?: ExtractSeoFi
  * 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`).
+ * - the page's own `robots: { index: false }` (canopycms-next's `entryToMetadata`),
+ * - exclusion from the sitemap (canopycms-next's `generateContentSitemap`), and
+ * - exclusion from AI content (`ai/generate.ts`, unless `exclude.noindex: false`).
  *
- * 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.
+ * Those surfaces shipping from one predicate is the point. Derived separately, a `noindex` entry
+ * stays advertised in one surface while correctly absent from another, and nothing warns.
  *
  * 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