canopycms 0.7.0 → 0.8.0

package/dist/operating-mode/branch-namespace.js

@@ -0,0 +1,121 @@
+/**
+ * Single resolution point for the branch namespace: the prefix every branch the GitHub gateway
+ * writes starts with, apart from this deployment's settings branch and the adopter's
+ * `legacyBranches` (worker/branch-policy.ts). It comes from a template in which `{deployment}`
+ * stands for the deployment name, so two deployments sharing a repository each get their own.
+ *
+ * Precedence, as for the deployment name and for the same reason: `CANOPYCMS_BRANCH_NAMESPACE`,
+ * which infrastructure stamps per stack, then `config.branchNamespace`, then
+ * {@link DEFAULT_BRANCH_NAMESPACE_TEMPLATE}. The gateway resolves its own from its own
+ * environment, never from anything the CMS Lambda can write.
+ */
+import { RESERVED_SETTINGS_BRANCH_PREFIX, sanitizeBranchName } from '../paths/branch-name.js';
+import { parseBranchRef } from '../paths/validation.js';
+import { canopyLogWarn } from '../utils/logger.js';
+import { resolveDeploymentName } from './deployment-name.js';
+let warned = false;
+function warnOnce(message) {
+    if (warned)
+        return;
+    warned = true;
+    canopyLogWarn(message);
+}
+/** The one placeholder a template may hold. */
+const DEPLOYMENT_PLACEHOLDER = '{deployment}';
+/** The template used when none is configured. */
+export const DEFAULT_BRANCH_NAMESPACE_TEMPLATE = `canopycms/${DEPLOYMENT_PLACEHOLDER}/`;
+/**
+ * The environment variable that carries the template, or the namespace it resolved to.
+ * @internal Exported for tests.
+ */
+export const BRANCH_NAMESPACE_ENV = 'CANOPYCMS_BRANCH_NAMESPACE';
+/**
+ * Why `namespace` cannot be a branch namespace, or null. It ends with `/`: a deployment name holds
+ * no `/`, so `canopycms/prod/` never starts `canopycms/prod-eu/`, as `canopycms-prod-` would start
+ * `canopycms-prod-eu-`. A branch in it must be a name git and the gateway take (checked with a
+ * branch appended), and none may be a settings branch, by name or by workspace directory.
+ */
+export function branchNamespaceProblem(namespace) {
+    if (!namespace.endsWith('/'))
+        return 'it must end with "/"';
+    const sample = `${namespace}x`;
+    if (!/^[\x21-\x7e]+$/.test(namespace))
+        return 'it is not printable ASCII without spaces';
+    if (/["%{}]/.test(namespace))
+        return 'it contains ", %, { or }';
+    if (/^(?:refs|heads|tags|remotes)\//i.test(namespace)) {
+        return "it starts with 'refs/', 'heads/', 'tags/' or 'remotes/'";
+    }
+    const parsed = parseBranchRef(sample);
+    if (!parsed.ok)
+        return `a branch in it would be refused (${parsed.error})`;
+    if (sample.split('/').some((part) => part.startsWith('.') || part.endsWith('.lock'))) {
+        return "a part of it starts with '.' or ends with '.lock'";
+    }
+    // A branch's directory is the namespace's own sanitized form followed by the rest, so a
+    // namespace that sanitizes to a start of the settings prefix (`canopycms/`) holds settings names.
+    const directoryPrefix = sanitizeBranchName(namespace);
+    if (RESERVED_SETTINGS_BRANCH_PREFIX.startsWith(directoryPrefix) ||
+        sanitizeBranchName(sample).startsWith(RESERVED_SETTINGS_BRANCH_PREFIX)) {
+        return `some branches in it would be ${RESERVED_SETTINGS_BRANCH_PREFIX}* settings branches`;
+    }
+    return null;
+}
+/**
+ * The branch names git cannot hold beside any branch in `namespace`: each path it runs through
+ * (`canopycms` and `canopycms/prod` for `canopycms/prod/`), since no ref lives under a branch.
+ */
+export function namespaceAncestors(namespace) {
+    const parts = namespace.split('/').filter(Boolean);
+    return parts.map((_, i) => parts.slice(0, i + 1).join('/'));
+}
+/**
+ * The namespace `template` names for `deploymentName`, or why it cannot be one. Throws, naming
+ * `source`, for a template with a placeholder other than `{deployment}` or a namespace
+ * {@link branchNamespaceProblem} refuses.
+ */
+export function resolveBranchNamespaceTemplate(template, deploymentName, source) {
+    const unknown = template.replaceAll(DEPLOYMENT_PLACEHOLDER, '').match(/\{[^}]*\}?/);
+    if (unknown) {
+        throw new Error(`CanopyCMS: invalid branch namespace ${JSON.stringify(template)} (from ${source}): ` +
+            `${JSON.stringify(unknown[0])} is not a placeholder; the only one is ${DEPLOYMENT_PLACEHOLDER}`);
+    }
+    const namespace = template.replaceAll(DEPLOYMENT_PLACEHOLDER, deploymentName);
+    const problem = branchNamespaceProblem(namespace);
+    if (problem !== null) {
+        throw new Error(`CanopyCMS: invalid branch namespace ${JSON.stringify(namespace)} (from ${source}): ${problem}`);
+    }
+    return namespace;
+}
+/**
+ * The branch namespace a process resolves: from `env`'s `CANOPYCMS_BRANCH_NAMESPACE` (trimmed,
+ * empty ignored), then `config.branchNamespace`, then the default, with `{deployment}` filled by
+ * `resolveDeploymentName`. Throws for an invalid template or deployment name.
+ */
+export function resolveBranchNamespace(config, modeDefault, env = process.env) {
+    const fromEnv = env[BRANCH_NAMESPACE_ENV]?.trim();
+    const [template, source] = fromEnv
+        ? [fromEnv, BRANCH_NAMESPACE_ENV]
+        : config.branchNamespace !== undefined
+            ? [config.branchNamespace, 'config.branchNamespace']
+            : [DEFAULT_BRANCH_NAMESPACE_TEMPLATE, 'the default'];
+    const deploymentName = resolveDeploymentName({ deploymentName: config.deploymentName }, modeDefault);
+    const namespace = resolveBranchNamespaceTemplate(template, deploymentName, source);
+    // Compared resolved: infrastructure stamps the namespace, config holds the template.
+    if (fromEnv && config.branchNamespace !== undefined) {
+        let fromConfig = null;
+        try {
+            fromConfig = resolveBranchNamespaceTemplate(config.branchNamespace, deploymentName, 'config.branchNamespace');
+        }
+        catch {
+            // An invalid config template is warned about too: the environment variable wins anyway.
+        }
+        if (fromConfig !== namespace) {
+            warnOnce(`CanopyCMS: ${BRANCH_NAMESPACE_ENV} (${JSON.stringify(fromEnv)}) and ` +
+                `config.branchNamespace (${JSON.stringify(config.branchNamespace)}) do not resolve to ` +
+                'the same valid namespace; using the environment variable, which infrastructure stamps ' +
+                'per stack.');
+        }
+    }
+    return namespace;
+}

package/dist/operating-mode/client-unsafe-strategy.js

@@ -4,6 +4,7 @@
  */
 import path from 'node:path';
 import { ProdClientSafeStrategy, DevClientSafeStrategy } from './client-safe-strategy.js';
+import { resolveBranchNamespace } from './branch-namespace.js';
 import { resolveDeploymentName } from './deployment-name.js';
 import { DEFAULT_PROD_WORKSPACE } from '../config/index.js';
 class ProdStrategy extends ProdClientSafeStrategy {
@@ -46,6 +47,9 @@ class ProdStrategy extends ProdClientSafeStrategy {
             return config.settingsBranch;
         return `canopycms-settings-${resolveDeploymentName(config, 'prod')}`;
     }
+    getBranchNamespace(config) {
+        return resolveBranchNamespace(config, 'prod');
+    }
     getSettingsRoot(sourceRoot) {
         return path.join(this.getWorkspaceRoot(sourceRoot), 'settings');
     }
@@ -95,6 +99,9 @@ class DevStrategy extends DevClientSafeStrategy {
             return config.settingsBranch;
         return `canopycms-settings-${resolveDeploymentName(config, 'local')}`;
     }
+    getBranchNamespace(config) {
+        return resolveBranchNamespace(config, 'local');
+    }
     getSettingsRoot(sourceRoot) {
         return path.join(this.getWorkspaceRoot(sourceRoot), 'settings');
     }

package/dist/operating-mode/types.d.ts

@@ -82,6 +82,14 @@ export interface ClientUnsafeStrategy extends ClientSafeStrategy {
         deploymentName?: string;
         defaultBaseBranch?: string;
     }): string;
+    /**
+     * The prefix of every branch editors create, resolved from the namespace template with this
+     * mode's default deployment name (operating-mode/branch-namespace.ts).
+     */
+    getBranchNamespace(config: {
+        branchNamespace?: string;
+        deploymentName?: string;
+    }): string;
     /** `{workspaceRoot}/settings`, where settings storage lives. */
     getSettingsRoot(sourceRoot?: string): string;
     usesSeparateSettingsBranch(): boolean;

package/dist/paths/branch-name.d.ts

@@ -18,9 +18,9 @@ export declare function sanitizeBranchName(branchName: string): SanitizedBranchN
  * Exported from this dependency-free module -- not rebuilt ad hoc at each call
  * site -- so every consumer of the namespace agrees on the exact string:
  * worker/git-sync.ts's `pushSettingsBranches` never pushes a
- * `canopycms-settings-*` branch this deployment doesn't own, and api/branch.ts's
- * `createBranchHandler` rejects a user-requested branch whose SANITIZED name
- * falls in this namespace.
+ * `canopycms-settings-*` branch this deployment doesn't own, and
+ * operating-mode/branch-namespace.ts refuses a branch namespace whose branches
+ * could fall in it.
  *
  * The WHOLE prefix is reserved, not just this deployment's own settings branch:
  * two deployments can share one GitHub repo, and a content branch landing on
@@ -29,24 +29,16 @@ export declare function sanitizeBranchName(branchName: string): SanitizedBranchN
  * branch.
  */
 export declare const RESERVED_SETTINGS_BRANCH_PREFIX = "canopycms-settings-";
+/**
+ * Branch `name`'s short name: the part after `namespace` for a branch in it, the full name for
+ * any other, and for one whose remainder holds a `/`. So a short name holding a `/` is always a
+ * full name, which the editor's unlisted request segment (editor/branch-names.ts `unlistedSegment`)
+ * relies on. The server rebuilds the ref from it (branch-param.ts's `resolveBranchParam`); the
+ * editor is never told the namespace.
+ */
+export declare function branchShortName(name: string, namespace: string | null): string;
 /**
  * Whether `branchName` is a settings branch, never a content branch: the reserved prefix, or the
  * configured name (which need not carry it). Compared sanitized, the form git and disk use.
  */
 export declare function isSettingsBranchName(branchName: string, settingsBranchName?: string): boolean;
-/**
- * Branch names that collide with a static top-level API route namespace.
- *
- * http/router.ts's `compareSpecificity` ranks a literal pattern segment above a
- * `:param`, so a branch named e.g. `admin` has its `/:branch/...` routes
- * shadowed by the static `/admin/...` ones -- and only partially, which is what
- * makes it confusing: bare `GET /admin` still reaches the branch handler, so the
- * branch looks half-alive while every nested route 404s or 403s.
- *
- * Listed rather than derived at runtime because api/validators.ts is imported
- * *by* the route modules, so importing the router here would cycle.
- * http/router.test.ts derives the same set from the live route table and asserts
- * it equals this constant, so a new top-level namespace fails that test until
- * this list is updated.
- */
-export declare const RESERVED_ROUTE_BRANCH_NAMES: readonly string[];

package/dist/paths/branch-name.js

@@ -22,9 +22,9 @@ export function sanitizeBranchName(branchName) {
  * Exported from this dependency-free module -- not rebuilt ad hoc at each call
  * site -- so every consumer of the namespace agrees on the exact string:
  * worker/git-sync.ts's `pushSettingsBranches` never pushes a
- * `canopycms-settings-*` branch this deployment doesn't own, and api/branch.ts's
- * `createBranchHandler` rejects a user-requested branch whose SANITIZED name
- * falls in this namespace.
+ * `canopycms-settings-*` branch this deployment doesn't own, and
+ * operating-mode/branch-namespace.ts refuses a branch namespace whose branches
+ * could fall in it.
  *
  * The WHOLE prefix is reserved, not just this deployment's own settings branch:
  * two deployments can share one GitHub repo, and a content branch landing on
@@ -33,6 +33,20 @@ export function sanitizeBranchName(branchName) {
  * branch.
  */
 export const RESERVED_SETTINGS_BRANCH_PREFIX = 'canopycms-settings-';
+/**
+ * Branch `name`'s short name: the part after `namespace` for a branch in it, the full name for
+ * any other, and for one whose remainder holds a `/`. So a short name holding a `/` is always a
+ * full name, which the editor's unlisted request segment (editor/branch-names.ts `unlistedSegment`)
+ * relies on. The server rebuilds the ref from it (branch-param.ts's `resolveBranchParam`); the
+ * editor is never told the namespace.
+ */
+export function branchShortName(name, namespace) {
+    if (namespace === null || !name.startsWith(namespace) || name.length === namespace.length) {
+        return name;
+    }
+    const rest = name.slice(namespace.length);
+    return rest.includes('/') ? name : rest;
+}
 /**
  * Whether `branchName` is a settings branch, never a content branch: the reserved prefix, or the
  * configured name (which need not carry it). Compared sanitized, the form git and disk use.
@@ -42,27 +56,3 @@ export function isSettingsBranchName(branchName, settingsBranchName) {
     return (sanitized.startsWith(RESERVED_SETTINGS_BRANCH_PREFIX) ||
         (settingsBranchName !== undefined && sanitized === sanitizeBranchName(settingsBranchName)));
 }
-/**
- * Branch names that collide with a static top-level API route namespace.
- *
- * http/router.ts's `compareSpecificity` ranks a literal pattern segment above a
- * `:param`, so a branch named e.g. `admin` has its `/:branch/...` routes
- * shadowed by the static `/admin/...` ones -- and only partially, which is what
- * makes it confusing: bare `GET /admin` still reaches the branch handler, so the
- * branch looks half-alive while every nested route 404s or 403s.
- *
- * Listed rather than derived at runtime because api/validators.ts is imported
- * *by* the route modules, so importing the router here would cycle.
- * http/router.test.ts derives the same set from the live route table and asserts
- * it equals this constant, so a new top-level namespace fails that test until
- * this list is updated.
- */
-export const RESERVED_ROUTE_BRANCH_NAMES = [
-    'admin',
-    'assets',
-    'branches',
-    'groups',
-    'permissions',
-    'users',
-    'whoami',
-];

package/dist/paths/index.d.ts

@@ -5,7 +5,7 @@
 export type { LogicalPath, PhysicalPath, SanitizedBranchName, BranchName, ContentId, Slug, PathValidationResult, } from './types.js';
 export { normalizeFilesystemPath, normalizeCollectionPath, hasTraversalSequence, createLogicalPath, createPhysicalPath, entryLogicalPath, joinPath, trimSlashes, } from './normalize.js';
 export { validateAndNormalizePath } from './normalize-server.js';
-export { validateContentPath, isValidCollectionPath, sanitizeForPath, hasEmbeddedContentId, looksLikePhysicalPath, looksLikeLogicalPath, parseLogicalPath, parsePhysicalPath, isValidContentId, parseContentId, parseBranchName, parseSlug, } from './validation.js';
+export { validateContentPath, isValidCollectionPath, sanitizeForPath, hasEmbeddedContentId, looksLikePhysicalPath, looksLikeLogicalPath, parseLogicalPath, parsePhysicalPath, isValidContentId, parseContentId, parseBranchName, parseBranchRef, parseCreatedBranchName, parseSlug, } from './validation.js';
 export { resolveLogicalPath } from './resolve.js';
 export { resolveBranchPath, getDefaultBranchBase, resolveBranchPaths, BranchPathError, namesNoWorkspace, type BranchPathOptions, type BranchPathResult, } from './branch.js';
-export { sanitizeBranchName, RESERVED_SETTINGS_BRANCH_PREFIX, RESERVED_ROUTE_BRANCH_NAMES, isSettingsBranchName, } from './branch-name.js';
+export { sanitizeBranchName, RESERVED_SETTINGS_BRANCH_PREFIX, branchShortName, isSettingsBranchName, } from './branch-name.js';

package/dist/paths/index.js

@@ -6,7 +6,7 @@
 export { normalizeFilesystemPath, normalizeCollectionPath, hasTraversalSequence, createLogicalPath, createPhysicalPath, entryLogicalPath, joinPath, trimSlashes, } from './normalize.js';
 // Normalization utilities (server-only, requires Node.js path module)
 export { validateAndNormalizePath } from './normalize-server.js';
-export { validateContentPath, isValidCollectionPath, sanitizeForPath, hasEmbeddedContentId, looksLikePhysicalPath, looksLikeLogicalPath, parseLogicalPath, parsePhysicalPath, isValidContentId, parseContentId, parseBranchName, parseSlug, } from './validation.js';
+export { validateContentPath, isValidCollectionPath, sanitizeForPath, hasEmbeddedContentId, looksLikePhysicalPath, looksLikeLogicalPath, parseLogicalPath, parsePhysicalPath, isValidContentId, parseContentId, parseBranchName, parseBranchRef, parseCreatedBranchName, parseSlug, } from './validation.js';
 export { resolveLogicalPath } from './resolve.js';
 export { resolveBranchPath, getDefaultBranchBase, resolveBranchPaths, BranchPathError, namesNoWorkspace, } from './branch.js';
-export { sanitizeBranchName, RESERVED_SETTINGS_BRANCH_PREFIX, RESERVED_ROUTE_BRANCH_NAMES, isSettingsBranchName, } from './branch-name.js';
+export { sanitizeBranchName, RESERVED_SETTINGS_BRANCH_PREFIX, branchShortName, isSettingsBranchName, } from './branch-name.js';

package/dist/paths/resolve.d.ts

@@ -11,6 +11,5 @@ import type { LogicalPath } from './types.js';
  * @example
  * resolveLogicalPath("content/docs.ABC/api.DEF", schemaItems)
  * // Returns: "content/docs/api"
- * @internal Exported for tests.
  */
 export declare function resolveLogicalPath(physicalPath: string, schemaItems: Iterable<FlatSchemaItem>): LogicalPath | string;

package/dist/paths/resolve.js

@@ -9,7 +9,6 @@
  * @example
  * resolveLogicalPath("content/docs.ABC/api.DEF", schemaItems)
  * // Returns: "content/docs/api"
- * @internal Exported for tests.
  */
 export function resolveLogicalPath(physicalPath, schemaItems) {
     const pathSegments = physicalPath.split('/');

package/dist/paths/validation.d.ts

@@ -64,7 +64,20 @@ export declare function parseContentId(id: string): {
     ok: false;
     error: string;
 };
-/** Validate a branch name against git's ref rules and cast it to BranchName. */
+/** Whether `param` is in the exact form, well formed or not: no branch name starts with `~`. */
+export declare function isExactBranchForm(param: string): boolean;
+/** The exact form of the branch whose full name is `fullName`. */
+export declare function exactBranchSegment(fullName: string): string;
+/**
+ * The full name the exact form `param` names, or null when `param` is no well-formed exact form:
+ * it starts with `~`, holds no `/`, and with each later `~` read as `/` names a branch
+ * `parseBranchRef` takes, which refuses an empty name or part (`~`, `~~a`, `~a~`).
+ */
+export declare function exactBranchName(param: string): string | null;
+/**
+ * Validate a branch named in a request, by a `/:branch` segment or `?branch=`, and cast it to
+ * BranchName: a name `parseBranchRef` takes, or a well-formed exact form of one.
+ */
 export declare function parseBranchName(name: string): {
     ok: true;
     name: BranchName;
@@ -72,6 +85,32 @@ export declare function parseBranchName(name: string): {
     ok: false;
     error: string;
 };
+/**
+ * Validate a branch's own name, the ref git and branch.json hold, against git's ref rules, except
+ * that an inner part may start with `.` or end `.lock` (`a/.b`, `a.lock/b`), and cast it to
+ * BranchName. It refuses every `~`, so the exact form is never one.
+ */
+export declare function parseBranchRef(name: string): {
+    ok: true;
+    name: BranchName;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * The branch an editor's typed name creates in `namespace`, or why it cannot: the typed name
+ * sanitized, so it holds no `/`, is the short name, and the ref is the namespace followed by it.
+ * `createBranchHandler` passes its resolved namespace; the editor, which is never told one, passes
+ * none and checks the typed name alone, so its length limit is the looser one.
+ */
+export declare function parseCreatedBranchName(typed: string, namespace?: string): {
+    ok: true;
+    name: BranchName;
+    shortName: string;
+} | {
+    ok: false;
+    error: string;
+};
 /** Validate a collection or entry slug and cast it to Slug. */
 export declare function parseSlug(slug: string): {
     ok: true;

package/dist/paths/validation.js

@@ -1,4 +1,5 @@
 /** Security-focused validation for content paths, IDs, branch names and slugs. */
+import { sanitizeBranchName } from './branch-name.js';
 import { normalizeFilesystemPath, hasTraversalSequence } from './normalize.js';
 /** Base58 alphabet for content IDs: excludes the ambiguous 0, O, I and l. */
 const BASE58_PATTERN = '[123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz]';
@@ -133,14 +134,60 @@ export function parseContentId(id) {
     }
     return { ok: true, id: id };
 }
-/** Validate a branch name against git's ref rules and cast it to BranchName. */
+/** The longest branch name taken, in characters: names become directory names. */
+const MAX_BRANCH_NAME_LENGTH = 250;
+/**
+ * What starts a branch's exact form: `~`, then its full name with each `/` written `~`, so
+ * `canopycms/prod/spring` is `~canopycms~prod~spring` and a branch outside the namespace named
+ * `spring` is `~spring`. That branch and the namespace branch `canopycms/prod/spring` both answer
+ * to `spring`, which opens the namespace one; `~spring` opens the other. Git refuses `~` in a
+ * branch name, so no other name starts with it and the mapping reverses exactly, and
+ * `encodeURIComponent` leaves `~` alone, so a request path carries the form without `%2F`.
+ */
+const EXACT_BRANCH_MARK = '~';
+/** Whether `param` is in the exact form, well formed or not: no branch name starts with `~`. */
+export function isExactBranchForm(param) {
+    return param.startsWith(EXACT_BRANCH_MARK);
+}
+/** The exact form of the branch whose full name is `fullName`. */
+export function exactBranchSegment(fullName) {
+    return `${EXACT_BRANCH_MARK}${fullName.replaceAll('/', EXACT_BRANCH_MARK)}`;
+}
+/**
+ * The full name the exact form `param` names, or null when `param` is no well-formed exact form:
+ * it starts with `~`, holds no `/`, and with each later `~` read as `/` names a branch
+ * `parseBranchRef` takes, which refuses an empty name or part (`~`, `~~a`, `~a~`).
+ */
+export function exactBranchName(param) {
+    if (!isExactBranchForm(param) || param.includes('/'))
+        return null;
+    const named = parseBranchRef(param.slice(EXACT_BRANCH_MARK.length).replaceAll(EXACT_BRANCH_MARK, '/'));
+    return named.ok ? named.name : null;
+}
+/**
+ * Validate a branch named in a request, by a `/:branch` segment or `?branch=`, and cast it to
+ * BranchName: a name `parseBranchRef` takes, or a well-formed exact form of one.
+ */
 export function parseBranchName(name) {
+    if (typeof name === 'string' && isExactBranchForm(name)) {
+        return exactBranchName(name) === null
+            ? { ok: false, error: 'Branch name starts with "~" but names no branch' }
+            : { ok: true, name: name };
+    }
+    return parseBranchRef(name);
+}
+/**
+ * Validate a branch's own name, the ref git and branch.json hold, against git's ref rules, except
+ * that an inner part may start with `.` or end `.lock` (`a/.b`, `a.lock/b`), and cast it to
+ * BranchName. It refuses every `~`, so the exact form is never one.
+ */
+export function parseBranchRef(name) {
     if (!name || typeof name !== 'string') {
         return { ok: false, error: 'Branch name is required' };
     }
-    // Length limit (branch names become directory names)
-    if (name.length > 250) {
-        return { ok: false, error: 'Branch name too long (max 250 characters)' };
+    // Length limit (branch names become directory names).
+    if (name.length > MAX_BRANCH_NAME_LENGTH) {
+        return { ok: false, error: `Branch name too long (max ${MAX_BRANCH_NAME_LENGTH} characters)` };
     }
     if (name.includes('..')) {
         return { ok: false, error: 'Branch name cannot contain ".."' };
@@ -178,6 +225,38 @@ export function parseBranchName(name) {
     }
     return { ok: true, name: name };
 }
+/**
+ * The branch an editor's typed name creates in `namespace`, or why it cannot: the typed name
+ * sanitized, so it holds no `/`, is the short name, and the ref is the namespace followed by it.
+ * `createBranchHandler` passes its resolved namespace; the editor, which is never told one, passes
+ * none and checks the typed name alone, so its length limit is the looser one.
+ */
+export function parseCreatedBranchName(typed, namespace = '') {
+    const valid = parseBranchRef(typed);
+    if (!valid.ok)
+        return valid;
+    if (namespace !== '' && typed.startsWith(namespace)) {
+        return {
+            ok: false,
+            error: `Type only the branch's own name, without "${namespace}" in front: CanopyCMS adds it`,
+        };
+    }
+    // Without a leading '-' or '.', which a branch name may not start with (`parseBranchRef`).
+    const shortName = sanitizeBranchName(typed).replace(/^[-.]+/, '');
+    // "_" alone would name a branch whose short name is no word at all.
+    if (!/[a-zA-Z0-9]/.test(shortName)) {
+        return { ok: false, error: 'Branch name needs at least one letter (a–z) or digit' };
+    }
+    const ref = `${namespace}${shortName}`;
+    if (ref.length > MAX_BRANCH_NAME_LENGTH) {
+        return {
+            ok: false,
+            error: `Branch name too long (max ${MAX_BRANCH_NAME_LENGTH - namespace.length} characters)`,
+        };
+    }
+    const parsed = parseBranchRef(ref);
+    return parsed.ok ? { ok: true, name: parsed.name, shortName } : parsed;
+}
 /** Validate a collection or entry slug and cast it to Slug. */
 export function parseSlug(slug) {
     if (!slug) {

package/dist/pr-comments.d.ts

@@ -1,17 +1,23 @@
 /**
- * The worker action that re-renders a PR's editor-comment summary: enqueued by
- * api/pr-comment-sync.ts, run by worker/task-runner.ts.
+ * The worker action that re-renders both blocks of a PR body that change after a submit, the
+ * editor-comment summary and the review block: enqueued by api/pr-comment-sync.ts, run by
+ * worker/task-runner.ts. The action string is the queue's contract.
  */
 export declare const SYNC_PR_COMMENTS_ACTION = "sync-pr-comments";
 /**
- * `body` with its comment summary re-rendered from `branchRoot`'s comments.json, or undefined
- * when there is nothing to write: no summary block to replace, or no change.
+ * `body` with its comment summary re-rendered from `branchRoot`'s comments.json and its review
+ * block from the review in branch.json as stored, or undefined when there is nothing to write.
+ * The two blocks are replaced independently: a body without one still gets the other, and a
+ * file that is corrupt leaves its block as it is, with a warning, without stopping the other.
+ * A missing file is no failure. Any other read error, an IO fault that may pass, is thrown so
+ * that the caller retries or fails visibly.
  */
 export declare function renderPrCommentsBody(options: {
     branchRoot: string;
     branch: string;
     editorUrl?: string;
-    body: string | null | undefined;
+    body: string;
+    warn: (message: string) => void;
 }): Promise<string | undefined>;
 /**
  * The in-process lock every direct-path write of a branch's PR body holds (submit and comment
@@ -19,10 +25,12 @@ export declare function renderPrCommentsBody(options: {
  */
 export declare function prBodyLockKey(branchRoot: string): string;
 /**
- * A submit's section with its comment block re-rendered from comments.json, for a queued submit
- * whose block was rendered when it was queued: a comment change since then, or a sync task that
- * ran while this one waited out a retry, would otherwise be overwritten. If comments.json cannot
- * be read, the section keeps the block it was queued with.
+ * A submit's section with its comment and review blocks re-rendered from disk, for a queued
+ * submit whose blocks were rendered when it was queued: a comment or review since
+ * then, or a sync task that ran while this one waited out a retry, would otherwise be
+ * overwritten. The review is the one stored, as in renderPrCommentsBody: a submit clears the
+ * last verdict before it writes the PR. A file that cannot be read leaves its block as it was
+ * queued.
  */
 export declare function refreshCommentsBlock(options: {
     branchRoot: string;

package/dist/pr-comments.js

@@ -1,19 +1,46 @@
-import { CommentStore } from './comment-store.js';
+import { CommentStore, CommentsFileMalformedError } from './comment-store.js';
 import { getErrorMessage } from './utils/error.js';
-import { buildCommentsBlock, mergeCommentsBlock } from './submission-attribution.js';
+import { BranchMetadataCorruptError, readBranchMetadataFile } from './branch-metadata-file.js';
+import { buildCommentsBlock, buildReviewBlock, mergeCommentsBlock, mergeReviewBlock, } from './submission-attribution.js';
 /**
- * The worker action that re-renders a PR's editor-comment summary: enqueued by
- * api/pr-comment-sync.ts, run by worker/task-runner.ts.
+ * The worker action that re-renders both blocks of a PR body that change after a submit, the
+ * editor-comment summary and the review block: enqueued by api/pr-comment-sync.ts, run by
+ * worker/task-runner.ts. The action string is the queue's contract.
  */
 export const SYNC_PR_COMMENTS_ACTION = 'sync-pr-comments';
 /**
- * `body` with its comment summary re-rendered from `branchRoot`'s comments.json, or undefined
- * when there is nothing to write: no summary block to replace, or no change.
+ * `body` with its comment summary re-rendered from `branchRoot`'s comments.json and its review
+ * block from the review in branch.json as stored, or undefined when there is nothing to write.
+ * The two blocks are replaced independently: a body without one still gets the other, and a
+ * file that is corrupt leaves its block as it is, with a warning, without stopping the other.
+ * A missing file is no failure. Any other read error, an IO fault that may pass, is thrown so
+ * that the caller retries or fails visibly.
  */
 export async function renderPrCommentsBody(options) {
-    const threads = await new CommentStore(options.branchRoot).listThreadsStrict();
-    const next = mergeCommentsBlock(options.body, buildCommentsBlock(threads, options.branch, options.editorUrl));
-    return next === undefined || next === options.body ? undefined : next;
+    const original = options.body;
+    let next = original;
+    try {
+        const threads = await new CommentStore(options.branchRoot).listThreadsStrict();
+        next =
+            mergeCommentsBlock(next, buildCommentsBlock(threads, options.branch, options.editorUrl)) ??
+                next;
+    }
+    catch (err) {
+        if (!(err instanceof SyntaxError || err instanceof CommentsFileMalformedError))
+            throw err;
+        options.warn(`Could not read the editor comments of ${options.branch}; the PR keeps its summary: ${getErrorMessage(err)}`);
+    }
+    try {
+        const file = await readBranchMetadataFile(options.branchRoot);
+        if (file)
+            next = mergeReviewBlock(next, buildReviewBlock(file.branch.review)) ?? next;
+    }
+    catch (err) {
+        if (!(err instanceof BranchMetadataCorruptError))
+            throw err;
+        options.warn(`Could not read the review state of ${options.branch}; the PR keeps its review block: ${getErrorMessage(err)}`);
+    }
+    return next === original ? undefined : next;
 }
 /**
  * The in-process lock every direct-path write of a branch's PR body holds (submit and comment
@@ -23,19 +50,30 @@ export function prBodyLockKey(branchRoot) {
     return `pr-body:${branchRoot}`;
 }
 /**
- * A submit's section with its comment block re-rendered from comments.json, for a queued submit
- * whose block was rendered when it was queued: a comment change since then, or a sync task that
- * ran while this one waited out a retry, would otherwise be overwritten. If comments.json cannot
- * be read, the section keeps the block it was queued with.
+ * A submit's section with its comment and review blocks re-rendered from disk, for a queued
+ * submit whose blocks were rendered when it was queued: a comment or review since
+ * then, or a sync task that ran while this one waited out a retry, would otherwise be
+ * overwritten. The review is the one stored, as in renderPrCommentsBody: a submit clears the
+ * last verdict before it writes the PR. A file that cannot be read leaves its block as it was
+ * queued.
  */
 export async function refreshCommentsBlock(options) {
+    let section = options.section;
     try {
         const threads = await new CommentStore(options.branchRoot).listThreadsStrict();
         const block = buildCommentsBlock(threads, options.branch, options.editorUrl);
-        return mergeCommentsBlock(options.section, block) ?? options.section;
+        section = mergeCommentsBlock(section, block) ?? section;
     }
     catch (err) {
         options.warn(`Could not re-read the editor comments of ${options.branch}; the PR gets the summary from submit time: ${getErrorMessage(err)}`);
-        return options.section;
     }
+    try {
+        const file = await readBranchMetadataFile(options.branchRoot);
+        if (file)
+            section = mergeReviewBlock(section, buildReviewBlock(file.branch.review)) ?? section;
+    }
+    catch (err) {
+        options.warn(`Could not re-read the review state of ${options.branch}; the PR gets it from submit time: ${getErrorMessage(err)}`);
+    }
+    return section;
 }

package/dist/services.js

@@ -29,6 +29,7 @@ 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 { baseBranchOf } from './utils/base-branch.js';
+import { shortNameOf } from './branch-param.js';
 import { detectHeadBranch, isCanopyInternalPath } from './utils/git.js';
 import { readsFromCheckout } from './build-mode.js';
 import { timeRequestPhase } from './utils/request-timing.js';
@@ -330,7 +331,7 @@ async function _createCanopyServicesInternal(config, options) {
             if (changedPaths?.length === 0) {
                 if (committed)
                     await git.resetKeepingChanges(preCommitSha);
-                throw new NothingToSubmitError(options.context.branch.name, effectiveBase);
+                throw new NothingToSubmitError(shortNameOf(config, options.context.branch.name), effectiveBase);
             }
             // A failure here leaves them uncommitted, so the next commit names them again.
             if (committed && uncommitted.length > 0) {