canopycms 0.7.1 → 0.8.0

package/dist/git-manager.d.ts

@@ -113,6 +113,10 @@ export interface GitManagerOptions {
     skipIndexMarker?: boolean;
 }
 export type GitStatus = Pick<StatusResult, 'files' | 'ahead' | 'behind' | 'current' | 'tracking'>;
+/** The remote has no branch of the base branch's name, so there is nothing to fork from. */
+export declare class BaseBranchMissingError extends Error {
+    constructor(remote: string, baseBranch: string);
+}
 /** @internal Exported for tests. */
 export declare class GitConflictError extends Error {
     readonly conflictedFiles: string[];
@@ -264,6 +268,13 @@ export declare class GitManager {
     static bareRemoteHasBranch(remotePath: string, branch: string, options?: {
         namespaces?: 'both' | 'tracking';
     }): Promise<boolean>;
+    /**
+     * The branches inside `branch` (`<branch>/…`) that a bare mirror holds as local heads or in
+     * GitHub's tracking namespace, which git cannot hold beside `branch` itself. `for-each-ref`
+     * matches a pattern up to a slash, so the pattern `<branch>` lists them. Throws, as
+     * {@link bareRemoteHasBranch} does, when the mirror is unreadable.
+     */
+    static bareRemoteBranchesInside(remotePath: string, branch: string): Promise<string[]>;
     /**
      * Delete `refs/heads/<branch>` from a bare local mirror, if present. A
      * no-op (not an error) when the ref doesn't exist.
@@ -489,6 +500,66 @@ export declare class GitManager {
     private fetchBaseTip;
     /** Repo-relative paths of every file in `rev`'s tree, under `under` when given. */
     private listTreeFiles;
+    /**
+     * Every file in `rev`'s tree below repo-relative directory `under`, with its size in bytes,
+     * so a caller can refuse a file too large to read before reading it.
+     */
+    listFilesWithSizeAt(rev: string, under: string): Promise<Array<{
+        path: string;
+        size: number;
+    }>>;
+    /**
+     * The commit HEAD forked from the base branch at, or `undefined` when they share no history.
+     * Takes the base tip from the remote by `ls-remote` rather than `<remote>/<base>`: the worker
+     * fetches by path, which moves no remote-tracking ref, so that ref is left behind by every
+     * rebase. A tip this clone lacks is fetched as objects only (`--refmap=`, `--no-tags`,
+     * `--no-write-fetch-head`, git 2.29+): no ref and no FETCH_HEAD moves, so a concurrent fetch
+     * pinning FETCH_HEAD is never repointed. Throws {@link BaseBranchMissingError} when the
+     * remote has no base branch, and any other error when it can't be read.
+     */
+    mergeBaseWithBase(): Promise<string | undefined>;
+    /** Whether this clone holds commit `sha`. */
+    private hasCommit;
+    /**
+     * Repo-relative paths whose working-tree content differs from commit `rev`, with `T` (a type
+     * change) reported as `M`. A sparse clone leaves a path outside its cone unchecked out, marked
+     * skip-worktree, and git reads that path's index entry in place of the missing file: it is never
+     * reported deleted, and differs from `rev` only as the index does.
+     *
+     * `diff-index`, not `git diff`: the porcelain refreshes the index and writes it back under
+     * `index.lock`, which would fail a concurrent writer's own git step. `diff-index` writes
+     * nothing, so it reports a file whose stat changed but whose content did not; those are
+     * hashed here and dropped when they match `rev`.
+     */
+    diffNameStatusAgainst(rev: string): Promise<Array<{
+        status: 'A' | 'M' | 'D';
+        path: string;
+    }>>;
+    /**
+     * The paths whose working-tree file hashes to `sha`, as git hashes it: a symlink's blob is its
+     * target, a file's goes through `hash-object --stdin-paths`, so its attributes' filters apply.
+     * Callers pass only paths whose mode is unchanged, since diff-index reports the working tree's
+     * own mode. A path that is gone or can't be hashed matches nothing, so it stays reported as
+     * changed. When git refuses a path (exit 128), having printed
+     * the SHAs before it, the next run resumes past that path, for at most {@link MAX_HASH_RUNS}
+     * runs. A run that ends any other way (killed, timed out, a signal) stops the hashing, and the
+     * paths it didn't reach stay changed.
+     */
+    private matchingBlobs;
+    /**
+     * `hash-object --stdin-paths` over `paths`: one SHA per path, in order, up to where it ended.
+     * `refused` is git's own exit 128 on a path it can't hash; `stopped` is any other ending.
+     */
+    private hashPaths;
+    /** What a git run outside simple-git needs to run as `this.git` does. */
+    private processOptions;
+    /** Repo-relative paths of the working tree's untracked, non-ignored files. */
+    listUntrackedFiles(): Promise<string[]>;
+    /**
+     * The text of repo-relative `filePath` at commit `rev`, or `undefined` when `rev` has no such
+     * path. Any other failure, such as an unknown `rev`, throws.
+     */
+    showFile(rev: string, filePath: string): Promise<string | undefined>;
     ensureAuthor(author: {
         name: string;
         email: string;

package/dist/git-manager.js

@@ -13,6 +13,7 @@
  *
  * Module map: ./AGENTS.md. Locking rules: ../../../docs/concurrency.md.
  */
+import { createHash } from 'node:crypto';
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -25,6 +26,7 @@ import { isMissingRemoteRefFailure, isNetworkRemoteUrl, resolveBaseBranch, stage
 import { BaseBranchUnresolvedError } from './utils/base-branch.js';
 import { canopyLogWarn } from './utils/logger.js';
 import { acquireProvisioningLock } from './utils/provisioning-lock.js';
+import { GitProcessError, runGit, spawnGit } from './worker/git-process.js';
 const log = createDebugLogger({ prefix: 'GitManager' });
 /**
  * Child environment for spawned git processes: a deterministic ALLOWLIST of
@@ -99,6 +101,25 @@ export function gitNetworkChildEnv() {
  * them; {@link REMOTE_GIT_CONFIG} covers that side.
  */
 const NO_AUTO_GC_CONFIG = ['gc.auto=0', 'maintenance.auto=false'];
+/** How long `hash-object --stdin-paths` may go without output before it is killed. */
+const HASH_INACTIVITY_TIMEOUT_MS = 60_000;
+/**
+ * `hash-object` runs per diff: each refused path costs a run, so 49 are resumed past and a 50th
+ * leaves the paths after it unhashed.
+ */
+const MAX_HASH_RUNS = 50;
+/** How long `ls-remote` may go without output before it is killed. */
+const LS_REMOTE_INACTIVITY_TIMEOUT_MS = 60_000;
+/**
+ * The blob SHA git gives a symlink pointing at `target`, in the object format of `likeSha` (a
+ * 40-character SHA-1 or a 64-character SHA-256).
+ */
+const symlinkBlobSha = (target, likeSha) => {
+    const body = Buffer.from(target, 'utf8');
+    return createHash(likeSha.length === 64 ? 'sha256' : 'sha1')
+        .update(Buffer.concat([Buffer.from(`blob ${body.length}\0`), body]))
+        .digest('hex');
+};
 /**
  * Settings written into every bare `remote.git` CanopyCMS creates: the worker's (prod) and the
  * simulated remote (dev). A push runs `receive-pack` with remote.git's own config and none of the
@@ -269,6 +290,13 @@ export async function ensureGitExcludePattern(repoPath, pattern) {
     await fs.writeFile(excludePath, newContent, 'utf-8');
     log.debug('git', 'Added pattern to .git/info/exclude', { pattern });
 }
+/** The remote has no branch of the base branch's name, so there is nothing to fork from. */
+export class BaseBranchMissingError extends Error {
+    constructor(remote, baseBranch) {
+        super(`CanopyCMS: remote '${remote}' has no branch '${baseBranch}'`);
+        this.name = 'BaseBranchMissingError';
+    }
+}
 /** @internal Exported for tests. */
 export class GitConflictError extends Error {
     constructor(conflictedFiles) {
@@ -666,6 +694,37 @@ export class GitManager {
         return (refs.includes(`refs/heads/${branch}`) ||
             refs.includes(`${GITHUB_TRACKING_REF_PREFIX}${branch}`));
     }
+    /**
+     * The branches inside `branch` (`<branch>/…`) that a bare mirror holds as local heads or in
+     * GitHub's tracking namespace, which git cannot hold beside `branch` itself. `for-each-ref`
+     * matches a pattern up to a slash, so the pattern `<branch>` lists them. Throws, as
+     * {@link bareRemoteHasBranch} does, when the mirror is unreadable.
+     */
+    static async bareRemoteBranchesInside(remotePath, branch) {
+        let output;
+        try {
+            output = await simpleGit().raw([
+                '--git-dir',
+                remotePath,
+                'for-each-ref',
+                '--format=%(refname)',
+                '--end-of-options',
+                `refs/heads/${branch}`,
+                `${GITHUB_TRACKING_REF_PREFIX}${branch}`,
+            ]);
+        }
+        catch (err) {
+            throw new Error(`Cannot inspect remote mirror at ${remotePath}: ${getErrorMessage(err)}`);
+        }
+        const inside = new Set();
+        for (const ref of output.split('\n').map((line) => line.trim())) {
+            for (const prefix of ['refs/heads/', GITHUB_TRACKING_REF_PREFIX]) {
+                if (ref.startsWith(`${prefix}${branch}/`))
+                    inside.add(ref.slice(prefix.length));
+            }
+        }
+        return [...inside].sort();
+    }
     /**
      * Delete `refs/heads/<branch>` from a bare local mirror, if present. A
      * no-op (not an error) when the ref doesn't exist.
@@ -1498,6 +1557,212 @@ export class GitManager {
         ]);
         return output.split('\0').filter((p) => p.length > 0);
     }
+    /**
+     * Every file in `rev`'s tree below repo-relative directory `under`, with its size in bytes,
+     * so a caller can refuse a file too large to read before reading it.
+     */
+    async listFilesWithSizeAt(rev, under) {
+        const dir = `${under.replace(/\/+$/, '')}/`;
+        const output = await this.git.raw([
+            'ls-tree',
+            '-r',
+            '-z',
+            '-l',
+            '--full-tree',
+            '--end-of-options',
+            rev,
+            dir,
+        ]);
+        // -z -l: "<mode> <type> <object> <padded size>\t<path>" per record, unquoted.
+        const files = [];
+        for (const record of output.split('\0')) {
+            const tab = record.indexOf('\t');
+            if (tab === -1)
+                continue;
+            const [, type, , size] = record.slice(0, tab).split(/ +/);
+            const filePath = record.slice(tab + 1);
+            if (type === 'blob' && filePath.startsWith(dir)) {
+                files.push({ path: filePath, size: Number(size) });
+            }
+        }
+        return files;
+    }
+    /**
+     * The commit HEAD forked from the base branch at, or `undefined` when they share no history.
+     * Takes the base tip from the remote by `ls-remote` rather than `<remote>/<base>`: the worker
+     * fetches by path, which moves no remote-tracking ref, so that ref is left behind by every
+     * rebase. A tip this clone lacks is fetched as objects only (`--refmap=`, `--no-tags`,
+     * `--no-write-fetch-head`, git 2.29+): no ref and no FETCH_HEAD moves, so a concurrent fetch
+     * pinning FETCH_HEAD is never repointed. Throws {@link BaseBranchMissingError} when the
+     * remote has no base branch, and any other error when it can't be read.
+     */
+    async mergeBaseWithBase() {
+        const tip = await this.remoteBranchTip(this.baseBranch);
+        if (!tip)
+            throw new BaseBranchMissingError(this.remote, this.baseBranch);
+        if (!(await this.hasCommit(tip))) {
+            await this.git.raw([
+                'fetch',
+                '--refmap=',
+                '--no-tags',
+                '--no-write-fetch-head',
+                '--end-of-options',
+                this.remote,
+                `refs/heads/${this.baseBranch}`,
+            ]);
+            if (!(await this.hasCommit(tip))) {
+                throw new Error(`CanopyCMS: could not fetch ${this.baseBranch}'s tip ${tip}`);
+            }
+        }
+        // With no shared commit merge-base exits 1 silently, which simple-git resolves as ''.
+        const forkPoint = (await this.git.raw(['merge-base', '--end-of-options', 'HEAD', tip])).trim();
+        return forkPoint || undefined;
+    }
+    /** Whether this clone holds commit `sha`. */
+    async hasCommit(sha) {
+        // `--quiet` makes a missing commit a silent non-zero exit, which simple-git resolves as ''.
+        return ((await this.git.raw(['rev-parse', '--verify', '--quiet', `${sha}^{commit}`])).trim() !== '');
+    }
+    /**
+     * Repo-relative paths whose working-tree content differs from commit `rev`, with `T` (a type
+     * change) reported as `M`. A sparse clone leaves a path outside its cone unchecked out, marked
+     * skip-worktree, and git reads that path's index entry in place of the missing file: it is never
+     * reported deleted, and differs from `rev` only as the index does.
+     *
+     * `diff-index`, not `git diff`: the porcelain refreshes the index and writes it back under
+     * `index.lock`, which would fail a concurrent writer's own git step. `diff-index` writes
+     * nothing, so it reports a file whose stat changed but whose content did not; those are
+     * hashed here and dropped when they match `rev`.
+     */
+    async diffNameStatusAgainst(rev) {
+        const output = await this.git.raw([
+            'diff-index',
+            '--raw',
+            '-z',
+            '--no-renames',
+            '--end-of-options',
+            rev,
+            '--',
+        ]);
+        // -z raw output alternates ":<srcmode> <dstmode> <srcsha> <dstsha> <status>" and a path.
+        const tokens = output.split('\0');
+        const changes = [];
+        for (let i = 0; i + 1 < tokens.length; i += 2) {
+            const [srcMode, dstMode, srcSha, dstSha, code] = tokens[i].slice(1).split(' ');
+            const path = tokens[i + 1];
+            const letter = code?.charAt(0);
+            if (letter === 'A' || letter === 'D')
+                changes.push({ status: letter, path });
+            else if (letter === 'M' || letter === 'T') {
+                // A mode change (a chmod, a file turned symlink) is a change whatever the bytes.
+                const unhashed = /^0+$/.test(dstSha) && srcMode === dstMode ? srcSha : undefined;
+                changes.push({ status: 'M', path, unhashed });
+            }
+        }
+        const unchanged = await this.matchingBlobs(changes.flatMap((c) => (c.unhashed ? [{ path: c.path, sha: c.unhashed }] : [])));
+        return changes
+            .filter((c) => !unchanged.has(c.path))
+            .map(({ status, path }) => ({ status, path }));
+    }
+    /**
+     * The paths whose working-tree file hashes to `sha`, as git hashes it: a symlink's blob is its
+     * target, a file's goes through `hash-object --stdin-paths`, so its attributes' filters apply.
+     * Callers pass only paths whose mode is unchanged, since diff-index reports the working tree's
+     * own mode. A path that is gone or can't be hashed matches nothing, so it stays reported as
+     * changed. When git refuses a path (exit 128), having printed
+     * the SHAs before it, the next run resumes past that path, for at most {@link MAX_HASH_RUNS}
+     * runs. A run that ends any other way (killed, timed out, a signal) stops the hashing, and the
+     * paths it didn't reach stay changed.
+     */
+    async matchingBlobs(files) {
+        const matching = new Set();
+        const regular = [];
+        for (const file of files) {
+            // --stdin-paths reads one path per line.
+            if (file.path.includes('\n'))
+                continue;
+            const stat = await fs.lstat(path.join(this.repoPath, file.path)).catch(() => undefined);
+            if (!stat)
+                continue;
+            if (stat.isSymbolicLink()) {
+                const target = await fs.readlink(path.join(this.repoPath, file.path)).catch(() => undefined);
+                if (target !== undefined && symlinkBlobSha(target, file.sha) === file.sha) {
+                    matching.add(file.path);
+                }
+            }
+            else if (stat.isFile())
+                regular.push(file);
+        }
+        for (let start = 0, runs = 0; start < regular.length && runs < MAX_HASH_RUNS; runs++) {
+            const batch = regular.slice(start);
+            const { shas, outcome } = await this.hashPaths(batch.map((f) => f.path));
+            shas.forEach((sha, i) => {
+                if (batch[i] && sha === batch[i].sha)
+                    matching.add(batch[i].path);
+            });
+            if (outcome !== 'refused')
+                break;
+            start += shas.length + 1;
+        }
+        return matching;
+    }
+    /**
+     * `hash-object --stdin-paths` over `paths`: one SHA per path, in order, up to where it ended.
+     * `refused` is git's own exit 128 on a path it can't hash; `stopped` is any other ending.
+     */
+    async hashPaths(paths) {
+        const chunks = [];
+        let proc;
+        try {
+            proc = spawnGit(['hash-object', '--stdin-paths'], {
+                ...this.processOptions(),
+                stdin: `${paths.join('\n')}\n`,
+                inactivityTimeoutMs: HASH_INACTIVITY_TIMEOUT_MS,
+            });
+        }
+        catch {
+            return { shas: [], outcome: 'stopped' };
+        }
+        const read = (async () => {
+            for await (const chunk of proc.stdout)
+                chunks.push(chunk);
+        })().catch(() => { });
+        const outcome = await proc.exited.then(() => 'complete', (err) => err instanceof GitProcessError && err.exitCode === 128
+            ? 'refused'
+            : 'stopped');
+        await read;
+        return { shas: Buffer.concat(chunks).toString('utf8').split('\n').filter(Boolean), outcome };
+    }
+    /** What a git run outside simple-git needs to run as `this.git` does. */
+    processOptions() {
+        return {
+            cwd: this.repoPath,
+            env: gitChildEnv({ GIT_CEILING_DIRECTORIES: path.dirname(this.repoPath) }),
+            config: NO_AUTO_GC_CONFIG,
+        };
+    }
+    /** Repo-relative paths of the working tree's untracked, non-ignored files. */
+    async listUntrackedFiles() {
+        // -z: NUL-separated and unquoted, so no path needs unescaping.
+        const output = await this.git.raw(['ls-files', '--others', '--exclude-standard', '-z']);
+        return output.split('\0').filter((p) => p.length > 0);
+    }
+    /**
+     * The text of repo-relative `filePath` at commit `rev`, or `undefined` when `rev` has no such
+     * path. Any other failure, such as an unknown `rev`, throws.
+     */
+    async showFile(rev, filePath) {
+        try {
+            return await this.git.raw(['show', '--end-of-options', `${rev}:${filePath}`]);
+        }
+        catch (err) {
+            // LC_ALL=C (gitChildEnv), so git's own wording is stable to match.
+            if (/fatal: path '.*' (does not exist in|exists on disk, but not in) '/.test(getErrorMessage(err))) {
+                return undefined;
+            }
+            throw err;
+        }
+    }
     async ensureAuthor(author) {
         const config = (await this.git.listConfig());
         // Verify this is a CanopyCMS-managed workspace before setting author
@@ -1694,7 +1959,11 @@ export class GitManager {
      */
     async remoteBranchTip(branch) {
         const ref = `refs/heads/${branch}`;
-        const output = await this.git.raw(['ls-remote', '--heads', this.remote, ref]);
+        // runGit, not simple-git, which resolves a silent non-zero exit as '' (no such branch).
+        const output = await runGit(['ls-remote', '--heads', '--end-of-options', this.remote, ref], {
+            ...this.processOptions(),
+            inactivityTimeoutMs: LS_REMOTE_INACTIVITY_TIMEOUT_MS,
+        });
         for (const line of output.split('\n')) {
             const [sha, name] = line.trim().split('\t');
             if (sha && name === ref)

package/dist/http/handler.js

@@ -6,13 +6,15 @@ import { assertAuthPluginAllowedForMode } from '../auth/plugin.js';
 import { createCanopyServices } from '../services.js';
 import { recordConfiguredSparseCone } from '../branch-sparse.js';
 import { recordServedSchemaRegistry } from '../schema-registry-record.js';
-import { loadBranchContext, BranchWorkspaceManager } from '../branch-workspace.js';
+import { BranchWorkspaceManager } from '../branch-workspace.js';
+import { resolveBranchParam } from '../branch-param.js';
 import { BranchMetadataCorruptError } from '../branch-metadata.js';
 import { BRANCH_METADATA_CORRUPT_MESSAGE } from '../branch-metadata-error.js';
 import { resolveCanopyUser } from '../resolve-canopy-user.js';
 import { authResultToCanopyUser } from '../user.js';
 import { isAdmin } from '../authorization/index.js';
 import { isSettingsBranchName } from '../paths/branch-name.js';
+import { exactBranchName } from '../paths/validation.js';
 import { clientOperatingStrategy, operatingStrategy } from '../operating-mode/index.js';
 import { getErrorMessage, redactCredentials, sanitizeErrorMessage } from '../utils/error.js';
 // canopyLogError, not console.error: this is shared code and not guaranteed to
@@ -36,10 +38,7 @@ const buildContext = async (options) => {
     const settingsBranch = operatingStrategy(operatingMode).getSettingsBranchName(services.config);
     const getBranchContext = options.getBranchContext ??
         (async (branch, opts) => {
-            const existing = await loadBranchContext({
-                branchName: branch,
-                mode: operatingMode,
-            });
+            const existing = await resolveBranchParam(branch, services.config);
             if (existing) {
                 if (opts?.loadSchema) {
                     const contentRootName = services.config.contentRoot || 'content';
@@ -52,12 +51,14 @@ const buildContext = async (options) => {
             // refreshActiveBranch() update takes effect immediately.
             const baseBranch = baseBranchOf(services.config);
             const activeBranch = services.config.defaultActiveBranch ?? baseBranch;
+            // The exact form names its full name's branch, and the editor sends a name holding a `/` so.
+            const named = exactBranchName(branch) ?? branch;
             const shouldAutoCreate = clientOperatingStrategy(operatingMode).supportsBranching() &&
-                (branch === baseBranch || branch === activeBranch);
+                (named === baseBranch || named === activeBranch);
             if (shouldAutoCreate) {
                 const manager = new BranchWorkspaceManager(services.config);
                 const context = await manager.openOrCreateBranch({
-                    branchName: branch,
+                    branchName: named,
                     mode: operatingMode,
                     createdBy: SYSTEM_USER_ID,
                 });
@@ -77,8 +78,9 @@ const buildContext = async (options) => {
         // content branch would let any request clone a content-history copy that a
         // submit pushes under the settings name, which settings provisioning then refuses,
         // leaving settings unavailable.
-        // Not found, like any branch the caller cannot resolve, even a workspace left on disk.
-        getBranchContext: (branch, opts) => isSettingsBranchName(branch, settingsBranch)
+        // Not found, like any branch the caller cannot resolve, even a workspace left on disk. The
+        // exact form (`exactBranchSegment`) names the same branch, so it is refused by that name.
+        getBranchContext: (branch, opts) => isSettingsBranchName(exactBranchName(branch) ?? branch, settingsBranch)
             ? Promise.resolve(null)
             : timeRequestPhase('branchContext', () => getBranchContext(branch, opts)),
         authPlugin: options.authPlugin,

package/dist/operating-mode/branch-namespace-fixtures.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Shared branch-namespace test fixture.
+ *
+ * The rules deciding whether a branch-namespace template is usable exist TWICE by necessity: at
+ * runtime (`branch-namespace.ts`'s `resolveBranchNamespaceTemplate`) and at synth time
+ * (`canopycms-cdk`'s `constructs/cms-service.ts`, which does not import core). A rule tightened
+ * at runtime but not at synth synths clean and then crash-loops the gateway at boot, so
+ * canopycms-cdk's suite requires the construct's verdict to match core's for every template here.
+ * Add a case when you change either copy of the rule.
+ *
+ * Dependency-free (plain arrays, no vitest import) so the CDK suite can import it across the
+ * package boundary. Every template is resolved with the deployment name `prod`.
+ */
+/** Templates both copies must ACCEPT, each with the namespace it resolves to for `prod`. */
+export declare const VALID_BRANCH_NAMESPACE_TEMPLATES: readonly [readonly ["canopycms/{deployment}/", "canopycms/prod/"], readonly ["cms/", "cms/"], readonly ["{deployment}/", "prod/"], readonly ["edits/{deployment}/drafts/", "edits/prod/drafts/"], readonly ["{deployment}-{deployment}/", "prod-prod/"], readonly ["team.a/{deployment}/", "team.a/prod/"], readonly ["Heads2/", "Heads2/"], readonly ["x.locked/", "x.locked/"]];
+/** Templates both copies must REJECT. */
+export declare const INVALID_BRANCH_NAMESPACE_TEMPLATES: readonly [readonly ["a namespace that sanitizes to the start of the settings prefix", "canopycms/"], readonly ["one that sanitizes to it with a dash", "canopycms-/"], readonly ["one that sanitizes further into it", "canopycms/settings/"], readonly ["no trailing slash", "canopycms/{deployment}"], readonly ["the empty string", ""], readonly ["an unknown placeholder", "canopycms/{env}/"], readonly ["an unclosed placeholder", "canopycms/{deployment/"], readonly ["a stray close brace", "canopycms/}/"], readonly ["a space", "canopycms edits/"], readonly ["a percent sign", "canopycms%2f/"], readonly ["a double quote", "canopycms\"/"], readonly ["dot-dot", "canopycms/../"], readonly ["an empty path component", "canopycms//{deployment}/"], readonly ["a leading slash", "/canopycms/"], readonly ["a leading dash", "-canopycms/"], readonly ["a leading dot", ".canopycms/"], readonly ["a dot-led component", "canopycms/.hidden/"], readonly ["a .lock component", "canopycms.lock/{deployment}/"], readonly ["a reflog selector", "canopycms@{1}/"], readonly ["a tilde", "canopycms~1/"], readonly ["a caret", "canopycms^/"], readonly ["a colon", "canopycms:/"], readonly ["a question mark", "canopycms?/"], readonly ["an asterisk", "canopycms*/"], readonly ["an open bracket", "canopycms[/"], readonly ["a backslash", "canopycms\\/"], readonly ["non-ASCII", "café/"], readonly ["a newline", "canopycms\n/"], readonly ["a leading refs/", "refs/heads/"], readonly ["a leading heads/", "heads/{deployment}/"], readonly ["a leading tags/", "tags/"], readonly ["a leading remotes/ in another case", "Remotes/"], readonly ["a name over the length limit", `${string}/`], readonly ["the settings branch prefix", "canopycms-settings-/"], readonly ["the settings branch prefix, after a slash", "canopycms/settings-/"], readonly ["the settings branch prefix, after sanitizing", "canopycms-settings!/"], readonly ["the settings branch prefix, through a placeholder", "canopycms-settings-{deployment}/"]];

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

@@ -0,0 +1,65 @@
+/**
+ * Shared branch-namespace test fixture.
+ *
+ * The rules deciding whether a branch-namespace template is usable exist TWICE by necessity: at
+ * runtime (`branch-namespace.ts`'s `resolveBranchNamespaceTemplate`) and at synth time
+ * (`canopycms-cdk`'s `constructs/cms-service.ts`, which does not import core). A rule tightened
+ * at runtime but not at synth synths clean and then crash-loops the gateway at boot, so
+ * canopycms-cdk's suite requires the construct's verdict to match core's for every template here.
+ * Add a case when you change either copy of the rule.
+ *
+ * Dependency-free (plain arrays, no vitest import) so the CDK suite can import it across the
+ * package boundary. Every template is resolved with the deployment name `prod`.
+ */
+/** Templates both copies must ACCEPT, each with the namespace it resolves to for `prod`. */
+export const VALID_BRANCH_NAMESPACE_TEMPLATES = [
+    ['canopycms/{deployment}/', 'canopycms/prod/'],
+    ['cms/', 'cms/'],
+    ['{deployment}/', 'prod/'],
+    ['edits/{deployment}/drafts/', 'edits/prod/drafts/'],
+    ['{deployment}-{deployment}/', 'prod-prod/'],
+    ['team.a/{deployment}/', 'team.a/prod/'],
+    ['Heads2/', 'Heads2/'],
+    ['x.locked/', 'x.locked/'],
+];
+/** Templates both copies must REJECT. */
+export const INVALID_BRANCH_NAMESPACE_TEMPLATES = [
+    // Their branches' directories start `canopycms-`, so `.../settings-x` would be a settings name.
+    ['a namespace that sanitizes to the start of the settings prefix', 'canopycms/'],
+    ['one that sanitizes to it with a dash', 'canopycms-/'],
+    ['one that sanitizes further into it', 'canopycms/settings/'],
+    ['no trailing slash', 'canopycms/{deployment}'],
+    ['the empty string', ''],
+    ['an unknown placeholder', 'canopycms/{env}/'],
+    ['an unclosed placeholder', 'canopycms/{deployment/'],
+    ['a stray close brace', 'canopycms/}/'],
+    ['a space', 'canopycms edits/'],
+    ['a percent sign', 'canopycms%2f/'],
+    ['a double quote', 'canopycms"/'],
+    ['dot-dot', 'canopycms/../'],
+    ['an empty path component', 'canopycms//{deployment}/'],
+    ['a leading slash', '/canopycms/'],
+    ['a leading dash', '-canopycms/'],
+    ['a leading dot', '.canopycms/'],
+    ['a dot-led component', 'canopycms/.hidden/'],
+    ['a .lock component', 'canopycms.lock/{deployment}/'],
+    ['a reflog selector', 'canopycms@{1}/'],
+    ['a tilde', 'canopycms~1/'],
+    ['a caret', 'canopycms^/'],
+    ['a colon', 'canopycms:/'],
+    ['a question mark', 'canopycms?/'],
+    ['an asterisk', 'canopycms*/'],
+    ['an open bracket', 'canopycms[/'],
+    ['a backslash', 'canopycms\\/'],
+    ['non-ASCII', 'café/'],
+    ['a newline', 'canopycms\n/'],
+    ['a leading refs/', 'refs/heads/'],
+    ['a leading heads/', 'heads/{deployment}/'],
+    ['a leading tags/', 'tags/'],
+    ['a leading remotes/ in another case', 'Remotes/'],
+    ['a name over the length limit', `${'a'.repeat(250)}/`],
+    ['the settings branch prefix', 'canopycms-settings-/'],
+    ['the settings branch prefix, after a slash', 'canopycms/settings-/'],
+    ['the settings branch prefix, after sanitizing', 'canopycms-settings!/'],
+    ['the settings branch prefix, through a placeholder', 'canopycms-settings-{deployment}/'],
+];

package/dist/operating-mode/branch-namespace.d.ts

@@ -0,0 +1,34 @@
+/** The template used when none is configured. */
+export declare const DEFAULT_BRANCH_NAMESPACE_TEMPLATE = "canopycms/{deployment}/";
+/**
+ * The environment variable that carries the template, or the namespace it resolved to.
+ * @internal Exported for tests.
+ */
+export declare 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 declare function branchNamespaceProblem(namespace: string): string | 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 declare function namespaceAncestors(namespace: string): string[];
+/**
+ * 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 declare function resolveBranchNamespaceTemplate(template: string, deploymentName: string, source: string): string;
+/**
+ * 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 declare function resolveBranchNamespace(config: {
+    branchNamespace?: string;
+    deploymentName?: string;
+}, modeDefault: string, env?: Readonly<Record<string, string | undefined>>): string;