canopycms 0.0.67 → 0.0.68-int.101

package/dist/api/client.d.ts

@@ -5,7 +5,7 @@
  * AUTO-GENERATED by scripts/generate-client.ts; do not edit this file manually
  * (changes will be overwritten), edit the generator's templates instead.
  */
-import type { BranchDeleteResponse, BranchListResponse, BranchResponse, CreateBranchBody, UpdateBranchAccessBody } from './branch.js';
+import type { BranchDeleteResponse, BranchListItemResponse, BranchListResponse, BranchResponse, CreateBranchBody, UpdateBranchAccessBody } from './branch.js';
 import type { BranchMergeResponse } from './branch-status.js';
 import type { AddCommentBody, AddCommentResponse, CommentsResponse, ResolveCommentResponse } from './comments.js';
 import type { ContentReadResponse, ContentWriteResponse, ReferenceValidationResponse, RenameEntryBody, RenameEntryResponse, ValidateReferencesBody, WriteContentBody } from './content.js';
@@ -25,6 +25,12 @@ export interface ApiClientOptions {
     baseUrl?: string;
     /** Custom fetch implementation, e.g. a mock in tests. */
     fetch?: typeof fetch;
+    /**
+     * End request paths with `/` (by `withTrailingSlash`'s rule), matching a Next host built with
+     * `trailingSlash: true`. Defaults to the value `withCanopy` inlines at build time (see
+     * `readTrailingSlashEnv`), else false.
+     */
+    trailingSlash?: boolean;
     /**
      * Called whenever a response comes back 401: the credential is no longer accepted. A
      * notification, not a retry; the editor's auth gate uses it to show sign-in.
@@ -44,12 +50,13 @@ export interface ApiClientOptions {
 export declare class CanopyApiClient {
     private baseUrl;
     private fetchFn;
+    private trailingSlash;
     private onUnauthorized;
     readonly branches: {
         /** GET /branches */
         list: () => Promise<BranchListResponse>;
         /** POST /branches */
-        create: (body: CreateBranchBody) => Promise<BranchResponse>;
+        create: (body: CreateBranchBody) => Promise<BranchListItemResponse>;
         /** DELETE /:branch */
         delete: (params: Record<string, string>) => Promise<BranchDeleteResponse>;
         /** PATCH /:branch/access */
@@ -57,17 +64,17 @@ export declare class CanopyApiClient {
     };
     readonly workflow: {
         /** POST /:branch/withdraw */
-        withdraw: (params: Record<string, string>) => Promise<BranchResponse>;
+        withdraw: (params: Record<string, string>) => Promise<BranchListItemResponse>;
         /** POST /:branch/request-changes */
-        requestChanges: (params: Record<string, string>) => Promise<BranchResponse>;
+        requestChanges: (params: Record<string, string>) => Promise<BranchListItemResponse>;
         /** POST /:branch/approve */
-        approve: (params: Record<string, string>) => Promise<BranchResponse>;
+        approve: (params: Record<string, string>) => Promise<BranchListItemResponse>;
         /** POST /:branch/mark-merged */
         markMerged: (params: Record<string, string>) => Promise<BranchMergeResponse>;
         /** GET /:branch/status */
         getStatus: (params: Record<string, string>) => Promise<BranchResponse>;
         /** POST /:branch/submit */
-        submit: (params: Record<string, string>) => Promise<BranchResponse>;
+        submit: (params: Record<string, string>) => Promise<BranchListItemResponse>;
     };
     readonly comments: {
         /** GET /:branch/comments */
@@ -179,5 +186,10 @@ export declare class CanopyApiClient {
     private buildPath;
     private request;
 }
+/**
+ * Whether `result` was converted from a body no CanopyCMS handler wrote (a proxy or CDN
+ * error page), so its status says nothing about the API itself.
+ */
+export declare function isNonApiResponse(result: object): boolean;
 /** Create a {@link CanopyApiClient}; pass a custom fetch for tests. */
 export declare function createApiClient(options?: ApiClientOptions): CanopyApiClient;

package/dist/api/client.js

@@ -6,6 +6,7 @@
  * (changes will be overwritten), edit the generator's templates instead.
  */
 import { computeContentSha256Hex } from './request-body-hash.js';
+import { readTrailingSlashEnv, withTrailingSlash } from '../utils/url-prefix.js';
 /**
  * Typed client for the CanopyCMS API: one method per endpoint, grouped by namespace, each
  * returning that endpoint's ApiResponse.
@@ -260,6 +261,7 @@ export class CanopyApiClient {
         this.baseUrl = options.baseUrl ?? '/api/canopycms';
         // An unbound fetch throws "Illegal invocation" in browsers; Node has no window.
         this.fetchFn = options.fetch ?? (typeof window !== 'undefined' ? fetch.bind(window) : fetch);
+        this.trailingSlash = options.trailingSlash ?? readTrailingSlashEnv();
         this.onUnauthorized = options.onUnauthorized;
     }
     buildPath(template, params) {
@@ -292,7 +294,7 @@ export class CanopyApiClient {
         return result;
     }
     async request(method, path, body, headers = {}) {
-        const url = `${this.baseUrl}${path}`;
+        const url = `${this.baseUrl}${this.trailingSlash ? withTrailingSlash(path) : path}`;
         const requestHeaders = {
             ...headers,
         };
@@ -324,21 +326,86 @@ export class CanopyApiClient {
         if (requestBody !== undefined) {
             init.body = requestBody;
         }
-        const response = await this.fetchFn(url, init);
+        let response = await this.fetchFn(url, init);
+        // A body from in front of the API (a proxy or CDN error page) may be empty, not JSON, or
+        // not an ApiResponse; every such body becomes an `ok: false` ApiResponse, never a throw.
+        let parsed = await response.json().catch(() => undefined);
+        // A 429 no handler wrote is a throttle in front of the API, such as Lambda's concurrency
+        // cap, which answers before the function runs. The request was never handled, so
+        // resending it is safe for writes too.
+        for (let attempt = 0; response.status === 429 && !isApiResponseBody(parsed); attempt++) {
+            const delay = throttleRetryDelayMs(response, attempt);
+            if (delay === undefined)
+                break;
+            await sleep(delay);
+            response = await this.fetchFn(url, init);
+            parsed = await response.json().catch(() => undefined);
+        }
         if (response.status === 401) {
             this.onUnauthorized?.();
-            // A 401 is an auth answer whatever its body: one from in front of the API (a proxy) may
-            // not be an ApiResponse, or not JSON. Always return it as one rather than throwing.
-            const body = await response.json().catch(() => undefined);
-            const error = typeof body === 'object' && body !== null && 'error' in body && typeof body.error === 'string'
-                ? body.error
-                : 'Unauthorized';
-            return { ok: false, status: 401, error };
+            return { ok: false, status: 401, error: errorFromBody(parsed) ?? 'Unauthorized' };
         }
-        const payload = await response.json();
-        // All responses use ApiResponse format: { ok, status, data?, error? }
-        return payload;
+        if (isApiResponseBody(parsed))
+            return parsed;
+        const converted = {
+            ok: false,
+            status: response.status,
+            error: errorFromBody(parsed) ?? `Unexpected response from server (HTTP ${response.status})`,
+        };
+        convertedResponses.add(converted);
+        return converted;
+    }
+}
+/**
+ * Base wait before each resend of a throttled request. A throttle from a burst of cold starts
+ * clears as they finish, so the waits span a few seconds.
+ */
+const THROTTLE_RETRY_DELAYS_MS = [250, 1000, 3000];
+/** The longest `Retry-After` honoured; a throttle asking for longer is reported, not resent. */
+const MAX_RETRY_AFTER_MS = 5000;
+/**
+ * The wait before resend `attempt`, or undefined when there is to be no resend: the attempts
+ * are used up, or `Retry-After` asks for longer than {@link MAX_RETRY_AFTER_MS}. The base delay,
+ * or `Retry-After` when longer, plus up to half the base again, so requests throttled in one
+ * burst do not resend in lockstep.
+ */
+function throttleRetryDelayMs(response, attempt) {
+    const base = THROTTLE_RETRY_DELAYS_MS[attempt];
+    if (base === undefined)
+        return undefined;
+    // Delta-seconds only; an HTTP-date or a blank value falls back to the base delay. A custom
+    // `fetch` option may return a Response-like without headers.
+    const header = response.headers?.get('retry-after')?.trim();
+    const retryAfter = header ? Number(header) : Number.NaN;
+    let wait = base;
+    if (Number.isFinite(retryAfter) && retryAfter >= 0) {
+        const ms = retryAfter * 1000;
+        if (ms > MAX_RETRY_AFTER_MS)
+            return undefined;
+        wait = Math.max(ms, base);
     }
+    return wait + Math.random() * base * 0.5;
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+const convertedResponses = new WeakSet();
+/**
+ * Whether `result` was converted from a body no CanopyCMS handler wrote (a proxy or CDN
+ * error page), so its status says nothing about the API itself.
+ */
+export function isNonApiResponse(result) {
+    return convertedResponses.has(result);
+}
+/** The `error` string of a JSON body, when it has one. */
+function errorFromBody(body) {
+    return typeof body === 'object' && body !== null && 'error' in body && typeof body.error === 'string'
+        ? body.error
+        : undefined;
+}
+/** Whether a parsed body has the `{ ok, status, ... }` shape every handler returns. */
+function isApiResponseBody(body) {
+    return typeof body === 'object' && body !== null && 'ok' in body && typeof body.ok === 'boolean';
 }
 /** Create a {@link CanopyApiClient}; pass a custom fetch for tests. */
 export function createApiClient(options) {

package/dist/api/content.d.ts

@@ -40,11 +40,12 @@ export interface WriteContentBody {
     data?: Record<string, unknown>;
     body?: string;
     /**
-     * OCC / create-intent token. Omit for a blind write (no opinion). A number
-     * from a prior read/write response rejects the write with 409 if the file
-     * has changed since. `null` means "this entry must not already exist" —
-     * the create path uses this so a create against an existing slug is
-     * rejected with 409 instead of silently overwriting it.
+     * OCC token. A number from a prior read/write response makes this an update,
+     * rejected with 409 if the file's mtime no longer matches (a file deleted
+     * since is written anew). `null` or omitted makes it
+     * a create, rejected with 409 if the entry already exists. There is no blind
+     * write: without a token, "no conflict detection" would be indistinguishable
+     * from "lost the token", so an update has to prove which version it read.
      */
     expectedVersion?: number | null;
 }

package/dist/api/content.js

@@ -5,7 +5,7 @@ import { ReferenceValidator } from '../validation/reference-validator.js';
 import { findUnknownKeys, mergeBodyIntoData, normalizeReferenceValues, validateEntryData, } from '../validation/entry-validator.js';
 import { validateEntryLinks } from '../validation/entry-link-validator.js';
 import { branchNameSchema, logicalPathSchema, slugSchema } from './validators.js';
-import { parseSlug } from '../paths/index.js';
+import { entryLogicalPath, parseSlug } from '../paths/index.js';
 import { getErrorMessage, isNotFoundError, sanitizeErrorMessage } from '../utils/error.js';
 import { isDataOnlyFormat } from '../utils/format.js';
 /**
@@ -52,7 +52,7 @@ const writeContentBodySchema = z.object({
     format: z.enum(['json', 'md', 'mdx', 'yaml']),
     data: boundedContentDataSchema.optional(),
     body: z.string().max(MAX_CONTENT_BODY_CHARS).optional(),
-    // null = create-intent ("must not already exist"); see WriteContentBody.
+    // null or omitted = create ("must not already exist"); see WriteContentBody.
     expectedVersion: z.number().nullish(),
 });
 const validateReferencesParamsSchema = z.object({
@@ -80,24 +80,27 @@ const readContentHandler = async (gc, ctx, req, params) => {
     const logicalPathSegments = parseApiPath(params.path, contentRoot);
     let schemaItem;
     let slug;
-    let relativePath;
     try {
         const resolved = store.resolvePath(logicalPathSegments);
         schemaItem = resolved.schemaItem;
         slug = resolved.slug;
-        const pathResult = await store.resolveDocumentPath(schemaItem.logicalPath, slug);
-        relativePath = pathResult.relativePath;
+        // Runs the store's slug and traversal checks before the permission check.
+        await store.resolveDocumentPath(schemaItem.logicalPath, slug);
     }
     catch (err) {
         const message = err instanceof ContentStoreError ? err.message : 'Invalid content request';
         return { ok: false, status: 400, error: sanitizeErrorMessage(message) };
     }
-    const access = await ctx.services.checkContentAccess(branchContext, branchContext.branchRoot, relativePath, req.user, 'read');
-    if (!access.allowed) {
+    // One checker for the entry and every reference target it resolves, so a reference cannot
+    // carry a target's data past the rules that would refuse a direct read of it.
+    const checkAccess = await ctx.services.createContentAccessChecker(branchContext, branchContext.branchRoot, req.user);
+    if (!checkAccess(entryLogicalPath(schemaItem.logicalPath, slug), 'read').allowed) {
         return { ok: false, status: 403, error: 'Forbidden' };
     }
     try {
-        const doc = await store.read(schemaItem.logicalPath, slug);
+        const doc = await store.read(schemaItem.logicalPath, slug, {
+            referenceAccess: (targetPath) => checkAccess(targetPath, 'read').allowed,
+        });
         return { ok: true, status: 200, data: doc };
     }
     catch (err) {
@@ -117,19 +120,18 @@ const writeContentHandler = async (gc, ctx, req, params, body) => {
     const logicalPathSegments = parseApiPath(params.path, contentRoot);
     let schemaItem;
     let slug;
-    let relativePath;
     try {
         const resolved = store.resolvePath(logicalPathSegments);
         schemaItem = resolved.schemaItem;
         slug = resolved.slug;
-        const pathResult = await store.resolveDocumentPath(schemaItem.logicalPath, slug);
-        relativePath = pathResult.relativePath;
+        // Runs the store's slug and traversal checks before the permission check.
+        await store.resolveDocumentPath(schemaItem.logicalPath, slug);
     }
     catch (err) {
         const message = err instanceof ContentStoreError ? err.message : 'Invalid content request';
         return { ok: false, status: 400, error: sanitizeErrorMessage(message) };
     }
-    const access = await ctx.services.checkContentAccess(branchContext, branchContext.branchRoot, relativePath, req.user, 'edit');
+    const access = await ctx.services.checkContentAccess(branchContext, branchContext.branchRoot, entryLogicalPath(schemaItem.logicalPath, slug), req.user, 'edit');
     if (!access.allowed) {
         return { ok: false, status: 403, error: 'Forbidden' };
     }
@@ -198,20 +200,21 @@ const writeContentHandler = async (gc, ctx, req, params, body) => {
     }
     const data = body.data ?? {};
     const isDataOnly = isDataOnlyFormat(body.format);
+    // The store's own `undefined` (blind write) is never reachable from here: an omitted token is
+    // a create, so an update that lost its token 409s instead of overwriting unchecked.
+    const expectedVersion = body.expectedVersion ?? null;
+    const createConflictError = body.expectedVersion === null
+        ? `An entry with slug "${slug}" already exists`
+        : `An entry with slug "${slug}" already exists; an update must send the expectedVersion from its last read`;
     try {
         const exists = await store.documentExists(schemaItem.logicalPath, slug);
-        // Create-intent guard: a create request (expectedVersion === null) against a slug that
-        // already has content must never silently overwrite it — short-circuit with 409 before field
-        // validation runs, so the error names the real problem instead of "field is required" or a
-        // bare conflict. store.write() re-enforces this itself inside its per-entry lock against a
-        // fresh stat (the race-safe authoritative check); this is just a cheaper fast path for the
-        // common case.
-        if (body.expectedVersion === null && exists) {
-            return {
-                ok: false,
-                status: 409,
-                error: `An entry with slug "${slug}" already exists`,
-            };
+        // Create guard: a create against a slug that already has content must never silently
+        // overwrite it — short-circuit with 409 before field validation runs, so the error names the
+        // real problem instead of "field is required" or a bare conflict. store.write() re-enforces
+        // this itself inside its per-entry lock against a fresh stat (the race-safe authoritative
+        // check); this is just a cheaper fast path for the common case.
+        if (expectedVersion === null && exists) {
+            return { ok: false, status: 409, error: createConflictError };
         }
         // [SLUG] Create-only routability check: `writeContentParamsSchema.path`'s `parseLogicalPath`
         // has no charset rule, and `ContentStore.resolvePath` only lowercases the slug — so this is
@@ -360,13 +363,13 @@ const writeContentHandler = async (gc, ctx, req, params, body) => {
             ? {
                 format: body.format,
                 data: normalizedData ?? {},
-                expectedVersion: body.expectedVersion,
+                expectedVersion,
             }
             : {
                 format: body.format,
                 data: normalizedData,
                 body: body.body ?? '',
-                expectedVersion: body.expectedVersion,
+                expectedVersion,
             };
         // Pass the resolved entryTypeName (not the raw, possibly-omitted
         // params.entryType) so the store's own format check agrees with the type
@@ -412,12 +415,8 @@ const writeContentHandler = async (gc, ctx, req, params, body) => {
             }
             // Race-safe fallback: the early `exists` check above catches the common case; this covers a
             // collision that lands between that check and store.write()'s in-lock stat.
-            if (body.expectedVersion === null) {
-                return {
-                    ok: false,
-                    status: 409,
-                    error: `An entry with slug "${slug}" already exists`,
-                };
+            if (expectedVersion === null) {
+                return { ok: false, status: 409, error: createConflictError };
             }
             return {
                 ok: false,
@@ -443,19 +442,19 @@ const validateReferencesHandler = async (gc, ctx, req, params, body) => {
     const contentRoot = ctx.services.config.contentRoot || 'content';
     const logicalPathSegments = parseApiPath(params.path, contentRoot);
     let schemaItem;
-    let relativePath;
+    let slug;
     try {
         const resolved = store.resolvePath(logicalPathSegments);
         schemaItem = resolved.schemaItem;
-        const slug = resolved.slug;
-        const pathResult = await store.resolveDocumentPath(schemaItem.logicalPath, slug);
-        relativePath = pathResult.relativePath;
+        slug = resolved.slug;
+        // Runs the store's slug and traversal checks before the permission check.
+        await store.resolveDocumentPath(schemaItem.logicalPath, slug);
     }
     catch (err) {
         const message = err instanceof ContentStoreError ? err.message : 'Invalid content request';
         return { ok: false, status: 400, error: sanitizeErrorMessage(message) };
     }
-    const access = await ctx.services.checkContentAccess(branchContext, branchContext.branchRoot, relativePath, req.user, 'read');
+    const access = await ctx.services.checkContentAccess(branchContext, branchContext.branchRoot, entryLogicalPath(schemaItem.logicalPath, slug), req.user, 'read');
     if (!access.allowed) {
         return { ok: false, status: 403, error: 'Forbidden' };
     }
@@ -510,22 +509,26 @@ const renameEntryHandler = async (gc, ctx, req, params, body) => {
     const logicalPathSegments = parseApiPath(params.path, contentRoot);
     let schemaItem;
     let currentSlug;
-    let relativePath;
     try {
         const resolved = store.resolvePath(logicalPathSegments);
         schemaItem = resolved.schemaItem;
         currentSlug = resolved.slug;
-        const pathResult = await store.resolveDocumentPath(schemaItem.logicalPath, currentSlug);
-        relativePath = pathResult.relativePath;
+        // Runs the store's slug and traversal checks before the permission check.
+        await store.resolveDocumentPath(schemaItem.logicalPath, currentSlug);
     }
     catch (err) {
         const message = err instanceof ContentStoreError ? err.message : 'Invalid content request';
         return { ok: false, status: 400, error: sanitizeErrorMessage(message) };
     }
-    const access = await ctx.services.checkContentAccess(branchContext, branchContext.branchRoot, relativePath, req.user, 'edit');
+    const access = await ctx.services.checkContentAccess(branchContext, branchContext.branchRoot, entryLogicalPath(schemaItem.logicalPath, currentSlug), req.user, 'edit');
     if (!access.allowed) {
         return { ok: false, status: 403, error: 'Forbidden' };
     }
+    // A rename creates the entry at its new path, so that path needs edit access too.
+    const destinationAccess = await ctx.services.checkContentAccess(branchContext, branchContext.branchRoot, entryLogicalPath(schemaItem.logicalPath, body.newSlug), req.user, 'edit');
+    if (!destinationAccess.allowed) {
+        return { ok: false, status: 403, error: 'Forbidden' };
+    }
     try {
         const result = await store.renameEntry(schemaItem.logicalPath, currentSlug, body.newSlug);
         return { ok: true, status: 200, data: { newPath: result.newPath } };

package/dist/api/entries.js

@@ -2,7 +2,7 @@ import path from 'node:path';
 import { z } from 'zod';
 import { BranchSyncingError, ContentConflictError, ContentStore, ContentStoreError, } from '../content-store.js';
 import { defineEndpoint } from './route-builder.js';
-import { normalizeFilesystemPath, parseSlug, parseLogicalPath } from '../paths/index.js';
+import { entryLogicalPath, normalizeFilesystemPath, parseSlug, parseLogicalPath } from '../paths/index.js';
 import { getErrorMessage, isNotFoundError, sanitizeErrorMessage } from '../utils/error.js';
 import { createDebugLogger } from '../utils/debug.js';
 import { resolveEntryTitle } from '../utils/title-field.js';
@@ -81,7 +81,7 @@ const listCollectionEntriesRecursive = async (root, targetPath, flatCollections)
 const filterWithAccessControl = (items, checkAccess, search) => {
     const results = [];
     for (const item of items) {
-        const readAccess = checkAccess(item.physicalPath, 'read');
+        const readAccess = checkAccess(item.logicalPath, 'read');
         if (!readAccess.allowed)
             continue;
         if (search) {
@@ -90,7 +90,7 @@ const filterWithAccessControl = (items, checkAccess, search) => {
                 continue;
         }
         // Compute edit access only for items that survive the read + search filters.
-        const editAccess = checkAccess(item.physicalPath, 'edit');
+        const editAccess = checkAccess(item.logicalPath, 'edit');
         results.push({ ...item, canEdit: editAccess.allowed });
     }
     return results;
@@ -255,11 +255,9 @@ const deleteEntryHandler = async (gc, ctx, req, params) => {
         };
     }
     const entrySlug = slugResult.slug;
-    // Resolve the real physical path before checking permissions
-    let physicalPath;
+    // Resolution runs the store's slug and traversal checks before the permission check.
     try {
-        const resolved = await contentStore.resolveDocumentPath(collectionLogicalPath, entrySlug);
-        physicalPath = resolved.relativePath;
+        await contentStore.resolveDocumentPath(collectionLogicalPath, entrySlug);
     }
     catch (err) {
         if (isNotFoundError(err)) {
@@ -272,7 +270,7 @@ const deleteEntryHandler = async (gc, ctx, req, params) => {
         }
         throw err;
     }
-    const editAccess = await ctx.services.checkContentAccess(branchContext, branchContext.branchRoot, physicalPath, req.user, 'edit');
+    const editAccess = await ctx.services.checkContentAccess(branchContext, branchContext.branchRoot, entryLogicalPath(collection.logicalPath, entrySlug), req.user, 'edit');
     if (!editAccess.allowed) {
         return {
             ok: false,
@@ -301,13 +299,16 @@ const deleteEntryHandler = async (gc, ctx, req, params) => {
                     // C6: order cleanup is best-effort hygiene after the entry is already deleted, so no
                     // failure here may turn an otherwise-successful delete into an error (a retry would
                     // just 404). Surface it as a warning instead (mirrors content.ts's `validationWarnings`).
-                    const reason = err instanceof SchemaStoreBusyError ? 'schema is busy' : getErrorMessage(err);
-                    log.warn('delete-entry', 'Skipped order cleanup', {
-                        collectionPath,
-                        contentId,
-                        error: getErrorMessage(err),
-                    });
-                    orderCleanupWarning = `Entry deleted, but the collection order list could not be updated (${sanitizeErrorMessage(reason)}); it will still list this entry until the next schema change.`;
+                    // An `'unknown'` outcome means the update ran to completion: nothing to warn of.
+                    if (!(err instanceof SchemaStoreBusyError && err.outcome === 'unknown')) {
+                        const reason = err instanceof SchemaStoreBusyError ? 'schema is busy' : getErrorMessage(err);
+                        log.warn('delete-entry', 'Skipped order cleanup', {
+                            collectionPath,
+                            contentId,
+                            error: getErrorMessage(err),
+                        });
+                        orderCleanupWarning = `Entry deleted, but the collection order list could not be updated (${sanitizeErrorMessage(reason)}); it will still list this entry until the next schema change.`;
+                    }
                 }
             }
         }

package/dist/api/github-sync.d.ts

@@ -1,5 +1,6 @@
 import type { ApiContext } from './types.js';
 import type { BranchContext, SyncStatus } from '../types.js';
+import { type SubmissionEditor } from '../submission-attribution.js';
 /**
  * The caller uses this to update branch metadata.
  */
@@ -8,12 +9,29 @@ export interface GitHubSyncResult {
     prNumber?: number;
     syncStatus?: SyncStatus;
 }
+/** What the PR body records about a submit. */
+export interface SubmissionRecord {
+    submitter?: SubmissionEditor;
+    changedPaths: readonly string[];
+}
 /**
  * Uses githubService directly if available, otherwise queues a task for the worker.
+ *
+ * The body is the canopycms PR section (submission-attribution.ts): an existing
+ * PR keeps whatever a human wrote outside it.
  */
-export declare function syncSubmitPr(ctx: ApiContext, context: BranchContext): Promise<GitHubSyncResult>;
+export declare function syncSubmitPr(ctx: ApiContext, context: BranchContext, submission: SubmissionRecord): Promise<GitHubSyncResult>;
 /**
  * Used by withdraw and request-changes. Uses githubService directly if
  * available, otherwise queues a task.
  */
 export declare function syncConvertToDraft(ctx: ApiContext, context: BranchContext): Promise<void>;
+/**
+ * Used by delete, after the local delete succeeded. Deletes the branch on GitHub when the CMS
+ * put it there: a content branch reaches GitHub only through submit, which always opens a PR,
+ * so a recorded PR number is the proof. Without one, a same-named GitHub branch is someone
+ * else's (the create-time collision check is best-effort) and is never touched.
+ *
+ * Returns a client-facing warning when the delete could not be done or queued; never throws.
+ */
+export declare function syncDeleteRemoteBranch(ctx: ApiContext, context: BranchContext): Promise<string | undefined>;

package/dist/api/github-sync.js

@@ -3,14 +3,23 @@ import { getTaskQueueDir } from '../task-queue/task-queue-config.js';
 import { clientOperatingStrategy } from '../operating-mode/index.js';
 import { getErrorMessage } from '../utils/error.js';
 import { sanitizeBranchName } from '../paths/branch-name.js';
+import { buildPrSection, mergePrSection } from '../submission-attribution.js';
+import { isRefAlreadyGoneError } from '../github-service.js';
 /**
  * Uses githubService directly if available, otherwise queues a task for the worker.
+ *
+ * The body is the canopycms PR section (submission-attribution.ts): an existing
+ * PR keeps whatever a human wrote outside it.
  */
-export async function syncSubmitPr(ctx, context) {
+export async function syncSubmitPr(ctx, context, submission) {
     const { githubService } = ctx.services;
     const mode = ctx.services.config.mode;
     const prTitle = context.branch.title || `Submit ${context.branch.name}`;
-    const prBody = context.branch.description || '';
+    const prSection = buildPrSection({
+        description: context.branch.description,
+        submitter: submission.submitter,
+        changedPaths: submission.changedPaths,
+    });
     // Target the fork point recorded at branch creation when available.
     const baseBranch = context.branch.baseBranch ?? ctx.services.config.defaultBaseBranch ?? 'main';
     if (!clientOperatingStrategy(mode).supportsPullRequests()) {
@@ -29,9 +38,12 @@ export async function syncSubmitPr(ctx, context) {
     if (githubService) {
         try {
             if (context.branch.pullRequestNumber) {
+                // Read before writing: the update keeps the human text around the
+                // canopycms section, and the same read says whether the PR is a draft.
+                const pr = await githubService.getPullRequest(context.branch.pullRequestNumber);
                 await githubService.updatePullRequest(context.branch.pullRequestNumber, {
                     title: prTitle,
-                    body: prBody,
+                    body: mergePrSection(pr.body, prSection),
                 });
                 // Best-effort draft->ready conversion. This branch updates a known
                 // PR number directly (not through createOrUpdatePR), so it doesn't
@@ -42,7 +54,6 @@ export async function syncSubmitPr(ctx, context) {
                 // consistent with createOrUpdatePullRequest's best-effort handling
                 // in github-service.ts.
                 try {
-                    const pr = await githubService.getPullRequest(context.branch.pullRequestNumber);
                     if (pr.draft) {
                         await githubService.convertToReady(context.branch.pullRequestNumber);
                     }
@@ -73,8 +84,9 @@ export async function syncSubmitPr(ctx, context) {
                     head: context.branch.name,
                     base: baseBranch,
                     title: prTitle,
-                    body: prBody,
+                    body: prSection,
                     markReadyIfDraft: true,
+                    mergeSectionIntoBody: true,
                 });
                 return {
                     prUrl: result.url,
@@ -105,13 +117,12 @@ export async function syncSubmitPr(ctx, context) {
         payload: {
             branch: context.branch.name,
             title: prTitle,
-            body: prBody,
+            body: prSection,
+            mergeSectionIntoBody: true,
             baseBranch,
             pullRequestNumber: context.branch.pullRequestNumber,
-            // Content submits are an explicit "ready for review" action — convert
-            // a pre-existing draft PR to ready, unlike the settings-branch sync
-            // path (services.ts commitToSettingsBranch), which enqueues the same
-            // action without this flag.
+            // A content submit is an explicit "ready for review" action: convert a
+            // pre-existing draft PR to ready.
             markReadyIfDraft: true,
         },
     });
@@ -146,6 +157,42 @@ export async function syncConvertToDraft(ctx, context) {
         });
     }
 }
+/**
+ * Used by delete, after the local delete succeeded. Deletes the branch on GitHub when the CMS
+ * put it there: a content branch reaches GitHub only through submit, which always opens a PR,
+ * so a recorded PR number is the proof. Without one, a same-named GitHub branch is someone
+ * else's (the create-time collision check is best-effort) and is never touched.
+ *
+ * Returns a client-facing warning when the delete could not be done or queued; never throws.
+ */
+export async function syncDeleteRemoteBranch(ctx, context) {
+    if (!context.branch.pullRequestNumber)
+        return undefined;
+    const { githubService } = ctx.services;
+    const branch = context.branch.name;
+    if (githubService) {
+        try {
+            await githubService.deleteBranch(branch);
+        }
+        catch (err) {
+            if (isRefAlreadyGoneError(err))
+                return undefined;
+            console.error(`CanopyCMS: Failed to delete GitHub branch for ${branch}:`, getErrorMessage(err));
+            return 'The branch could not be deleted on GitHub; delete it there by hand';
+        }
+        return undefined;
+    }
+    const mode = ctx.services.config.mode;
+    if (!clientOperatingStrategy(mode).supportsPullRequests())
+        return undefined;
+    const result = await enqueueGitHubTask(ctx, context, {
+        action: 'delete-remote-branch',
+        payload: { branch, pullRequestNumber: context.branch.pullRequestNumber },
+    });
+    return result.syncStatus === 'sync-failed'
+        ? 'Deleting the branch on GitHub could not be queued; delete it there by hand'
+        : undefined;
+}
 async function enqueueGitHubTask(ctx, context, task) {
     const taskDir = getTaskQueueDir(ctx.services.config);
     try {

package/dist/api/index.d.ts

@@ -1,5 +1,5 @@
 export type { ApiResponse, ApiRequest, ApiContext } from './types.js';
-export type { BranchResponse, BranchListResponse, BranchDeleteResponse, CreateBranchBody, UpdateBranchAccessBody, } from './branch.js';
+export type { BranchResponse, BranchListItemResponse, BranchListResponse, BranchDeleteResponse, CreateBranchBody, UpdateBranchAccessBody, } from './branch.js';
 export type { BranchMergeResponse } from './branch-merge.js';
 export type { CommentsResponse, AddCommentResponse, ResolveCommentResponse } from './comments.js';
 export type { EntriesResponse, ListEntriesResponse, CollectionItem, ListEntriesParams, DeleteEntryResponse, } from './entries.js';