canopycms 0.0.67 → 0.0.68-int.93

package/dist/services.js

@@ -9,8 +9,12 @@ import { operatingStrategy } from './operating-mode/index.js';
 import { BranchSchemaCache } from './branch-schema-cache.js';
 import { enqueueTask } from './task-queue/cms-task-queue.js';
 import { getTaskQueueDir } from './task-queue/task-queue-config.js';
-import { detectHeadBranch } from './utils/git.js';
+import { detectHeadBranch, isCanopyInternalPath } from './utils/git.js';
 import { readsFromCheckout } from './build-mode.js';
+import { timeRequestPhase } from './utils/request-timing.js';
+import { BRANCH_META_DIR } from './branch-metadata-file.js';
+import { appendTrailers, buildEditorTrailers, } from './submission-attribution.js';
+import { getErrorMessage, redactCredentials } from './utils/error.js';
 /**
  * A per-instance active-branch detector with its own 5s TTL cache, in priority
  * order: an explicitly configured value; `defaultBaseBranch ?? 'main'` with no
@@ -97,7 +101,7 @@ async function _createCanopyServicesInternal(config, options) {
     const branchSchemaCache = options.branchSchemaCache ?? new BranchSchemaCache(config.mode);
     const checkBranchAccess = createCheckBranchAccess(config.defaultBranchAccess ?? 'deny', config);
     // Content access loads permissions dynamically from the settings branch (orphan git branch)
-    const getSettingsBranchRoot = options.getSettingsBranchRoot ??
+    const ensureSettingsBranchRoot = options.getSettingsBranchRoot ??
         (async () => {
             const strategy = operatingStrategy(config.mode);
             const settingsRoot = strategy.getSettingsRoot();
@@ -111,9 +115,10 @@ async function _createCanopyServicesInternal(config, options) {
             });
             return settingsRoot;
         });
+    const getSettingsBranchRoot = () => timeRequestPhase('settingsRoot', ensureSettingsBranchRoot);
     const contentAccessDeps = {
         checkBranchAccess,
-        loadPathPermissions,
+        loadPathPermissions: (repoRoot, mode) => timeRequestPhase('permissions', () => loadPathPermissions(repoRoot, mode)),
         defaultPathAccess: config.defaultPathAccess ?? 'deny',
         mode: config.mode,
         getSettingsBranchRoot,
@@ -164,15 +169,36 @@ async function _createCanopyServicesInternal(config, options) {
         // and success is reported though the commit never reached the remote. Push
         // whenever there is something new to send — we just committed, or the local
         // branch already had unpushed commits from an earlier attempt.
+        // canopycms's own state under .canopy-meta/ is never content, so it neither
+        // makes a commit worth creating nor gets staged into one.
         let committed = false;
-        if (status.files.length > 0) {
-            await git.add('.');
-            await git.commit(options.message ?? `Submit ${options.context.branch.name}`);
+        if (status.files.some((f) => !isCanopyInternalPath(f.path))) {
+            await git.addAllExceptCanopyState();
+            const trailers = buildEditorTrailers(options.submitter ? [options.submitter] : [], {
+                editedBy: config.gitEditedByTrailers ?? true,
+                coAuthoredBy: config.gitCoAuthoredByTrailers ?? false,
+            });
+            await git.commit(appendTrailers(options.message ?? `Submit ${options.context.branch.name}`, trailers));
             committed = true;
         }
         if (committed || (await git.hasUnpushedCommits(options.context.branch.name))) {
             await git.push(options.context.branch.name);
         }
+        // The list only feeds the PR body, so a failure to compute it falls back to
+        // this submit's own working-tree changes rather than failing a submit that
+        // has already been pushed.
+        let changedPaths;
+        try {
+            changedPaths = await git.listChangedPathsSinceBase();
+        }
+        catch (err) {
+            console.warn(`CanopyCMS: Could not list the changes on ${options.context.branch.name} against its base; ` +
+                "the PR body lists only this submit's changes:", redactCredentials(getErrorMessage(err)));
+            changedPaths = status.files.map((f) => f.path);
+        }
+        return {
+            changedPaths: changedPaths.filter((p) => !p.startsWith(`${BRANCH_META_DIR}/`)),
+        };
     };
     // Must be initialized before closures that reference it (commitToSettingsBranch)
     let githubService;
@@ -233,57 +259,31 @@ async function _createCanopyServicesInternal(config, options) {
                     error: error instanceof Error ? error.message : 'Push failed',
                 };
             }
-            // Create or update PR — dual-path like content branches (api/github-sync.ts)
-            if (options.createPR !== false) {
-                // Permissions and groups are read live from the settings workspace
-                // (getSettingsBranchRoot), never from this PR's base branch, so the
-                // change took effect when it was committed and pushed above, before
-                // this PR existed. Merging re-activates nothing; it only records the
-                // change on `base` for review and audit history.
-                const settingsPRBody = 'Automated PR for permission and group changes. These changes already took ' +
-                    'effect in the CMS when they were saved — merging this PR does not change ' +
-                    "what's live; it only records the change here for review and audit history.";
-                // Direct path: githubService available (has internet)
-                if (githubService) {
-                    let prUrl;
-                    try {
-                        // Settings-branch PRs never pass markReadyIfDraft: a settings sync
-                        // has no explicit "submit for review" step the way a content submit
-                        // does, so an existing draft PR stays draft until an admin says so.
-                        const result = await githubService.createOrUpdatePR({
-                            head: settingsBranch,
-                            base: config.defaultBaseBranch ?? 'main',
-                            title: 'Update permissions and groups',
-                            body: settingsPRBody,
-                        });
-                        prUrl = result.url;
-                    }
-                    catch (err) {
-                        console.warn('Failed to create/update PR:', err);
-                        return { committed: true, pushed: true, syncStatus: 'sync-failed' };
-                    }
-                    return { committed: true, pushed: true, prUrl, syncStatus: 'synced' };
-                }
-                // Async path: queue task for worker (prod Lambda has no internet)
-                const taskDir = getTaskQueueDir(config);
-                try {
-                    await enqueueTask(taskDir, {
-                        action: 'push-and-create-or-update-pr',
-                        payload: {
-                            branch: settingsBranch,
-                            baseBranch: config.defaultBaseBranch ?? 'main',
-                            title: 'Update permissions and groups',
-                            body: settingsPRBody,
-                        },
-                    });
-                    return { committed: true, pushed: true, syncStatus: 'pending-sync' };
-                }
-                catch (err) {
-                    console.warn('Failed to enqueue settings PR task:', err);
-                    return { committed: true, pushed: true, syncStatus: 'sync-failed' };
-                }
+            // The settings branch is an orphan: it shares no history with the base
+            // branch, so GitHub rejects a PR for it. The change took effect when it
+            // was committed and pushed above (permissions and groups are read live
+            // from the settings workspace); the only GitHub step is mirroring the
+            // branch, so there is never a PR.
+            if (!operatingStrategy(mode).supportsPullRequests()) {
+                return { committed: true, pushed: true };
+            }
+            // With a githubService the push above already reached GitHub: both it and
+            // the workspace remote come from `defaultRemoteUrl`. Without one (prod
+            // Lambda has no internet) the worker pushes it.
+            if (githubService) {
+                return { committed: true, pushed: true, syncStatus: 'synced' };
+            }
+            try {
+                await enqueueTask(getTaskQueueDir(config), {
+                    action: 'push-branch',
+                    payload: { branch: settingsBranch },
+                });
+                return { committed: true, pushed: true, syncStatus: 'pending-sync' };
+            }
+            catch (err) {
+                console.warn('Failed to enqueue settings push task:', err);
+                return { committed: true, pushed: true, syncStatus: 'sync-failed' };
             }
-            return { committed: true, pushed: true };
         }
         catch (error) {
             return {

package/dist/settings-workspace.js

@@ -9,6 +9,35 @@ const log = createDebugLogger({ prefix: 'SettingsWorkspace' });
 // In-memory lock against concurrent init within one process. One lock suffices,
 // unlike content branches, which need one per branch.
 let settingsInitLock = null;
+/**
+ * Settings workspaces this process has fully ensured, keyed by {@link ensuredKey}. A hit
+ * skips the guard, the init lock and initializeWorkspace's dozen git subprocesses, which
+ * otherwise ran on every API request. It is sound because that pass never fetched, pulled or
+ * reset the settings branch, so settings freshness never came from it: every process reads the
+ * one shared workspace. Everything it verified is fixed for the process: the settings-branch name resolves once
+ * from config, the remote URL comes from config, and nothing in CanopyCMS checks the settings
+ * workspace out onto another branch. groups.json and permissions.json are still read from
+ * disk on every request; only the provisioning is memoized. Failures are never recorded. In
+ * dev, a hit also skips re-seeding a deleted `.canopy-dev/remote.git`; a dev-server restart
+ * re-seeds it.
+ *
+ * A hit still reads `.git/HEAD`, so a workspace removed, re-cloned onto another branch, or
+ * caught mid-clone by another process (HEAD still on the base branch) misses and runs the full
+ * path, guard and lock included.
+ */
+const ensuredSettingsWorkspaces = new Set();
+function ensuredKey(options) {
+    return `${path.resolve(options.settingsRoot)}\0${options.branchName}`;
+}
+async function checkedOutOn(settingsRoot, branchName) {
+    try {
+        const head = await fs.readFile(path.join(settingsRoot, '.git', 'HEAD'), 'utf-8');
+        return head.trim() === `ref: refs/heads/${branchName}`;
+    }
+    catch {
+        return false;
+    }
+}
 const SETTINGS_INIT_LOCK_DIR = '.settings-init';
 const SETTINGS_INIT_LOCK_NAME = 'lock';
 /**
@@ -122,6 +151,12 @@ export class SettingsWorkspaceManager {
         this.config = config;
     }
     async ensureGitWorkspace(options) {
+        const key = ensuredKey(options);
+        if (ensuredSettingsWorkspaces.has(key)) {
+            if (await checkedOutOn(options.settingsRoot, options.branchName))
+                return;
+            ensuredSettingsWorkspaces.delete(key);
+        }
         return log.timed('workspace', 'ensureGitWorkspace', async () => {
             // Layer 1: In-memory lock (prevents redundant async calls within same process)
             if (settingsInitLock) {
@@ -170,6 +205,7 @@ export class SettingsWorkspaceManager {
                             gitBotAuthorName: this.config.gitBotAuthorName,
                             gitBotAuthorEmail: this.config.gitBotAuthorEmail,
                         });
+                        ensuredSettingsWorkspaces.add(key);
                     }
                     finally {
                         try {

package/dist/static/seo.d.ts

@@ -9,14 +9,14 @@
  * entry-schema.ts, which builds a schema group from these same names so the schema side and
  * the read side cannot drift.
  */
-import { isAbsoluteUrl, stripTrailingSlashes } from '../utils/url-prefix.js';
+import { isAbsoluteUrl, stripTrailingSlashes, withTrailingSlash } from '../utils/url-prefix.js';
 /**
  * Re-exported so this module's public surface (and `canopycms/server`'s, via `static/index.ts`)
  * is unchanged by their move to `utils/url-prefix.ts` — where they now sit beside
  * `joinUrlPrefix`, the shared join that `assets/asset-url.ts` also needs and that must not
  * import anything under `static/`.
  */
-export { isAbsoluteUrl, stripTrailingSlashes };
+export { isAbsoluteUrl, stripTrailingSlashes, withTrailingSlash };
 /** og:type values covered by the recommended group. */
 export type SeoOgType = 'website' | 'article' | 'profile';
 /** twitter:card values covered by the recommended group. */
@@ -87,18 +87,6 @@ export declare function extractSeoFields(entryData: unknown, opts?: ExtractSeoFi
  * resolves for anyone holding the link.
  */
 export declare function isNoindexEntry(entryData: unknown, opts?: SeoFieldLocation): boolean;
-/**
- * Append a trailing slash to a site-relative path, matching a site that serves `/contact/`.
- *
- * Leaves the root (`/`) and file-like paths (a last segment containing a dot, e.g.
- * `/blog/rss.xml`) alone, and never doubles an existing slash.
- *
- * A query string and/or fragment (`?page=2`, `#section`) is split off BEFORE the slash decision
- * and placement, then reattached after — so `/blog?page=2` becomes `/blog/?page=2`, never
- * `/blog?page=2/` (a literal trailing slash inside the query string, which is not what "serve
- * with a trailing slash" means and breaks the URL).
- */
-export declare function withTrailingSlash(path: string): string;
 export interface ResolveSeoUrlOptions {
     /** Site origin (e.g. `https://example.com`). Trailing slashes are stripped. */
     siteUrl?: string;

package/dist/static/seo.js

@@ -9,14 +9,14 @@
  * entry-schema.ts, which builds a schema group from these same names so the schema side and
  * the read side cannot drift.
  */
-import { isAbsoluteUrl, joinUrlPrefix, stripTrailingSlashes, toSameOriginPath, } from '../utils/url-prefix.js';
+import { isAbsoluteUrl, joinUrlPrefix, stripTrailingSlashes, toSameOriginPath, withTrailingSlash, } from '../utils/url-prefix.js';
 /**
  * Re-exported so this module's public surface (and `canopycms/server`'s, via `static/index.ts`)
  * is unchanged by their move to `utils/url-prefix.ts` — where they now sit beside
  * `joinUrlPrefix`, the shared join that `assets/asset-url.ts` also needs and that must not
  * import anything under `static/`.
  */
-export { isAbsoluteUrl, stripTrailingSlashes };
+export { isAbsoluteUrl, stripTrailingSlashes, withTrailingSlash };
 /**
  * The recommended SEO field names. `defineSeoFieldGroup()` emits a schema group using exactly
  * these names, so an adopter who uses both ends needs no configuration at all.
@@ -106,29 +106,6 @@ export function extractSeoFields(entryData, opts = {}) {
 export function isNoindexEntry(entryData, opts = {}) {
     return extractSeoFields(entryData, opts).noindex === true;
 }
-/**
- * Append a trailing slash to a site-relative path, matching a site that serves `/contact/`.
- *
- * Leaves the root (`/`) and file-like paths (a last segment containing a dot, e.g.
- * `/blog/rss.xml`) alone, and never doubles an existing slash.
- *
- * A query string and/or fragment (`?page=2`, `#section`) is split off BEFORE the slash decision
- * and placement, then reattached after — so `/blog?page=2` becomes `/blog/?page=2`, never
- * `/blog?page=2/` (a literal trailing slash inside the query string, which is not what "serve
- * with a trailing slash" means and breaks the URL).
- */
-export function withTrailingSlash(path) {
-    const splitIndex = path.search(/[?#]/);
-    const base = splitIndex === -1 ? path : path.slice(0, splitIndex);
-    const suffix = splitIndex === -1 ? '' : path.slice(splitIndex);
-    const withLeading = base.startsWith('/') ? base : `/${base}`;
-    if (withLeading === '/' || withLeading.endsWith('/'))
-        return withLeading + suffix;
-    const lastSegment = withLeading.slice(withLeading.lastIndexOf('/') + 1);
-    if (lastSegment.includes('.'))
-        return withLeading + suffix;
-    return `${withLeading}/${suffix}`;
-}
 /**
  * Resolve a possibly-relative URL for public emission (canonical tag, sitemap URL, OG image).
  *

package/dist/submission-attribution.d.ts

@@ -0,0 +1,73 @@
+import type { CanopyUser } from './user.js';
+/**
+ * Who submitted (and edited) a branch, recorded in the submit commit's trailers
+ * and the pull request body. The bot stays the commit author; these records are
+ * the only place the editing user appears.
+ *
+ * Display names, ids and emails come from the auth provider and end up in git
+ * history and in GitHub-rendered Markdown, so each passes through a sanitizer
+ * below before it is written anywhere.
+ */
+export interface SubmissionEditor {
+    userId: string;
+    name?: string;
+    email?: string;
+}
+/**
+ * The PR body region canopycms owns. On update only the text between these
+ * markers is replaced, so anything a human wrote around it survives.
+ * @internal Exported for tests.
+ */
+export declare const PR_SECTION_START = "<!-- canopycms:submission:start -->";
+/** @internal Exported for tests. */
+export declare const PR_SECTION_END = "<!-- canopycms:submission:end -->";
+/**
+ * A display name safe for a single line of git trailer or Markdown, or undefined.
+ * @internal Exported for tests.
+ */
+export declare function sanitizeDisplayName(raw: string | undefined): string | undefined;
+/**
+ * The auth user id unchanged, or undefined if it holds characters unsafe to record.
+ * @internal Exported for tests.
+ */
+export declare function sanitizeUserId(raw: string | undefined): string | undefined;
+/**
+ * The email as given if it is a plain single-address email, otherwise undefined.
+ * @internal Exported for tests.
+ */
+export declare function sanitizeEmail(raw: string | undefined): string | undefined;
+/** The submitter as a SubmissionEditor, or undefined for an anonymous user. */
+export declare function submissionEditorFromUser(user: CanopyUser): SubmissionEditor | undefined;
+export interface CommitTrailerOptions {
+    /** One `Edited-by: Name (id)` per editor. */
+    editedBy: boolean;
+    /** One `Co-authored-by: Name <email>` per editor whose email is valid. */
+    coAuthoredBy: boolean;
+}
+/** Git trailer lines for the given editors, deduplicated by user id. */
+export declare function buildEditorTrailers(editors: readonly SubmissionEditor[], options: CommitTrailerOptions): string[];
+/**
+ * `subject`, then a blank line and the trailer block when there are trailers.
+ * Git reads trailers only from the last paragraph, so the blank line is what
+ * makes them trailers rather than part of the subject.
+ */
+export declare function appendTrailers(subject: string, trailers: readonly string[]): string;
+export interface PrSectionInput {
+    /** The branch description the editor wrote; free Markdown. */
+    description?: string;
+    submitter?: SubmissionEditor;
+    /** Editors other than the submitter, when known. */
+    editors?: readonly SubmissionEditor[];
+    /** Repo-relative paths changed on the branch. */
+    changedPaths: readonly string[];
+}
+/** The canopycms-owned PR body section, including its start and end markers. */
+export declare function buildPrSection(input: PrSectionInput): string;
+/**
+ * `existing` with its canopycms section replaced by `section`, keeping every
+ * character outside the markers. The section is the first end marker together
+ * with the nearest start marker before it, so a lone start marker a human quoted
+ * earlier in the body is skipped. With no such pair, stray markers are
+ * removed and `section` is appended after the human text.
+ */
+export declare function mergePrSection(existing: string | null | undefined, section: string): string;

package/dist/submission-attribution.js

@@ -0,0 +1,221 @@
+import { canopyLogWarn } from './utils/logger.js';
+const MAX_NAME_LENGTH = 80;
+const MAX_ID_LENGTH = 128;
+const MAX_EMAIL_LENGTH = 254;
+const MAX_DESCRIPTION_LENGTH = 10_000;
+const MAX_LISTED_ENTRIES = 100;
+/**
+ * The PR body region canopycms owns. On update only the text between these
+ * markers is replaced, so anything a human wrote around it survives.
+ * @internal Exported for tests.
+ */
+export const PR_SECTION_START = '<!-- canopycms:submission:start -->';
+/** @internal Exported for tests. */
+export const PR_SECTION_END = '<!-- canopycms:submission:end -->';
+// Cc (C0/C1 controls incl. newlines), Cf (zero-width and bidi overrides), Zl/Zp
+// (Unicode line/paragraph separators) can forge a trailer line or hide text; Cs
+// (a lone surrogate) reaches git as U+FFFD, since Node encodes it so.
+const INVISIBLE_OR_CONTROL = /[\p{Cc}\p{Cf}\p{Cs}\p{Zl}\p{Zp}]/gu;
+// `<>` would end a Co-authored-by email or open HTML / a section marker, `()`
+// would let a name forge the id that follows it, a backtick would close the
+// code span names render in, and a backslash is Markdown's escape character.
+const STRUCTURAL = /[<>()`\\]/g;
+function truncate(value, max) {
+    const chars = Array.from(value);
+    return chars.length > max ? `${chars.slice(0, max - 1).join('')}…` : value;
+}
+/**
+ * A changed path for a code span: only what could break out of the span or out
+ * of the section is removed, so `app/(group)/page.mdx` stays distinct from
+ * `app/page.mdx`. No NFKC, for the same reason.
+ */
+function cleanPath(raw) {
+    const cleaned = raw.replace(INVISIBLE_OR_CONTROL, ' ').replace(/[<>`]/g, '').trim();
+    return cleaned ? truncate(cleaned, 300) : undefined;
+}
+function cleanText(raw, max) {
+    if (raw === undefined)
+        return undefined;
+    const cleaned = raw
+        .normalize('NFKC')
+        .replace(INVISIBLE_OR_CONTROL, ' ')
+        .replace(STRUCTURAL, '')
+        .replace(/\s+/g, ' ')
+        .trim();
+    return cleaned ? truncate(cleaned, max) : undefined;
+}
+/**
+ * A display name safe for a single line of git trailer or Markdown, or undefined.
+ * @internal Exported for tests.
+ */
+export function sanitizeDisplayName(raw) {
+    return cleanText(raw, MAX_NAME_LENGTH);
+}
+// Ids and emails are accepted as the provider issued them or rejected, never
+// cleaned: cleaning could merge two users or attribute an edit to someone else.
+// A trailer still swaps in look-alikes for display (trailerText).
+const UNSAFE_VERBATIM_CHAR = /[\s\p{Cc}\p{Cf}\p{Cs}<>()`\\]/u;
+/**
+ * The auth user id unchanged, or undefined if it holds characters unsafe to record.
+ * @internal Exported for tests.
+ */
+export function sanitizeUserId(raw) {
+    if (!raw || Array.from(raw).length > MAX_ID_LENGTH || UNSAFE_VERBATIM_CHAR.test(raw))
+        return undefined;
+    return raw;
+}
+const EMAIL_SHAPE = /^[^\s@<>()"',;:\\[\]]+@[^\s@<>()"',;:\\[\]]+\.[^\s@<>()"',;:\\[\]]+$/;
+/**
+ * The email as given if it is a plain single-address email, otherwise undefined.
+ * @internal Exported for tests.
+ */
+export function sanitizeEmail(raw) {
+    if (raw === undefined)
+        return undefined;
+    const trimmed = raw.trim();
+    // `\s` misses most C0/C1 controls, and a NUL makes git's spawn throw. `#` is
+    // legal in an address but GitHub links `#12` in a commit message.
+    if (trimmed.length > MAX_EMAIL_LENGTH ||
+        UNSAFE_VERBATIM_CHAR.test(trimmed) ||
+        trimmed.includes('#'))
+        return undefined;
+    return EMAIL_SHAPE.test(trimmed) ? trimmed : undefined;
+}
+/** The submitter as a SubmissionEditor, or undefined for an anonymous user. */
+export function submissionEditorFromUser(user) {
+    if (user.type !== 'authenticated')
+        return undefined;
+    return { userId: user.userId, name: user.name, email: user.email };
+}
+function cleanEditors(editors) {
+    const seen = new Set();
+    const result = [];
+    for (const editor of editors) {
+        const userId = sanitizeUserId(editor.userId);
+        if (!userId) {
+            // The id itself stays out of the log: it is the unsafe value.
+            if (editor.userId) {
+                canopyLogWarn('CanopyCMS: Not recording an editor whose user id is unsafe to write to git');
+            }
+            continue;
+        }
+        if (seen.has(userId))
+            continue;
+        seen.add(userId);
+        result.push({
+            userId,
+            name: sanitizeDisplayName(editor.name),
+            email: sanitizeEmail(editor.email),
+        });
+    }
+    return result;
+}
+/**
+ * GitHub autolinks commit messages: `@user` mentions, `scheme://` URLs, and `#12` /
+ * `GH-12` issue references, which a closing keyword ("Closes #12") turns into an
+ * issue close once the commit reaches the default branch. A trailer value gets
+ * `@` and `#` swapped for look-alikes and the other two patterns broken. Its
+ * input is already single-line and structure-free.
+ */
+function trailerText(value) {
+    return value
+        .replace(/@/g, '＠')
+        .replace(/#/g, '＃')
+        .replace(/:\/\//g, ': //')
+        .replace(/\bGH-(?=\d)/gi, (m) => `${m.slice(0, 2)}‐`);
+}
+/** Git trailer lines for the given editors, deduplicated by user id. */
+export function buildEditorTrailers(editors, options) {
+    const trailers = [];
+    const clean = cleanEditors(editors);
+    if (options.editedBy) {
+        for (const editor of clean) {
+            trailers.push(editor.name
+                ? `Edited-by: ${trailerText(editor.name)} (${trailerText(editor.userId)})`
+                : `Edited-by: ${trailerText(editor.userId)}`);
+        }
+    }
+    if (options.coAuthoredBy) {
+        for (const editor of clean) {
+            if (!editor.email)
+                continue;
+            trailers.push(`Co-authored-by: ${trailerText(editor.name ?? editor.userId)} <${editor.email}>`);
+        }
+    }
+    return trailers;
+}
+/**
+ * `subject`, then a blank line and the trailer block when there are trailers.
+ * Git reads trailers only from the last paragraph, so the blank line is what
+ * makes them trailers rather than part of the subject.
+ */
+export function appendTrailers(subject, trailers) {
+    return trailers.length > 0 ? `${subject.trimEnd()}\n\n${trailers.join('\n')}` : subject;
+}
+/**
+ * Renders as inline code: GitHub neither autolinks, mentions nor interprets HTML
+ * inside a code span. The input is already free of backticks.
+ */
+function codeSpan(value) {
+    return `\`${value}\``;
+}
+/**
+ * Free Markdown with every HTML comment opener and closer escaped, so the text
+ * can neither close the canopycms section early nor open a comment that hides
+ * the rest of the body. Escaped comments render as their literal text.
+ */
+function neutralizeComments(text) {
+    return text.replace(/<!--/g, '&lt;!--').replace(/--!?>/g, '--&gt;');
+}
+function editorLabel(editor) {
+    return editor.name
+        ? `${codeSpan(editor.name)} (${codeSpan(editor.userId)})`
+        : codeSpan(editor.userId);
+}
+/** The canopycms-owned PR body section, including its start and end markers. */
+export function buildPrSection(input) {
+    const parts = [];
+    const [submitter] = input.submitter ? cleanEditors([input.submitter]) : [];
+    parts.push(submitter
+        ? `Submitted by ${editorLabel(submitter)} via CanopyCMS.`
+        : 'Submitted via CanopyCMS.');
+    const others = cleanEditors(input.editors ?? []).filter((e) => e.userId !== submitter?.userId);
+    if (others.length > 0) {
+        parts.push(`Also edited by: ${others.map(editorLabel).join(', ')}`);
+    }
+    const paths = [...new Set(input.changedPaths)]
+        .map(cleanPath)
+        .filter((p) => p !== undefined);
+    if (paths.length > 0) {
+        const listed = paths.slice(0, MAX_LISTED_ENTRIES).map((p) => `- ${codeSpan(p)}`);
+        if (paths.length > MAX_LISTED_ENTRIES) {
+            listed.push(`- …and ${paths.length - MAX_LISTED_ENTRIES} more`);
+        }
+        parts.push(`**Changed entries (${paths.length})**\n\n${listed.join('\n')}`);
+    }
+    // Last, so an unclosed fence or `<details>` in free Markdown cannot swallow
+    // the attribution above it.
+    const description = input.description?.trim();
+    if (description)
+        parts.push(neutralizeComments(truncate(description, MAX_DESCRIPTION_LENGTH)));
+    return `${PR_SECTION_START}\n${parts.join('\n\n')}\n${PR_SECTION_END}`;
+}
+/**
+ * `existing` with its canopycms section replaced by `section`, keeping every
+ * character outside the markers. The section is the first end marker together
+ * with the nearest start marker before it, so a lone start marker a human quoted
+ * earlier in the body is skipped. With no such pair, stray markers are
+ * removed and `section` is appended after the human text.
+ */
+export function mergePrSection(existing, section) {
+    const body = existing ?? '';
+    for (let end = body.indexOf(PR_SECTION_END); end >= 0;) {
+        const start = body.lastIndexOf(PR_SECTION_START, end - PR_SECTION_START.length);
+        if (start >= 0) {
+            return body.slice(0, start) + section + body.slice(end + PR_SECTION_END.length);
+        }
+        end = body.indexOf(PR_SECTION_END, end + PR_SECTION_END.length);
+    }
+    const human = body.split(PR_SECTION_START).join('').split(PR_SECTION_END).join('').trimEnd();
+    return human ? `${human}\n\n${section}` : section;
+}

package/dist/sync-core.js

@@ -8,6 +8,7 @@ import path from 'node:path';
 import { simpleGit } from 'simple-git';
 import { invalidateBranchContentCaches } from './content-index-generation.js';
 import { filePathExists } from './utils/fs.js';
+import { isCanopyInternalPath, stageAllExceptCanopyState } from './utils/git.js';
 /** Git tag marking the last known sync point, used as the merge base for `sync both` 3-way merges. */
 export const SYNC_BASE_TAG = 'canopycms-sync-base';
 /** Validate that a resolved path stays within the expected parent directory. */
@@ -154,15 +155,13 @@ export async function pushContentToWorkspace(options) {
     // The content dir was replaced wholesale, so ContentStore ID indexes rooted
     // at this workspace must be marked stale — in this process and (via the
     // on-disk generation marker) in every other process sharing the filesystem.
-    // Done in the finally AFTER the git add/commit below: the marker lives under
-    // .canopy-meta/ inside the clone, and writing it first would stage it into
-    // the sync commit via `add -A` (production workspaces git-exclude
-    // .canopy-meta/, but this function shouldn't depend on that).
+    // Done in the finally AFTER the git add/commit below, and staging skips
+    // .canopy-meta/, where the marker lives.
     try {
         const wsGit = simpleGit({ baseDir: branchPath });
-        await wsGit.add('-A');
-        const postStatus = await wsGit.status();
-        if (postStatus.files.length === 0) {
+        await stageAllExceptCanopyState(wsGit);
+        const staged = (await wsGit.status()).files.filter((f) => !isCanopyInternalPath(f.path));
+        if (staged.length === 0) {
             if (baseTag)
                 await wsGit.tag(['-f', baseTag]);
             return { fileCount: 0 };
@@ -170,7 +169,7 @@ export async function pushContentToWorkspace(options) {
         await wsGit.commit(commitMessage ?? 'sync: update content from working tree');
         if (baseTag)
             await wsGit.tag(['-f', baseTag]);
-        return { fileCount: postStatus.files.length };
+        return { fileCount: staged.length };
     }
     finally {
         await invalidateBranchContentCaches(branchPath);