canopycms 0.7.0 → 0.8.0

package/dist/api/groups.d.ts

@@ -58,29 +58,29 @@ export declare const GROUP_ROUTES: {
             description: z.ZodOptional<z.ZodString>;
             members: z.ZodArray<z.ZodString, "many">;
         }, "strip", z.ZodTypeAny, {
-            name: string;
             id: string;
+            name: string;
             members: string[];
             description?: string | undefined;
         }, {
-            name: string;
             id: string;
+            name: string;
             members: string[];
             description?: string | undefined;
         }>, "many">;
         expectedContentVersion: z.ZodOptional<z.ZodNumber>;
     }, "strip", z.ZodTypeAny, {
         groups: {
-            name: string;
             id: string;
+            name: string;
             members: string[];
             description?: string | undefined;
         }[];
         expectedContentVersion?: number | undefined;
     }, {
         groups: {
-            name: string;
             id: string;
+            name: string;
             members: string[];
             description?: string | undefined;
         }[];

package/dist/api/pr-comment-sync.d.ts

@@ -1,18 +1,19 @@
 import type { ApiContext } from './types.js';
 import type { BranchContext } from '../types.js';
 /**
- * Brings the PR's editor-comment summary up to date after a comment is added, replied to or
- * resolved. Best-effort: a failure is logged and never fails the comment request.
+ * Brings both of the PR body's blocks, the editor-comment summary and the review block, up to
+ * date after a comment is added, replied to or resolved, or a review is given or withdrawn.
+ * Best-effort: a failure is logged and never fails the request.
  *
- * Direct path: read the PR body, replace the block, write it back, within
- * DIRECT_SYNC_TIMEOUT_MS so a slow or rate-limited GitHub never holds the comment request.
+ * Direct path: read the PR body, replace the blocks, write it back, within
+ * DIRECT_SYNC_TIMEOUT_MS so a slow or rate-limited GitHub never holds the request.
  * GitHub's PR update takes no expected version; the per-branch lock (prBodyLockKey) only
  * orders this process's writers (docs/concurrency.md).
  *
  * Queued path: one pending task per branch and PR, rendered by the worker from comments.json
- * when it runs, so a burst of comments costs one update. The comment was written before this
- * call and a pending task reads comments.json only after it leaves pending, so its run carries
- * the change this call skipped; a task already running doesn't count, so a later change gets
- * a run of its own.
+ * and branch.json when it runs, so a burst of changes costs one update. The change was written
+ * before this call and a pending task reads those files only after it leaves pending, so its
+ * run carries the change this call skipped; a task already running doesn't count, so a later
+ * change gets a run of its own.
  */
 export declare function syncPrComments(ctx: ApiContext, context: BranchContext): Promise<void>;

package/dist/api/pr-comment-sync.js

@@ -5,7 +5,8 @@ import { enqueueTask, listTasks } from '../task-queue/cms-task-queue.js';
 import { getTaskQueueDir } from '../task-queue/task-queue-config.js';
 import { withLock } from '../utils/async-mutex.js';
 import { getErrorMessage } from '../utils/error.js';
-/** A PR the comment summary is still worth updating on: one exists and is not merged or closed. */
+import { shortNameOf } from '../branch-param.js';
+/** A PR whose body blocks are still worth updating: one exists and is not merged or closed. */
 function openPullRequest(context) {
     const { pullRequestNumber, pullRequestState, status } = context.branch;
     if (!pullRequestNumber || status === 'archived')
@@ -14,22 +15,23 @@ function openPullRequest(context) {
         ? undefined
         : pullRequestNumber;
 }
-/** How long a comment request waits on GitHub for its summary update, lock wait included. */
+/** How long a request waits on GitHub for its PR body update, lock wait included. */
 const DIRECT_SYNC_TIMEOUT_MS = 10_000;
 /**
- * Brings the PR's editor-comment summary up to date after a comment is added, replied to or
- * resolved. Best-effort: a failure is logged and never fails the comment request.
+ * Brings both of the PR body's blocks, the editor-comment summary and the review block, up to
+ * date after a comment is added, replied to or resolved, or a review is given or withdrawn.
+ * Best-effort: a failure is logged and never fails the request.
  *
- * Direct path: read the PR body, replace the block, write it back, within
- * DIRECT_SYNC_TIMEOUT_MS so a slow or rate-limited GitHub never holds the comment request.
+ * Direct path: read the PR body, replace the blocks, write it back, within
+ * DIRECT_SYNC_TIMEOUT_MS so a slow or rate-limited GitHub never holds the request.
  * GitHub's PR update takes no expected version; the per-branch lock (prBodyLockKey) only
  * orders this process's writers (docs/concurrency.md).
  *
  * Queued path: one pending task per branch and PR, rendered by the worker from comments.json
- * when it runs, so a burst of comments costs one update. The comment was written before this
- * call and a pending task reads comments.json only after it leaves pending, so its run carries
- * the change this call skipped; a task already running doesn't count, so a later change gets
- * a run of its own.
+ * and branch.json when it runs, so a burst of changes costs one update. The change was written
+ * before this call and a pending task reads those files only after it leaves pending, so its
+ * run carries the change this call skipped; a task already running doesn't count, so a later
+ * change gets a run of its own.
  */
 export async function syncPrComments(ctx, context) {
     const prNumber = openPullRequest(context);
@@ -38,6 +40,8 @@ export async function syncPrComments(ctx, context) {
     if (!clientOperatingStrategy(ctx.services.config.mode).supportsPullRequests())
         return;
     const branch = context.branch.name;
+    // The short name, which `?branch=` resolves, for the body's links.
+    const shortName = shortNameOf(ctx.services.config, branch);
     const editorUrl = ctx.services.config.editorUrl ?? context.branch.editorUrl;
     try {
         const { githubService } = ctx.services;
@@ -48,9 +52,10 @@ export async function syncPrComments(ctx, context) {
                     return;
                 const body = await renderPrCommentsBody({
                     branchRoot: context.branchRoot,
-                    branch,
+                    branch: shortName,
                     editorUrl,
                     body: pr.body,
+                    warn: (message) => console.warn(`CanopyCMS: ${message}`),
                 });
                 if (body !== undefined)
                     await githubService.updatePullRequest(prNumber, { body }, signal);
@@ -66,11 +71,16 @@ export async function syncPrComments(ctx, context) {
             return;
         await enqueueTask(taskDir, {
             action: SYNC_PR_COMMENTS_ACTION,
-            payload: { branch, pullRequestNumber: prNumber, ...(editorUrl ? { editorUrl } : {}) },
+            payload: {
+                branch,
+                pullRequestNumber: prNumber,
+                ...(editorUrl ? { editorUrl } : {}),
+                editorBranch: shortName,
+            },
         });
     }
     catch (err) {
-        console.warn(`CanopyCMS: Could not update the editor comments on PR #${prNumber} for ${branch}:`, isApiTimeoutError(err)
+        console.warn(`CanopyCMS: Could not update the editor comments or review state on PR #${prNumber} for ${branch}:`, isApiTimeoutError(err)
             ? `GitHub did not answer within ${DIRECT_SYNC_TIMEOUT_MS / 1000} s`
             : getErrorMessage(err));
     }

package/dist/api/routes.js

@@ -5,6 +5,8 @@
  * `http-reaches-api-only-via-routes` dependency-cruiser rule holds this one.
  */
 import { BRANCH_ROUTES } from './branch.js';
+import { BRANCH_CHANGES_ROUTES } from './branch-changes.js';
+import { BRANCH_ENTRY_CHANGE_ROUTES } from './branch-entry-changes.js';
 import { WORKFLOW_ROUTES } from './branch-status.js';
 import { COMMENT_ROUTES } from './comments.js';
 import { CONTENT_ROUTES } from './content.js';
@@ -24,6 +26,8 @@ import { ADMIN_ROUTES } from './admin.js';
 export function buildCanopyRoutes() {
     return [
         ...Object.values(BRANCH_ROUTES),
+        ...Object.values(BRANCH_CHANGES_ROUTES),
+        ...Object.values(BRANCH_ENTRY_CHANGE_ROUTES),
         ...Object.values(WORKFLOW_ROUTES),
         ...Object.values(COMMENT_ROUTES),
         ...Object.values(CONTENT_ROUTES),

package/dist/api/types.d.ts

@@ -65,5 +65,7 @@ export interface ApiResponse<TData = unknown> {
  * 409, see `SettingsVersionConflictError`); nothing was saved, and a reload shows the other edit.
  * The other settings 409, a busy file lock, carries no code. `BRANCH_SYNCING`: an entry save was
  * refused because the branch is mid-rebase (a 409); nothing was saved, and a retry soon can pass.
+ * `BRANCH_NAME_REFUSED`: a branch create was refused for the name it gave (a 400 or 409), so only
+ * another name can pass; no other create failure carries it.
  */
-export type ApiErrorCode = 'SCHEMA_UNAVAILABLE' | 'WORKER_FAILED' | 'WRITE_OUTCOME_UNKNOWN' | 'ENTRY_GONE' | 'EDITOR_MODE_MISMATCH' | 'SETTINGS_CHANGED' | 'BRANCH_SYNCING';
+export type ApiErrorCode = 'SCHEMA_UNAVAILABLE' | 'WORKER_FAILED' | 'WRITE_OUTCOME_UNKNOWN' | 'ENTRY_GONE' | 'EDITOR_MODE_MISMATCH' | 'SETTINGS_CHANGED' | 'BRANCH_SYNCING' | 'BRANCH_NAME_REFUSED';

package/dist/authorization/groups/schema.d.ts

@@ -14,21 +14,21 @@ export declare const GroupsFileSchema: z.ZodObject<{
         description: z.ZodOptional<z.ZodString>;
         members: z.ZodArray<z.ZodType<string, z.ZodTypeDef, string>, "many">;
     }, "strip", z.ZodTypeAny, {
-        name: string;
         id: string;
+        name: string;
         members: string[];
         description?: string | undefined;
     }, {
-        name: string;
         id: string;
+        name: string;
         members: string[];
         description?: string | undefined;
     }>, "many">;
 }, "strip", z.ZodTypeAny, {
     updatedAt: string;
     groups: {
-        name: string;
         id: string;
+        name: string;
         members: string[];
         description?: string | undefined;
     }[];
@@ -38,8 +38,8 @@ export declare const GroupsFileSchema: z.ZodObject<{
 }, {
     updatedAt: string;
     groups: {
-        name: string;
         id: string;
+        name: string;
         members: string[];
         description?: string | undefined;
     }[];

package/dist/authorization/protected-branch.d.ts

@@ -52,9 +52,9 @@ export interface BranchWriteProtection extends BranchProtection {
 /**
  * Whether `branchName` is the protected base branch for `config`.
  *
- * The comparison is sanitization-aware: branch metadata names are sanitized but
- * `config.defaultBaseBranch` holds the raw git name, so both sides go through
- * `sanitizeBranchName` first.
+ * The comparison is sanitization-aware: both sides go through `sanitizeBranchName`
+ * first, the form a workspace directory takes, so a base workspace whose recorded
+ * name is sanitized still matches the raw git name `config.defaultBaseBranch` holds.
  *
  * `recordedBaseBranch` (a branch's own recorded fork point) is a second, purely
  * additive clause: a branch whose fork point equals its own name IS a base

package/dist/authorization/protected-branch.js

@@ -15,9 +15,9 @@ import { baseBranchOf } from '../utils/base-branch.js';
 /**
  * Whether `branchName` is the protected base branch for `config`.
  *
- * The comparison is sanitization-aware: branch metadata names are sanitized but
- * `config.defaultBaseBranch` holds the raw git name, so both sides go through
- * `sanitizeBranchName` first.
+ * The comparison is sanitization-aware: both sides go through `sanitizeBranchName`
+ * first, the form a workspace directory takes, so a base workspace whose recorded
+ * name is sanitized still matches the raw git name `config.defaultBaseBranch` holds.
  *
  * `recordedBaseBranch` (a branch's own recorded fork point) is a second, purely
  * additive clause: a branch whose fork point equals its own name IS a base

package/dist/branch-metadata-file.d.ts

@@ -85,6 +85,34 @@ export declare const branchMetadataSchema: z.ZodObject<{
     syncFailureReason: z.ZodOptional<z.ZodString>;
     editors: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     uncommittedEditors: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    review: z.ZodCatch<z.ZodOptional<z.ZodObject<{
+        state: z.ZodEnum<["approved", "changes-requested"]>;
+        by: z.ZodObject<{
+            userId: z.ZodString;
+            name: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            userId: string;
+            name?: string | undefined;
+        }, {
+            userId: string;
+            name?: string | undefined;
+        }>;
+        at: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        at: string;
+        state: "approved" | "changes-requested";
+        by: {
+            userId: string;
+            name?: string | undefined;
+        };
+    }, {
+        at: string;
+        state: "approved" | "changes-requested";
+        by: {
+            userId: string;
+            name?: string | undefined;
+        };
+    }>>>;
 }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
     name: z.ZodString;
     title: z.ZodOptional<z.ZodString>;
@@ -150,6 +178,34 @@ export declare const branchMetadataSchema: z.ZodObject<{
     syncFailureReason: z.ZodOptional<z.ZodString>;
     editors: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     uncommittedEditors: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    review: z.ZodCatch<z.ZodOptional<z.ZodObject<{
+        state: z.ZodEnum<["approved", "changes-requested"]>;
+        by: z.ZodObject<{
+            userId: z.ZodString;
+            name: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            userId: string;
+            name?: string | undefined;
+        }, {
+            userId: string;
+            name?: string | undefined;
+        }>;
+        at: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        at: string;
+        state: "approved" | "changes-requested";
+        by: {
+            userId: string;
+            name?: string | undefined;
+        };
+    }, {
+        at: string;
+        state: "approved" | "changes-requested";
+        by: {
+            userId: string;
+            name?: string | undefined;
+        };
+    }>>>;
 }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
     name: z.ZodString;
     title: z.ZodOptional<z.ZodString>;
@@ -215,6 +271,34 @@ export declare const branchMetadataSchema: z.ZodObject<{
     syncFailureReason: z.ZodOptional<z.ZodString>;
     editors: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     uncommittedEditors: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    review: z.ZodCatch<z.ZodOptional<z.ZodObject<{
+        state: z.ZodEnum<["approved", "changes-requested"]>;
+        by: z.ZodObject<{
+            userId: z.ZodString;
+            name: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            userId: string;
+            name?: string | undefined;
+        }, {
+            userId: string;
+            name?: string | undefined;
+        }>;
+        at: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        at: string;
+        state: "approved" | "changes-requested";
+        by: {
+            userId: string;
+            name?: string | undefined;
+        };
+    }, {
+        at: string;
+        state: "approved" | "changes-requested";
+        by: {
+            userId: string;
+            name?: string | undefined;
+        };
+    }>>>;
 }, z.ZodTypeAny, "passthrough">>;
 /**
  * Read, parse and validate `branch.json`, with no locking, no OCC and no side

package/dist/branch-metadata-file.js

@@ -84,6 +84,15 @@ const branchMetadataShape = {
     syncFailureReason: z.string().optional(),
     editors: z.array(z.string()).optional(),
     uncommittedEditors: z.array(z.string()).optional(),
+    // Dropped when malformed: it only decorates the PR body, so it never fails a read.
+    review: z
+        .object({
+        state: z.enum(['approved', 'changes-requested']),
+        by: z.object({ userId: z.string(), name: z.string().optional() }),
+        at: z.string(),
+    })
+        .optional()
+        .catch(undefined),
 };
 /** The `branch` object, also embedded in the registry snapshot (branch-registry.ts). */
 export const branchMetadataSchema = z.object(branchMetadataShape).passthrough();

package/dist/branch-metadata.d.ts

@@ -124,11 +124,11 @@ export interface BranchMetadataUpdate {
  * worker's merge-poll (CmsWorker.pollMergeState) and the manual markAsMerged
  * API (api/branch-merge.ts), so both produce identical metadata.
  *
- * Deliberately omits pullRequestNumber/pullRequestUrl: save() keeps existing
- * values for fields the incoming update omits, so the recorded PR number and
- * URL survive untouched.
+ * Deliberately omits `name` and pullRequestNumber/pullRequestUrl: save() keeps
+ * existing values for fields the incoming update omits, so the branch's ref and
+ * its recorded PR number and URL survive untouched.
  */
-export declare function buildMergedBranchUpdate(branchName: string, now?: Date): NonNullable<BranchMetadataUpdate['branch']>;
+export declare function buildMergedBranchUpdate(now?: Date): NonNullable<BranchMetadataUpdate['branch']>;
 /** {@link BranchMetadataFileManager.get} as a function. */
 export declare const getBranchMetadataFileManager: (branchRoot: string, baseRoot: string, options?: {
     settleMs?: number;

package/dist/branch-metadata.js

@@ -272,13 +272,12 @@ export function buildInitialBranchMetadata(incoming, now) {
  * worker's merge-poll (CmsWorker.pollMergeState) and the manual markAsMerged
  * API (api/branch-merge.ts), so both produce identical metadata.
  *
- * Deliberately omits pullRequestNumber/pullRequestUrl: save() keeps existing
- * values for fields the incoming update omits, so the recorded PR number and
- * URL survive untouched.
+ * Deliberately omits `name` and pullRequestNumber/pullRequestUrl: save() keeps
+ * existing values for fields the incoming update omits, so the branch's ref and
+ * its recorded PR number and URL survive untouched.
  */
-export function buildMergedBranchUpdate(branchName, now = new Date()) {
+export function buildMergedBranchUpdate(now = new Date()) {
     return {
-        name: branchName,
         status: 'archived',
         pullRequestState: 'merged',
         mergedAt: now.toISOString(),

package/dist/branch-param.d.ts

@@ -0,0 +1,24 @@
+import type { CanopyConfig } from './config/index.js';
+import type { BranchContext } from './types.js';
+export type BranchParamConfig = Pick<CanopyConfig, 'mode' | 'defaultBaseBranch' | 'defaultActiveBranch' | 'branchNamespace' | 'deploymentName'>;
+/**
+ * The name pull request links and messages give the branch whose ref is `name`: its short name
+ * under this CMS's namespace, or the full ref when the short name is the base or active
+ * branch's, which the resolver would answer instead.
+ */
+export declare function shortNameOf(config: BranchParamConfig, name: string): string;
+/**
+ * The workspace `param` names, or null. A `param` in the exact form (`exactBranchSegment`,
+ * `~canopycms~prod~spring`) names only the branch whose branch.json `name` it decodes to, and a
+ * malformed one names none. Any other `param`, in order:
+ * 1. the base or configured active branch, exactly, so no namespace branch ever shadows it;
+ * 2. the namespace branch whose short name is `param` (which holds no `/`), when its branch.json
+ *    `name` is that ref;
+ * 3. a branch outside the namespace by its full name, when its `name` is `param`. A namespace
+ *    branch's full ref resolves here too. A branch outside the namespace that step 2 shadows
+ *    opens only by the exact form.
+ * Throws what loading throws for a name that can name no workspace (`namesNoWorkspace`).
+ */
+export declare function resolveBranchParam(param: string, config: BranchParamConfig, options?: {
+    basePathOverride?: string;
+}): Promise<BranchContext | null>;

package/dist/branch-param.js

@@ -0,0 +1,87 @@
+/**
+ * The one way a branch named in a request, by a `/:branch` segment or `?branch=`, becomes its
+ * workspace. A branch has three names: its ref (`canopycms/prod/spring`), which git and
+ * branch.json's `name` hold; its key (`sanitizeBranchName(ref)`), the workspace directory and
+ * registry key; and its short name (`spring`, `branchShortName`), which pull request links carry
+ * and requests may carry in place of the ref.
+ */
+import { loadBranchContext } from './branch-metadata.js';
+import { operatingStrategy } from './operating-mode/index.js';
+import { namesNoWorkspace } from './paths/branch.js';
+import { branchShortName } from './paths/branch-name.js';
+import { exactBranchName, isExactBranchForm } from './paths/validation.js';
+import { BaseBranchUnresolvedError, baseBranchOf } from './utils/base-branch.js';
+/**
+ * The namespace this CMS creates branches in, or null when its template is invalid: creation
+ * then refuses, and System health names why.
+ */
+function cmsBranchNamespace(config) {
+    try {
+        return operatingStrategy(config.mode).getBranchNamespace(config);
+    }
+    catch {
+        return null;
+    }
+}
+/** Whether `param` is the base or configured active branch, which resolve before any other. */
+function namesBaseOrActive(param, config) {
+    let base;
+    try {
+        base = baseBranchOf(config);
+    }
+    catch (err) {
+        if (err instanceof BaseBranchUnresolvedError)
+            return false;
+        throw err;
+    }
+    return param === base || param === (config.defaultActiveBranch ?? base);
+}
+/**
+ * The name pull request links and messages give the branch whose ref is `name`: its short name
+ * under this CMS's namespace, or the full ref when the short name is the base or active
+ * branch's, which the resolver would answer instead.
+ */
+export function shortNameOf(config, name) {
+    const short = branchShortName(name, cmsBranchNamespace(config));
+    return short !== name && namesBaseOrActive(short, config) ? name : short;
+}
+/**
+ * The workspace `param` names, or null. A `param` in the exact form (`exactBranchSegment`,
+ * `~canopycms~prod~spring`) names only the branch whose branch.json `name` it decodes to, and a
+ * malformed one names none. Any other `param`, in order:
+ * 1. the base or configured active branch, exactly, so no namespace branch ever shadows it;
+ * 2. the namespace branch whose short name is `param` (which holds no `/`), when its branch.json
+ *    `name` is that ref;
+ * 3. a branch outside the namespace by its full name, when its `name` is `param`. A namespace
+ *    branch's full ref resolves here too. A branch outside the namespace that step 2 shadows
+ *    opens only by the exact form.
+ * Throws what loading throws for a name that can name no workspace (`namesNoWorkspace`).
+ */
+export async function resolveBranchParam(param, config, options = {}) {
+    const load = (branchName) => loadBranchContext({ branchName, mode: config.mode, basePathOverride: options.basePathOverride });
+    if (isExactBranchForm(param)) {
+        const exact = exactBranchName(param);
+        if (exact === null)
+            return null;
+        const named = await load(exact);
+        return named?.branch.name === exact ? named : null;
+    }
+    if (namesBaseOrActive(param, config))
+        return load(param);
+    const namespace = cmsBranchNamespace(config);
+    // A short name holding a `/` is a full name (`branchShortName`), so a `param` with one names no
+    // namespace branch by the part after the namespace.
+    if (namespace !== null && !param.includes('/')) {
+        const ref = `${namespace}${param}`;
+        // A ref past a filename's length can still leave `param` naming a branch outside it.
+        const inNamespace = await load(ref).catch((err) => {
+            if (namesNoWorkspace(err))
+                return null;
+            throw err;
+        });
+        if (inNamespace?.branch.name === ref)
+            return inNamespace;
+    }
+    const outside = await load(param);
+    return outside?.branch.name === param ? outside : null;
+}

package/dist/branch-provisioning.d.ts

@@ -5,11 +5,12 @@ import type { ProvisionLog } from './utils/provision-log.js';
 export declare const CREATE_RESIDUE_MIN_QUIET_MS = 60000;
 /**
  * Retriable: another process is setting this branch up, or what is at its path is too recently
- * touched (or under an admin repair) to judge. Callers answer 503.
+ * touched (or under an admin repair) to judge. Callers answer 503. The message names the branch
+ * by `shortName`, which an editor knows it by, not by its workspace directory.
  */
 export declare class BranchProvisioningBusyError extends Error {
     readonly dirName: string;
-    constructor(dirName: string, message?: string);
+    constructor(dirName: string, shortName?: string, message?: string);
 }
 /** The branch's path holds a git repository this deployment did not create (prod only). */
 export declare class BranchDirOccupiedError extends Error {
@@ -130,12 +131,14 @@ export declare function stageBranchWorkspace(options: StageBranchOptions): Promi
  * The branch's provisioning lock with a bounded wait; contention is
  * {@link BranchProvisioningBusyError}.
  */
-export declare function lockBranchName(baseRoot: string, dirName: string): Promise<() => Promise<void>>;
+export declare function lockBranchName(baseRoot: string, dirName: string, shortName?: string): Promise<() => Promise<void>>;
 /** What blocks a refused publish rename, as {@link publishStaging} sees it. */
 export type BlockingKind = 'live' | 'protected' | 'residue';
 export interface PublishOptions {
     baseRoot: string;
     dirName: string;
+    /** What a busy answer calls the branch; defaults to `dirName`. */
+    shortName?: string;
     stagingPath: string;
     /** branch.json's `writeId` in the staged workspace: proof the rename was ours. */
     writeId: string | undefined;

package/dist/branch-provisioning.js

@@ -45,10 +45,11 @@ const DELETING_MAX_AGE_MS = 10 * 60_000;
 const SETTINGS_TRASH_MAX_AGE_MS = 30 * 24 * 60 * 60_000;
 /**
  * Retriable: another process is setting this branch up, or what is at its path is too recently
- * touched (or under an admin repair) to judge. Callers answer 503.
+ * touched (or under an admin repair) to judge. Callers answer 503. The message names the branch
+ * by `shortName`, which an editor knows it by, not by its workspace directory.
  */
 export class BranchProvisioningBusyError extends Error {
-    constructor(dirName, message = `Branch '${dirName}' is still being set up. Try again in a minute.`) {
+    constructor(dirName, shortName = dirName, message = `Branch '${shortName}' is still being set up. Try again in a minute.`) {
         super(message);
         this.dirName = dirName;
         this.name = 'BranchProvisioningBusyError';
@@ -334,13 +335,14 @@ export async function stageBranchWorkspace(options) {
  * The branch's provisioning lock with a bounded wait; contention is
  * {@link BranchProvisioningBusyError}.
  */
-export async function lockBranchName(baseRoot, dirName) {
+export async function lockBranchName(baseRoot, dirName, shortName = dirName) {
     try {
         return await acquireProvisioningLockWithin(baseRoot, branchProvisioningLockName(dirName), PUBLISH_LOCK_WAIT_MS);
     }
     catch (err) {
-        if (isNodeError(err) && err.code === 'ELOCKED')
-            throw new BranchProvisioningBusyError(dirName);
+        if (isNodeError(err) && err.code === 'ELOCKED') {
+            throw new BranchProvisioningBusyError(dirName, shortName);
+        }
         throw err;
     }
 }
@@ -363,9 +365,9 @@ const RENAME_BLOCKED = new Set(['EEXIST', 'ENOTEMPTY', 'ENOTDIR']);
  * `writeId`. The caller removes the staging directory on any outcome but `published`.
  */
 export async function publishStaging(options) {
-    const { baseRoot, dirName, stagingPath } = options;
+    const { baseRoot, dirName, stagingPath, shortName = dirName } = options;
     const finalPath = path.join(baseRoot, dirName);
-    const release = await lockBranchName(baseRoot, dirName);
+    const release = await lockBranchName(baseRoot, dirName, shortName);
     try {
         for (let attempt = 0; attempt < 2; attempt++) {
             try {
@@ -388,7 +390,7 @@ export async function publishStaging(options) {
             if (blocking === 'live')
                 return 'exists';
             if (blocking === 'protected')
-                throw new BranchProvisioningBusyError(dirName);
+                throw new BranchProvisioningBusyError(dirName, shortName);
             const result = await quarantineResidueAt(baseRoot, dirName, {
                 minQuietMs: CREATE_RESIDUE_MIN_QUIET_MS,
                 expectedRemoteUrl: options.expectedRemoteUrl,
@@ -403,9 +405,9 @@ export async function publishStaging(options) {
             }
             if (result.reason === 'foreign')
                 throw new BranchDirOccupiedError(dirName);
-            throw new BranchProvisioningBusyError(dirName);
+            throw new BranchProvisioningBusyError(dirName, shortName);
         }
-        throw new BranchProvisioningBusyError(dirName);
+        throw new BranchProvisioningBusyError(dirName, shortName);
     }
     finally {
         await release().catch((err) => {

package/dist/branch-registry.d.ts

@@ -56,6 +56,12 @@ export declare class BranchRegistry {
      * genuinely-absent branch costs at most one extra scan per window.
      */
     get(name: string): Promise<BranchContext | undefined>;
+    /**
+     * Returns the branch whose workspace directory is `key` (`sanitizeBranchName` of its ref),
+     * whatever its name, with {@link get}'s backstop.
+     */
+    getByKey(key: string): Promise<BranchContext | undefined>;
+    private find;
     private shouldForceRefresh;
     /**
      * Marks the cache stale for every process sharing this root by bumping the

package/dist/branch-registry.js

@@ -136,14 +136,23 @@ export class BranchRegistry {
      * genuinely-absent branch costs at most one extra scan per window.
      */
     async get(name) {
-        const branches = await this.list();
-        const found = branches.find((b) => b.branch.name === name);
+        return this.find((b) => b.branch.name === name);
+    }
+    /**
+     * Returns the branch whose workspace directory is `key` (`sanitizeBranchName` of its ref),
+     * whatever its name, with {@link get}'s backstop.
+     */
+    async getByKey(key) {
+        return this.find((b) => path.basename(b.branchRoot) === key);
+    }
+    async find(matches) {
+        const found = (await this.list()).find(matches);
         if (found)
             return found;
         if (!this.shouldForceRefresh())
             return undefined;
         const refreshed = await this.regenerate();
-        return refreshed.find((b) => b.branch.name === name);
+        return refreshed.find(matches);
     }
     shouldForceRefresh() {
         const now = Date.now();