canopycms 0.7.1 → 0.8.0

package/dist/cli/init.js

@@ -557,6 +557,8 @@ var init_config = __esm({
       // (operating-mode/deployment-name.ts) implements — config would always "win" over
       // modeDefault, masking dev's real default of 'local'. Do not remove `.optional()`.
       deploymentName: deploymentNameSchema.optional(),
+      // Checked where it is resolved (operating-mode/branch-namespace.ts), with the deployment name.
+      branchNamespace: z5.string().optional(),
       contentRoot: contentRootSchema.default("content"),
       sourceRoot: sourceRootSchema.optional(),
       basePath: basePathSchema,
@@ -1599,6 +1601,60 @@ var DevClientSafeStrategy = class {
 // dist/operating-mode/client-unsafe-strategy.js
 import path from "node:path";
 
+// dist/paths/branch-name.js
+function sanitizeBranchName(branchName) {
+  const replaced = branchName.replace(/[^a-zA-Z0-9._-]/g, "-");
+  const squashed = replaced.replace(/-+/g, "-");
+  const trimmedDots = squashed.replace(/^\.+/, "").replace(/(?<!\.)\.+$/, "");
+  return trimmedDots || "branch";
+}
+var RESERVED_SETTINGS_BRANCH_PREFIX = "canopycms-settings-";
+
+// dist/paths/validation.js
+var BASE58_PATTERN = "[123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz]";
+var CONTENT_ID_PATTERN = new RegExp(`^${BASE58_PATTERN}{12}$`);
+var PHYSICAL_SEGMENT_PATTERN = new RegExp(`\\.${BASE58_PATTERN}{12}(?:\\.[a-z]+)?$`);
+var MAX_BRANCH_NAME_LENGTH = 250;
+function parseBranchRef(name) {
+  if (!name || typeof name !== "string") {
+    return { ok: false, error: "Branch name is required" };
+  }
+  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 ".."' };
+  }
+  if (name.startsWith("/") || name.endsWith("/") || name.includes("//")) {
+    return { ok: false, error: "Invalid branch name format (invalid slashes)" };
+  }
+  if (name.includes(" ")) {
+    return { ok: false, error: "Branch name cannot contain spaces" };
+  }
+  if (name.startsWith("-")) {
+    return { ok: false, error: 'Branch name cannot start with "-"' };
+  }
+  if (name.startsWith(".") || name.endsWith(".")) {
+    return { ok: false, error: "Branch name cannot start or end with a dot" };
+  }
+  if (name.includes("@{")) {
+    return { ok: false, error: 'Branch name cannot contain "@{"' };
+  }
+  if (name === "HEAD" || name === "@") {
+    return { ok: false, error: 'Branch name cannot be the reserved ref "HEAD" or "@"' };
+  }
+  if (/[~^:?*[\\\x00-\x1f\x7f]/.test(name)) {
+    return { ok: false, error: "Branch name contains invalid characters" };
+  }
+  if (name.endsWith(".lock")) {
+    return { ok: false, error: 'Branch name cannot end with ".lock"' };
+  }
+  return { ok: true, name };
+}
+
+// dist/operating-mode/branch-namespace.js
+init_logger();
+
 // dist/operating-mode/deployment-name.js
 init_logger();
 var warned = false;
@@ -1619,6 +1675,70 @@ function resolveDeploymentName(config, modeDefault) {
   return resolved;
 }
 
+// dist/operating-mode/branch-namespace.js
+var warned2 = false;
+function warnOnce(message) {
+  if (warned2)
+    return;
+  warned2 = true;
+  canopyLogWarn(message);
+}
+var DEPLOYMENT_PLACEHOLDER = "{deployment}";
+var DEFAULT_BRANCH_NAMESPACE_TEMPLATE = `canopycms/${DEPLOYMENT_PLACEHOLDER}/`;
+var BRANCH_NAMESPACE_ENV = "CANOPYCMS_BRANCH_NAMESPACE";
+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'";
+  }
+  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;
+}
+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;
+}
+function resolveBranchNamespace(config, modeDefault, env = process.env) {
+  const fromEnv = env[BRANCH_NAMESPACE_ENV]?.trim();
+  const [template, source] = fromEnv ? [fromEnv, BRANCH_NAMESPACE_ENV] : config.branchNamespace !== void 0 ? [config.branchNamespace, "config.branchNamespace"] : [DEFAULT_BRANCH_NAMESPACE_TEMPLATE, "the default"];
+  const deploymentName = resolveDeploymentName({ deploymentName: config.deploymentName }, modeDefault);
+  const namespace = resolveBranchNamespaceTemplate(template, deploymentName, source);
+  if (fromEnv && config.branchNamespace !== void 0) {
+    let fromConfig = null;
+    try {
+      fromConfig = resolveBranchNamespaceTemplate(config.branchNamespace, deploymentName, "config.branchNamespace");
+    } catch {
+    }
+    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;
+}
+
 // dist/operating-mode/client-unsafe-strategy.js
 init_config2();
 var ProdStrategy = class extends ProdClientSafeStrategy {
@@ -1659,6 +1779,9 @@ var ProdStrategy = class 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");
   }
@@ -1708,6 +1831,9 @@ var DevStrategy = class 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/comment-store.d.ts

@@ -35,6 +35,9 @@ export interface CommentsFile {
     writeId?: string;
     threads: Record<string, CommentThread>;
 }
+/** comments.json parses but has no `threads` object; text that does not parse throws SyntaxError. */
+export declare class CommentsFileMalformedError extends Error {
+}
 /**
  * Comment storage for a branch workspace, in .canopy-meta/comments.json and
  * never committed to git.

package/dist/comment-store.js

@@ -20,6 +20,9 @@ function ownThread(data, threadId) {
         ? data.threads[threadId]
         : undefined;
 }
+/** comments.json parses but has no `threads` object; text that does not parse throws SyntaxError. */
+export class CommentsFileMalformedError extends Error {
+}
 /**
  * Comment storage for a branch workspace, in .canopy-meta/comments.json and
  * never committed to git.
@@ -65,7 +68,7 @@ export class CommentStore {
             ? parsed.threads
             : undefined;
         if (typeof threads !== 'object' || threads === null) {
-            throw new Error('comments.json has no threads object');
+            throw new CommentsFileMalformedError('comments.json has no threads object');
         }
         return Object.values(threads);
     }

package/dist/config/schemas/config.d.ts

@@ -68,6 +68,7 @@ export declare const CanopyConfigSchema: z.ZodObject<{
     allowNetworkRemoteInProd: z.ZodOptional<z.ZodBoolean>;
     settingsBranch: z.ZodOptional<z.ZodString>;
     deploymentName: z.ZodOptional<z.ZodDefault<z.ZodString>>;
+    branchNamespace: z.ZodOptional<z.ZodString>;
     contentRoot: z.ZodDefault<z.ZodDefault<z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>, string, string>>>;
     sourceRoot: z.ZodOptional<z.ZodOptional<z.ZodString>>;
     basePath: z.ZodOptional<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>>;
@@ -200,6 +201,7 @@ export declare const CanopyConfigSchema: z.ZodObject<{
     githubTokenEnvVar?: string | undefined;
     allowNetworkRemoteInProd?: boolean | undefined;
     deploymentName?: string | undefined;
+    branchNamespace?: string | undefined;
     sourceRoot?: string | undefined;
     basePath?: string | undefined;
     editorUrl?: string | undefined;
@@ -267,6 +269,7 @@ export declare const CanopyConfigSchema: z.ZodObject<{
     deployedAs?: "static" | "server" | undefined;
     allowNetworkRemoteInProd?: boolean | undefined;
     deploymentName?: string | undefined;
+    branchNamespace?: string | undefined;
     contentRoot?: string | undefined;
     sourceRoot?: string | undefined;
     basePath?: string | undefined;

package/dist/config/schemas/config.js

@@ -120,6 +120,8 @@ export const CanopyConfigSchema = z
     // (operating-mode/deployment-name.ts) implements — config would always "win" over
     // modeDefault, masking dev's real default of 'local'. Do not remove `.optional()`.
     deploymentName: deploymentNameSchema.optional(),
+    // Checked where it is resolved (operating-mode/branch-namespace.ts), with the deployment name.
+    branchNamespace: z.string().optional(),
     contentRoot: contentRootSchema.default('content'),
     sourceRoot: sourceRootSchema.optional(),
     basePath: basePathSchema,

package/dist/config/types.d.ts

@@ -433,6 +433,7 @@ export interface EntryValidationIssue {
 export interface ValidateEntryInput {
     /** Logical entry path including the content root (e.g. 'content/posts/hello-world'). */
     entryPath: string;
+    /** The branch's full name, as git holds it (`canopycms/prod/spring-update`). */
     branch: string;
     /**
      * The entry type the save is validated and written as: an existing entry's on-disk type, else
@@ -474,6 +475,8 @@ export interface CanopyConfig {
     allowNetworkRemoteInProd?: boolean;
     settingsBranch?: string;
     deploymentName?: string;
+    /** The branch namespace template — see {@link CanopyConfigInput.branchNamespace}. */
+    branchNamespace?: string;
     contentRoot: ContentRoot;
     sourceRoot?: SourceRoot;
     /** Deployment prefix the host app is served under — see {@link CanopyConfigInput.basePath}. */
@@ -539,6 +542,14 @@ export interface CanopyConfigInput {
     allowNetworkRemoteInProd?: boolean;
     settingsBranch?: string;
     deploymentName?: string;
+    /**
+     * The prefix of every branch editors create, which the GitHub gateway confines its writes to,
+     * as a template in which `{deployment}` is the deployment name, ending with `/` (default
+     * `canopycms/{deployment}/`). `CANOPYCMS_BRANCH_NAMESPACE` wins over it, as the deployment
+     * name's variable does; a CDK deployment sets that variable for the CMS and for the GitHub
+     * gateway from `CanopyCmsService`'s `branchNamespace`.
+     */
+    branchNamespace?: string;
     contentRoot?: string;
     sourceRoot?: string;
     /**

package/dist/content-id-index.d.ts

@@ -1,4 +1,9 @@
 import { type LogicalPath, type PhysicalPath, type Slug, type ContentId } from './paths/index.js';
+/**
+ * Strips the embedded ID from each physical segment to produce a logical path:
+ * "content/posts.a1b2c3d4e5f6" → "content/posts".
+ */
+export declare function toLogicalCollectionPath(physicalPath: string): LogicalPath;
 /**
  * The path the editor lists the entry a file stores under (`EditorEntry.path`, which its
  * `entry` param matches), or null for a file that cannot be a listed entry: outside

package/dist/content-id-index.js

@@ -34,7 +34,7 @@ const EMPTY_LOGICAL_PATH = '';
  * Strips the embedded ID from each physical segment to produce a logical path:
  * "content/posts.a1b2c3d4e5f6" → "content/posts".
  */
-function toLogicalCollectionPath(physicalPath) {
+export function toLogicalCollectionPath(physicalPath) {
     if (physicalPath === '.')
         return EMPTY_LOGICAL_PATH;
     return physicalPath

package/dist/content-listing.d.ts

@@ -18,7 +18,60 @@ export interface CollectionListItem {
     data: Record<string, unknown>;
     updatedAt?: string;
 }
+/**
+ * Parse an entry file's text into its data and, for md/mdx, its markdown content apart, as
+ * `ContentStore.read` shapes a document. Throws on text that does not parse.
+ */
+export declare const parseEntryParts: (raw: string, format: ContentFormat) => {
+    data: Record<string, unknown>;
+    body?: string;
+};
+/**
+ * Parse an entry file's text. For md/mdx: frontmatter fields plus the body content under
+ * `bodyFieldName` (defaults to `'body'`); for json/yaml, the parsed object. Throws on text
+ * that does not parse.
+ */
+export declare const parseEntryData: (raw: string, format: ContentFormat, bodyFieldName?: string) => Record<string, unknown>;
 export { parseTypedFilename } from './utils/typed-filename.js';
+/** What a repo-relative file path is to the editor: an entry, a collection's settings, or neither. */
+export type RepoPathRef = {
+    kind: 'entry';
+    logicalPath: LogicalPath;
+    contentId: ContentId;
+    entryType: string;
+    collectionPath: LogicalPath;
+    physicalPath: string;
+} | {
+    kind: 'collection-meta';
+    collectionPath: LogicalPath;
+    physicalPath: string;
+} | {
+    kind: 'other';
+    physicalPath: string;
+};
+/**
+ * Map a repo-relative file path, as git prints it, to the entry or collection settings it holds
+ * under `flatSchema`. Reads nothing from disk, so it maps a file that no longer exists.
+ * `contentRoot` is the config's (`'content'`): logical paths start with it, and a branch clone's
+ * root is the repo root, so its git paths do too.
+ *
+ * A file is an entry only as `listCollectionEntries` would list it: in a collection's
+ * directory, named `{type}.{slug}.{id}` with one of that collection's entry types and that
+ * type's extension. Directory segments below `contentRoot` compare lowercased, as
+ * `resolveCollectionPath` reads them. Anything else is `other`, including a path outside
+ * `contentRoot` and one with an empty, `.` or `..` segment, which no collection segment matches.
+ */
+export declare function entryRefFromRepoPath(repoPath: string, flatSchema: readonly FlatSchemaItem[], contentRoot: string): RepoPathRef;
+/**
+ * An entry or collection-settings ref read from `repoPath`'s shape alone, with no schema, for a
+ * file the current schema can't place: one deleted with its collection, under a collection's old
+ * name, or of an entry type since removed. The collection path strips the ids from the
+ * directory names, as the ContentId index does, and `entryType` is the filename's. Undefined
+ * for a path outside `contentRoot` or a filename of neither shape.
+ */
+export declare function entryRefFromRepoPathShape(repoPath: string, contentRoot: string): Exclude<RepoPathRef, {
+    kind: 'other';
+}> | undefined;
 /**
  * A flat entry item from listEntries.
  * Structural metadata is always present; `data` is controlled by the extract option.

package/dist/content-listing.js

@@ -8,8 +8,9 @@ import { parse as yamlParse } from 'yaml';
 import { findBodyFieldName } from './utils/body-field.js';
 import { computeEntryUrl } from './utils/entry-url.js';
 import { asRecord, getFormatExtension } from './utils/format.js';
-import { resolveCollectionPath } from './content-id-index.js';
+import { resolveCollectionPath, toLogicalCollectionPath } from './content-id-index.js';
 import { entryLogicalPath, validateAndNormalizePath } from './paths/index.js';
+import { resolveLogicalPath } from './paths/resolve.js';
 import { isNotFoundError, getErrorMessage } from './utils/error.js';
 import { createDebugLogger } from './utils/debug.js';
 import { ContentStore, ContentStoreError, createReferenceResolveCache, } from './content-store.js';
@@ -25,35 +26,45 @@ const normalizePath = (root, target) => {
     return result.normalizedPath;
 };
 /**
- * Read entry data from a file. For md/mdx: frontmatter fields plus the body content under
- * `bodyFieldName` (defaults to `'body'`); for json/yaml, the parsed object. Returns an empty
- * object on read/parse failure.
+ * Parse an entry file's text into its data and, for md/mdx, its markdown content apart, as
+ * `ContentStore.read` shapes a document. Throws on text that does not parse.
+ */
+export const parseEntryParts = (raw, format) => {
+    if (format === 'json')
+        return { data: asRecord(JSON.parse(raw)) };
+    if (format === 'yaml')
+        return { data: asRecord(yamlParse(raw)) };
+    // Read-only here, and the result is copied immediately below before anything
+    // is written into it -- see that comment for the hazard being avoided.
+    // eslint-disable-next-line no-restricted-syntax
+    const parsed = matter(raw);
+    // A copy, never gray-matter's own object. gray-matter keeps a PROCESS-GLOBAL cache keyed by
+    // file content and hands every caller the same `data` object instance, so writing the body
+    // into it in place wrote it into a shared object that later, unrelated `matter()` calls then
+    // saw as frontmatter: listing a collection containing an md entry poisoned the cache, and a
+    // reference resolution to that same entry (through `ContentStore.read()`, whose md branch
+    // calls `matter()` again) returned the body as a frontmatter field -- one entry with two
+    // shapes, decided by unrelated listing scope.
+    return { data: { ...(parsed.data ?? {}) }, body: parsed.content };
+};
+/**
+ * Parse an entry file's text. For md/mdx: frontmatter fields plus the body content under
+ * `bodyFieldName` (defaults to `'body'`); for json/yaml, the parsed object. Throws on text
+ * that does not parse.
+ */
+export const parseEntryData = (raw, format, bodyFieldName = 'body') => {
+    const { data, body } = parseEntryParts(raw, format);
+    if (body)
+        data[bodyFieldName] = body;
+    return data;
+};
+/**
+ * Read entry data from a file, parsed by {@link parseEntryData}. Returns an empty object on
+ * read/parse failure.
  */
 const readEntryData = async (filePath, format, bodyFieldName = 'body') => {
     try {
-        const raw = await fs.readFile(filePath, 'utf8');
-        if (format === 'json') {
-            return asRecord(JSON.parse(raw));
-        }
-        if (format === 'yaml') {
-            return asRecord(yamlParse(raw));
-        }
-        // Read-only here, and the result is copied immediately below before anything
-        // is written into it -- see that comment for the hazard being avoided.
-        // eslint-disable-next-line no-restricted-syntax
-        const parsed = matter(raw);
-        // Copy before writing the body in. gray-matter keeps a PROCESS-GLOBAL cache keyed by file
-        // content and hands every caller the same `data` object instance, so mutating it in place
-        // wrote the body into a shared object that later, unrelated `matter()` calls then saw as
-        // frontmatter: listing a collection containing an md entry poisoned the cache, and a
-        // reference resolution to that same entry (through `ContentStore.read()`, whose md branch
-        // calls `matter()` again) returned the body as a frontmatter field -- one entry with two
-        // shapes, decided by unrelated listing scope.
-        const data = { ...(parsed.data ?? {}) };
-        if (parsed.content) {
-            data[bodyFieldName] = parsed.content;
-        }
-        return data;
+        return parseEntryData(await fs.readFile(filePath, 'utf8'), format, bodyFieldName);
     }
     catch (err) {
         if (isNotFoundError(err))
@@ -67,6 +78,91 @@ const readEntryData = async (filePath, format, bodyFieldName = 'body') => {
 // and `canopycms/server` -- import it from here.
 export { parseTypedFilename } from './utils/typed-filename.js';
 import { parseTypedFilename } from './utils/typed-filename.js';
+/**
+ * Map a repo-relative file path, as git prints it, to the entry or collection settings it holds
+ * under `flatSchema`. Reads nothing from disk, so it maps a file that no longer exists.
+ * `contentRoot` is the config's (`'content'`): logical paths start with it, and a branch clone's
+ * root is the repo root, so its git paths do too.
+ *
+ * A file is an entry only as `listCollectionEntries` would list it: in a collection's
+ * directory, named `{type}.{slug}.{id}` with one of that collection's entry types and that
+ * type's extension. Directory segments below `contentRoot` compare lowercased, as
+ * `resolveCollectionPath` reads them. Anything else is `other`, including a path outside
+ * `contentRoot` and one with an empty, `.` or `..` segment, which no collection segment matches.
+ */
+export function entryRefFromRepoPath(repoPath, flatSchema, contentRoot) {
+    const physicalPath = repoPath.replace(/^(?:\.\/)+/, '').replace(/\/+$/, '');
+    const other = { kind: 'other', physicalPath };
+    const segments = physicalPath.split('/');
+    const rootSegments = contentRoot.split('/').filter(Boolean);
+    if (segments.length <= rootSegments.length ||
+        rootSegments.some((segment, i) => segments[i] !== segment)) {
+        return other;
+    }
+    const filename = segments[segments.length - 1];
+    const collectionDir = [
+        ...rootSegments,
+        ...segments.slice(rootSegments.length, -1).map((segment) => segment.toLowerCase()),
+    ].join('/');
+    // resolveLogicalPath echoes a path it cannot match, so only a listed collection counts.
+    const resolved = resolveLogicalPath(collectionDir, flatSchema);
+    const collection = flatSchema.find((item) => item.type === 'collection' && item.logicalPath === resolved);
+    if (!collection)
+        return other;
+    if (filename === '.collection.json') {
+        return { kind: 'collection-meta', collectionPath: collection.logicalPath, physicalPath };
+    }
+    const entryTypes = collection.entries ?? [];
+    const parsed = parseTypedFilename(filename, entryTypes);
+    const entryType = parsed ? entryTypes.find((e) => e.name === parsed.type) : undefined;
+    if (!parsed || !entryType || !filename.endsWith(getFormatExtension(entryType.format))) {
+        return other;
+    }
+    return {
+        kind: 'entry',
+        logicalPath: entryLogicalPath(collection.logicalPath, parsed.slug),
+        contentId: parsed.id,
+        entryType: parsed.type,
+        collectionPath: collection.logicalPath,
+        physicalPath,
+    };
+}
+const CONTENT_EXTENSIONS = ['.md', '.mdx', '.json', '.yaml'];
+/**
+ * An entry or collection-settings ref read from `repoPath`'s shape alone, with no schema, for a
+ * file the current schema can't place: one deleted with its collection, under a collection's old
+ * name, or of an entry type since removed. The collection path strips the ids from the
+ * directory names, as the ContentId index does, and `entryType` is the filename's. Undefined
+ * for a path outside `contentRoot` or a filename of neither shape.
+ */
+export function entryRefFromRepoPathShape(repoPath, contentRoot) {
+    const physicalPath = repoPath.replace(/^(?:\.\/)+/, '').replace(/\/+$/, '');
+    const segments = physicalPath.split('/');
+    const rootSegments = contentRoot.split('/').filter(Boolean);
+    if (segments.length <= rootSegments.length ||
+        rootSegments.some((segment, i) => segments[i] !== segment) ||
+        segments.some((segment) => segment === '' || segment === '.' || segment === '..')) {
+        return undefined;
+    }
+    const filename = segments[segments.length - 1];
+    const collectionPath = [
+        ...rootSegments,
+        ...segments.slice(rootSegments.length, -1).map((segment) => toLogicalCollectionPath(segment)),
+    ].join('/');
+    if (filename === '.collection.json')
+        return { kind: 'collection-meta', collectionPath, physicalPath };
+    const parsed = parseTypedFilename(filename);
+    if (!parsed || !CONTENT_EXTENSIONS.some((ext) => filename.endsWith(ext)))
+        return undefined;
+    return {
+        kind: 'entry',
+        logicalPath: entryLogicalPath(collectionPath, parsed.slug),
+        contentId: parsed.id,
+        entryType: parsed.type,
+        collectionPath,
+        physicalPath,
+    };
+}
 /**
  * Build the `ContentStore` + shared cache that a batch listing resolves references through.
  *

package/dist/content-reader.js

@@ -1,8 +1,10 @@
-import { loadBranchContext, loadOrCreateBranchContext } from './branch-workspace.js';
+import { loadOrCreateBranchContext } from './branch-workspace.js';
+import { resolveBranchParam } from './branch-param.js';
 import { SchemaUnavailableError } from './schema/schema-unavailable-error.js';
 import { ContentStore, ContentStoreError } from './content-store.js';
 import { namesNoWorkspace, resolveBranchPaths, } from './paths/index.js';
 import { trimSlashes } from './paths/normalize.js';
+import { exactBranchName, isExactBranchForm } from './paths/validation.js';
 import { computeEntryUrl, isIndexSlug } from './utils/entry-url.js';
 import { isDeployedStatic, isBuildMode, readsFromCheckout } from './build-mode.js';
 import { isNotFoundError } from './utils/error.js';
@@ -40,28 +42,33 @@ export const createContentReader = (options) => {
                 throw new ContentStoreError(`Branch not found: ${branchName}`, 'NOT_FOUND');
             return resolved;
         }
-        if (allowCreateBranch) {
-            return loadOrCreateBranchContext({
+        // An existing branch resolves first, so a short name reads its namespace branch; only a
+        // name that resolves to none is provisioned.
+        const existing = await resolveBranchParam(branchName, services.config, {
+            basePathOverride,
+        }).catch((err) => {
+            if (namesNoWorkspace(err))
+                return null;
+            throw err;
+        });
+        if (existing)
+            return existing;
+        // The exact form provisions the branch its full name names; a malformed one names none.
+        const named = isExactBranchForm(branchName) ? exactBranchName(branchName) : branchName;
+        if (allowCreateBranch && named !== null) {
+            const context = await loadOrCreateBranchContext({
                 config: services.config,
-                branchName,
+                branchName: named,
                 mode: operatingMode,
                 basePathOverride,
                 createdBy,
                 remoteUrl: services.config.defaultRemoteUrl,
             });
+            // A workspace already at this name's key that holds another branch is that branch's.
+            if (context.branch.name === named)
+                return context;
         }
-        const existing = await loadBranchContext({
-            branchName,
-            mode: operatingMode,
-            basePathOverride,
-        }).catch((err) => {
-            if (namesNoWorkspace(err))
-                return null;
-            throw err;
-        });
-        if (!existing)
-            throw new ContentStoreError(`Branch not found: ${branchName}`, 'NOT_FOUND');
-        return existing;
+        throw new ContentStoreError(`Branch not found: ${branchName}`, 'NOT_FOUND');
     };
     const resolveStore = async (branchName) => {
         const context = await resolveBranchContext(branchName);

package/dist/context.js

@@ -3,7 +3,8 @@ import { createContentReader } from './content-reader.js';
 import { ContentStoreError } from './content-store.js';
 import { createLogicalPath, namesNoWorkspace, parseSlug, resolveBranchPaths, } from './paths/index.js';
 import { resolveUrlPathCandidates } from './url-path-resolver.js';
-import { loadBranchContext, loadOrCreateBranchContext } from './branch-workspace.js';
+import { loadOrCreateBranchContext } from './branch-workspace.js';
+import { resolveBranchParam } from './branch-param.js';
 import { buildContentTree as buildContentTreeImpl, } from './content-tree.js';
 import { listEntries as listEntriesImpl, } from './content-listing.js';
 import { createDebugLogger } from './utils/debug.js';
@@ -34,13 +35,13 @@ function isBranchOption(branch) {
     return branch == null || typeof branch === 'string';
 }
 /**
- * A branch that already has a workspace, or null. A name that cannot name one
- * is null too (`namesNoWorkspace`): it arrives from the request, so it reads as
- * not-found rather than failing the page.
+ * The existing branch `param` names (`resolveBranchParam`), or null. A name that cannot name one
+ * is null too (`namesNoWorkspace`): it arrives from the request, so it reads as not-found rather
+ * than failing the page.
  */
-async function loadExistingBranch(branchName, mode) {
+async function loadExistingBranch(param, config) {
     try {
-        return await loadBranchContext({ branchName, mode });
+        return await resolveBranchParam(param, config);
     }
     catch (err) {
         if (namesNoWorkspace(err))
@@ -119,7 +120,7 @@ export function createCanopyContext(options) {
                     remoteUrl: services.config.defaultRemoteUrl,
                 });
             }
-            const context = await loadExistingBranch(requested, services.config.mode);
+            const context = await loadExistingBranch(requested, services.config);
             if (!context)
                 return null;
             if (enforceAcls && !services.checkBranchAccess(context, user).allowed)

package/dist/editor/BranchManager.d.ts

@@ -3,9 +3,12 @@ import type { OperatingMode } from '../operating-mode/index.js';
 import type { 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';
 /** @internal Exported for tests. */
 export interface BranchSummary {
     name: string;
+    /** What the card shows for the branch (`displayBranchName`); the full `name` keys it. */
+    shortName?: string;
     status: string;
     createdBy?: string;
     updatedAt?: string;
@@ -78,14 +81,15 @@ export interface BranchManagerProps {
     /** Awaited before the spinner starts, so a confirmation it shows never reads as a hung create. `false` abandons the create. */
     onBeforeCreate?: () => Promise<boolean>;
     /**
-     * Resolving `false` means the branch was not created, so the form stays open
-     * with the user's values; any other return (including none) closes it.
+     * Resolving `false` means the branch was not created, so the form stays open with the user's
+     * values; `{ refusal }` also shows why under the name field. Any other return (including none)
+     * closes it.
      */
     onCreate?: (branch: {
         name: string;
         title?: string;
         description?: string;
-    }) => Promise<boolean> | void;
+    }) => Promise<boolean | CreateRefusal> | void;
     onDelete?: (name: string) => void;
     onSubmit?: (name: string) => void;
     onWithdraw?: (name: string) => void;