canopycms 0.7.1 → 0.8.1

package/dist/api/admin-branch-health.js

@@ -19,13 +19,14 @@ import { BranchMetadataFileManager, getBranchMetadataFileManager } from '../bran
 import { BRANCH_META_DIR, BRANCH_META_FILE } from '../branch-metadata-file.js';
 import { ORPHAN_YOUTH_THRESHOLD_MS, scanBranchHealth, } from '../branch-health.js';
 import { formatDirStamp } from '../branch-provisioning.js';
+import { gitChildEnv } from '../git-manager.js';
 import { ContentIdIndex } from '../content-id-index.js';
 import { invalidateContentIndexesDurable } from '../content-index-generation.js';
 import { getDefaultBranchBase, sanitizeBranchName } from '../paths/index.js';
 import { withOccFileLock } from '../utils/occ-json-write.js';
 import { branchProvisioningLockName, tryAcquireProvisioningLock } from '../utils/provisioning-lock.js';
 import { withContentWriteLock, ContentWriteLockBusyError, DEFAULT_CONTENT_WRITE_LOCK_WAIT_MS, } from '../utils/content-write-lock.js';
-import { getErrorMessage, isNodeError, isNotFoundError } from '../utils/error.js';
+import { getErrorMessage, isNodeError, isNotFoundError, sanitizeErrorMessage } from '../utils/error.js';
 import { defineEndpoint } from './route-builder.js';
 import { baseBranchOf } from '../utils/base-branch.js';
 /** [H1] A fresh (< 5 min old) init lock blocks purge -- provisioning may be running. */
@@ -297,6 +298,10 @@ const repairBranchDirHandler = async (_gc, ctx, req, params) => {
             ? { ok: false, status: 409, error: 'Metadata is healthy' }
             : { ok: false, status: 409, error: 'No metadata file -- use purge for orphans' };
     }
+    const checkedOut = await checkedOutBranch(dirPath, params.dirName);
+    if (!checkedOut.ok)
+        return { ok: false, status: 409, error: checkedOut.error };
+    const branchName = checkedOut.branch;
     // Zero-retry provisioning lock, mirroring purge's: fails fast (409) on
     // genuine live contention instead of hanging the request.
     // Held until the `finally` below, AFTER save() completes.
@@ -339,9 +344,6 @@ const repairBranchDirHandler = async (_gc, ctx, req, params) => {
                 error: `Could not lock branch metadata: ${getErrorMessage(err)}`,
             };
         }
-        // Prefer the clone's actual checked-out branch over the
-        // (possibly sanitized) directory name -- see resolveRepairedBranchName.
-        const branchName = await resolveRepairedBranchName(dirPath, params.dirName);
         // Lock released above (we're outside the withOccFileLock callback now) --
         // save() takes its own hold on the same lock internally. Its defaults
         // path fabricates the rest of BranchMetadata and invalidates the
@@ -375,30 +377,55 @@ const repairBranchDirHandler = async (_gc, ctx, req, params) => {
         }
     }
 };
+const LOCAL_BRANCH_PREFIX = 'refs/heads/';
 /**
- * Best-effort read of the branch actually checked out in the
- * clone at `dirPath`, falling back to `dirName` on any failure (no `.git`,
- * detached HEAD, corrupt repo, etc.). Workspace directory names are
- * sanitized (slashes stripped, see paths/branch.ts's `sanitizeBranchName`),
- * so a branch named `feature/foo` lives in a directory named `feature-foo`
- * -- writing `dirName` as `branch.name` would make later push/PR tasks
- * target the wrong ref.
+ * The branch checked out in the clone at `dirPath`, which repair records as `branch.name`, or why
+ * there is none. Nothing else names the branch: the directory is its key, which a ref's `/`s do
+ * not survive, and a guessed name would send later pushes and PRs to the wrong ref. The branch
+ * counts only when its key is `dirName`, the directory's own name; a clone on any other branch is
+ * not this directory's workspace. Git reads only this clone's `.git`, never a repository above it.
  */
-async function resolveRepairedBranchName(dirPath, dirName) {
+async function checkedOutBranch(dirPath, dirName) {
+    const cannot = 'Cannot repair this branch: ';
+    const then = ' Check out its branch in the clone, then repair again, or purge the directory.';
+    const gitDir = path.join(dirPath, '.git');
     const hasGitDir = await fs
-        .stat(path.join(dirPath, '.git'))
+        .stat(gitDir)
         .then(() => true)
         .catch(() => false);
-    if (!hasGitDir)
-        return dirName;
+    if (!hasGitDir) {
+        return {
+            ok: false,
+            error: `${cannot}the directory holds no git clone, so the branch it belongs to is unknown.${then}`,
+        };
+    }
+    let ref;
     try {
-        const current = await simpleGit({ baseDir: dirPath }).revparse(['--abbrev-ref', 'HEAD']);
-        const trimmed = current.trim();
-        return trimmed || dirName;
+        // `-q` makes a detached HEAD a quiet failure, which simple-git resolves as empty output.
+        ref = (await simpleGit({ baseDir: dirPath })
+            .env(gitChildEnv({ GIT_CEILING_DIRECTORIES: path.dirname(dirPath) }))
+            .raw(['--git-dir', gitDir, '--work-tree', dirPath, 'symbolic-ref', '-q', 'HEAD'])).trim();
     }
-    catch {
-        return dirName;
+    catch (err) {
+        return {
+            ok: false,
+            error: `${cannot}git could not read the clone's checked-out branch (${sanitizeErrorMessage(getErrorMessage(err))}).${then}`,
+        };
+    }
+    const branch = ref.startsWith(LOCAL_BRANCH_PREFIX) ? ref.slice(LOCAL_BRANCH_PREFIX.length) : '';
+    if (!branch) {
+        return {
+            ok: false,
+            error: `${cannot}its clone has no branch checked out (a detached HEAD), so the branch it belongs to is unknown.${then}`,
+        };
+    }
+    if (sanitizeBranchName(branch) !== dirName) {
+        return {
+            ok: false,
+            error: `${cannot}its clone has "${branch}" checked out, which is not the branch this directory holds.${then}`,
+        };
     }
+    return { ok: true, branch };
 }
 /** Classify branch.json's current state for repair's precondition checks. */
 async function checkStillCorrupt(dirPath) {

package/dist/api/admin.d.ts

@@ -9,7 +9,7 @@ import { z } from 'zod';
 import type { ApiResponse } from './types.js';
 import type { Task, QueueStats, CorruptTaskFile } from '../task-queue/cms-task-queue.js';
 import type { BuildIdentity, WorkerStatusReport } from '../types.js';
-import type { OperatingMode } from '../operating-mode/index.js';
+import { type OperatingMode } from '../operating-mode/index.js';
 import type { SchemaIssue } from '../schema/types.js';
 export type { BranchHealthResponse, PurgeBranchDirResponse, RepairBranchDirResponse, RepairContentDuplicatesResponse, } from './admin-branch-health.js';
 type WorkerLivenessState = 'alive' | 'stale' | 'absent';
@@ -40,6 +40,18 @@ export interface AdminStatusData {
     settingsWorkspaceError?: string;
     /** What the base branch's schema leaves out under this process's code; absent when nothing. */
     schemaIssues?: SchemaIssue[];
+    /**
+     * The branch namespace this process resolves for the branches it creates, or why it cannot.
+     * System health compares it with the GitHub gateway's (`workerStatus.gatewayBranchNamespace`).
+     * Optional on the wire, so an editor reading an older API shows nothing rather than failing.
+     */
+    branchNamespace?: {
+        ok: true;
+        namespace: string;
+    } | {
+        ok: false;
+        error: string;
+    };
     /** Build of the API process answering this request. */
     build: BuildIdentity;
     /** Whether `media` is configured; without it every upload returns 501. */

package/dist/api/admin.js

@@ -10,7 +10,8 @@ import path from 'node:path';
 import { z } from 'zod';
 import { getQueueStats, listTasks, listCorruptTaskFiles, requeueFailedTask, } from '../task-queue/cms-task-queue.js';
 import { getTaskQueueDir } from '../task-queue/task-queue-config.js';
-import { WORKER_STATUS_FILE } from '../task-queue/worker-status.js';
+import { readWorkerStatus } from '../task-queue/worker-status.js';
+import { operatingStrategy } from '../operating-mode/index.js';
 import { defineEndpoint } from './route-builder.js';
 import { getErrorMessage, isNotFoundError, redactCredentials } from '../utils/error.js';
 import { getBuildIdentity } from '../build-identity.js';
@@ -52,29 +53,6 @@ async function classifyWorkerLiveness(taskDir) {
         lockAgeMs,
     };
 }
-/** Read + parse worker-status.json (written by the worker daemon, PR-W1). */
-async function readWorkerStatus(taskDir) {
-    const statusPath = path.join(taskDir, WORKER_STATUS_FILE);
-    let content;
-    try {
-        content = await fs.readFile(statusPath, 'utf-8');
-    }
-    catch (err) {
-        if (isNotFoundError(err))
-            return { workerStatus: null };
-        return { workerStatus: null, statusReadError: getErrorMessage(err) };
-    }
-    try {
-        // Trust boundary: this file is written only by the CMS worker daemon
-        // (PR-W1), never derived from request input — cast rather than
-        // runtime-validate every field.
-        const parsed = JSON.parse(content);
-        return { workerStatus: parsed };
-    }
-    catch (err) {
-        return { workerStatus: null, statusReadError: getErrorMessage(err) };
-    }
-}
 async function readSettingsWorkspaceError(ctx) {
     try {
         await ctx.services.getSettingsBranchRoot();
@@ -190,6 +168,7 @@ const getAdminStatusHandler = async (_gc, ctx, _req) => {
                 ...(statusReadError ? { statusReadError } : {}),
                 ...(settingsWorkspaceError ? { settingsWorkspaceError } : {}),
                 ...(schemaIssues.length > 0 ? { schemaIssues } : {}),
+                branchNamespace: resolveOwnBranchNamespace(ctx),
                 build: getBuildIdentity(),
                 assetStore: { configured: !!ctx.assetStore },
                 imageProcessing,
@@ -200,6 +179,16 @@ const getAdminStatusHandler = async (_gc, ctx, _req) => {
         return { ok: false, status: 500, error: getErrorMessage(err) };
     }
 };
+/** This process's branch namespace, as an answer rather than a throw. */
+function resolveOwnBranchNamespace(ctx) {
+    try {
+        const { config } = ctx.services;
+        return { ok: true, namespace: operatingStrategy(config.mode).getBranchNamespace(config) };
+    }
+    catch (err) {
+        return { ok: false, error: getErrorMessage(err) };
+    }
+}
 const listAdminTasksHandler = async (_gc, ctx, _req, params) => {
     const taskDir = getTaskQueueDir(ctx.services.config);
     const limit = params.limit ?? DEFAULT_ADMIN_TASKS_LIMIT;
@@ -306,6 +295,7 @@ const getAdminStatus = defineEndpoint({
         build: { canopycmsVersion: '0.0.0' },
         assetStore: { configured: false },
         imageProcessing: { available: true },
+        branchNamespace: { ok: true, namespace: 'canopycms/prod/' },
     },
     guards: ['admin'],
     handler: getAdminStatusHandler,

package/dist/api/branch-changes.d.ts

@@ -0,0 +1,87 @@
+import type { z } from 'zod';
+import type { ApiContext, ApiResponse } from './types.js';
+/** An entry whose saved state on the branch differs from the base branch. */
+export interface BranchChangeEntry {
+    status: 'added' | 'modified' | 'deleted' | 'moved';
+    logicalPath: string;
+    /** A moved entry's path at the base. */
+    previousLogicalPath?: string;
+    contentId: string;
+    collectionPath: string;
+    entryType: string;
+    /** A deleted entry's title at the base. */
+    title?: string;
+}
+export interface BranchChangesData {
+    base: string;
+    mergeBaseSha?: string;
+    entries: BranchChangeEntry[];
+    /** Collections whose settings (`.collection.json`) differ. */
+    collections: Array<{
+        status: 'added' | 'modified' | 'deleted';
+        logicalPath: string;
+    }>;
+    /** Something changed that this user may not read. Never a count, which would leak its size. */
+    hiddenChanges: boolean;
+    /** The branch and its base share no commit, so there is no fork point to compare against. */
+    baseUnavailable?: boolean;
+    /** The remote no longer has the base branch, so nothing can be compared until it is back. */
+    baseMissing?: boolean;
+    /** Changed files that are neither entries nor collection settings. Admins only. */
+    otherFiles?: string[];
+    /** `otherFiles` holds only the first {@link MAX_OTHER_FILES}. Admins only. */
+    otherFilesTruncated?: boolean;
+}
+export type BranchChangesResponse = ApiResponse<BranchChangesData>;
+type BranchGit = ReturnType<ApiContext['services']['createGitManagerFor']>;
+/** Why a read of a branch against its base can't be trusted: see {@link readWhileSteady}. */
+export type UnsteadyRead = 'syncing' | 'moved';
+export type SteadyRead<T> = {
+    steady: true;
+    value: T;
+} | {
+    steady: false;
+    reason: UnsteadyRead;
+};
+/**
+ * `read`'s result, taken lock-free, or why it can't be trusted: `syncing` while a rebase is
+ * under way before or after it, since a half-rebased tree reports the base's own changes as
+ * the branch's; `moved` when HEAD moved during it, as a submit's commit does, leaving a mix of
+ * two trees.
+ */
+export declare const readWhileSteady: <T>(branchRoot: string, git: BranchGit, read: () => Promise<T>) => Promise<SteadyRead<T>>;
+/** The 409 for a read {@link readWhileSteady} refused, nothing lost. */
+export declare const unsteadyReadResponse: (reason: UnsteadyRead, base: string) => ApiResponse<never>;
+/** The 503 for a git failure, logged with the branch and base it compared. */
+export declare const branchReadFailedResponse: (branch: string, base: string, err: unknown) => ApiResponse<never>;
+/**
+ * What this branch changes against its base: its working tree, saved but uncommitted edits
+ * included, against the commit it forked from.
+ * GET /:branch/changes
+ * @internal Exported for tests.
+ */
+export declare const listBranchChanges: import("./route-builder.js").RouteDefinition<z.ZodObject<{
+    branch: z.ZodType<import("../paths/index.js").BranchName, z.ZodTypeDef, import("../paths/index.js").BranchName>;
+}, "strip", z.ZodTypeAny, {
+    branch: string & {
+        readonly __brand: "BranchName";
+    };
+}, {
+    branch: string & {
+        readonly __brand: "BranchName";
+    };
+}>, undefined, BranchChangesResponse>;
+export declare const BRANCH_CHANGES_ROUTES: {
+    readonly list: import("./route-builder.js").RouteDefinition<z.ZodObject<{
+        branch: z.ZodType<import("../paths/index.js").BranchName, z.ZodTypeDef, import("../paths/index.js").BranchName>;
+    }, "strip", z.ZodTypeAny, {
+        branch: string & {
+            readonly __brand: "BranchName";
+        };
+    }, {
+        branch: string & {
+            readonly __brand: "BranchName";
+        };
+    }>, undefined, BranchChangesResponse>;
+};
+export {};

package/dist/api/branch-changes.js

@@ -0,0 +1,269 @@
+import { entryRefFromRepoPath, entryRefFromRepoPathShape, parseEntryData, } from '../content-listing.js';
+import { getFormatExtension } from '../utils/format.js';
+import { defineEndpoint } from './route-builder.js';
+import { BaseBranchMissingError } from '../git-manager.js';
+import { branchParamSchema } from './validators.js';
+import { getBranchProtection } from '../authorization/protected-branch.js';
+import { isAdmin } from '../authorization/helpers.js';
+import { baseBranchOf } from '../utils/base-branch.js';
+import { isCanopyInternalPath, isRebaseInProgress } from '../utils/git.js';
+import { resolveEntryTitle } from '../utils/title-field.js';
+import { getErrorMessage, redactCredentials } from '../utils/error.js';
+import { canopyLogWarn } from '../utils/logger.js';
+/** Deleted entries whose titles are read from the base, one `git show` each. */
+const MAX_DELETED_TITLES = 200;
+/** Other files listed to an admin; the rest are counted only as `otherFilesTruncated`. */
+const MAX_OTHER_FILES = 200;
+const SYNCING_ERROR = (base) => `This branch is being synced with ${base}. Try again in a moment.`;
+const CHANGED_MID_READ_ERROR = 'This branch changed while its changes were being read. Try again in a moment.';
+const READ_FAILED_ERROR = "Couldn't read this branch's changes right now. Try again in a moment.";
+/**
+ * `read`'s result, taken lock-free, or why it can't be trusted: `syncing` while a rebase is
+ * under way before or after it, since a half-rebased tree reports the base's own changes as
+ * the branch's; `moved` when HEAD moved during it, as a submit's commit does, leaving a mix of
+ * two trees.
+ */
+export const readWhileSteady = async (branchRoot, git, read) => {
+    if (await isRebaseInProgress(branchRoot))
+        return { steady: false, reason: 'syncing' };
+    const head = await git.headSha();
+    const value = await read();
+    if (await isRebaseInProgress(branchRoot))
+        return { steady: false, reason: 'syncing' };
+    if ((await git.headSha()) !== head)
+        return { steady: false, reason: 'moved' };
+    return { steady: true, value };
+};
+/** The 409 for a read {@link readWhileSteady} refused, nothing lost. */
+export const unsteadyReadResponse = (reason, base) => ({
+    ok: false,
+    status: 409,
+    error: reason === 'syncing' ? SYNCING_ERROR(base) : CHANGED_MID_READ_ERROR,
+});
+/** The 503 for a git failure, logged with the branch and base it compared. */
+export const branchReadFailedResponse = (branch, base, err) => {
+    canopyLogWarn(`CanopyCMS: could not read what ${branch} changes against ${base}:`, redactCredentials(getErrorMessage(err)));
+    return { ok: false, status: 503, error: READ_FAILED_ERROR };
+};
+const FORMATS = ['mdx', 'md', 'json', 'yaml'];
+const COLLECTION_STATUS = { A: 'added', M: 'modified', D: 'deleted' };
+/**
+ * Every changed file's status against `mergeBase`: tracked changes plus untracked files as
+ * added. A path both deleted from the index and present untracked is a modified file.
+ */
+const changedFiles = async (git, mergeBase) => {
+    const [tracked, untracked] = await Promise.all([
+        git.diffNameStatusAgainst(mergeBase),
+        git.listUntrackedFiles(),
+    ]);
+    const files = new Map();
+    for (const { status, path } of tracked)
+        files.set(path, status);
+    for (const path of untracked)
+        files.set(path, files.get(path) === 'D' ? 'M' : 'A');
+    for (const path of files.keys())
+        if (isCanopyInternalPath(path))
+            files.delete(path);
+    return files;
+};
+const branchChangesHandler = async (gc, ctx, req, _params) => {
+    const { branchContext } = gc;
+    const { config } = ctx.services;
+    const base = branchContext.branch.baseBranch ?? baseBranchOf(config);
+    const empty = { base, entries: [], collections: [], hiddenChanges: false };
+    if (getBranchProtection(config, branchContext.branch.name, branchContext.branch.baseBranch)
+        .isProtected) {
+        return { ok: true, status: 200, data: empty };
+    }
+    const git = ctx.services.createGitManagerFor(branchContext.branchRoot, {
+        baseBranch: branchContext.branch.baseBranch,
+    });
+    let read;
+    try {
+        read = await readWhileSteady(branchContext.branchRoot, git, async () => {
+            const mergeBase = await git.mergeBaseWithBase();
+            return mergeBase ? readChanges(ctx, req, branchContext, git, mergeBase) : null;
+        });
+    }
+    catch (err) {
+        if (err instanceof BaseBranchMissingError) {
+            return { ok: true, status: 200, data: { ...empty, baseMissing: true } };
+        }
+        return branchReadFailedResponse(branchContext.branch.name, base, err);
+    }
+    if (!read.steady)
+        return unsteadyReadResponse(read.reason, base);
+    if (!read.value)
+        return { ok: true, status: 200, data: { ...empty, baseUnavailable: true } };
+    return { ok: true, status: 200, data: { base, ...read.value } };
+};
+/** The branch's changes against `mergeBase`, filtered to what `req.user` may read. */
+const readChanges = async (ctx, req, branchContext, git, mergeBase) => {
+    const files = await changedFiles(git, mergeBase);
+    const flatSchema = branchContext.flatSchema;
+    const contentRoot = ctx.services.config.contentRoot || 'content';
+    const checkAccess = await ctx.services.createContentAccessChecker(branchContext, branchContext.branchRoot, req.user);
+    const readable = (logicalPath) => checkAccess(logicalPath, 'read').allowed;
+    const admin = isAdmin(req.user.groups);
+    const underContentRoot = (path) => path.startsWith(`${contentRoot}/`);
+    let hiddenChanges = false;
+    const entries = [];
+    const collections = [];
+    const otherFiles = [];
+    const added = new Map();
+    const deleted = new Map();
+    const modified = [];
+    const push = (map, ref) => map.set(ref.contentId, [...(map.get(ref.contentId) ?? []), ref]);
+    for (const [path, status] of files) {
+        let ref = entryRefFromRepoPath(path, flatSchema, contentRoot);
+        // A deleted file the schema no longer places, as under a renamed or deleted collection, is
+        // read from its path's shape, so it still reads as deleted or as the old side of a move.
+        if (ref.kind === 'other' && status === 'D') {
+            ref = entryRefFromRepoPathShape(path, contentRoot) ?? ref;
+        }
+        if (ref.kind === 'other') {
+            otherFiles.push(ref.physicalPath);
+            // Under the content root it may be content this user can't see placed; never nothing.
+            if (!admin && underContentRoot(path))
+                hiddenChanges = true;
+        }
+        else if (ref.kind === 'collection-meta') {
+            // `/*`, as entries.ts probes a collection: a rule for its contents decides too.
+            if (readable(ref.collectionPath) && readable(`${ref.collectionPath}/*`)) {
+                collections.push({ status: COLLECTION_STATUS[status], logicalPath: ref.collectionPath });
+            }
+            else
+                hiddenChanges = true;
+        }
+        else if (status === 'A')
+            push(added, ref);
+        else if (status === 'D')
+            push(deleted, ref);
+        else
+            modified.push(ref);
+    }
+    const toEntry = (ref, status, previous) => ({
+        status,
+        logicalPath: ref.logicalPath,
+        ...(previous && { previousLogicalPath: previous.logicalPath }),
+        contentId: ref.contentId,
+        collectionPath: ref.collectionPath,
+        entryType: ref.entryType,
+    });
+    const addedShown = [];
+    const deletedShown = [];
+    const showAdded = (ref) => {
+        if (readable(ref.logicalPath))
+            addedShown.push(ref);
+        else
+            hiddenChanges = true;
+    };
+    const showDeleted = (ref) => {
+        if (readable(ref.logicalPath))
+            deletedShown.push(ref);
+        else
+            hiddenChanges = true;
+    };
+    for (const ref of modified) {
+        if (readable(ref.logicalPath))
+            entries.push(toEntry(ref, 'modified'));
+        else
+            hiddenChanges = true;
+    }
+    for (const [contentId, adds] of added) {
+        const dels = deleted.get(contentId) ?? [];
+        deleted.delete(contentId);
+        // A content id on more than one file on either side is a duplicate, not one entry moving,
+        // so its files are listed as they are.
+        if (adds.length !== 1 || dels.length !== 1) {
+            adds.forEach(showAdded);
+            dels.forEach(showDeleted);
+            continue;
+        }
+        const [ref] = adds;
+        const [from] = dels;
+        const toReadable = readable(ref.logicalPath);
+        const fromReadable = readable(from.logicalPath);
+        if (from.logicalPath === ref.logicalPath) {
+            // The same entry under another entry type.
+            if (toReadable)
+                entries.push(toEntry(ref, 'modified'));
+            else
+                hiddenChanges = true;
+        }
+        else if (toReadable && fromReadable) {
+            entries.push(toEntry(ref, 'moved', from));
+        }
+        else {
+            // A move with a side this user can't read shows only the side they can, so the other
+            // side's path never reaches them.
+            showAdded(ref);
+            showDeleted(from);
+        }
+    }
+    for (const dels of deleted.values())
+        dels.forEach(showDeleted);
+    for (const ref of addedShown)
+        entries.push(toEntry(ref, 'added'));
+    const titles = await Promise.all(deletedShown.map((ref, i) => i < MAX_DELETED_TITLES ? deletedTitle(git, mergeBase, ref, flatSchema) : undefined));
+    deletedShown.forEach((ref, i) => {
+        const title = titles[i];
+        entries.push({ ...toEntry(ref, 'deleted'), ...(title !== undefined && { title }) });
+    });
+    entries.sort((a, b) => a.logicalPath.localeCompare(b.logicalPath));
+    collections.sort((a, b) => a.logicalPath.localeCompare(b.logicalPath));
+    otherFiles.sort();
+    return {
+        mergeBaseSha: mergeBase,
+        entries,
+        collections,
+        hiddenChanges,
+        ...(admin && {
+            otherFiles: otherFiles.slice(0, MAX_OTHER_FILES),
+            otherFilesTruncated: otherFiles.length > MAX_OTHER_FILES,
+        }),
+    };
+};
+/** A deleted entry's title as the listing would have shown it, from its file at `rev`. */
+const deletedTitle = async (git, rev, ref, flatSchema) => {
+    const collection = flatSchema.find((item) => item.type === 'collection' && item.logicalPath === ref.collectionPath);
+    const entryType = collection?.entries?.find((e) => e.name === ref.entryType);
+    // An entry the schema no longer places is parsed by its extension, with no field list.
+    const format = entryType?.format ?? FORMATS.find((f) => ref.physicalPath.endsWith(getFormatExtension(f)));
+    if (!format)
+        return undefined;
+    try {
+        const raw = await git.showFile(rev, ref.physicalPath);
+        if (raw === undefined)
+            return undefined;
+        return resolveEntryTitle(parseEntryData(raw, format), {
+            schema: entryType?.schema,
+            entryTypeLabel: entryType?.label,
+            slug: ref.logicalPath.slice(ref.logicalPath.lastIndexOf('/') + 1),
+        });
+    }
+    catch {
+        return undefined;
+    }
+};
+/**
+ * What this branch changes against its base: its working tree, saved but uncommitted edits
+ * included, against the commit it forked from.
+ * GET /:branch/changes
+ * @internal Exported for tests.
+ */
+export const listBranchChanges = defineEndpoint({
+    namespace: 'changes',
+    name: 'list',
+    method: 'GET',
+    path: '/:branch/changes',
+    params: branchParamSchema,
+    responseType: 'BranchChangesResponse',
+    response: {},
+    defaultMockData: { base: 'main', entries: [], collections: [], hiddenChanges: false },
+    guards: ['branchAccessWithSchema'],
+    handler: branchChangesHandler,
+});
+export const BRANCH_CHANGES_ROUTES = {
+    list: listBranchChanges,
+};

package/dist/api/branch-entry-changes.d.ts

@@ -0,0 +1,83 @@
+import { z } from 'zod';
+import type { ApiResponse } from './types.js';
+import type { ContentFormat } from '../config/index.js';
+import type { LogicalPath } from '../paths/types.js';
+/** One side of an entry's change: its file as the editor reads it, references unresolved. */
+export interface EntryChangeSide {
+    format: ContentFormat;
+    entryType: string;
+    data: Record<string, unknown>;
+    /** An md/mdx entry's markdown content. */
+    body?: string;
+    /** The field `body` maps to on this side, as `ContentStore.read` names it. */
+    bodyFieldName?: string;
+}
+export interface BranchEntryChangeData {
+    /** The entry at the commit the branch forked from; null when it is new on the branch. */
+    before: EntryChangeSide | null;
+    /** The entry as saved on the branch; null when the branch deleted it. */
+    after: EntryChangeSide | null;
+    mergeBaseSha: string;
+}
+export type BranchEntryChangeResponse = ApiResponse<BranchEntryChangeData>;
+/**
+ * One entry's saved state on the branch against the commit the branch forked from, for the
+ * editor's "Show changes". A moved entry takes `from`, its path at the base; `id` pins both
+ * sides to one content id.
+ * GET /:branch/changes/...entryPath
+ * @internal Exported for tests.
+ */
+export declare const readBranchEntryChange: import("./route-builder.js").RouteDefinition<z.ZodObject<{
+    branch: z.ZodType<import("../paths/index.js").BranchName, z.ZodTypeDef, import("../paths/index.js").BranchName>;
+    entryPath: z.ZodType<LogicalPath, z.ZodTypeDef, LogicalPath>;
+    /** A moved entry's path at the base. */
+    from: z.ZodOptional<z.ZodType<LogicalPath, z.ZodTypeDef, LogicalPath>>;
+    /** The entry's content id: both sides must carry it, so a slug reused by another entry isn't it. */
+    id: z.ZodOptional<z.ZodType<import("../paths/index.js").ContentId, z.ZodTypeDef, import("../paths/index.js").ContentId>>;
+}, "strip", z.ZodTypeAny, {
+    branch: string & {
+        readonly __brand: "BranchName";
+    };
+    entryPath: string & {
+        readonly __brand: "LogicalPath";
+    };
+    id?: import("../paths/index.js").ContentId | undefined;
+    from?: LogicalPath | undefined;
+}, {
+    branch: string & {
+        readonly __brand: "BranchName";
+    };
+    entryPath: string & {
+        readonly __brand: "LogicalPath";
+    };
+    id?: import("../paths/index.js").ContentId | undefined;
+    from?: LogicalPath | undefined;
+}>, undefined, BranchEntryChangeResponse>;
+export declare const BRANCH_ENTRY_CHANGE_ROUTES: {
+    readonly entry: import("./route-builder.js").RouteDefinition<z.ZodObject<{
+        branch: z.ZodType<import("../paths/index.js").BranchName, z.ZodTypeDef, import("../paths/index.js").BranchName>;
+        entryPath: z.ZodType<LogicalPath, z.ZodTypeDef, LogicalPath>;
+        /** A moved entry's path at the base. */
+        from: z.ZodOptional<z.ZodType<LogicalPath, z.ZodTypeDef, LogicalPath>>;
+        /** The entry's content id: both sides must carry it, so a slug reused by another entry isn't it. */
+        id: z.ZodOptional<z.ZodType<import("../paths/index.js").ContentId, z.ZodTypeDef, import("../paths/index.js").ContentId>>;
+    }, "strip", z.ZodTypeAny, {
+        branch: string & {
+            readonly __brand: "BranchName";
+        };
+        entryPath: string & {
+            readonly __brand: "LogicalPath";
+        };
+        id?: import("../paths/index.js").ContentId | undefined;
+        from?: LogicalPath | undefined;
+    }, {
+        branch: string & {
+            readonly __brand: "BranchName";
+        };
+        entryPath: string & {
+            readonly __brand: "LogicalPath";
+        };
+        id?: import("../paths/index.js").ContentId | undefined;
+        from?: LogicalPath | undefined;
+    }>, undefined, BranchEntryChangeResponse>;
+};