canopycms 0.8.1 → 0.8.3

package/dist/cli/configured-asset-store.js

@@ -4,11 +4,11 @@
  * site's own dependencies, which a release job given `--bucket` does not have.
  */
 import path from 'node:path';
-import { createJiti } from 'jiti';
 import { z } from 'zod';
 import { createAssetStore } from '../assets/factory.js';
 import { mediaSchema } from '../config/schemas/media.js';
 import { operatingStrategy } from '../operating-mode/index.js';
+import { importSiteServerConfig } from './site-config.js';
 const serverConfigSchema = z.object({
     mode: z.enum(['prod', 'dev']),
     media: mediaSchema.optional(),
@@ -19,13 +19,7 @@ const serverConfigSchema = z.object({
  * local store, prod never does.
  */
 export async function loadConfiguredAssetStore(projectDir) {
-    const configPath = path.join(projectDir, 'canopycms.config.ts');
-    const jiti = createJiti(import.meta.url);
-    const mod = (await jiti.import(configPath));
-    const configExport = mod.default ?? mod.config ?? mod;
-    const server = typeof configExport === 'object' && configExport !== null && 'server' in configExport
-        ? configExport.server
-        : configExport;
+    const { configPath, server } = await importSiteServerConfig(projectDir);
     const parsed = serverConfigSchema.safeParse(server);
     if (!parsed.success) {
         throw new Error(`Invalid CanopyCMS config at ${configPath}: ${parsed.error.message}`);

package/dist/cli/generate-ai-content.js

@@ -4404,6 +4404,7 @@ init_error();
 import fs5 from "node:fs/promises";
 import path7 from "node:path";
 import { randomUUID } from "node:crypto";
+init_logger();
 var log4 = createDebugLogger({ prefix: "ResourceGeneration" });
 var META_DIR2 = ".canopy-meta";
 function resourceGenerationPath(root, resource) {
@@ -4415,9 +4416,7 @@ async function bumpResourceGeneration(root, resource, options) {
     await atomicWriteFile(resourceGenerationPath(root, resource), token);
     return token;
   } catch (err) {
-    log4.warn("generation", `Failed to bump ${resource} generation for ${root}`, {
-      error: getErrorMessage(err)
-    });
+    canopyLogWarn(`CanopyCMS: failed to bump ${resource} generation for ${root}:`, getErrorMessage(err));
     if (options?.mustSucceed)
       throw err;
     return null;
@@ -7848,9 +7847,20 @@ var branchMetadataShape = {
   mergedAt: z7.string().optional(),
   rebaseFailure: z7.object({ message: z7.string(), firstAt: z7.string(), lastAt: z7.string() }).optional(),
   historyRewrittenFrom: z7.string().optional(),
+  lastGitHubTip: z7.string().optional(),
+  keptOverGitHub: z7.array(z7.string()).optional(),
+  rewrittenOnGitHub: z7.string().optional(),
+  submitUnfinished: z7.boolean().optional(),
+  submitNotQueued: z7.boolean().optional(),
+  unpublishedAtMerge: z7.boolean().optional(),
   syncFailureReason: z7.string().optional(),
   editors: z7.array(z7.string()).optional(),
   uncommittedEditors: z7.array(z7.string()).optional(),
+  // Dropped when malformed: it only decorates the branch card, so it never fails a read.
+  pullRequestHold: z7.discriminatedUnion("kind", [
+    z7.object({ kind: z7.literal("conflicts") }),
+    z7.object({ kind: z7.literal("retargeted"), base: z7.string() })
+  ]).optional().catch(void 0),
   // Dropped when malformed: it only decorates the PR body, so it never fails a read.
   review: z7.object({
     state: z7.enum(["approved", "changes-requested"]),
@@ -10927,6 +10937,9 @@ async function loadOrCreateBranchContext(options) {
   });
 }
 
+// dist/system-users.js
+var AI_USER_ID = "canopycms-ai";
+
 // dist/ai/resolve-branch.js
 async function resolveBranchRoot(config) {
   if (readsFromCheckout(config)) {
@@ -10945,7 +10958,7 @@ async function resolveBranchRoot(config) {
     config: resolved,
     branchName: activeBranch,
     mode: config.mode,
-    createdBy: "canopycms-ai",
+    createdBy: AI_USER_ID,
     remoteUrl: config.defaultRemoteUrl
   });
   return context.branchRoot;

package/dist/cli/init.js

@@ -1207,7 +1207,7 @@ async function failTask(taskDir, taskId, error, logger = nullLogger) {
   });
   logger.debug("Failed task", { id: taskId, error });
 }
-async function retryTask(taskDir, taskId, error, logger = nullLogger) {
+async function retryTask(taskDir, taskId, error, logger = nullLogger, options = {}) {
   const processingPath = path6.join(taskDir, "processing", `${taskId}.json`);
   const pendingDir = path6.join(taskDir, "pending");
   const pendingPath = path6.join(pendingDir, `${taskId}.json`);
@@ -1228,7 +1228,7 @@ async function retryTask(taskDir, taskId, error, logger = nullLogger) {
     throw err;
   }
   const retryCount = (task.retryCount ?? 0) + 1;
-  const backoffMs = Math.min(5e3 * Math.pow(2, retryCount - 1), 6e4);
+  const backoffMs = options.delayMs ?? Math.min(5e3 * Math.pow(2, retryCount - 1), 6e4);
   task.status = "pending";
   task.retryCount = retryCount;
   task.retryAfter = new Date(Date.now() + backoffMs).toISOString();

package/dist/cli/site-config.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Imports a site's `canopycms.config.ts` for CLI commands that need it (`sync`, and
+ * `configured-asset-store.ts`). Importing runs the site's config and loads its own dependencies.
+ */
+/** The site's server config export (`server` of a split config, else the export itself). */
+export declare function importSiteServerConfig(projectDir: string): Promise<{
+    configPath: string;
+    server: unknown;
+}>;

package/dist/cli/site-config.js

@@ -0,0 +1,17 @@
+/**
+ * Imports a site's `canopycms.config.ts` for CLI commands that need it (`sync`, and
+ * `configured-asset-store.ts`). Importing runs the site's config and loads its own dependencies.
+ */
+import path from 'node:path';
+import { createJiti } from 'jiti';
+/** The site's server config export (`server` of a split config, else the export itself). */
+export async function importSiteServerConfig(projectDir) {
+    const configPath = path.join(projectDir, 'canopycms.config.ts');
+    const jiti = createJiti(import.meta.url);
+    const mod = (await jiti.import(configPath));
+    const configExport = mod.default ?? mod.config ?? mod;
+    const server = typeof configExport === 'object' && configExport !== null && 'server' in configExport
+        ? configExport.server
+        : configExport;
+    return { configPath, server };
+}

package/dist/cli/sync.js

@@ -16,13 +16,20 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 import { simpleGit } from 'simple-git';
 import * as p from '@clack/prompts';
+import { z } from 'zod';
+import { resolveBranchParam } from '../branch-param.js';
+import { readBranchMetadataFile } from '../branch-metadata-file.js';
+import { namesNoWorkspace, resolveBranchPath } from '../paths/branch.js';
+import { exactBranchName, exactBranchSegment, isExactBranchForm, parseBranchRef, } from '../paths/validation.js';
+import { getErrorMessage } from '../utils/error.js';
 import { filePathExists } from '../utils/fs.js';
-import { isCanopyInternalPath, stageAllExceptCanopyState } from '../utils/git.js';
+import { detectHeadBranch, isCanopyInternalPath, stageAllExceptCanopyState } from '../utils/git.js';
 import { assertWithinDir, copyDir, listFilesRecursive, pushContentToWorkspace, safeReplaceDir, SYNC_BASE_TAG, } from '../sync-core.js';
 import { invalidateBranchContentCaches } from '../content-index-generation.js';
 import { ContentWriteLockBusyError, withContentWriteLock } from '../utils/content-write-lock.js';
 import { ensureGitExcludePattern } from '../git-manager.js';
 import { operatingStrategy } from '../operating-mode/index.js';
+import { importSiteServerConfig } from './site-config.js';
 /**
  * Sync precondition failure (missing content dir, unknown branch, …).
  * Thrown so the CLI exits non-zero — scripts/CI must not sail past a
@@ -78,12 +85,183 @@ async function detectCurrentBranch(projectDir) {
         throw new Error('Detached HEAD — use --branch to specify a branch name');
     return branch;
 }
+/** The site config fields that decide which workspace a branch name names. */
+const branchConfigSchema = z.object({
+    branchNamespace: z.string().optional(),
+    deploymentName: z.string().optional(),
+    defaultBaseBranch: z.string().optional(),
+    defaultActiveBranch: z.string().optional(),
+});
+/** {@link branchConfigSchema}'s fields from the site config: none, with a warning, when unusable. */
+async function readBranchConfigFields(projectDir) {
+    if (!(await filePathExists(path.join(projectDir, 'canopycms.config.ts'))))
+        return {};
+    let why;
+    try {
+        const parsed = branchConfigSchema.safeParse((await importSiteServerConfig(projectDir)).server);
+        if (parsed.success)
+            return parsed.data;
+        why = parsed.error.message;
+    }
+    catch (err) {
+        why = getErrorMessage(err);
+    }
+    p.log.warn(`Could not use canopycms.config.ts (${why}); branch names resolve against the default branch settings.`);
+    return {};
+}
+/**
+ * The config {@link resolveBranchParam} resolves names against, built as the dev server builds
+ * it: dev mode, the site config's branch fields, and an unset base or active branch taken from the
+ * project's git HEAD (services.ts).
+ */
+async function loadBranchParamConfig(projectDir) {
+    const fields = await readBranchConfigFields(projectDir);
+    const head = await detectHeadBranch(projectDir, fields.defaultBaseBranch ?? 'main');
+    return {
+        ...fields,
+        mode: 'dev',
+        defaultBaseBranch: fields.defaultBaseBranch ?? head,
+        defaultActiveBranch: fields.defaultActiveBranch ?? head,
+    };
+}
+/**
+ * Refuses a directory that is not the top of its own git repository. Git run there would walk up
+ * to the developer's own repository and commit and tag in it.
+ */
+async function assertOwnRepository(branchPath) {
+    const top = await simpleGit({ baseDir: branchPath })
+        .revparse(['--show-toplevel'])
+        .then((out) => out.trim())
+        .catch(() => '');
+    if (top && (await fs.realpath(top)) === (await fs.realpath(branchPath)))
+        return;
+    throw new SyncError(`"${path.basename(branchPath)}" under content-branches/ is not a branch workspace: git does not report it as the top of its own repository.`);
+}
+/** The branch a workspace's HEAD is on (an unborn one included), or null when it is detached. */
+async function workspaceHead(branchPath) {
+    return simpleGit({ baseDir: branchPath })
+        .raw(['symbolic-ref', '--short', '-q', 'HEAD'])
+        .then((out) => out.trim() || null)
+        .catch(() => null);
+}
+/** The workspace at directory `key` under content-branches/, named by its branch.json or HEAD. */
+async function keyWorkspace(key, projectDir) {
+    const branchPath = path.join(operatingStrategy('dev').getContentBranchesRoot(projectDir), key);
+    await assertOwnRepository(branchPath);
+    const meta = await readBranchMetadataFile(branchPath);
+    return { branchName: meta?.branch.name ?? (await workspaceHead(branchPath)) ?? key, branchPath };
+}
+/** The ref `name` gives: decoded from the exact form (`~fix~x`), else `name` itself. */
+function refOf(name) {
+    if (!isExactBranchForm(name))
+        return name;
+    const ref = exactBranchName(name);
+    if (ref === null)
+        throw new SyncError(`"${name}" is not a valid branch name.`);
+    return ref;
+}
+/**
+ * The workspace `name` names, as the dev server resolves it, or null:
+ * 1. what the runtime resolves it to (`resolveBranchParam`): the ref, a namespace branch's short
+ *    name, or the exact form;
+ * 2. a workspace key, the directory itself;
+ * 3. the directory the ref keys to, when it holds a workspace sync built (no branch.json) on that
+ *    ref. Two refs can sanitize to one key, so one whose branch.json or HEAD names another branch
+ *    is refused.
+ * A `name` read from git HEAD (`byRef`) is a ref, never a short name or key: it resolves in its
+ * exact form and skips step 2, so a local branch never lands in an editor's branch or in another
+ * ref's workspace that shares its key.
+ */
+async function resolveSyncWorkspace(name, projectDir, keys, byRef) {
+    const config = await loadBranchParamConfig(projectDir);
+    const param = byRef ? exactBranchSegment(name) : name;
+    const resolved = await resolveBranchParam(param, config, { basePathOverride: projectDir }).catch((err) => {
+        if (namesNoWorkspace(err))
+            return null;
+        throw err;
+    });
+    if (resolved) {
+        // The base and active branch resolve by directory alone, without branch.json's name.
+        const ref = refOf(name);
+        if (resolved.branch.name !== ref && resolved.branchRoot === refKeyPath(ref, projectDir)) {
+            throw holdsAnotherBranch(resolved.branchRoot, resolved.branch.name, ref);
+        }
+        await assertOwnRepository(resolved.branchRoot);
+        return { branchName: resolved.branch.name, branchPath: resolved.branchRoot };
+    }
+    if (!byRef && keys.includes(name))
+        return keyWorkspace(name, projectDir);
+    const ref = refOf(name);
+    const branchPath = refKeyPath(ref, projectDir);
+    const present = await filePathExists(branchPath).catch((err) => {
+        if (namesNoWorkspace(err))
+            throw new SyncError(`"${ref}" cannot name a branch workspace.`);
+        throw err;
+    });
+    if (!present)
+        return null;
+    await assertOwnRepository(branchPath);
+    const meta = await readBranchMetadataFile(branchPath);
+    const holder = meta ? meta.branch.name : await workspaceHead(branchPath);
+    if (holder !== ref)
+        throw holdsAnotherBranch(branchPath, holder, ref);
+    return { branchName: ref, branchPath };
+}
+/** The refusal for a workspace another ref, sharing `ref`'s key, holds (`holder`; null: detached). */
+function holdsAnotherBranch(branchPath, holder, ref) {
+    // mergeIntoWorkspace's temporary branch, left checked out when `both` was interrupted.
+    const recovery = holder?.startsWith('sync-incoming-')
+        ? ` An interrupted "sync both" left it there: run "git checkout ${ref}" in that workspace.`
+        : '';
+    return new SyncError(`Branch workspace "${path.basename(branchPath)}" holds ${holder === null ? 'a detached HEAD' : `branch "${holder}"`}, not "${ref}".${recovery}`);
+}
+/** The workspace directory the runtime keys ref `name` to (`resolveBranchPath`). */
+function refKeyPath(name, projectDir) {
+    try {
+        return resolveBranchPath({ mode: 'dev', branchName: name, basePathOverride: projectDir })
+            .branchRoot;
+    }
+    catch (err) {
+        if (namesNoWorkspace(err))
+            throw new SyncError(`"${name}" cannot name a branch workspace.`);
+        throw err;
+    }
+}
+/**
+ * Auto-create a minimal workspace for the branch `name` gives (git init + empty commit) so push
+ * can copy content in, at the directory the dev server reads for that ref. This is lighter than
+ * BranchWorkspaceManager's clone-based setup -- no remote config, content structure or
+ * branch.json -- and the dev server adopts it in place when it provisions that ref
+ * (BranchWorkspaceManager.provisionBranch).
+ */
+async function createSyncWorkspace(name, projectDir) {
+    const ref = refOf(name);
+    const parsed = parseBranchRef(ref);
+    if (!parsed.ok)
+        throw new SyncError(`"${ref}" is not a valid branch name: ${parsed.error}`);
+    const branchPath = refKeyPath(ref, projectDir);
+    await fs.mkdir(branchPath, { recursive: true });
+    const wsGit = simpleGit({ baseDir: branchPath });
+    await wsGit.init();
+    await wsGit.checkoutLocalBranch(ref);
+    await wsGit.raw(['commit', '--allow-empty', '-m', 'init: workspace created by sync']);
+    // Runtime metadata (.canopy-meta/: branch metadata, comments, content-index
+    // marker) must never be staged by sync's `add -A`. Fully provisioned workspaces
+    // get this exclude from GitManager.initializeWorkspace; this minimal one needs it
+    // too. Sync is dev-mode-only, so this asks the dev strategy for the pattern
+    // rather than hardcoding it.
+    await ensureGitExcludePattern(branchPath, operatingStrategy('dev').getGitExcludePattern());
+    p.log.info(`Created branch workspace: ${path.basename(branchPath)}`);
+    return { branchName: ref, branchPath };
+}
 /**
- * Select a branch workspace. Auto-selects if only one exists, prompts if
- * multiple, or uses the --branch flag (defaulting to the current git branch).
- * When autoCreate is true, creates a new workspace if the branch doesn't exist.
+ * Select a branch workspace. Uses the --branch flag (defaulting to the current git branch),
+ * resolved as the dev server resolves it ({@link resolveSyncWorkspace}); else auto-selects the
+ * only workspace directory, or prompts for one. When autoCreate is true, creates a new workspace
+ * if a named branch has none.
  */
-async function selectBranch(options, branchesDir) {
+async function selectBranch(options) {
+    const branchesDir = operatingStrategy('dev').getContentBranchesRoot(options.projectDir);
     let branches = [];
     if (await filePathExists(branchesDir)) {
         const entries = await fs.readdir(branchesDir, { withFileTypes: true });
@@ -93,6 +271,7 @@ async function selectBranch(options, branchesDir) {
         branches = entries.filter((e) => e.isDirectory() && !e.name.startsWith('.')).map((e) => e.name);
     }
     let branchName = options.branch;
+    const byRef = !branchName;
     if (!branchName) {
         try {
             branchName = await detectCurrentBranch(options.projectDir);
@@ -105,48 +284,25 @@ async function selectBranch(options, branchesDir) {
         if (branches.length === 0) {
             throw new SyncError('No branch workspaces found and could not detect current git branch. Use --branch to specify.');
         }
-        if (branches.length === 1) {
-            branchName = branches[0];
-        }
-        else {
-            const result = await p.select({
-                message: 'Which branch?',
-                options: branches.map((b) => ({ value: b, label: b })),
-            });
-            if (p.isCancel(result)) {
-                p.cancel('Sync cancelled.');
-                return null;
-            }
-            branchName = result;
-        }
-    }
-    // Validate branch name does not escape the branches directory
-    const branchPath = path.join(branchesDir, branchName);
-    assertWithinDir(branchPath, branchesDir, '--branch');
-    if (!branches.includes(branchName)) {
-        if (options.autoCreate) {
-            // Auto-create a minimal workspace (git init + empty commit) so push can
-            // copy content in. This is lighter than BranchWorkspaceManager's clone-based
-            // setup — no remote config or content structure — but sufficient for sync.
-            await fs.mkdir(branchPath, { recursive: true });
-            const wsGit = simpleGit({ baseDir: branchPath });
-            await wsGit.init();
-            await wsGit.checkoutLocalBranch(branchName);
-            await wsGit.raw(['commit', '--allow-empty', '-m', 'init: workspace created by sync']);
-            // Runtime metadata (.canopy-meta/: branch metadata, comments, content-index
-            // marker) must never be staged by sync's `add -A`. Fully provisioned workspaces
-            // get this exclude from GitManager.initializeWorkspace; this minimal one needs it
-            // too. Sync is dev-mode-only (see branchesDir), so this asks the dev strategy for
-            // the pattern rather than hardcoding it.
-            await ensureGitExcludePattern(branchPath, operatingStrategy('dev').getGitExcludePattern());
-            p.log.info(`Created branch workspace: ${branchName}`);
-        }
-        else {
-            const available = branches.length > 0 ? ` Available branches: ${branches.join(', ')}` : '';
-            throw new SyncError(`Branch workspace "${branchName}" not found.${available}`);
+        if (branches.length === 1)
+            return keyWorkspace(branches[0], options.projectDir);
+        const result = await p.select({
+            message: 'Which branch?',
+            options: branches.map((b) => ({ value: b, label: b })),
+        });
+        if (p.isCancel(result)) {
+            p.cancel('Sync cancelled.');
+            return null;
         }
-    }
-    return branchName;
+        return keyWorkspace(result, options.projectDir);
+    }
+    const existing = await resolveSyncWorkspace(branchName, options.projectDir, branches, byRef);
+    if (existing)
+        return existing;
+    if (options.autoCreate)
+        return createSyncWorkspace(branchName, options.projectDir);
+    const available = branches.length > 0 ? ` Available branches: ${branches.join(', ')}` : '';
+    throw new SyncError(`Branch workspace "${branchName}" not found.${available}`);
 }
 /**
  * Push: copy working-tree content into a branch workspace and commit.
@@ -155,7 +311,6 @@ async function selectBranch(options, branchesDir) {
 async function syncPush(options) {
     const { projectDir } = options;
     const contentRoot = options.contentRoot || 'content';
-    const branchesDir = path.join(projectDir, '.canopy-dev', 'content-branches');
     // Validate source content BEFORE selectBranch, which may create a workspace —
     // a push with nothing to push must not leave side effects behind.
     const srcContentDir = path.join(projectDir, contentRoot);
@@ -163,11 +318,10 @@ async function syncPush(options) {
     if (!(await filePathExists(srcContentDir))) {
         throw new SyncError(`Content directory not found: ${contentRoot}/ (expected at ${srcContentDir})`);
     }
-    const branchName = await selectBranch({ ...options, projectDir, autoCreate: true }, branchesDir);
-    if (!branchName)
+    const ws = await selectBranch({ ...options, projectDir, autoCreate: true });
+    if (!ws)
         return { fileCount: 0 };
-    const branchPath = path.join(branchesDir, branchName);
-    assertWithinDir(branchPath, branchesDir, '--branch');
+    const { branchName, branchPath } = ws;
     const wsGit = simpleGit({ baseDir: branchPath });
     const status = await wsGit.status();
     if (status.conflicted.length > 0) {
@@ -235,18 +389,20 @@ async function syncPush(options) {
  * Pull: copy content from a branch workspace back into the working tree.
  */
 async function syncPull(options) {
+    const ws = await selectBranch({ ...options, projectDir: options.projectDir });
+    if (!ws)
+        return { fileCount: 0 };
+    return pullFromWorkspace(options, ws);
+}
+/** The body of {@link syncPull}, once its workspace is chosen. */
+async function pullFromWorkspace(options, ws) {
     const { projectDir } = options;
     const contentRoot = options.contentRoot || 'content';
-    const branchesDir = path.join(projectDir, '.canopy-dev', 'content-branches');
-    const branchName = await selectBranch({ ...options, projectDir }, branchesDir);
-    if (!branchName)
-        return { fileCount: 0 };
-    const branchPath = path.join(branchesDir, branchName);
-    assertWithinDir(branchPath, branchesDir, '--branch');
+    const { branchName, branchPath } = ws;
     const branchContentDir = path.join(branchPath, contentRoot);
     assertWithinDir(branchContentDir, branchPath, '--content-root');
     if (!(await filePathExists(branchContentDir))) {
-        throw new SyncError(`Content directory not found in branch workspace: ${branchName}/${contentRoot}`);
+        throw new SyncError(`Content directory not found in branch workspace: ${path.basename(branchPath)}/${contentRoot}`);
     }
     p.log.step(`Pulling content from branch: ${branchName}`);
     const destContentDir = path.join(projectDir, contentRoot);
@@ -342,18 +498,16 @@ async function syncPull(options) {
 async function syncBoth(options) {
     const { projectDir } = options;
     const contentRoot = options.contentRoot || 'content';
-    const branchesDir = path.join(projectDir, '.canopy-dev', 'content-branches');
     // Validate source content BEFORE selectBranch, which may create a workspace
     const srcContentDir = path.join(projectDir, contentRoot);
     assertWithinDir(srcContentDir, projectDir, '--content-root');
     if (!(await filePathExists(srcContentDir))) {
         throw new SyncError(`Content directory not found: ${contentRoot}/ (expected at ${srcContentDir})`);
     }
-    const branchName = await selectBranch({ ...options, projectDir, autoCreate: true }, branchesDir);
-    if (!branchName)
+    const ws = await selectBranch({ ...options, projectDir, autoCreate: true });
+    if (!ws)
         return { pushed: 0, pulled: 0 };
-    const branchPath = path.join(branchesDir, branchName);
-    assertWithinDir(branchPath, branchesDir, '--branch');
+    const { branchName, branchPath } = ws;
     const wsGit = simpleGit({ baseDir: branchPath });
     const status = await wsGit.status();
     if (status.conflicted.length > 0) {
@@ -375,7 +529,7 @@ async function syncBoth(options) {
 }
 /** The locked body of {@link syncBoth}: everything that rewrites the workspace. */
 async function mergeIntoWorkspace(options, ws) {
-    const { branchName, branchPath, srcContentDir, contentRoot } = ws;
+    const { branchPath, srcContentDir, contentRoot } = ws;
     const wsGit = simpleGit({ baseDir: branchPath });
     const status = await wsGit.status();
     // Auto-commit uncommitted workspace changes (preserves editor work for the merge)
@@ -421,7 +575,7 @@ async function mergeIntoWorkspace(options, ws) {
             await wsGit.checkout(currentBranch);
             await wsGit.raw(['branch', '-D', incomingBranch]);
             p.log.info('No working-tree changes to merge — pulling editor changes only');
-            const pullResult = await syncPull({ ...options, branch: branchName, force: true });
+            const pullResult = await pullFromWorkspace({ ...options, force: true }, ws);
             return { pushed: 0, pulled: pullResult.fileCount };
         }
         await wsGit.commit('sync: incoming working-tree changes');
@@ -446,8 +600,9 @@ async function mergeIntoWorkspace(options, ws) {
                     p.log.error(`  ${file}`);
                 }
                 p.log.info('The branch workspace is now in a merge state.');
-                p.log.info('Resolve the conflicts in the workspace, then run: canopycms sync pull');
-                p.log.info('Or abort the merge with: canopycms sync abort');
+                const branchFlag = options.branch ? ` --branch ${options.branch}` : '';
+                p.log.info(`Resolve the conflicts in the workspace, then run: canopycms sync pull${branchFlag}`);
+                p.log.info(`Or abort the merge with: canopycms sync abort${branchFlag}`);
                 // Clean up the incoming branch (leave merge state for user resolution)
                 await wsGit.raw(['branch', '-D', incomingBranch]).catch(() => { });
                 return { pushed: 0, pulled: 0 };
@@ -459,7 +614,7 @@ async function mergeIntoWorkspace(options, ws) {
         await wsGit.raw(['branch', '-D', incomingBranch]);
         await wsGit.tag(['-f', SYNC_BASE_TAG]);
         p.log.success('Merged working-tree changes with editor changes');
-        const pullResult = await syncPull({ ...options, branch: branchName, force: true });
+        const pullResult = await pullFromWorkspace({ ...options, force: true }, ws);
         return { pushed: incomingFiles.length, pulled: pullResult.fileCount };
     }
     finally {
@@ -471,13 +626,10 @@ async function mergeIntoWorkspace(options, ws) {
  * Restores the workspace to its pre-merge state.
  */
 async function syncAbort(options) {
-    const { projectDir } = options;
-    const branchesDir = path.join(projectDir, '.canopy-dev', 'content-branches');
-    const branchName = await selectBranch({ ...options, projectDir }, branchesDir);
-    if (!branchName)
+    const ws = await selectBranch({ ...options, projectDir: options.projectDir });
+    if (!ws)
         return;
-    const branchPath = path.join(branchesDir, branchName);
-    assertWithinDir(branchPath, branchesDir, '--branch');
+    const { branchName, branchPath } = ws;
     if (!(await abortWorkspaceMerge(branchPath, branchName))) {
         p.log.info(`Branch workspace "${branchName}" is not in a merge state — nothing to abort.`);
         return;

package/dist/editor/BranchManager.d.ts

@@ -1,6 +1,6 @@
 import React from 'react';
 import type { OperatingMode } from '../operating-mode/index.js';
-import type { ConflictStatus, PullRequestState, SyncStatus } from '../types.js';
+import type { BranchHold, ConflictStatus, PullRequestState, SyncStatus } from '../types.js';
 import type { CommentThread } from '../comment-store.js';
 import type { UserSearchResult } from '../auth/types.js';
 import type { CreateRefusal } from './hooks/create-branch-request.js';
@@ -32,17 +32,21 @@ export interface BranchSummary {
     conflictStatus?: ConflictStatus;
     /** ContentIds of entries where --theirs was applied during rebase; cleared on clean rebase */
     conflictFiles?: string[];
+    /** What is stuck and needs a person (api/branch.ts). */
+    hold?: BranchHold;
     commentCount?: number;
     isProtected?: boolean;
     readOnly?: boolean;
     /**
-     * Server-computed compound submit rule (base-branch OR non-'editing'
-     * status) -- see `useBranchManager.tsx`'s `BranchSummary.submitBlocked` and
-     * `BranchWriteProtection.submitBlockedIncludingStatus` for the full
+     * Server-computed compound submit rule (base-branch, non-'editing'
+     * status, or rewritten on GitHub) -- see `useBranchManager.tsx`'s
+     * `BranchSummary.submitBlocked` and `BranchWriteProtection.submitBlockedIncludingStatus` for the full
      * rationale. `getBranchPermissions`'s `canSubmit` consumes this directly
      * instead of re-deriving `status === 'editing' && !isProtected`.
      */
     submitBlocked?: boolean;
+    /** Server-computed: the API refuses Approve, as the last submit didn't finish. */
+    approveBlocked?: boolean;
 }
 export interface UserContext {
     userId: string;