canopycms 0.12.0 → 0.12.1

package/dist/api/types.d.ts

@@ -58,7 +58,8 @@ export interface ApiResponse<TData = unknown> {
  * `WRITE_OUTCOME_UNKNOWN`: an entry save ran but lost its branch lock mid-write, so it may have
  * landed (a 409); the version the caller holds may be stale, so it must re-read before retrying.
  * `ENTRY_GONE`: an entry update found no file, because the entry was deleted or moved since the
- * caller read it (a 409); it was not saved, and only a create can bring the entry back.
+ * caller read it (a 409); it was not saved, and only a create can bring the entry back. A
+ * resolve-entry answers it too, for an entry no longer where its conflict was shown.
  * `EDITOR_MODE_MISMATCH`: the editor bundle was built for the other operating mode than the
  * server runs (a 412, see operating-mode/editor-mode-check.ts); only a rebuild fixes it.
  * `SETTINGS_CHANGED`: a groups or permissions save named a version the file has moved on from (a
@@ -66,6 +67,9 @@ export interface ApiResponse<TData = unknown> {
  * The other settings 409, a busy file lock, carries no code. `BRANCH_SYNCING`: an entry save was
  * refused because the branch is mid-rebase (a 409); nothing was saved, and a retry soon can pass.
  * `BRANCH_NAME_REFUSED`: a branch create was refused for the name it gave (a 400 or 409), so only
- * another name can pass; no other create failure carries it.
+ * another name can pass; no other create failure carries it. `OPEN_CONFLICTS`: a submit or approval
+ * was refused while a merge's conflicts are open on the branch (a 409, merge-conflicts.ts).
+ * `CONFLICT_CHANGED`: a resolve-entry named a conflict the record no longer holds as shown (a 409);
+ * re-read the branch's conflicts.
  */
-export type ApiErrorCode = 'SCHEMA_UNAVAILABLE' | 'WORKER_FAILED' | 'WRITE_OUTCOME_UNKNOWN' | 'ENTRY_GONE' | 'EDITOR_MODE_MISMATCH' | 'SETTINGS_CHANGED' | 'BRANCH_SYNCING' | 'BRANCH_NAME_REFUSED';
+export type ApiErrorCode = 'SCHEMA_UNAVAILABLE' | 'WORKER_FAILED' | 'WRITE_OUTCOME_UNKNOWN' | 'ENTRY_GONE' | 'EDITOR_MODE_MISMATCH' | 'SETTINGS_CHANGED' | 'BRANCH_SYNCING' | 'BRANCH_NAME_REFUSED' | 'OPEN_CONFLICTS' | 'CONFLICT_CHANGED';

package/dist/base-update.d.ts

@@ -0,0 +1,26 @@
+import type { BranchMetadata } from './types.js';
+/**
+ * Asking for the latest changes: the API records the request on branch.json and queues this action
+ * (api/branch-update-from-base.ts), the worker's sync answers it in `lastBaseUpdate`
+ * (worker/rebase.ts), and the editor waits while it stands. Dependency-free, so all three share it.
+ */
+export declare const SYNC_BRANCH_ACTION = "sync-branch";
+/**
+ * How long a request, or an answer that didn't fail, stands for the next request on the branch,
+ * which joins it instead (api/branch-update-from-base.ts).
+ */
+export declare const BASE_UPDATE_REQUEST_INTERVAL_MS = 30000;
+/** How long the editor waits on a request, polling for its answer. */
+export declare const BASE_UPDATE_GIVE_UP_MS: number;
+/**
+ * How long the worker asks itself for early cycles while a request goes unanswered; its regular
+ * cycles answer it after that. Each cycle reads every branch in review from GitHub, so it is short.
+ */
+export declare const BASE_UPDATE_EARLY_RETRY_MS: number;
+/**
+ * How far in the future a request time may lie and still count: the Lambdas' clocks keep NTP time,
+ * so a later one is corrupt and is never waited on.
+ */
+export declare const BASE_UPDATE_CLOCK_SKEW_MS = 60000;
+/** Whether the branch's latest request for the latest changes is still unanswered. */
+export declare function isBaseUpdatePending(branch: Pick<BranchMetadata, 'baseUpdateRequestedAt' | 'lastBaseUpdate'>): boolean;

package/dist/base-update.js

@@ -0,0 +1,31 @@
+/**
+ * Asking for the latest changes: the API records the request on branch.json and queues this action
+ * (api/branch-update-from-base.ts), the worker's sync answers it in `lastBaseUpdate`
+ * (worker/rebase.ts), and the editor waits while it stands. Dependency-free, so all three share it.
+ */
+export const SYNC_BRANCH_ACTION = 'sync-branch';
+/**
+ * How long a request, or an answer that didn't fail, stands for the next request on the branch,
+ * which joins it instead (api/branch-update-from-base.ts).
+ */
+export const BASE_UPDATE_REQUEST_INTERVAL_MS = 30_000;
+/** How long the editor waits on a request, polling for its answer. */
+export const BASE_UPDATE_GIVE_UP_MS = 10 * 60_000;
+/**
+ * How long the worker asks itself for early cycles while a request goes unanswered; its regular
+ * cycles answer it after that. Each cycle reads every branch in review from GitHub, so it is short.
+ */
+export const BASE_UPDATE_EARLY_RETRY_MS = 2 * 60_000;
+/**
+ * How far in the future a request time may lie and still count: the Lambdas' clocks keep NTP time,
+ * so a later one is corrupt and is never waited on.
+ */
+export const BASE_UPDATE_CLOCK_SKEW_MS = 60_000;
+/** Whether the branch's latest request for the latest changes is still unanswered. */
+export function isBaseUpdatePending(branch) {
+    const requestedAt = branch.baseUpdateRequestedAt;
+    if (requestedAt === undefined)
+        return false;
+    const answeredAt = branch.lastBaseUpdate?.at;
+    return answeredAt === undefined || Date.parse(answeredAt) < Date.parse(requestedAt);
+}

package/dist/branch-metadata-file.d.ts

@@ -136,6 +136,23 @@ export declare const branchMetadataSchema: z.ZodObject<{
             name?: string | undefined;
         };
     }>>>;
+    baseUpdateRequestedAt: z.ZodCatch<z.ZodOptional<z.ZodString>>;
+    lastBaseUpdate: z.ZodCatch<z.ZodOptional<z.ZodObject<{
+        at: z.ZodString;
+        outcome: z.ZodEnum<["merged", "up-to-date", "conflicts", "failed"]>;
+        baseSha: z.ZodOptional<z.ZodString>;
+        keptEntries: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        at: string;
+        outcome: "merged" | "conflicts" | "up-to-date" | "failed";
+        baseSha?: string | undefined;
+        keptEntries?: number | undefined;
+    }, {
+        at: string;
+        outcome: "merged" | "conflicts" | "up-to-date" | "failed";
+        baseSha?: string | undefined;
+        keptEntries?: number | undefined;
+    }>>>;
 }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
     name: z.ZodString;
     title: z.ZodOptional<z.ZodString>;
@@ -252,6 +269,23 @@ export declare const branchMetadataSchema: z.ZodObject<{
             name?: string | undefined;
         };
     }>>>;
+    baseUpdateRequestedAt: z.ZodCatch<z.ZodOptional<z.ZodString>>;
+    lastBaseUpdate: z.ZodCatch<z.ZodOptional<z.ZodObject<{
+        at: z.ZodString;
+        outcome: z.ZodEnum<["merged", "up-to-date", "conflicts", "failed"]>;
+        baseSha: z.ZodOptional<z.ZodString>;
+        keptEntries: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        at: string;
+        outcome: "merged" | "conflicts" | "up-to-date" | "failed";
+        baseSha?: string | undefined;
+        keptEntries?: number | undefined;
+    }, {
+        at: string;
+        outcome: "merged" | "conflicts" | "up-to-date" | "failed";
+        baseSha?: string | undefined;
+        keptEntries?: number | undefined;
+    }>>>;
 }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
     name: z.ZodString;
     title: z.ZodOptional<z.ZodString>;
@@ -368,6 +402,23 @@ export declare const branchMetadataSchema: z.ZodObject<{
             name?: string | undefined;
         };
     }>>>;
+    baseUpdateRequestedAt: z.ZodCatch<z.ZodOptional<z.ZodString>>;
+    lastBaseUpdate: z.ZodCatch<z.ZodOptional<z.ZodObject<{
+        at: z.ZodString;
+        outcome: z.ZodEnum<["merged", "up-to-date", "conflicts", "failed"]>;
+        baseSha: z.ZodOptional<z.ZodString>;
+        keptEntries: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        at: string;
+        outcome: "merged" | "conflicts" | "up-to-date" | "failed";
+        baseSha?: string | undefined;
+        keptEntries?: number | undefined;
+    }, {
+        at: string;
+        outcome: "merged" | "conflicts" | "up-to-date" | "failed";
+        baseSha?: string | undefined;
+        keptEntries?: number | undefined;
+    }>>>;
 }, z.ZodTypeAny, "passthrough">>;
 /**
  * Read, parse and validate `branch.json`, with no locking, no OCC and no side

package/dist/branch-metadata-file.js

@@ -108,6 +108,17 @@ const branchMetadataShape = {
     })
         .optional()
         .catch(undefined),
+    baseUpdateRequestedAt: z.string().optional().catch(undefined),
+    // Dropped when malformed: it only ends the editor's wait, which then times out instead.
+    lastBaseUpdate: z
+        .object({
+        at: z.string(),
+        outcome: z.enum(['merged', 'up-to-date', 'conflicts', 'failed']),
+        baseSha: z.string().optional(),
+        keptEntries: z.number().int().nonnegative().optional(),
+    })
+        .optional()
+        .catch(undefined),
 };
 /** The `branch` object, also embedded in the registry snapshot (branch-registry.ts). */
 export const branchMetadataSchema = z.object(branchMetadataShape).passthrough();

package/dist/branch-schema-cache.d.ts

@@ -2,6 +2,11 @@ import type { RootCollectionConfig } from './config/index.js';
 import type { FlatSchemaItem } from './config/types.js';
 import type { OperatingMode } from './operating-mode/index.js';
 import type { EntrySchemaRegistry, SchemaIssue, SchemaResolutionResult, UnknownSchemaPolicy } from './schema/types.js';
+/**
+ * Bump when BranchSchemaCacheEntry shape changes to auto-invalidate stale caches.
+ * @internal Exported for tests.
+ */
+export declare const SCHEMA_CACHE_VERSION = 4;
 /** File name of the schema cache inside {@link schemaCacheDir}. */
 export declare const SCHEMA_CACHE_FILE = "schema-cache.json";
 /** resource-generation.ts resource key for the schema cache's marker. */
@@ -32,6 +37,13 @@ export interface ResolvedBranchSchema {
     flatSchema: FlatSchemaItem[];
     issues: SchemaIssue[];
 }
+/**
+ * The entry types and collections of a branch's last persisted schema snapshot, for a reader with
+ * no entry schema registry to resolve one: the worker's merge, which names conflicts by them.
+ * Undefined when there is no snapshot of this version. Its freshness is not checked, so it can lag
+ * the tree.
+ */
+export declare function readSchemaSnapshot(branchRoot: string): Promise<readonly FlatSchemaItem[] | undefined>;
 /**
  * Per-branch schema cache: one file in {@link schemaCacheDir}, the only state
  * shared across processes. Each process keeps the entries it parsed or wrote,

package/dist/branch-schema-cache.js

@@ -10,8 +10,11 @@ import { bumpResourceGeneration, readResourceGeneration, isGenerationCurrent, }
 import { timeRequestPhase } from './utils/request-timing.js';
 import { CANOPY_META_DIR } from './utils/git.js';
 import { canopyLogWarn } from './utils/logger.js';
-/** Bump when BranchSchemaCacheEntry shape changes to auto-invalidate stale caches */
-const SCHEMA_CACHE_VERSION = 4;
+/**
+ * Bump when BranchSchemaCacheEntry shape changes to auto-invalidate stale caches.
+ * @internal Exported for tests.
+ */
+export const SCHEMA_CACHE_VERSION = 4;
 /** Minimum interval between mtime staleness checks (ms) */
 const MTIME_CHECK_DEBOUNCE_MS = 1000;
 /** Cap on the parsed snapshots one process keeps, counted in bytes of their files. */
@@ -89,6 +92,28 @@ async function schemaCacheDir(branchRoot) {
     const isClone = await fs.stat(gitDir).then((stat) => stat.isDirectory(), () => false);
     return isClone ? path.join(gitDir, 'canopycms') : path.join(branchRoot, CANOPY_META_DIR);
 }
+/**
+ * The entry types and collections of a branch's last persisted schema snapshot, for a reader with
+ * no entry schema registry to resolve one: the worker's merge, which names conflicts by them.
+ * Undefined when there is no snapshot of this version. Its freshness is not checked, so it can lag
+ * the tree.
+ */
+export async function readSchemaSnapshot(branchRoot) {
+    try {
+        const cachePath = path.join(await schemaCacheDir(branchRoot), SCHEMA_CACHE_FILE);
+        const entry = JSON.parse(await fs.readFile(cachePath, 'utf-8'));
+        if (typeof entry !== 'object' || entry === null)
+            return undefined;
+        if (!('version' in entry) || entry.version !== SCHEMA_CACHE_VERSION)
+            return undefined;
+        if (!('flatSchema' in entry) || !Array.isArray(entry.flatSchema))
+            return undefined;
+        return entry.flatSchema;
+    }
+    catch {
+        return undefined;
+    }
+}
 /**
  * Per-branch schema cache: one file in {@link schemaCacheDir}, the only state
  * shared across processes. Each process keeps the entries it parsed or wrote,

package/dist/cli/backfill-item-keys.d.ts

@@ -0,0 +1,77 @@
+/**
+ * CLI command: npx canopycms backfill-item-keys [--check] [--force] [--app-dir <dir>]
+ *
+ * Writes the `_key` of every object-list item and block (`item-keys.ts`) into the site's content,
+ * so an editor's first save of an entry adds no key lines and a merge sees only real edits.
+ *
+ * Each entry goes through the editor's own save path, with nothing re-derived:
+ * `ContentStore.read` keys the items exactly as the editor's form holds them, and
+ * `ContentStore.write` writes that data back with the read's version, through the serialiser,
+ * content-write lock and version check a save uses, after the content API's own
+ * `entryDataAsSaved`. So a written file is byte for byte what an editor save of the unedited entry
+ * leaves, a second run finds every item keyed and writes nothing, and the next editor save adds no
+ * lines of its own, a CRLF markdown file aside (safeinsights/canopycms#1234).
+ *
+ * A file is written only when its items lack keys. The write then also carries whatever else an
+ * unedited save normalises (a one-line JSON file comes out pretty-printed, a stray frontmatter key
+ * named as the body goes), and those files are listed apart for review. Out of scope, as for the editor: list fields the schema does not
+ * describe, `.collection.json`, and entries of a type this code's registry lacks.
+ */
+import type { FlatSchemaItem } from '../config/index.js';
+/** One entry file the backfill keys. */
+interface BackfillFileResult {
+    /** Path relative to the project root. */
+    path: string;
+    /** Items and blocks whose file text gives them no usable key, or one an earlier item holds. */
+    itemsKeyed: number;
+    /** Lines the write changes besides adding `_key` lines: what else an unedited save normalises. */
+    otherLines: number;
+}
+interface BackfillResult {
+    /** Files written, or with `check`, files a run would write; by path. */
+    changed: BackfillFileResult[];
+    /** Entries that could not be read or written, and collections that could not be listed. */
+    failed: {
+        path: string;
+        error: string;
+    }[];
+    /** Entries left alone because the registry has no schema for their entry type. */
+    unavailable: string[];
+    /** Files in a collection that look like entries but whose names don't parse as one. */
+    malformed: string[];
+}
+interface BackfillOptions {
+    /** The project root: the directory holding the content root. */
+    root: string;
+    flatSchema: FlatSchemaItem[];
+    contentRootName: string;
+    /** Report what a run would write, and write nothing. */
+    check: boolean;
+}
+/**
+ * Keys every entry's items under `root`, or with `check`, reports which files a run would write.
+ * @internal Exported for tests.
+ */
+export declare function backfillItemKeys(options: BackfillOptions): Promise<BackfillResult>;
+export interface BackfillItemKeysCLIOptions {
+    projectDir: string;
+    /** Directory holding `schemas.ts`, relative to the project. Default `app`. */
+    appDir?: string;
+    check?: boolean;
+    /** Write even when the content tree has uncommitted changes. */
+    force?: boolean;
+}
+/**
+ * Exit codes. `--check`: 0 when no file needs keys, 1 when some would change. A run: 0 when done,
+ * 1 when it would not write: uncommitted content changes, or no git to ask. Both: 2 when the
+ * site's config or schema could not be loaded, a collection listed, or an entry read or written.
+ * @internal Exported for tests.
+ */
+export declare const BACKFILL_EXIT_CODES: {
+    readonly ok: 0;
+    readonly changesOrRefused: 1;
+    readonly loadError: 2;
+};
+/** Runs the command and returns its exit code. */
+export declare function backfillItemKeysCLI(options: BackfillItemKeysCLIOptions): Promise<number>;
+export {};

package/dist/cli/backfill-item-keys.js

@@ -0,0 +1,320 @@
+/**
+ * CLI command: npx canopycms backfill-item-keys [--check] [--force] [--app-dir <dir>]
+ *
+ * Writes the `_key` of every object-list item and block (`item-keys.ts`) into the site's content,
+ * so an editor's first save of an entry adds no key lines and a merge sees only real edits.
+ *
+ * Each entry goes through the editor's own save path, with nothing re-derived:
+ * `ContentStore.read` keys the items exactly as the editor's form holds them, and
+ * `ContentStore.write` writes that data back with the read's version, through the serialiser,
+ * content-write lock and version check a save uses, after the content API's own
+ * `entryDataAsSaved`. So a written file is byte for byte what an editor save of the unedited entry
+ * leaves, a second run finds every item keyed and writes nothing, and the next editor save adds no
+ * lines of its own, a CRLF markdown file aside (safeinsights/canopycms#1234).
+ *
+ * A file is written only when its items lack keys. The write then also carries whatever else an
+ * unedited save normalises (a one-line JSON file comes out pretty-printed, a stray frontmatter key
+ * named as the body goes), and those files are listed apart for review. Out of scope, as for the editor: list fields the schema does not
+ * describe, `.collection.json`, and entries of a type this code's registry lacks.
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { diffArrays } from 'diff';
+import { simpleGit } from 'simple-git';
+import { flattenSchema } from '../config/index.js';
+import { contentIndexGenerationPath } from '../content-index-generation.js';
+import { listCollectionEntries, parseEntryParts, } from '../content-listing.js';
+import { entryDataAsSaved } from '../api/content.js';
+import { ContentStore } from '../content-store.js';
+import { ITEM_KEY, withItemKeys } from '../item-keys.js';
+import { isValidSchema, resolveSchema } from '../schema/index.js';
+import { serializeEntry } from '../utils/content-serialize.js';
+import { getErrorMessage, isNodeError } from '../utils/error.js';
+import { filePathExists } from '../utils/fs.js';
+import { CANOPY_META_DIR } from '../utils/git.js';
+import { isPlainRecord } from '../validation/field-traversal.js';
+import { importSiteEntrySchemaRegistry, importSiteServerConfig } from './site-config.js';
+/**
+ * Keys every entry's items under `root`, or with `check`, reports which files a run would write.
+ * @internal Exported for tests.
+ */
+export async function backfillItemKeys(options) {
+    const { root, flatSchema, contentRootName, check } = options;
+    const store = new ContentStore(root, flatSchema, { contentRootName });
+    const result = { changed: [], failed: [], unavailable: [], malformed: [] };
+    const collections = flatSchema.filter((item) => item.type === 'collection' && !!item.entries);
+    for (const collection of collections) {
+        const entryTypes = collection.entries ?? [];
+        let listed;
+        try {
+            listed = await listCollectionEntries(root, collection, (file) => result.malformed.push(path.posix.join(file.collectionPath, file.filename)));
+        }
+        catch (err) {
+            result.failed.push({ path: `${collection.logicalPath}/`, error: getErrorMessage(err) });
+            continue;
+        }
+        for (const item of listed) {
+            const entryType = entryTypes.find((type) => type.name === item.entryType);
+            if (!entryType || entryType.unavailable) {
+                result.unavailable.push(item.physicalPath);
+                continue;
+            }
+            try {
+                const changed = await backfillEntry(store, root, item, entryType.schema, check);
+                if (changed)
+                    result.changed.push({ path: item.physicalPath, ...changed });
+            }
+            catch (err) {
+                result.failed.push({ path: item.physicalPath, error: getErrorMessage(err) });
+            }
+        }
+    }
+    const byPath = (a, b) => a.path.localeCompare(b.path);
+    result.changed.sort(byPath);
+    result.failed.sort(byPath);
+    result.unavailable.sort();
+    result.malformed.sort();
+    return result;
+}
+/** The entry's counts when its items lack keys, after writing it unless `check`; else null. */
+async function backfillEntry(store, root, item, fields, check) {
+    const doc = await store.read(item.collectionPath, item.slug, { resolveReferences: false });
+    // The store finds a slug's file by name alone, so a slug another file in the collection also
+    // carries (another entry type's, or a stray copy) addresses only one of them.
+    if (doc.absolutePath !== path.resolve(root, item.physicalPath)) {
+        throw new Error(`Another file in its collection has the slug "${item.slug}", so neither a save nor the ` +
+            'backfill can address this one. Rename or remove one of them.');
+    }
+    // After the read: its version was taken before its own read of the file, so a change landing
+    // between the two fails the write's version check rather than writing over it.
+    const before = await fs.readFile(doc.absolutePath, 'utf8');
+    const asWritten = parseEntryParts(before, doc.format).data;
+    const keyed = withItemKeys(fields, asWritten, 'content');
+    if (keyed === asWritten)
+        return null;
+    const entry = savedEntry(doc, fields);
+    let after;
+    if (check) {
+        after = serializeEntry(entry, before, fields);
+    }
+    else {
+        if (doc.version === undefined)
+            throw new Error('The read carried no version to write against.');
+        await store.write(item.collectionPath, item.slug, { ...entry, expectedVersion: doc.version }, item.entryType);
+        after = await fs.readFile(doc.absolutePath, 'utf8');
+    }
+    return {
+        itemsKeyed: countAddedKeys(keyed, asWritten),
+        otherLines: countOtherLines(before, after),
+    };
+}
+/** What a save of the entry, opened and saved unedited, hands the serialiser. */
+function savedEntry(doc, fields) {
+    const data = entryDataAsSaved(fields, doc.format, doc.data);
+    if (doc.format === 'json')
+        return { format: 'json', data };
+    if (doc.format === 'yaml')
+        return { format: 'yaml', data };
+    return { format: doc.format, data, body: doc.body };
+}
+/**
+ * The `_key`s `keyed` holds that `asWritten` lacks or holds differently. `withItemKeys` returns
+ * every subtree it left alone as the same object, so the walk skips those.
+ */
+function countAddedKeys(keyed, asWritten) {
+    if (keyed === asWritten)
+        return 0;
+    if (Array.isArray(keyed)) {
+        const was = Array.isArray(asWritten) ? asWritten : [];
+        return keyed.reduce((n, value, i) => n + countAddedKeys(value, was[i]), 0);
+    }
+    if (!isPlainRecord(keyed))
+        return 0;
+    const was = isPlainRecord(asWritten) ? asWritten : {};
+    let count = ITEM_KEY in keyed && keyed[ITEM_KEY] !== was[ITEM_KEY] ? 1 : 0;
+    for (const [name, value] of Object.entries(keyed)) {
+        if (name !== ITEM_KEY)
+            count += countAddedKeys(value, was[name]);
+    }
+    return count;
+}
+/** A `_key` line as YAML (frontmatter included) or JSON spells it, its trailing comma trimmed. */
+function isKeyLine(line) {
+    const text = line.trim().replace(/^-\s/, '').trimStart();
+    for (const name of ['_key:', '"_key":']) {
+        if (text.startsWith(name))
+            return /^\s*\S+$/.test(text.slice(name.length));
+    }
+    return false;
+}
+/**
+ * Lines changed between `before` and `after` other than added `_key` lines, a changed line ending
+ * included. A trailing comma is ignored, since a JSON key appended to an object adds one to the
+ * line above it.
+ */
+function countOtherLines(before, after) {
+    const lines = (text) => text.split('\n').map((line) => line.replace(/,(\r?)$/, '$1'));
+    let other = 0;
+    for (const change of diffArrays(lines(before), lines(after))) {
+        if (change.removed)
+            other += change.value.length;
+        else if (change.added)
+            other += change.value.filter((line) => !isKeyLine(line)).length;
+    }
+    return other;
+}
+/**
+ * Exit codes. `--check`: 0 when no file needs keys, 1 when some would change. A run: 0 when done,
+ * 1 when it would not write: uncommitted content changes, or no git to ask. Both: 2 when the
+ * site's config or schema could not be loaded, a collection listed, or an entry read or written.
+ * @internal Exported for tests.
+ */
+export const BACKFILL_EXIT_CODES = { ok: 0, changesOrRefused: 1, loadError: 2 };
+/** Runs the command and returns its exit code. */
+export async function backfillItemKeysCLI(options) {
+    const { projectDir, appDir = 'app', check = false, force = false } = options;
+    console.log('\nCanopyCMS backfill-item-keys\n');
+    let contentRootName;
+    let registry;
+    try {
+        const { server } = await importSiteServerConfig(projectDir);
+        const contentRoot = isPlainRecord(server) ? (server.contentRoot ?? 'content') : null;
+        if (typeof contentRoot !== 'string') {
+            throw new Error('canopycms.config.ts does not export a config made by defineCanopyConfig().');
+        }
+        contentRootName = contentRoot;
+        registry = (await importSiteEntrySchemaRegistry(projectDir, appDir)).registry;
+    }
+    catch (err) {
+        console.error(`Could not load the site: ${getErrorMessage(err)}`);
+        return BACKFILL_EXIT_CODES.loadError;
+    }
+    let flatSchema;
+    try {
+        const contentDir = path.join(projectDir, contentRootName);
+        const resolved = await resolveSchema(contentDir, registry, {
+            unknownSchema: 'degrade',
+        });
+        if (!isValidSchema(resolved.schema)) {
+            throw new Error(`No .collection.json files describe ${contentRootName}/.`);
+        }
+        for (const issue of resolved.issues)
+            console.warn(`  Warning: ${issue.message}`);
+        flatSchema = flattenSchema(resolved.schema, contentRootName);
+    }
+    catch (err) {
+        console.error(`Could not load the schema: ${getErrorMessage(err)}`);
+        return BACKFILL_EXIT_CODES.loadError;
+    }
+    if (!check && !force) {
+        const refusal = await uncommittedContent(projectDir, contentRootName);
+        if (refusal) {
+            console.error(refusal);
+            return BACKFILL_EXIT_CODES.changesOrRefused;
+        }
+    }
+    const metaDir = path.join(projectDir, CANOPY_META_DIR);
+    const metaDirExisted = await filePathExists(metaDir);
+    let result;
+    try {
+        result = await backfillItemKeys({ root: projectDir, flatSchema, contentRootName, check });
+    }
+    catch (err) {
+        console.error(`Could not finish: ${getErrorMessage(err)}` +
+            (check ? '' : '\nFiles keyed before the error stay written; finish with --force.'));
+        return BACKFILL_EXIT_CODES.loadError;
+    }
+    finally {
+        // The marker tells other processes to rebuild their ID index, and the backfill moves no file,
+        // so no index goes stale. An adopter's .gitignore need not cover `.canopy-meta/`, so at a
+        // project root that had none, remove what this run created there.
+        if (!check && !metaDirExisted)
+            await removeOwnMetaDir(projectDir, metaDir);
+    }
+    printResult(result, check);
+    if (result.failed.length > 0)
+        return BACKFILL_EXIT_CODES.loadError;
+    if (check && result.changed.length > 0)
+        return BACKFILL_EXIT_CODES.changesOrRefused;
+    return BACKFILL_EXIT_CODES.ok;
+}
+/** Why a run must not write: the content tree has uncommitted changes, or no git to ask. */
+async function uncommittedContent(projectDir, contentRootName) {
+    let status;
+    try {
+        status = await simpleGit({ baseDir: projectDir }).raw([
+            'status',
+            '--porcelain',
+            '--untracked-files=all',
+            '--',
+            contentRootName,
+        ]);
+    }
+    catch (err) {
+        return (`Could not ask git whether ${contentRootName}/ has uncommitted changes ` +
+            `(${getErrorMessage(err)}). Run inside the site's git checkout, or pass --force.`);
+    }
+    const dirty = status.split('\n').filter((line) => line.trim() !== '');
+    if (dirty.length === 0)
+        return null;
+    const shown = dirty.slice(0, 10).map((line) => `    ${line}`);
+    if (dirty.length > shown.length)
+        shown.push(`    … and ${dirty.length - shown.length} more`);
+    return (`${contentRootName}/ has uncommitted changes, so the backfill's own changes could not be ` +
+        `reviewed apart from them:\n${shown.join('\n')}\n` +
+        'Commit or stash them first, or pass --force.');
+}
+async function removeOwnMetaDir(projectDir, metaDir) {
+    try {
+        await fs.rm(contentIndexGenerationPath(projectDir), { force: true });
+        await fs.rmdir(metaDir);
+    }
+    catch (err) {
+        if (isNodeError(err) && err.code === 'ENOENT')
+            return;
+        console.warn(`  Left ${CANOPY_META_DIR}/ in place: ${getErrorMessage(err)}`);
+    }
+}
+function printResult(result, check) {
+    const plural = (n, word, words = `${word}s`) => `${n} ${n === 1 ? word : words}`;
+    const keysOnly = result.changed.filter((file) => file.otherLines === 0);
+    const normalised = result.changed.filter((file) => file.otherLines > 0);
+    const verb = check ? 'Would key' : 'Keyed';
+    if (keysOnly.length > 0) {
+        console.log(`  ${verb} items in ${plural(keysOnly.length, 'file')}, adding only _key lines:`);
+        for (const file of keysOnly)
+            console.log(`    ${file.path}  ${plural(file.itemsKeyed, 'item')}`);
+    }
+    if (normalised.length > 0) {
+        console.log(`\n  ${verb} items in ${plural(normalised.length, 'file')} that an unedited save also ` +
+            'normalises in other lines. Review these before committing:');
+        for (const file of normalised) {
+            console.log(`    ${file.path}  ${plural(file.itemsKeyed, 'item')}, ` +
+                `${plural(file.otherLines, 'other line')}`);
+        }
+    }
+    if (result.unavailable.length > 0) {
+        console.warn(`\n  Skipped ${plural(result.unavailable.length, 'entry', 'entries')} whose entry type the schema ` +
+            'registry does not have.');
+    }
+    if (result.malformed.length > 0) {
+        console.warn(`\n  Skipped ${plural(result.malformed.length, 'file')} that look like entries but whose ` +
+            `names don't parse:\n${result.malformed.map((file) => `    ${file}`).join('\n')}`);
+    }
+    if (result.failed.length > 0) {
+        console.error(`\n  Could not ${check ? 'check' : 'key'}:`);
+        for (const file of result.failed)
+            console.error(`    ${file.path}: ${file.error}`);
+    }
+    const skippedAny = result.failed.length + result.unavailable.length + result.malformed.length > 0;
+    if (result.changed.length === 0) {
+        console.log(`  Every ${skippedAny ? 'other ' : ''}entry's items already have their keys.`);
+    }
+    else if (check) {
+        console.log(`\n  Run \`canopycms backfill-item-keys\` to write them.`);
+    }
+    else {
+        console.log('\n  Commit these changes on their own, so the commit holds nothing else.');
+    }
+    console.log('');
+}

package/dist/cli/cli.d.ts

@@ -4,7 +4,7 @@
  *
  * Routes commands to their implementations:
  *   init, init-deploy, init-github-app, worker, generate-ai-content, collect-asset-refs,
- *   materialize-assets, sync, migrate
+ *   materialize-assets, sync, migrate, backfill-item-keys
  *
  * Command implementations live in separate files (init.ts, sync.ts, etc.)
  * and are dynamically imported to keep startup fast.