canopycms 0.0.67 → 0.0.68-int.101

package/dist/git-manager.d.ts

@@ -1,7 +1,64 @@
 import { type SimpleGitOptions, type StatusResult } from 'simple-git';
 import type { OperatingMode } from './operating-mode/index.js';
+import type { ProvisionLog } from './utils/provision-log.js';
 export declare function gitChildEnv(overrides: Record<string, string>): Record<string, string>;
 export declare function gitNetworkChildEnv(): Record<string, string>;
+/**
+ * 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
+ * pusher's: git unsets `GIT_CONFIG_PARAMETERS` before spawning it for a local-path push. Unset, a
+ * push starts auto-housekeeping there (detached, or inside a Lambda that is frozen mid-run) that
+ * repacks while another process clones, and pushes under the default `unpackLimit` (100) leave
+ * loose objects that every local clone copies one NFS round trip at a time.
+ *
+ * Never an `extensions.*` key: once a repo is at `repositoryformatversion` 1, a git that does not
+ * know the key refuses it, and Lambda runs git 2.39.
+ * @internal Exported for tests.
+ */
+export declare const REMOTE_GIT_CONFIG: ReadonlyArray<readonly [key: string, value: string]>;
+/** Write each of {@link REMOTE_GIT_CONFIG} into the bare repo `gitDir` only where it differs. */
+export declare function ensureRemoteGitConfig(gitDir: string): Promise<void>;
+interface BareRemoteObjectCounts {
+    loose: number;
+    packs: number;
+}
+export type BareRemoteRepackResult = {
+    repacked: false;
+    before: BareRemoteObjectCounts;
+} | {
+    repacked: true;
+    before: BareRemoteObjectCounts;
+    after: BareRemoteObjectCounts;
+    ms: number;
+};
+/**
+ * Repack the bare repo `gitDir` once it holds more than {@link REMOTE_GIT_MAX_LOOSE_OBJECTS}
+ * loose objects or {@link REMOTE_GIT_MAX_PACKS} packs, then pack its refs. Under
+ * {@link REMOTE_GIT_CONFIG} every push adds a pack, and nothing else ever compacts them.
+ *
+ * Safe beside concurrent pushes and clones, which is why it is `--cruft` with no expiry:
+ * unreachable objects move into a cruft pack rather than being dropped, so a push that read an
+ * old object before the repack still finds it, and a repack only deletes packs it listed when it
+ * began. A clone that hardlinked a pack keeps that inode when the repack unlinks the remote's
+ * name for it, and packs are never modified in place. `repack -d` also removes the loose objects
+ * it packed and their emptied fan-out directories.
+ */
+export declare function repackBareRemoteIfNeeded(gitDir: string): Promise<BareRemoteRepackResult>;
+/**
+ * Config every workspace clone writes into its own `.git/config`: the managed
+ * marker that ensureRemote's guard checks, and a fallback author for internal
+ * commits such as the orphan settings init (ensureAuthor() sets the real one
+ * before user-facing commits).
+ */
+export declare function managedWorkspaceConfig(gitBotAuthorName: string, gitBotAuthorEmail: string): Record<string, string>;
+export interface CloneRepoOptions {
+    /** The clone's remote name; git's default is `origin`. */
+    remoteName?: string;
+    /** Leave the working tree unpopulated for the caller to check out. */
+    noCheckout?: boolean;
+    /** Written into the new repo's own config by the clone (`git clone -c`). */
+    config?: Record<string, string>;
+}
 /**
  * Remote-tracking namespace that `syncGit()`'s GitHub fetch lands refs in
  * (`+refs/heads/*:${GITHUB_TRACKING_REF_PREFIX}*`), instead of writing
@@ -69,6 +126,17 @@ export declare class GitRemoteRefMissingError extends Error {
      */
     gitError?: unknown | undefined);
 }
+/**
+ * No git remote is configured and the one the strategy auto-detects does not
+ * exist yet: in prod, the EC2 worker creates `{workspaceRoot}/remote.git` on
+ * its first boot, so until then every request that needs a workspace fails
+ * here. Usually transient, unlike a missing remote in a mode with nothing to wait for.
+ * The HTTP layer maps it to a 503 (`http/worker-not-ready.ts`).
+ */
+export declare class RemoteNotReadyError extends Error {
+    readonly expectedRemotePath: string;
+    constructor(expectedRemotePath: string);
+}
 export interface ResolveRemoteUrlOptions {
     mode: OperatingMode;
     remoteUrl?: string;
@@ -108,6 +176,8 @@ export interface InitializeWorkspaceOptions {
      * only; settings workspaces commit by explicit path and don't need it.
      */
     gitExcludePattern?: string;
+    /** Times each provisioning step; no step lines are printed without one. */
+    provisionLog?: ProvisionLog;
 }
 export declare class GitManager {
     private readonly git;
@@ -116,7 +186,13 @@ export declare class GitManager {
     private readonly remote;
     private readonly skipIndexMarker;
     constructor(options: GitManagerOptions, gitOptions?: Partial<SimpleGitOptions>);
-    static cloneRepo(remoteUrl: string, targetPath: string, baseBranch?: string): Promise<void>;
+    /**
+     * Single-branch clone of `baseBranch`, retried once: a clone can lose a race
+     * with the worker's repack of `remote.git` deleting a pack it had just
+     * listed. Before the retry it clears only what it created itself, so a
+     * target that held files beforehand is never touched.
+     */
+    static cloneRepo(remoteUrl: string, targetPath: string, baseBranch?: string, options?: CloneRepoOptions): Promise<void>;
     /**
      * Initializes a local bare git repository to simulate a remote for dev mode,
      * seeded with the current state of baseBranch. Idempotent: an existing remote
@@ -173,7 +249,7 @@ export declare class GitManager {
      * 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
+     * (`GitManager.push()` pushes the branch to the same name, 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.
@@ -223,6 +299,8 @@ export declare class GitManager {
      * @param source - Where `url` came from, for the thrown error message only.
      */
     private static assertRemoteUrlAllowedInMode;
+    /** The not-ready error for a mode whose remote is auto-detected, or `undefined` for other modes. */
+    private static remoteNotReadyError;
     /**
      * Resolves the remote URL for git operations following the priority:
      * 1. Explicit remoteUrl parameter
@@ -239,6 +317,17 @@ export declare class GitManager {
      * @returns Remote URL or undefined if no remote is needed
      */
     static resolveRemoteUrl(options: ResolveRemoteUrlOptions): Promise<string | undefined>;
+    /**
+     * {@link resolveRemoteUrl} for a workspace about to be cloned, which needs a
+     * remote: none resolving is the worker-not-ready error in a mode whose
+     * remote the worker creates, and a configuration error otherwise.
+     */
+    static resolveCloneRemoteUrl(options: ResolveRemoteUrlOptions): Promise<string>;
+    /**
+     * {@link cloneRepo} for a workspace, failing with one message that names the
+     * workspace, the remote and the base branch, which git's own error mixes.
+     */
+    static cloneWorkspace(remoteUrl: string, workspacePath: string, baseBranch: string, options: CloneRepoOptions): Promise<void>;
     /**
      * Check whether a git repository is already initialized at `workspacePath`.
      *
@@ -275,6 +364,14 @@ export declare class GitManager {
      */
     private invalidateContentIndexes;
     checkoutBranch(branch: string): Promise<void>;
+    /**
+     * The one checkout of a `--no-checkout` clone, which has the base branch
+     * and its remote-tracking ref and nothing else, so neither the branch
+     * listing nor the fetch that {@link checkoutBranch} starts with is needed.
+     * The missing index makes git populate the whole tree, even for the base
+     * branch HEAD already names.
+     */
+    checkoutFreshClone(branch: string): Promise<void>;
     private checkoutBranchInner;
     pullBase(): Promise<void>;
     private pullBaseInner;
@@ -282,9 +379,22 @@ export declare class GitManager {
     private pullCurrentBranchInner;
     rebaseOntoBase(): Promise<void>;
     private rebaseOntoBaseInner;
+    /** `--sparse` stages a named path outside a sparse clone's cone (branch-sparse.ts). */
     add(files: string | string[]): Promise<void>;
+    /**
+     * Restrict the working tree to `dirs` in cone mode, which always keeps the root-level files.
+     * Runs before a `--no-checkout` clone's one checkout, which invalidates the content caches.
+     */
+    setSparseCone(dirs: readonly string[]): Promise<void>;
+    /** Stage every working-tree change except canopycms's own state. See {@link stageAllExceptCanopyState}. */
+    addAllExceptCanopyState(): Promise<void>;
     commit(message: string): Promise<void>;
     push(branch?: string): Promise<void>;
+    /**
+     * The checked-out branch's plain name. `rev-parse --abbrev-ref HEAD` prints
+     * `heads/<name>` when a same-named tag exists, which is not a branch name.
+     */
+    private currentBranchName;
     /**
      * Whether the local branch has commits the remote mirror doesn't -- i.e.
      * whether push() would move the remote ref forward.
@@ -303,10 +413,19 @@ export declare class GitManager {
      * ("couldn't find remote ref"); that counts as "ahead", not an error.
      */
     hasUnpushedCommits(branch?: string): Promise<boolean>;
+    /**
+     * Repo-relative paths that differ between HEAD and its merge base with the
+     * base branch: everything the branch changes, across all of its commits.
+     * Diffs against the just-fetched base tip pinned to a SHA — the pullBaseInner
+     * constraint.
+     */
+    listChangedPathsSinceBase(): Promise<string[]>;
     ensureAuthor(author: {
         name: string;
         email: string;
     }): Promise<void>;
+    /** Writes each key into this repo's own config only where it differs. */
+    ensureLocalConfig(values: Record<string, string>): Promise<void>;
     ensureRemote(remoteUrl: string): Promise<void>;
     hasUncommittedChanges(): Promise<boolean>;
     getUncommittedFiles(): Promise<string[]>;
@@ -317,11 +436,59 @@ export declare class GitManager {
      */
     ensureGitExclude(pattern: string): Promise<void>;
     /**
-     * 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).
+     * Put the workspace on the settings branch: an orphan (no shared history),
+     * 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).
+     *
+     * The remote is the settings branch's durable copy, and the workspace clone
+     * is `--single-branch` at the base branch, so the remote is asked first:
+     * - no local branch: check out the remote's, or create an empty orphan only
+     *   when the remote has none. An unreadable remote throws
+     *   {@link SettingsRemoteUnreadableError} rather than guess "none".
+     * - local branch present: a history unrelated to the remote's is repaired
+     *   onto the remote's when the local branch is still its empty initial
+     *   commit with a clean working tree, and otherwise throws
+     *   {@link SettingsBranchDivergedError}; local commits are never discarded.
+     *   An unreadable remote throws only for that empty branch, since one that
+     *   holds settings can serve them and the next save surfaces the remote error.
+     * Either way a remote branch holding content is never adopted:
+     * {@link SettingsBranchHasContentHistoryError}.
      */
     createOrphanSettingsBranch(branchName: string, initialFiles: Record<string, string>): Promise<void>;
     private createOrphanSettingsBranchInner;
+    /**
+     * Compares the checked-out local settings branch with the remote's tip.
+     * Related histories are left for the next settings pull to reconcile; only
+     * an unrelated one is acted on here.
+     */
+    private reconcileLocalSettingsBranch;
+    /**
+     * The remote's tip for `branch`, or `undefined` when the remote has no such
+     * branch. A remote that cannot be read throws: `ls-remote` exits 0 with no
+     * output only for a reachable remote without the ref.
+     */
+    private remoteBranchTip;
+    /**
+     * Fetch `branch` from the remote and return the fetched commit, pinned as
+     * pullBaseInner explains. The full ref: a bare name resolves to a
+     * same-named tag first.
+     */
+    private fetchBranchTip;
+    /**
+     * Refuse to adopt a remote settings branch that holds content: its tip has a file other than
+     * the settings files, or its roots include the base branch's (a settings branch is an orphan).
+     * Neither alone suffices: a base can have a root of its own, and a content tree can be pruned.
+     * The base comes from the remote when the clone lacks it (it was cloned at an earlier base).
+     */
+    private assertNotContentHistory;
+    private baseBranchRev;
+    private rootCommits;
+    /**
+     * Whether `branch` is a single parentless commit with an empty tree, as
+     * orphan creation leaves it. Full refs throughout: a bare name resolves to a
+     * same-named tag first, and clones fetch tags.
+     */
+    private isEmptyInitialBranch;
 }
+export {};