canopycms 0.0.67-int.90 → 0.0.67

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

@@ -12,155 +12,54 @@ import type { WorkerContext } from './worker-context.js';
  * 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:
+ * One ordering is load-bearing and nothing enforces it: `runRebaseCycle` MUST
+ * follow `reconcileTrackedBranches`. 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.
+ * (`pushSettingsBranches` consuming `trackedNames` is a DATA dependency its
+ * signature already enforces; `refreshBaseBranchWorkspace` and the two sweeps
+ * are order-independent.)
  *
- * - `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.
+ * 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.
+ * 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.
+ * Narrowed to that ONE branch, never every local `canopycms-settings-*`:
+ * `reconcileTrackedBranches` creates local heads for branches that exist on
+ * GitHub, so ANOTHER deployment's settings branch (sharing this GitHub repo)
+ * can legitimately show up as a local head here. Pushing it would be this
+ * deployment shipping settings state it does not 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.
+ * [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}. A name that doesn't match `.trash-{dirName}-
+ * {STAMP}`, or whose stamp fails to parse, is left alone and logged once per
+ * cycle: 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>.
+ * (content-branches/<baseBranch>) to match origin/<baseBranch>, every sync
+ * cycle, so the drift window is bounded by gitSyncInterval.
  *
- * 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.
+ * A dedicated, explicit and LOUD step rather than a side effect of the rebase
+ * loop, whose skip paths (a dirty tree, a missing .git) are silent: a wedged
+ * base clone otherwise leaves no diagnosable signal, and an editor forking a
+ * new branch "from base" silently gets a stale snapshot.
  *
  * 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.
+ * origin/<baseBranch>, so a merge that isn't a fast-forward (diverged local
+ * history) is left untouched rather than force-resolved.
  */
 export declare function refreshBaseBranchWorkspace(ctx: GitSyncContext): Promise<void>;