canopycms 0.0.65 → 0.0.66-int.82

package/dist/worker/git-sync.d.ts

@@ -0,0 +1,166 @@
+import { simpleGit } from 'simple-git';
+import { type RebaseContext } from './rebase.js';
+import type { WorkerContext } from './worker-context.js';
+/**
+ * The git-sync cluster: everything reachable from `CmsWorker.syncGit()`, the
+ * slower of the worker's two poll loops (default 5 minutes, against the task
+ * queue's 5 seconds).
+ *
+ * One cycle, in order: fetch every GitHub branch into the tracking namespace,
+ * bring `refs/heads/*` toward it non-destructively (`reconcileTrackedBranches`),
+ * push this deployment's own settings branch, fast-forward the base branch's
+ * workspace, rebase every branch that is behind it (rebase.ts), then sweep old
+ * tasks and expired trashed branch directories.
+ *
+ * Two of those steps are ordered by something the code enforces, and the rest
+ * are not ordered at all:
+ *
+ * - `pushSettingsBranches` consumes `trackedNames` from
+ *   `reconcileTrackedBranches`, which is a DATA dependency its signature
+ *   already enforces -- see its own comment, which says as much.
+ * - `runRebaseCycle` must follow `reconcileTrackedBranches`, and this is the
+ *   one dependency nothing enforces. Branch clones fetch the base tip from
+ *   `remote.git` (`origin`), and `reconcileTrackedBranches` is what advances
+ *   `remote.git`'s `refs/heads/*` toward what the fetch above put in the
+ *   tracking namespace. Reorder them and every branch rebases onto the
+ *   PREVIOUS cycle's base tip -- not corrupting, but silently a cycle behind.
+ *
+ * `refreshBaseBranchWorkspace` and the two sweeps are order-independent.
+ *
+ * What matters more than any of that is that the whole cycle is wrapped so
+ * both outcomes record a worker-status.json snapshot, since an operator's only
+ * view of this loop is the admin panel.
+ */
+export type GitSyncContext = Pick<WorkerContext, 'baseBranch' | 'sanitizedBaseBranch' | 'contentBranchesPath' | 'remoteGitPath' | 'taskDir' | 'taskTimeoutMs' | 'log' | 'buildGitHubUrl' | 'ensureSettingsBranch' | 'ensureStatusReport' | 'isRunning'> & RebaseContext;
+/**
+ * Per-cycle outcome of `reconcileTrackedBranches()` -- the non-destructive
+ * replacement for the old `+refs/heads/*:refs/heads/*` fetch refspec (see
+ * `GITHUB_TRACKING_REF_PREFIX`'s doc comment for the bug this fixes). Folded
+ * by `syncGit()` into the worker's self-reported status
+ * (`WorkerStatusReport.lastGitSync.tracked`, see worker-status.ts).
+ */
+export interface TrackedBranchSummary {
+    /** GitHub branches with no corresponding local `refs/heads/<name>` yet -- created at GitHub's tip. */
+    created: string[];
+    /** Local heads that were strict ancestors of GitHub's tip -- fast-forwarded to it. */
+    fastForwarded: string[];
+    /**
+     * Local heads AHEAD of GitHub's tip -- unpushed editor/settings work.
+     * Deliberately left untouched; this is exactly what the old refspec used
+     * to force-rewind or (with --prune) delete outright.
+     */
+    ahead: string[];
+    /**
+     * Local heads that diverged from GitHub's tip (neither side is an
+     * ancestor of the other) -- left untouched and logged. A real collision
+     * (e.g. another deployment moved the same branch name); the next push
+     * attempt will be rejected non-fast-forward, which is the correct,
+     * visible outcome.
+     */
+    diverged: string[];
+    /**
+     * Local heads that diverged from GitHub's tip because THIS worker's rebase
+     * loop rewrote them and published the rewrite into `remote.git`, with the
+     * GitHub push still outstanding (`BranchMetadata.historyRewrittenFrom` is
+     * set). Structurally identical to `diverged` at the ref level, but a known,
+     * self-resolving state rather than a cross-deployment collision -- kept in
+     * its own bucket so the collision warning stays meaningful.
+     */
+    rewritten: string[];
+}
+/**
+ * Push THIS deployment's own settings branch (`ensureSettingsBranch()`) from
+ * remote.git to GitHub. Non-fatal: a no-op push for an up-to-date branch
+ * just succeeds quietly.
+ *
+ * Deliberately narrowed to one branch — this used to push EVERY local
+ * branch matching `canopycms-settings-*`. With the tracking-namespace fetch
+ * fix (GITHUB_TRACKING_REF_PREFIX), `reconcileTrackedBranches` creates local
+ * heads for branches that exist on GitHub, so ANOTHER deployment's settings
+ * branch (sharing this same GitHub repo) can legitimately show up as a
+ * local head here too. Pushing it would be this deployment shipping
+ * settings state it doesn't own.
+ */
+export declare function pushSettingsBranches(ctx: GitSyncContext, git: ReturnType<typeof simpleGit>, trackedNames: ReadonlySet<string>): Promise<void>;
+/**
+ * Bring `refs/heads/*` in `remote.git` toward what was just fetched into
+ * `GITHUB_TRACKING_REF_PREFIX` -- WITHOUT ever force-rewinding or deleting
+ * a local head. This is the non-destructive replacement for what the old
+ * `+refs/heads/*:refs/heads/*` fetch refspec used to do implicitly (and
+ * destructively) as part of the fetch itself; see
+ * `GITHUB_TRACKING_REF_PREFIX`'s doc comment for the two failure modes
+ * that refspec caused.
+ *
+ * Per tracked branch:
+ * - no local `refs/heads/<name>` yet -> create it at the tracked commit
+ *   (a branch created on GitHub, or by another deployment sharing this
+ *   GitHub repo, becomes visible locally).
+ * - local is a strict ancestor of tracked (behind) -> fast-forward it.
+ * - local === tracked -> nothing to do.
+ * - tracked is a strict ancestor of local (ahead) -> LEAVE IT ALONE. This
+ *   is unpushed editor/settings work; the queued push task (or
+ *   pushSettingsBranches) ships it. This is exactly the branch state the
+ *   old refspec used to destroy.
+ * - neither is an ancestor of the other (diverged) -> LEAVE IT ALONE and
+ *   count/log it. A real collision (e.g. another deployment moved the
+ *   same branch name on GitHub); the next push attempt will be rejected
+ *   non-fast-forward, which is the correct, visible outcome -- this
+ *   method must never silently pick a winner. The one expected, benign
+ *   form of this -- our own rebase loop having published a rewrite into
+ *   remote.git with the GitHub push still queued -- is split out into the
+ *   `rewritten` bucket so the collision warning stays meaningful.
+ *
+ * Never deletes a local head: a branch removed on GitHub simply stops
+ * being tracked here; the local ref persists until removed through its
+ * own explicit path (the sync loop must not be one of them).
+ *
+ * `remote.git` is bare, so there is no worktree to invalidate by moving
+ * these refs -- unlike a non-bare repo, updating the ref that happens to
+ * be "checked out" is a non-issue here.
+ *
+ * Concurrency: `remote.git` is bare and on EFS, and the Lambda pushes into
+ * it concurrently (`GitManager.push()`'s `target:target` refspec) while
+ * this runs. Every `update-ref` below passes the expected old value (the
+ * all-zeros OID for "must not exist yet" on creation, the previously-read
+ * SHA for the fast-forward case) so a concurrent Lambda write landing in
+ * the gap between the read and the write loses the ref update instead of
+ * being silently clobbered -- the branch is simply revisited next cycle.
+ */
+export declare function reconcileTrackedBranches(ctx: GitSyncContext, git: ReturnType<typeof simpleGit>): Promise<{
+    summary: TrackedBranchSummary;
+    trackedNames: Set<string>;
+}>;
+export declare function syncGit(ctx: GitSyncContext): Promise<void>;
+/**
+ * [C1] Remove `.trash-*` branch directories (created by the admin purge
+ * action, api/admin-branch-health.ts) whose name-embedded stamp is older
+ * than {@link TRASH_RETENTION_MS}. Names that don't match the expected
+ * `.trash-{dirName}-{STAMP}` shape, or whose stamp fails to parse, are
+ * left alone (logged once per cycle, not per file, to avoid flooding logs
+ * if something odd accumulates) -- purge is the only writer of this
+ * naming scheme, so an unparseable name is unexpected and worth a human
+ * looking rather than a silent skip.
+ */
+export declare function cleanupTrashedBranchDirs(ctx: Pick<GitSyncContext, 'contentBranchesPath'>): Promise<number>;
+/**
+ * Fast-forward the base branch's own working-tree clone
+ * (content-branches/<baseBranch>) to match origin/<baseBranch>.
+ *
+ * Previously this clone was refreshed only incidentally, by the generic
+ * rebase loop below (rebaseActiveBranches): for a branch with status
+ * 'editing', rebasing onto origin/<baseBranch> degenerates to a
+ * fast-forward when the clone IS the base branch. But that loop's skip
+ * paths -- a dirty tree, a missing .git -- are silent, which is the
+ * suspected live failure mode: a wedged base clone with no diagnosable
+ * signal in the logs. This dedicated step makes the refresh explicit,
+ * ff-only, and loud, so a stuck base view (an editor forking a new branch
+ * "from base" that's actually a stale snapshot) is diagnosable from logs.
+ * This runs every sync cycle so the drift window is bounded by
+ * gitSyncInterval.
+ *
+ * ff-only on purpose: this clone must stay a linear mirror of
+ * origin/<baseBranch>, so a merge that isn't a fast-forward (diverged
+ * local history) is treated as a should-never-happen condition and left
+ * untouched rather than force-resolved.
+ */
+export declare function refreshBaseBranchWorkspace(ctx: GitSyncContext): Promise<void>;