canopycms 0.7.0 → 0.8.0

package/dist/api/branch-entry-changes.js

@@ -0,0 +1,262 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { z } from 'zod';
+import { entryRefFromRepoPath, entryRefFromRepoPathShape, parseEntryParts, } from '../content-listing.js';
+import { ContentStore, ContentStoreError } from '../content-store.js';
+import { resolveCollectionPath } from '../content-id-index.js';
+import { BaseBranchMissingError } from '../git-manager.js';
+import { withItemKeys } from '../item-keys.js';
+import { getBranchProtection } from '../authorization/protected-branch.js';
+import { baseBranchOf } from '../utils/base-branch.js';
+import { findBodyFieldName } from '../utils/body-field.js';
+import { isNodeError, isNotFoundError } from '../utils/error.js';
+import { getFormatExtension } from '../utils/format.js';
+import { entryLogicalPath } from '../paths/index.js';
+import { defineEndpoint } from './route-builder.js';
+import { branchNameSchema, contentIdSchema, logicalPathSchema } from './validators.js';
+import { branchReadFailedResponse, readWhileSteady, unsteadyReadResponse, } from './branch-changes.js';
+/** The most of a side's file read, so one huge file can't hold the API or the browser. */
+const MAX_SIDE_BYTES = 1024 * 1024;
+const NOT_COMPARABLE_ERROR = "This entry can't be compared.";
+const UNREADABLE_ERROR = "This entry couldn't be read on one side, so it can't be compared.";
+const TOO_LARGE_ERROR = 'This entry is too large to compare here.';
+const FORMATS = ['mdx', 'md', 'json', 'yaml'];
+const entryChangeParamsSchema = z.object({
+    branch: branchNameSchema,
+    entryPath: logicalPathSchema,
+    /** A moved entry's path at the base. */
+    from: logicalPathSchema.optional(),
+    /** The entry's content id: both sides must carry it, so a slug reused by another entry isn't it. */
+    id: contentIdSchema.optional(),
+});
+/** `logicalPath` under `contentRoot`, as content reads take it with or without the root. */
+const underContentRoot = (logicalPath, contentRoot) => logicalPath === contentRoot || logicalPath.startsWith(`${contentRoot}/`)
+    ? logicalPath
+    : `${contentRoot}/${logicalPath}`;
+/**
+ * The path as the store resolves it (the slug lowercased, separators collapsed), so a path rule
+ * judges the entry that is read, as api/content.ts judges it. A collection the schema lacks has
+ * nothing to read in the working tree; its path is the requested segments rejoined, and only a
+ * base file at exactly that path matches it.
+ */
+const canonicalPath = (store, requested) => {
+    const segments = requested.split('/').filter(Boolean);
+    try {
+        const { schemaItem, slug } = store.resolvePath(segments);
+        return {
+            logicalPath: entryLogicalPath(schemaItem.logicalPath, slug),
+            stored: { collectionPath: schemaItem.logicalPath, slug },
+        };
+    }
+    catch (err) {
+        if (err instanceof ContentStoreError)
+            return { logicalPath: segments.join('/') };
+        throw err;
+    }
+};
+/** The entry type `entryType` names in `collectionPath`, when the schema still has both. */
+const entryTypeIn = (flatSchema, collectionPath, entryType) => flatSchema
+    .find((item) => item.type === 'collection' && item.logicalPath === collectionPath)
+    ?.entries?.find((e) => e.name === entryType);
+/**
+ * The entry at `target` in the working tree, read as the editor's content read does. With `id`,
+ * a file at that path holding another id is not this entry.
+ */
+const readAfter = async (store, flatSchema, target, id) => {
+    if (!target.stored)
+        return { side: undefined };
+    const { collectionPath, slug } = target.stored;
+    let located;
+    try {
+        located = await store.resolveDocumentPath(collectionPath, slug);
+    }
+    catch (err) {
+        if (err instanceof ContentStoreError)
+            return { side: undefined };
+        throw err;
+    }
+    if (!located.existed || (id !== undefined && located.id !== id))
+        return { side: undefined };
+    const fields = entryTypeIn(flatSchema, collectionPath, located.entryTypeName)?.schema;
+    const found = { contentId: located.id, fields };
+    try {
+        const stat = await fs.stat(located.absolutePath);
+        if (stat.size > MAX_SIDE_BYTES)
+            return { ...found, side: 'too-large' };
+        const doc = await store.read(collectionPath, slug, { resolveReferences: false });
+        // The read resolves the slug again; another file there now is another entry than the one
+        // whose id and size were checked.
+        if (doc.absolutePath !== located.absolutePath)
+            return { side: 'moved' };
+        return {
+            ...found,
+            side: {
+                format: doc.format,
+                entryType: located.entryTypeName,
+                data: doc.data,
+                ...('body' in doc && { body: doc.body, bodyFieldName: doc.bodyFieldName }),
+            },
+        };
+    }
+    catch (err) {
+        if (isNotFoundError(err))
+            return { side: undefined };
+        // A filesystem failure (a `syscall` error) is the server's; anything else is this file not
+        // parsing, or its entry type's schema failing to load (SchemaUnavailableError). A parser's
+        // errors carry a `code` too, so `code` alone doesn't tell them apart.
+        if (isNodeError(err) && err.syscall !== undefined)
+            throw err;
+        return { ...found, side: 'unreadable' };
+    }
+};
+/**
+ * The entry at `logicalPath` in `mergeBase`'s tree, matched by `contentId` when there is one.
+ * Looked for under the collection's directory first, then the whole content root when that
+ * directory isn't in the base tree (a collection renamed or deleted on the branch). Files map
+ * to entries as GET /:branch/changes maps them, so the entry it lists resolves to the same
+ * file here. A base file whose collection or entry type the schema no longer has is keyed with
+ * `afterFields`, the saved side's, so its unchanged items carry the keys the saved side's do.
+ */
+const readBefore = async (git, mergeBase, logicalPath, match, branchContext, contentRoot) => {
+    const { flatSchema, branchRoot } = branchContext;
+    const collectionPath = logicalPath.slice(0, logicalPath.lastIndexOf('/'));
+    const collectionDir = await resolveCollectionPath(branchRoot, collectionPath);
+    const dirs = [
+        ...(collectionDir ? [path.relative(branchRoot, collectionDir).split(path.sep).join('/')] : []),
+        contentRoot,
+    ];
+    for (const dir of dirs) {
+        const files = await git.listFilesWithSizeAt(mergeBase, dir);
+        for (const file of files) {
+            const placed = entryRefFromRepoPath(file.path, flatSchema, contentRoot);
+            const ref = placed.kind === 'other' ? entryRefFromRepoPathShape(file.path, contentRoot) : placed;
+            if (ref?.kind !== 'entry' || ref.logicalPath !== logicalPath)
+                continue;
+            if (match.contentId !== undefined && ref.contentId !== match.contentId)
+                continue;
+            if (file.size > MAX_SIDE_BYTES)
+                return 'too-large';
+            const entryType = entryTypeIn(flatSchema, ref.collectionPath, ref.entryType);
+            const fields = entryType?.schema ?? match.afterFields ?? [];
+            // An entry type the schema no longer has is parsed by its extension.
+            const format = entryType?.format ?? FORMATS.find((f) => file.path.endsWith(getFormatExtension(f)));
+            if (!format)
+                return 'unreadable';
+            const raw = await git.showFile(mergeBase, file.path);
+            if (raw === undefined)
+                return undefined;
+            let parsed;
+            try {
+                parsed = parseEntryParts(raw, format);
+            }
+            catch {
+                return 'unreadable';
+            }
+            return {
+                format,
+                entryType: ref.entryType,
+                // Keyed as ContentStore.read keys the working tree's side, so an item unchanged since the
+                // base carries the same key on both.
+                data: withItemKeys(fields, parsed.data, 'content'),
+                ...(parsed.body !== undefined && {
+                    body: parsed.body,
+                    bodyFieldName: findBodyFieldName(fields),
+                }),
+            };
+        }
+        // The collection's directory is in the base tree, so an entry not in it is new.
+        if (files.length > 0)
+            return undefined;
+    }
+    return undefined;
+};
+const entryChangeHandler = async (gc, ctx, req, params) => {
+    const { branchContext } = gc;
+    const { config } = ctx.services;
+    const base = branchContext.branch.baseBranch ?? baseBranchOf(config);
+    const contentRoot = config.contentRoot || 'content';
+    const notComparable = {
+        ok: false,
+        status: 404,
+        error: NOT_COMPARABLE_ERROR,
+    };
+    if (getBranchProtection(config, branchContext.branch.name, branchContext.branch.baseBranch)
+        .isProtected) {
+        return notComparable;
+    }
+    const store = new ContentStore(branchContext.branchRoot, branchContext.flatSchema, {
+        contentRootName: contentRoot,
+    });
+    const target = canonicalPath(store, underContentRoot(params.entryPath, contentRoot));
+    const from = params.from === undefined
+        ? undefined
+        : canonicalPath(store, underContentRoot(params.from, contentRoot));
+    // A path this user can't read answers as one with nothing to compare, so the answer never
+    // says the entry exists.
+    const checkAccess = await ctx.services.createContentAccessChecker(branchContext, branchContext.branchRoot, req.user);
+    if (!checkAccess(target.logicalPath, 'read').allowed ||
+        (from !== undefined && !checkAccess(from.logicalPath, 'read').allowed)) {
+        return notComparable;
+    }
+    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();
+            if (!mergeBase)
+                return null;
+            const after = await readAfter(store, branchContext.flatSchema, target, params.id);
+            const before = await readBefore(git, mergeBase, (from ?? target).logicalPath, { contentId: params.id ?? after.contentId, afterFields: after.fields }, branchContext, contentRoot);
+            return { mergeBase, before, after: after.side };
+        });
+    }
+    catch (err) {
+        if (err instanceof BaseBranchMissingError)
+            return notComparable;
+        return branchReadFailedResponse(branchContext.branch.name, base, err);
+    }
+    if (!read.steady)
+        return unsteadyReadResponse(read.reason, base);
+    if (!read.value)
+        return notComparable;
+    const { mergeBase, before, after } = read.value;
+    if (before === 'moved' || after === 'moved')
+        return unsteadyReadResponse('moved', base);
+    if (before === 'too-large' || after === 'too-large') {
+        return { ok: false, status: 413, error: TOO_LARGE_ERROR };
+    }
+    if (before === 'unreadable' || after === 'unreadable') {
+        return { ok: false, status: 422, error: UNREADABLE_ERROR };
+    }
+    if (!before && !after)
+        return notComparable;
+    return {
+        ok: true,
+        status: 200,
+        data: { before: before ?? null, after: after ?? null, mergeBaseSha: mergeBase },
+    };
+};
+/**
+ * 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 const readBranchEntryChange = defineEndpoint({
+    namespace: 'changes',
+    name: 'entry',
+    method: 'GET',
+    path: '/:branch/changes/...entryPath',
+    params: entryChangeParamsSchema,
+    responseType: 'BranchEntryChangeResponse',
+    response: {},
+    defaultMockData: { before: null, after: null, mergeBaseSha: '' },
+    guards: ['branchAccessWithSchema'],
+    handler: entryChangeHandler,
+});
+export const BRANCH_ENTRY_CHANGE_ROUTES = {
+    entry: readBranchEntryChange,
+};

package/dist/api/branch-merge.js

@@ -45,7 +45,7 @@ const markAsMergedHandler = async (gc, ctx, _req, params) => {
     }
     // Update branch status to 'archived'
     const meta = getBranchMetadataFileManager(branchContext.branchRoot, branchContext.baseRoot);
-    await meta.save({ branch: buildMergedBranchUpdate(branchName) });
+    await meta.save({ branch: buildMergedBranchUpdate() });
     // Optionally delete remote branch (disabled by default for safety)
     // if (ctx.services.githubService && req.body?.deleteRemoteBranch) {
     //   try {
@@ -61,7 +61,7 @@ const markAsMergedHandler = async (gc, ctx, _req, params) => {
         status: 200,
         data: {
             branch: {
-                name: branchName,
+                name: branchContext.branch.name,
                 status: 'archived',
             },
         },

package/dist/api/branch-review.js

@@ -9,6 +9,7 @@ import { CommentStore } from '../comment-store.js';
 import { getErrorMessage } from '../utils/error.js';
 import { REQUEST_CHANGES_NOTE_MAX_LENGTH } from '../authorization/review-role.js';
 import { getBranchProtection } from '../authorization/index.js';
+import { sanitizeDisplayName } from '../submission-attribution.js';
 /** Optional on the wire: a bodiless request means no note. */
 const requestChangesBodySchema = z
     .object({ note: z.string().trim().max(REQUEST_CHANGES_NOTE_MAX_LENGTH).optional() })
@@ -36,6 +37,18 @@ const approveConflict = (status) => ({
         ? 'This branch is already approved.'
         : staleStatusError(status, "it can't be approved"),
 });
+/**
+ * The verdict `user` gives. The reviewer guard admits only authenticated users, and the record is
+ * always written, so a new verdict replaces whatever the last one left.
+ */
+const reviewBy = (user, state) => ({
+    state,
+    by: {
+        userId: user.userId,
+        name: user.type === 'authenticated' ? sanitizeDisplayName(user.name) : undefined,
+    },
+    at: new Date().toISOString(),
+});
 const requestChangesHandler = async (gc, ctx, req, _params, body) => {
     const { branchContext } = gc;
     if (!canRequestChangesFrom(branchContext.branch.status)) {
@@ -48,7 +61,13 @@ const requestChangesHandler = async (gc, ctx, req, _params, body) => {
     // conversion above is left as it is: withdraw converts the pull request to a draft too, and a
     // merged one cannot be converted.
     let found;
-    const updated = await meta.saveIf({ branch: { name: branchContext.branch.name, status: 'editing' } }, (existing) => {
+    const updated = await meta.saveIf({
+        branch: {
+            name: branchContext.branch.name,
+            status: 'editing',
+            review: reviewBy(req.user, 'changes-requested'),
+        },
+    }, (existing) => {
         found = existing?.branch.status;
         return canRequestChangesFrom(found);
     });
@@ -70,9 +89,12 @@ const requestChangesHandler = async (gc, ctx, req, _params, body) => {
             console.error(`CanopyCMS: Failed to save the request-changes note for ${branchContext.branch.name}:`, getErrorMessage(err));
             warning = NOTE_NOT_SAVED_WARNING;
         }
-        if (!warning)
-            await syncPrComments(ctx, { ...branchContext, branch: updated.branch });
     }
+    // After the save and the note, which the PR body renders from, so one update carries both; the
+    // draft conversion above never writes the body. The branch is the one the status write returned:
+    // the guard read it earlier, and on the queued path the worker can record the PR's number in
+    // between. Best-effort: syncPrComments only logs failures.
+    await syncPrComments(ctx, { ...branchContext, branch: updated.branch });
     return {
         ok: true,
         status: 200,
@@ -110,12 +132,21 @@ const approveBranchHandler = async (gc, ctx, req, _params) => {
     const meta = getBranchMetadataFileManager(branchContext.branchRoot, branchContext.baseRoot);
     // As for request changes, the status on disk decides, in the step that writes.
     let found;
-    const updated = await meta.saveIf({ branch: { name: branchContext.branch.name, status: 'approved' } }, (existing) => {
+    const updated = await meta.saveIf({
+        branch: {
+            name: branchContext.branch.name,
+            status: 'approved',
+            review: reviewBy(req.user, 'approved'),
+        },
+    }, (existing) => {
         found = existing?.branch.status;
         return found === 'submitted';
     });
     if (!updated)
         return approveConflict(found);
+    // Against the branch the save returned, as for request changes. Best-effort: syncPrComments
+    // only logs failures.
+    await syncPrComments(ctx, { ...branchContext, branch: updated.branch });
     return {
         ok: true,
         status: 200,

package/dist/api/branch-status.js

@@ -14,6 +14,7 @@ import { ContentWriteLockBusyError } from '../utils/content-write-lock.js';
 import { submissionEditorFromUser } from '../submission-attribution.js';
 import { NothingToSubmitError } from '../services.js';
 import { baseBranchOf } from '../utils/base-branch.js';
+import { shortNameOf } from '../branch-param.js';
 import { resolveEditorUrl } from '../editor-url.js';
 const getBranchStatusHandler = async (gc, ctx, req, _params) => {
     const { branchContext } = gc;
@@ -103,6 +104,7 @@ const submitBranchForMergeHandler = async (gc, ctx, req, _params, body) => {
         if (err instanceof NothingToSubmitError) {
             return { ok: false, status: 400, error: err.message };
         }
+        const shortName = shortNameOf(ctx.services.config, branchContext.branch.name);
         // Retriable either way: a resubmit commits nothing new and pushes only
         // what has not reached the remote.
         if (err instanceof ContentWriteLockBusyError) {
@@ -110,8 +112,8 @@ const submitBranchForMergeHandler = async (gc, ctx, req, _params, body) => {
                 ok: false,
                 status: 409,
                 error: err.outcome === 'not-run'
-                    ? `Could not submit "${branchContext.branch.name}" right now: it is being synced with its base branch, or a save is in flight. Nothing was submitted; try again in a moment.`
-                    : `"${branchContext.branch.name}" was being synced while it was submitted, so the submit may not have completed. Try submitting again.`,
+                    ? `Could not submit "${shortName}" right now: it is being synced with its base branch, or a save is in flight. Nothing was submitted; try again in a moment.`
+                    : `"${shortName}" was being synced while it was submitted, so the submit may not have completed. Try submitting again.`,
             };
         }
         const message = getErrorMessage(err);
@@ -137,7 +139,7 @@ const submitBranchForMergeHandler = async (gc, ctx, req, _params, body) => {
             return {
                 ok: false,
                 status: 409,
-                error: `Could not submit "${branchContext.branch.name}": it has diverged from the copy in ` +
+                error: `Could not submit "${shortName}": it has diverged from the copy in ` +
                     `this deployment's repository and needs to be reconciled before it can be submitted. ` +
                     `The background worker reconciles branches when the base branch moves, so this often ` +
                     `clears on its own within a few minutes -- try again shortly, and ask an administrator ` +
@@ -150,6 +152,13 @@ const submitBranchForMergeHandler = async (gc, ctx, req, _params, body) => {
             error: `Failed to push branch changes: ${sanitizeErrorMessage(message)}`,
         };
     }
+    // The verdict covers one submit. It is cleared on disk before the PR is written, because a
+    // comment sync between that write and the status save below renders the PR body from disk and
+    // would otherwise put the last round's verdict back on the new body.
+    const meta = getBranchMetadataFileManager(branchContext.branchRoot, branchContext.baseRoot);
+    if (branchContext.branch.review) {
+        await meta.save({ branch: { name: branchContext.branch.name, review: undefined } });
+    }
     // Create or update PR (sync via githubService, or async via task queue)
     const submittedAt = new Date().toISOString();
     const editorUrl = submitEditorUrl(ctx, req, body?.editorUrl);
@@ -161,7 +170,6 @@ const submitBranchForMergeHandler = async (gc, ctx, req, _params, body) => {
         editorUrl,
         submittedAt,
     });
-    const meta = getBranchMetadataFileManager(branchContext.branchRoot, branchContext.baseRoot);
     const pushed = prResult.pushedToGitHub ? { pushedToGitHubAt: submittedAt } : {};
     // GitHub found nothing between the pushed branch and its base, though the diff above found
     // changes: GitHub's base can already hold them, or the diff could not be computed. The branch
@@ -172,7 +180,7 @@ const submitBranchForMergeHandler = async (gc, ctx, req, _params, body) => {
         return {
             ok: false,
             status: 400,
-            error: new NothingToSubmitError(branchContext.branch.name, base).message,
+            error: new NothingToSubmitError(shortNameOf(ctx.services.config, branchContext.branch.name), base).message,
         };
     }
     const updated = await meta.save({
@@ -191,6 +199,7 @@ const submitBranchForMergeHandler = async (gc, ctx, req, _params, body) => {
             // pre-submit rebase-failure record would otherwise stick as a stale
             // warning through review and archive.
             rebaseFailure: undefined,
+            review: undefined,
         },
     });
     return {

package/dist/api/branch-withdraw.js

@@ -4,6 +4,7 @@ import { getBranchMetadataFileManager } from '../branch-metadata.js';
 import { defineEndpoint } from './route-builder.js';
 import { canPerformWorkflowAction, getBranchProtection } from '../authorization/index.js';
 import { syncConvertToDraft } from './github-sync.js';
+import { syncPrComments } from './pr-comment-sync.js';
 const withdrawBranchHandler = async (gc, ctx, req, _params) => {
     const { branchContext } = gc;
     // Check if user can perform workflow actions (creator OR ACL access). On the
@@ -53,11 +54,17 @@ const withdrawBranchHandler = async (gc, ctx, req, _params) => {
         branch: {
             name: branchContext.branch.name,
             status: 'editing',
+            // A verdict covers one submit; the next review starts blank.
+            review: undefined,
             ...(wasClosed
                 ? { pullRequestState: undefined, pullRequestNumber: undefined, pullRequestUrl: undefined }
                 : {}),
         },
     });
+    // The PR body still says "Approved" until it is re-rendered from the cleared review.
+    // Against the branch the save returned, so a PR number recorded since the guard read is seen.
+    // Best-effort: syncPrComments logs its failures and never throws.
+    await syncPrComments(ctx, { ...branchContext, branch: updated.branch });
     return {
         ok: true,
         status: 200,

package/dist/api/branch.d.ts

@@ -15,7 +15,13 @@ import type { UserProfile } from '../auth/types.js';
  * rather than silently behaving as if nothing changed. That is by design:
  * wire compatibility here means "doesn't break", not "behaves the same".
  */
-export interface BranchListItem extends BranchMetadata {
+export interface BranchListItem extends Omit<BranchMetadata, 'review'> {
+    /**
+     * What pull request links carry for this branch, which `?branch=` and the `/:branch` segment
+     * accept beside `name` (branch-param.ts's `shortNameOf`): `name` less the namespace for a branch
+     * in it, else the full `name`.
+     */
+    shortName?: string;
     isProtected?: boolean;
     readOnly?: boolean;
     /**
@@ -152,6 +158,12 @@ export interface CreateBranchBody {
  * dev-mode refreshActiveBranch() updates are reflected.
  */
 export declare const toBranchListItem: (config: ApiContext["services"]["config"], branch: BranchMetadata, viewer: CanopyUser) => BranchListItem;
+/**
+ * The API's static top-level route segments, which the router ranks above `/:branch`, so a branch
+ * whose short name is one would be shadowed. `http/router.test.ts` holds this list to the router.
+ * @internal Exported for tests.
+ */
+export declare const TOP_LEVEL_ROUTE_SEGMENTS: readonly string[];
 /** @internal Exported for tests. */
 export declare const createBranchHandler: (ctx: ApiContext, req: ApiRequest, body: z.infer<typeof createBranchBodySchema>) => Promise<BranchListItemResponse>;
 /** @internal Exported for tests. */