canopycms 0.0.67-int.90 → 0.0.67

package/dist/git-manager.d.ts

@@ -1,12 +1,5 @@
 import { type SimpleGitOptions, type StatusResult } from 'simple-git';
 import type { OperatingMode } from './operating-mode/index.js';
-/**
- * Exported for GitManager's own use (see `this.git.env(...)` above),
- * the worker's push-rejection-classified GitHub calls
- * (`pushBranchToGitHub` in worker/task-runner.ts, `syncGit`'s
- * fetch/`pushSettingsBranches` instance in worker/git-sync.ts),
- * and tests.
- */
 export declare function gitChildEnv(overrides: Record<string, string>): Record<string, string>;
 export declare function gitNetworkChildEnv(): Record<string, string>;
 /**
@@ -14,31 +7,18 @@ export declare function gitNetworkChildEnv(): Record<string, string>;
  * (`+refs/heads/*:${GITHUB_TRACKING_REF_PREFIX}*`), instead of writing
  * directly into `refs/heads/*`.
  *
- * `remote.git`'s `refs/heads/*` is NOT a throwaway mirror: it's the
- * deployment's local origin. `GitManager.push()` writes editor work into it
- * (`target:target`), branch-workspace clones are cloned FROM it, and the CMS
- * worker itself pushes it on to GitHub (`pushBranchToGitHub` in
- * worker/task-runner.ts, `pushSettingsBranches` in worker/git-sync.ts). A fetch that force-writes
- * GitHub's refs straight into `refs/heads/*` (the old
- * `+refs/heads/*:refs/heads/*` refspec) can therefore destroy work that
- * reached `remote.git` but not GitHub yet: with `--prune`, a branch pushed
- * into `remote.git` and not yet on GitHub gets deleted outright; without
- * needing `--prune`, a branch where `remote.git` is ahead of GitHub gets
- * force-rewound to GitHub's older tip, and the worker's next push then
- * no-ops ("Everything up-to-date") -- the editor's commit silently never
- * reaches GitHub even though the branch reports `synced`.
- *
- * Fetching into this remote-tracking namespace instead makes `--prune`/`+`
- * safe again -- they now only ever affect GitHub's-view-of-the-world refs,
- * never the local heads other code depends on. `reconcileTrackedBranches()`
- * (worker/git-sync.ts) is what subsequently, and non-destructively, brings
- * `refs/heads/*` toward what's tracked here.
- *
- * Lives here (not the worker, where this constant originated) so
- * `GitManager.bareRemoteHasBranch` -- which must recognize this namespace
- * too, since it's what a branch pushed by another CanopyCMS deployment (or
- * pushed directly to GitHub) shows up in before/without ever gaining a local
- * head -- doesn't need a worker/ -> git-manager.ts back-reference.
+ * `remote.git`'s `refs/heads/*` is NOT a throwaway mirror: it is the
+ * deployment's local origin. `GitManager.push()` writes editor work into it,
+ * branch-workspace clones are cloned FROM it, and the worker pushes it on to
+ * GitHub. A fetch that force-writes GitHub's refs straight into `refs/heads/*`
+ * therefore destroys work that reached `remote.git` but not GitHub yet: with
+ * `--prune` a not-yet-pushed branch is deleted outright, and a branch where
+ * `remote.git` is ahead is force-rewound to GitHub's older tip, so the worker's
+ * next push no-ops and the editor's commit never arrives while the branch still
+ * reports `synced`. Confining `+`/`--prune` to this namespace keeps them off
+ * those local heads; `reconcileTrackedBranches()` (worker/git-sync.ts) is what
+ * subsequently, and non-destructively, brings `refs/heads/*` toward what is
+ * tracked here.
  */
 export declare const GITHUB_TRACKING_REF_PREFIX = "refs/remotes/github/";
 /**
@@ -61,6 +41,7 @@ export interface GitManagerOptions {
     skipIndexMarker?: boolean;
 }
 export type GitStatus = Pick<StatusResult, 'files' | 'ahead' | 'behind' | 'current' | 'tracking'>;
+/** @internal Exported for tests. */
 export declare class GitConflictError extends Error {
     readonly conflictedFiles: string[];
     constructor(conflictedFiles: string[]);
@@ -68,12 +49,10 @@ export declare class GitConflictError extends Error {
 /**
  * The branch has no ref on the remote yet, so there is nothing to pull.
  *
- * Distinguishing this from a real pull failure matters: it is the ONLY benign
- * outcome of `pullCurrentBranch`, and callers that want to shrug it off (a
- * settings branch's first-ever commit, see services.ts `commitToSettingsBranch`)
- * must not shrug off merge failures with it. Everything else — a merge that
- * cannot proceed, a corrupt workspace, an unreachable remote — is a genuine
- * error the caller has to surface.
+ * The ONLY benign outcome of `pullCurrentBranch`: callers that shrug it off (a
+ * settings branch's first-ever commit — services.ts `commitToSettingsBranch`)
+ * must not shrug off anything else with it. A merge that cannot proceed, a
+ * corrupt workspace and an unreachable remote are genuine errors to surface.
  */
 export declare class GitRemoteRefMissingError extends Error {
     readonly branch: string;
@@ -124,11 +103,9 @@ export interface InitializeWorkspaceOptions {
     /** Git author email for internal commits (e.g., orphan branch init). */
     gitBotAuthorEmail: string;
     /**
-     * Pattern to add to `.git/info/exclude` so runtime metadata
-     * (e.g., `.canopy-meta/`) never enters the workspace's git history.
-     * Only applied to content branches; settings workspaces don't need it
-     * (their payloads live at the workspace root and are committed by
-     * explicit path).
+     * Pattern added to `.git/info/exclude` so runtime metadata (e.g.
+     * `.canopy-meta/`) never enters the workspace's git history. Content branches
+     * only; settings workspaces commit by explicit path and don't need it.
      */
     gitExcludePattern?: string;
 }
@@ -141,17 +118,11 @@ export declare class GitManager {
     constructor(options: GitManagerOptions, gitOptions?: Partial<SimpleGitOptions>);
     static cloneRepo(remoteUrl: string, targetPath: string, baseBranch?: string): Promise<void>;
     /**
-     * Initializes a local bare git repository to simulate a remote for dev mode.
-     *
-     * This is idempotent - if the remote already exists, it will not be recreated.
-     *
-     * The remote is seeded with the current state of the baseBranch (e.g., 'main').
-     * When the remote already exists but is missing the requested baseBranch
-     * (dev-mode branch auto-detect makes this routine: any git branch created
-     * after the remote was first seeded), that branch is pushed from the source
-     * repo on demand. Branches that already exist in the remote are never
-     * updated here — the CMS pushes editor state into this remote, and a
-     * refresh from the source repo would clobber it.
+     * Initializes a local bare git repository to simulate a remote for dev mode,
+     * seeded with the current state of baseBranch. Idempotent: an existing remote
+     * is never recreated, and a branch already in it is never refreshed from the
+     * source repo — the CMS pushes editor state into this remote, so a refresh
+     * would clobber it. A baseBranch the remote lacks is pushed on demand.
      *
      * @throws Error if not a git repo, no commits, or baseBranch doesn't exist
      */
@@ -166,39 +137,28 @@ export declare class GitManager {
      * EITHER the local-heads namespace (`refs/heads/<branch>`) or the GitHub
      * tracking namespace (`GITHUB_TRACKING_REF_PREFIX<branch>`).
      *
-     * Originally checked `refs/heads/*` only, for dev-mode's
-     * `ensureLocalSimulatedRemote` (a simulated remote never gets a tracking
-     * namespace, so that caller only ever needed the local-heads check).
-     * Generalized/promoted to public for api/branch.ts's create-time collision
-     * guard, which also needs the tracking namespace: `syncGit()` fetches
-     * GitHub into `GITHUB_TRACKING_REF_PREFIX*` rather than `refs/heads/*`
-     * directly (see that constant's doc comment above), and
-     * `reconcileTrackedBranches()` (worker/git-sync.ts) only
-     * non-destructively brings `refs/heads/*` toward what's tracked there — so
-     * a branch that another CanopyCMS deployment sharing this repo (or a
-     * direct push to GitHub) just created can sit in the tracking namespace
-     * for a while before, or without ever, gaining a local head here. Checking
-     * `refs/heads/*` alone would miss exactly the two-deployments-one-repo
-     * collision that guard exists to catch.
+     * Both namespaces matter to api/branch.ts's create-time collision guard: a
+     * branch another CanopyCMS deployment sharing this repo (or a direct push to
+     * GitHub) just created sits in the tracking namespace before, or without
+     * ever, gaining a local head here (see GITHUB_TRACKING_REF_PREFIX above), so
+     * checking `refs/heads/*` alone would miss exactly the
+     * two-deployments-one-repo collision that guard exists to catch.
      *
      * Runs git with an explicit `--git-dir` instead of a cwd inside the repo:
      * environments with `safe.bareRepository=explicit` (sandboxed/CI git setups)
      * refuse cwd-based discovery of bare repos but expressly allow `--git-dir`.
-     * A single `for-each-ref` call checks both candidate refs at once (no
-     * exception-based control flow — `for-each-ref` exits 0 whether or not
-     * either ref exists, same reason the old implementation used `branch
-     * --list` instead of `rev-parse --verify --quiet`: simple-git only fails a
-     * task on stderr output, and `--quiet` suppresses exactly that).
-     * `--end-of-options` guards the ref-name positionals the same way
-     * `push` below does, since `branch` here can be a sanitized but otherwise
-     * caller-influenced string.
+     * A single `for-each-ref` call checks both candidate refs at once, without
+     * exception-based control flow — it exits 0 whether or not either ref
+     * exists, whereas `rev-parse --verify --quiet` suppresses the stderr output
+     * that is the only thing simple-git fails a task on. `--end-of-options`
+     * guards the ref-name positionals the same way `push` below does, since
+     * `branch` here is sanitized but otherwise caller-influenced.
      *
      * A failure here therefore means the remote itself is unreadable and is
      * surfaced, NOT treated as "branch absent" — that would route
      * `ensureLocalSimulatedRemote` to the push path against a repo it couldn't
      * even read, and would silently skip api/branch.ts's collision check
-     * instead of letting that caller distinguish "unreadable" from "absent"
-     * and decide what to do.
+     * instead of letting that caller distinguish "unreadable" from "absent".
      */
     static bareRemoteHasBranch(remotePath: string, branch: string, options?: {
         namespaces?: 'both' | 'tracking';
@@ -207,36 +167,30 @@ export declare class GitManager {
      * Delete `refs/heads/<branch>` from a bare local mirror, if present. A
      * no-op (not an error) when the ref doesn't exist.
      *
-     * This is the "explicit path" for removing a deleted branch's local head
-     * that the sync loop deliberately is not (see GITHUB_TRACKING_REF_PREFIX's
-     * doc comment: reconcileTrackedBranches never deletes a head). Called by
-     * api/branch.ts's deleteBranchHandler: without it, a deleted branch's head
-     * lives in `remote.git` forever, and the ordinary create -> publish ->
-     * squash-merge -> delete -> reuse-the-name cycle then has the REUSED
-     * branch's first publish rejected non-fast-forward against the stale head
-     * (`GitManager.push()` pushes `branch:branch`, and a squash-merged old tip
-     * is not an ancestor of the new branch) -- a permanent, misleading 409.
-     * Worse, a retried submit skips the local push (clean tree) and enqueues
-     * the worker push of the STALE head, resurrecting the deleted branch's
-     * content on GitHub as an apparent success.
+     * The explicit path for removing a deleted branch's local head, which the
+     * sync loop deliberately is not (reconcileTrackedBranches never deletes a
+     * head — see GITHUB_TRACKING_REF_PREFIX). Called by api/branch.ts's
+     * deleteBranchHandler: a head left in `remote.git` forever makes the
+     * create -> publish -> squash-merge -> delete -> reuse-the-name cycle reject
+     * the reused branch's first publish non-fast-forward against the stale head
+     * (`GitManager.push()` pushes `branch:branch`, and a squash-merged old tip is
+     * not an ancestor of the new branch), and a retried submit then skips the
+     * local push on a clean tree and enqueues the worker push of the STALE head,
+     * resurrecting the deleted branch's content on GitHub as an apparent success.
      *
-     * Deliberately leaves the tracking ref (`GITHUB_TRACKING_REF_PREFIX<branch>`)
-     * alone: that namespace mirrors GitHub's view, and if the branch still
-     * exists on GitHub, the create-time collision check SHOULD keep reporting
-     * it until the remote side is actually gone.
+     * Leaves the tracking ref (`GITHUB_TRACKING_REF_PREFIX<branch>`) alone: that
+     * namespace mirrors GitHub's view, so while the branch still exists there the
+     * create-time collision check SHOULD keep reporting it.
      *
-     * Same `--git-dir` invocation style as bareRemoteHasBranch above (works
-     * under `safe.bareRepository=explicit`). The existence pre-check makes
-     * "absent" deterministic instead of parsing update-ref's locale-dependent
-     * failure text, and its captured SHA is passed to `update-ref -d` as the
-     * expected old value -- same pattern as reconcileTrackedBranches'
-     * guarded updates (worker/git-sync.ts): a concurrent Lambda push
-     * re-creating/moving this branch between the read and the delete makes
-     * update-ref throw (surfaced as the caller's best-effort warning) instead
-     * of silently deleting a commit that was just pushed. No
-     * `--end-of-options` on update-ref (older gits don't accept it there);
-     * the ref argument always begins with the literal `refs/heads/` prefix,
-     * so it can never parse as an option.
+     * Same `--git-dir` invocation style as bareRemoteHasBranch above (works under
+     * `safe.bareRepository=explicit`). The existence pre-check makes "absent"
+     * deterministic instead of parsing update-ref's locale-dependent failure
+     * text, and its captured SHA is passed to `update-ref -d` as the expected old
+     * value, so a concurrent push re-creating or moving this branch between the
+     * read and the delete makes update-ref throw instead of silently deleting a
+     * just-pushed commit. No `--end-of-options` on update-ref (older gits reject
+     * it there); the ref argument always begins with the literal `refs/heads/`
+     * prefix, so it can never parse as an option.
      */
     static deleteBareRemoteHead(remotePath: string, branch: string): Promise<void>;
     /**
@@ -250,34 +204,23 @@ export declare class GitManager {
      */
     private static pushBranchToLocalRemote;
     /**
-     * Find the git root directory
      * @returns Path to git root, or cwd if not in a git repo
      */
     static findGitRoot(): Promise<string>;
     /**
-     * Validate that a git repository exists at the given path
-     * @param repoPath - Path to check for .git directory
      * @throws Error if git repo doesn't exist
      */
     static validateGitRepoExists(repoPath: string): Promise<void>;
     /**
      * Guards prod mode against pointing git operations at a NETWORK remote
-     * (http(s)://, ssh://, git://, or scp-like `user@host:path`).
+     * (http(s)://, ssh://, git://, or scp-like `user@host:path`): the prod CMS
+     * Lambda has no internet access and would hang until timeout trying to
+     * clone/fetch/push one. Fires only for `mode === 'prod'`, and only for the
+     * three resolvable sources (explicit param, config, env var) — `file://`
+     * URLs, plain filesystem paths and `resolveRemoteUrl`'s auto-detect step
+     * (local by construction) are always allowed.
      *
-     * In the intended prod architecture the CMS Lambda has no internet access:
-     * all git network I/O happens on the EC2 worker against the EFS-local bare
-     * repo `{workspace}/remote.git`, which the Lambda reaches via auto-detect
-     * (see `resolveRemoteUrl`'s auto-detect step, which always yields a local
-     * path by construction — never checked here). A network URL supplied via
-     * any of the three resolvable sources (explicit param, config, env var) is
-     * almost always a misconfiguration: the internet-less Lambda would try to
-     * clone/fetch/push it directly and hang until timeout.
-     *
-     * Dev mode is never restricted here — this only fires for `mode === 'prod'`.
-     * `file://` URLs and plain filesystem paths are LOCAL and always allowed.
-     *
-     * @param source - Human-readable description of where `url` came from, used
-     *   only in the thrown error message (e.g. "config.defaultRemoteUrl").
+     * @param source - Where `url` came from, for the thrown error message only.
      */
     private static assertRemoteUrlAllowedInMode;
     /**
@@ -287,17 +230,12 @@ export declare class GitManager {
      * 3. Environment variable (mode-specific)
      * 4. Auto-initialized local remote (for dev mode)
      *
-     * Uses strategy flags to determine behavior, GitManager executes the logic.
-     *
-     * In prod mode, a resolved network URL from any of the first three sources
-     * is rejected unless `options.allowNetworkRemoteInProd` is set — see
-     * `assertRemoteUrlAllowedInMode`. Auto-detect/auto-init (source 4) are never
-     * checked: they always yield a local filesystem path by construction.
-     *
-     * @param options.sourceRoot - Optional source directory for monorepos. When provided,
-     *   this directory (relative to git root) is used as the source for the simulated remote.
-     *   Defaults to process.cwd().
+     * In prod mode a resolved network URL from any of the first three sources is
+     * rejected unless `options.allowNetworkRemoteInProd` is set — see
+     * `assertRemoteUrlAllowedInMode`.
      *
+     * @param options.sourceRoot - Source directory for monorepos, relative to the
+     *   git root; the source for the simulated remote. Defaults to process.cwd().
      * @returns Remote URL or undefined if no remote is needed
      */
     static resolveRemoteUrl(options: ResolveRemoteUrlOptions): Promise<string | undefined>;
@@ -306,45 +244,34 @@ export declare class GitManager {
      *
      * Uses `rev-parse --git-dir` with `GIT_CEILING_DIRECTORIES` pinned to the
      * parent directory so a corrupt/missing `.git` can't make git silently
-     * traverse upward and report a false positive from an ancestor repo (the
-     * same protection `initializeWorkspace` relies on below).
+     * traverse upward and report a false positive from an ancestor repo.
      *
      * Shared by `initializeWorkspace` (clone-vs-reuse decision) and
      * `SettingsWorkspaceManager`'s rename guard (settings-workspace.ts), which
      * must know whether a settings workspace ALREADY exists before touching it —
-     * touching an existing orphan settings branch under a different name wipes
-     * permissions.json/groups.json (see that guard's doc comment).
+     * re-initializing one under a different name wipes permissions.json/groups.json.
      */
     static repoExistsAt(workspacePath: string): Promise<boolean>;
     /**
      * Ensures a git workspace is initialized and ready for use.
      * Handles cloning, remote configuration, and branch checkout/creation.
      *
-     * This centralizes the common initialization sequence used by both BranchWorkspaceManager
-     * and SettingsWorkspaceManager.
-     *
      * Note: Does NOT configure git author - that should be done before commits, not during init.
-     *
-     * @returns Configured GitManager instance for the workspace
      */
     static initializeWorkspace(options: InitializeWorkspaceOptions): Promise<GitManager>;
     status(): Promise<GitStatus>;
     /**
      * Mark ContentStore ID indexes AND the resolved-schema cache rooted at (or
-     * under) this repo as stale. Called after operations that mutate the
-     * working tree (checkout/merge/rebase) so ID→path lookups don't keep
-     * resolving to pre-mutation paths, and so a rebase/checkout that pulled in
-     * upstream `.collection.json` changes doesn't leave the schema cache
-     * pinned to the pre-mutation schema. Invoked in `finally` blocks because
-     * even failed merges/rebases may have touched the tree before aborting;
-     * over-invalidating is safe.
+     * under) this repo as stale, so ID→path lookups and `.collection.json`
+     * schemas don't stay pinned to the pre-mutation tree. Called in `finally`
+     * blocks around every working-tree mutation (checkout/merge/rebase) because
+     * even a failed merge may have touched the tree; over-invalidating is safe.
      *
-     * Covers both scopes: in-process stores/caches via their registries, and
-     * consumers in OTHER processes sharing the filesystem (worker vs Lambda on
-     * EFS) via the on-disk generation markers — unless this manager targets a
-     * settings workspace (skipIndexMarker), where only the free in-process
-     * content-index invalidation runs and NEITHER marker is bumped (settings
-     * workspaces have no schema cache of their own either).
+     * Covers in-process stores/caches via their registries and other processes
+     * sharing the filesystem (worker vs Lambda on EFS) via the on-disk generation
+     * markers — except on a settings workspace (skipIndexMarker), where only the
+     * free in-process content-index invalidation runs and NEITHER marker is
+     * bumped (such workspaces have no schema cache of their own either).
      */
     private invalidateContentIndexes;
     checkoutBranch(branch: string): Promise<void>;
@@ -359,27 +286,21 @@ export declare class GitManager {
     commit(message: string): Promise<void>;
     push(branch?: string): Promise<void>;
     /**
-     * Check whether the local branch has commits the remote mirror doesn't
-     * have -- i.e. whether push() would actually move the remote ref forward.
+     * Whether the local branch has commits the remote mirror doesn't -- i.e.
+     * whether push() would move the remote ref forward.
      *
-     * Exists so callers (submitBranch) can gate pushing on "is there anything
-     * new to send" rather than on "is the working tree dirty": committing
-     * cleans the tree, so a dirty-tree gate around commit+push skips the push
-     * entirely on a retry after a failed push, even though the just-created
-     * commit never reached the remote (see services.ts submitBranch).
+     * Callers (services.ts submitBranch) gate pushing on this rather than on "is
+     * the working tree dirty": committing cleans the tree, so a dirty-tree gate
+     * around commit+push skips the push entirely when retried after a failed
+     * push, even though the commit never reached the remote.
      *
-     * Workspaces are cloned `--single-branch`, so the remote-tracking ref for
-     * any branch other than the one cloned never exists locally -- same
-     * constraint pullBaseInner works around. This fetches the specific branch
-     * directly (bypassing the configured single-branch refspec, exactly like
-     * pullBaseInner) and pins the result to FETCH_HEAD's SHA immediately after
-     * the fetch that populated it, rather than trusting `<remote>/<branch>`:
-     * FETCH_HEAD is a shared mutable file that any other fetch in this clone
-     * can repoint before it's read.
+     * Fetches the specific branch directly and pins FETCH_HEAD's SHA immediately
+     * after, rather than trusting `<remote>/<branch>` -- the pullBaseInner
+     * constraint: single-branch clones have no remote-tracking ref for any other
+     * branch, and FETCH_HEAD is shared mutable state.
      *
-     * A branch that has never been pushed has no ref on the remote at all --
-     * `git fetch` then fails ("couldn't find remote ref"), which this treats
-     * as "ahead" (needs pushing) rather than an error.
+     * A branch never pushed has no ref on the remote, so `git fetch` fails
+     * ("couldn't find remote ref"); that counts as "ahead", not an error.
      */
     hasUnpushedCommits(branch?: string): Promise<boolean>;
     ensureAuthor(author: {
@@ -387,39 +308,19 @@ export declare class GitManager {
         email: string;
     }): Promise<void>;
     ensureRemote(remoteUrl: string): Promise<void>;
-    /**
-     * Check if working directory has uncommitted changes
-     */
     hasUncommittedChanges(): Promise<boolean>;
-    /**
-     * Get list of uncommitted file paths
-     */
     getUncommittedFiles(): Promise<string[]>;
-    /**
-     * Get remote URL for current repo
-     */
     getRemoteUrl(): Promise<string | undefined>;
     /**
-     * Add a pattern to .git/info/exclude to prevent it from being committed/pushed.
-     * This is used to exclude .canopy-meta/ from content branch workspaces.
-     *
-     * .git/info/exclude is a per-repository gitignore that never gets committed.
-     * Perfect for runtime metadata that should never leave the workspace.
-     *
-     * This is idempotent - if the pattern already exists, it won't be added again.
+     * Excludes `pattern` (e.g. `.canopy-meta/`) from this workspace's git, so it
+     * can never be committed or pushed. See {@link ensureGitExcludePattern}.
      */
     ensureGitExclude(pattern: string): Promise<void>;
     /**
-     * Create an orphan branch for settings (permissions/groups).
-     *
-     * Orphan branches have no shared history with other branches - they start fresh.
-     * This is perfect for deployment-specific settings that shouldn't pollute content history.
-     *
-     * The branch contains only settings files committed by explicit path
-     * (e.g. permissions.json, groups.json at the workspace root).
-     *
-     * @param branchName - Name of the orphan branch (e.g., 'canopycms-settings-prod')
-     * @param initialFiles - Files to commit to the new branch (e.g., { 'permissions.json': '{}', 'groups.json': '{}' })
+     * Create an orphan branch (no shared history) for settings, so
+     * deployment-specific settings never pollute content history. It holds only
+     * settings files committed by explicit path (permissions.json, groups.json at
+     * the workspace root).
      */
     createOrphanSettingsBranch(branchName: string, initialFiles: Record<string, string>): Promise<void>;
     private createOrphanSettingsBranchInner;