canopycms 0.12.0 → 0.13.0

package/dist/api/routes.js

@@ -7,6 +7,7 @@
 import { BRANCH_ROUTES } from './branch.js';
 import { BRANCH_CHANGES_ROUTES } from './branch-changes.js';
 import { BRANCH_ENTRY_CHANGE_ROUTES } from './branch-entry-changes.js';
+import { MERGE_CONFLICT_ROUTES } from './merge-conflicts.js';
 import { WORKFLOW_ROUTES } from './branch-status.js';
 import { COMMENT_ROUTES } from './comments.js';
 import { CONTENT_ROUTES } from './content.js';
@@ -28,6 +29,7 @@ export function buildCanopyRoutes() {
         ...Object.values(BRANCH_ROUTES),
         ...Object.values(BRANCH_CHANGES_ROUTES),
         ...Object.values(BRANCH_ENTRY_CHANGE_ROUTES),
+        ...Object.values(MERGE_CONFLICT_ROUTES),
         ...Object.values(WORKFLOW_ROUTES),
         ...Object.values(COMMENT_ROUTES),
         ...Object.values(CONTENT_ROUTES),

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,10 @@ 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. `BRANCH_MOVED`: an approval or a request for changes named a commit
+ * other than the branch's head, or none (a 409, api/branch-review.ts); reload the branch first.
  */
-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' | 'BRANCH_MOVED';

package/dist/base-update.d.ts

@@ -0,0 +1,32 @@
+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;
+/**
+ * How a run in the request (operating-mode `baseUpdateRunsInRequest`) went: it answered the
+ * request; a lock held it back; or the branch clones from a remote other than the workspace's
+ * `remote.git`, the only one such a run fetches.
+ */
+export type BaseUpdateRun = 'answered' | 'busy' | 'other-remote';
+/** 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

@@ -83,6 +83,7 @@ export declare const branchMetadataSchema: z.ZodObject<{
         lastAt: string;
     }>>;
     historyRewrittenFrom: z.ZodOptional<z.ZodString>;
+    historyRewrittenTo: z.ZodOptional<z.ZodString>;
     lastGitHubTip: z.ZodOptional<z.ZodString>;
     keptOverGitHub: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     rewrittenOnGitHub: z.ZodOptional<z.ZodString>;
@@ -121,6 +122,7 @@ export declare const branchMetadataSchema: z.ZodObject<{
             name?: string | undefined;
         }>;
         at: z.ZodString;
+        commit: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
         at: string;
         state: "approved" | "changes-requested";
@@ -128,6 +130,7 @@ export declare const branchMetadataSchema: z.ZodObject<{
             userId: string;
             name?: string | undefined;
         };
+        commit?: string | undefined;
     }, {
         at: string;
         state: "approved" | "changes-requested";
@@ -135,6 +138,25 @@ export declare const branchMetadataSchema: z.ZodObject<{
             userId: string;
             name?: string | undefined;
         };
+        commit?: string | undefined;
+    }>>>;
+    baseUpdateRequestedAt: z.ZodCatch<z.ZodOptional<z.ZodString>>;
+    latestChangesWaiting: 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;
@@ -199,6 +221,7 @@ export declare const branchMetadataSchema: z.ZodObject<{
         lastAt: string;
     }>>;
     historyRewrittenFrom: z.ZodOptional<z.ZodString>;
+    historyRewrittenTo: z.ZodOptional<z.ZodString>;
     lastGitHubTip: z.ZodOptional<z.ZodString>;
     keptOverGitHub: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     rewrittenOnGitHub: z.ZodOptional<z.ZodString>;
@@ -237,6 +260,7 @@ export declare const branchMetadataSchema: z.ZodObject<{
             name?: string | undefined;
         }>;
         at: z.ZodString;
+        commit: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
         at: string;
         state: "approved" | "changes-requested";
@@ -244,6 +268,7 @@ export declare const branchMetadataSchema: z.ZodObject<{
             userId: string;
             name?: string | undefined;
         };
+        commit?: string | undefined;
     }, {
         at: string;
         state: "approved" | "changes-requested";
@@ -251,6 +276,25 @@ export declare const branchMetadataSchema: z.ZodObject<{
             userId: string;
             name?: string | undefined;
         };
+        commit?: string | undefined;
+    }>>>;
+    baseUpdateRequestedAt: z.ZodCatch<z.ZodOptional<z.ZodString>>;
+    latestChangesWaiting: 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;
@@ -315,6 +359,7 @@ export declare const branchMetadataSchema: z.ZodObject<{
         lastAt: string;
     }>>;
     historyRewrittenFrom: z.ZodOptional<z.ZodString>;
+    historyRewrittenTo: z.ZodOptional<z.ZodString>;
     lastGitHubTip: z.ZodOptional<z.ZodString>;
     keptOverGitHub: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     rewrittenOnGitHub: z.ZodOptional<z.ZodString>;
@@ -353,6 +398,7 @@ export declare const branchMetadataSchema: z.ZodObject<{
             name?: string | undefined;
         }>;
         at: z.ZodString;
+        commit: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
         at: string;
         state: "approved" | "changes-requested";
@@ -360,6 +406,7 @@ export declare const branchMetadataSchema: z.ZodObject<{
             userId: string;
             name?: string | undefined;
         };
+        commit?: string | undefined;
     }, {
         at: string;
         state: "approved" | "changes-requested";
@@ -367,6 +414,25 @@ export declare const branchMetadataSchema: z.ZodObject<{
             userId: string;
             name?: string | undefined;
         };
+        commit?: string | undefined;
+    }>>>;
+    baseUpdateRequestedAt: z.ZodCatch<z.ZodOptional<z.ZodString>>;
+    latestChangesWaiting: 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">>;
 /**

package/dist/branch-metadata-file.js

@@ -82,6 +82,7 @@ const branchMetadataShape = {
         .object({ message: z.string(), firstAt: z.string(), lastAt: z.string() })
         .optional(),
     historyRewrittenFrom: z.string().optional(),
+    historyRewrittenTo: z.string().optional(),
     lastGitHubTip: z.string().optional(),
     keptOverGitHub: z.array(z.string()).optional(),
     rewrittenOnGitHub: z.string().optional(),
@@ -99,12 +100,26 @@ const branchMetadataShape = {
     ])
         .optional()
         .catch(undefined),
-    // Dropped when malformed: it only decorates the PR body, so it never fails a read.
+    // Dropped when malformed, never failing a read: it decorates the PR body, and without `commit`
+    // the worker judges a move against the clone's head before it (worker/github-commits.ts).
     review: z
         .object({
         state: z.enum(['approved', 'changes-requested']),
         by: z.object({ userId: z.string(), name: z.string().optional() }),
         at: z.string(),
+        commit: z.string().optional(),
+    })
+        .optional()
+        .catch(undefined),
+    baseUpdateRequestedAt: z.string().optional().catch(undefined),
+    latestChangesWaiting: 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),

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 {};