canopycms 0.0.68-int.111 → 0.0.68-int.113

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

@@ -24,18 +24,20 @@ import type { WorkerContext } from './worker-context.js';
  * `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
+ * (`pushSettingsBranches` consuming `trackedTips` is a DATA dependency its
  * signature already enforces; `refreshBaseBranchWorkspace` and the two sweeps
  * are order-independent.)
  *
  * 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' | 'schemaHoldMaxMs' | 'taskDir' | 'taskTimeoutMs' | 'log' | 'buildGitHubUrl' | 'githubMirror' | 'ensureSettingsBranch' | 'ensureStatusReport' | 'isRunning' | 'isDraining' | 'shutdownSignal'> & RebaseContext;
+export type GitSyncContext = Pick<WorkerContext, 'baseBranch' | 'sanitizedBaseBranch' | 'contentBranchesPath' | 'remoteGitPath' | 'schemaHoldMaxMs' | 'taskDir' | 'taskTimeoutMs' | 'log' | 'github' | 'ensureSettingsBranch' | 'ensureStatusReport' | 'isRunning' | 'isDraining' | 'shutdownSignal'> & RebaseContext;
 /**
  * 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. Skipped when `trackedTips`, GitHub's tips
+ * as fetched this cycle, already has the local head, so an unchanged branch
+ * costs no GitHub round trip; every push that does happen still passes the
+ * refusal checks in `MirrorSession.pushToGitHub`.
  *
  * Narrowed to that ONE branch, never every local `canopycms-settings-*`:
  * `reconcileTrackedBranches` creates local heads for branches that exist on
@@ -43,7 +45,7 @@ export type GitSyncContext = Pick<WorkerContext, 'baseBranch' | 'sanitizedBaseBr
  * 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>;
+export declare function pushSettingsBranches(ctx: GitSyncContext, git: ReturnType<typeof simpleGit>, trackedTips: ReadonlyMap<string, string>): Promise<void>;
 export declare function syncGit(ctx: GitSyncContext): Promise<void>;
 /**
  * Repair what killed provisioning and deletes left under the branches root: quarantine residue

package/dist/worker/git-sync.js

@@ -14,6 +14,7 @@ import { CANOPY_META_DIR, isCanopyInternalPath, isNonFastForwardRejection } from
 import { MAX_REPORTED_PATHS, TRACKED_CANOPY_STATE_FIX, isUntracked, listTrackedCanopyState, restoreRetiredSchemaCache, splitByUpstreamTracking, untrackInIndex, } from './canopy-state.js';
 import { hasPendingHistoryRewrite } from './history-rewrite.js';
 import { runRebaseCycle } from './rebase.js';
+import { describeMove } from './github-gateway.js';
 import { cleanupOldTasks } from '../task-queue/cms-task-queue.js';
 import { writeWorkerStatus } from '../task-queue/worker-status.js';
 import { workerLog, workerLogError, workerLogWarn } from './log.js';
@@ -30,8 +31,10 @@ import { reapplySparseCones } from './sparse-cone.js';
 const TRASH_RETENTION_MS = 30 * 24 * 60 * 60_000;
 /**
  * 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. Skipped when `trackedTips`, GitHub's tips
+ * as fetched this cycle, already has the local head, so an unchanged branch
+ * costs no GitHub round trip; every push that does happen still passes the
+ * refusal checks in `MirrorSession.pushToGitHub`.
  *
  * Narrowed to that ONE branch, never every local `canopycms-settings-*`:
  * `reconcileTrackedBranches` creates local heads for branches that exist on
@@ -39,7 +42,7 @@ const TRASH_RETENTION_MS = 30 * 24 * 60 * 60_000;
  * can legitimately show up as a local head here. Pushing it would be this
  * deployment shipping settings state it does not own.
  */
-export async function pushSettingsBranches(ctx, git, trackedNames) {
+export async function pushSettingsBranches(ctx, git, trackedTips) {
     try {
         const settingsBranch = ctx.ensureSettingsBranch();
         const branches = await git.branch();
@@ -65,7 +68,7 @@ export async function pushSettingsBranches(ctx, git, trackedNames) {
         // With this deployment's own branch also missing, the API and this worker
         // have resolved different deploymentNames, and every settings change the
         // API commits is stranded in remote.git forever.
-        const strandedLocal = foreign.filter((b) => !trackedNames.has(b));
+        const strandedLocal = foreign.filter((b) => !trackedTips.has(b));
         if (strandedLocal.length > 0) {
             workerLogWarn(ownBranchMissing
                 ? `Settings branch mismatch: this worker owns "${settingsBranch}", which does not ` +
@@ -83,18 +86,24 @@ export async function pushSettingsBranches(ctx, git, trackedNames) {
             return;
         }
         try {
-            // `git` is remote.git, read for the commit to send; the push itself runs in the
-            // worker's private mirror, which alone ever sees the credential.
+            // `git` is remote.git, read for the commit to send; the push itself goes through the
+            // GitHub gateway, which alone ever sees the credential.
             const sha = (await git.revparse(['--verify', `refs/heads/${settingsBranch}`])).trim();
-            const githubUrl = await ctx.buildGitHubUrl();
-            await ctx
-                .githubMirror()
-                .exclusive((mirror) => mirror.pushToGitHub(githubUrl, settingsBranch, sha, { signal: ctx.shutdownSignal() }));
-            workerLog(`Pushed settings branch ${settingsBranch} to GitHub`);
+            const outcome = trackedTips.get(settingsBranch) === sha
+                ? null
+                : await ctx
+                    .github()
+                    .push({ branch: settingsBranch, sha, protectedBranches: [ctx.baseBranch] }, ctx.shutdownSignal());
+            if (outcome?.moved) {
+                workerLog(`Pushed settings branch ${settingsBranch} to GitHub (${describeMove(outcome)})`);
+            }
+            else {
+                ctx.log.debug(`Settings branch ${settingsBranch} already up to date on GitHub`);
+            }
         }
         catch (err) {
-            // Non-fatal: the branch may already be up to date, and this call site has
-            // no task to throw a PermanentTaskError into (unlike pushBranchToGitHub).
+            // Non-fatal: this call site has no task to throw a PermanentTaskError
+            // into (unlike pushBranchToGitHub).
             // A non-fast-forward rejection here still gets its own wording: it means
             // another deployment's worker already pushed ITS OWN state to this
             // settings-branch name on GitHub -- an actual collision, not just the
@@ -280,15 +289,15 @@ async function reconcileTrackedBranches(ctx, git) {
     if (rewritten.length > 0) {
         workerLog(`  Tracked-branch reconcile: ${rewritten.length} branch(es) rebased locally with the GitHub push still pending: ${rewritten.join(', ')}`);
     }
-    // trackedNames is returned alongside the summary rather than folded into it:
-    // it is a working set for pushSettingsBranches' stranded-branch check, and
+    // trackedTips is returned alongside the summary rather than folded into it:
+    // it is a working set for pushSettingsBranches, and
     // listing every branch on GitHub would bloat worker-status.json for no reader.
     // A base GitHub no longer has can be held for nothing.
     if (!tracked.has(ctx.baseBranch))
         baseHold = { hold: undefined };
     return {
         summary: { created, fastForwarded, ahead, diverged, rewritten },
-        trackedNames: new Set(tracked.keys()),
+        trackedTips: tracked,
         baseHold,
     };
 }
@@ -339,7 +348,7 @@ export async function syncGit(ctx) {
             workerLogWarn(`remote.git maintenance failed: ${getErrorMessage(err)}`);
         }
         try {
-            await ctx.githubMirror().maintain();
+            await ctx.github().maintain();
         }
         catch (err) {
             workerLogWarn(`GitHub mirror maintenance failed: ${getErrorMessage(err)}`);
@@ -350,13 +359,9 @@ export async function syncGit(ctx) {
         // refs/heads/* -- see that constant's doc comment for the destructive-fetch bug this avoids.
         // Both are killed at the drain deadline; a killed ref update leaves the ref as it was or
         // fully moved.
-        const githubUrl = await ctx.buildGitHubUrl();
-        await ctx.githubMirror().exclusive(async (mirror) => {
-            await mirror.fetchFromGitHub(githubUrl, ctx.shutdownSignal());
-            await mirror.publishTrackingRefs(ctx.shutdownSignal());
-        });
+        await ctx.github().fetch({ have: [] }, ctx.shutdownSignal());
         workerLog('Fetched from GitHub');
-        const { summary: trackedSummary, trackedNames, baseHold, } = await reconcileTrackedBranches(ctx, git);
+        const { summary: trackedSummary, trackedTips, baseHold, } = await reconcileTrackedBranches(ctx, git);
         // Recorded at once, so a step below that throws still persists the hold through the catch.
         if (baseHold) {
             const report = ctx.ensureStatusReport();
@@ -366,11 +371,9 @@ export async function syncGit(ctx) {
                 delete report.baseHold;
         }
         // Push settings branches to GitHub (belt-and-suspenders for task queue).
-        // Ensures settings reach GitHub even if a task queue entry is lost.
-        // Ordering relative to the fetch/reconcile above is no longer a
-        // correctness dependency now that the fetch can't clobber refs/heads/*
-        // -- this could run before or after them just as safely.
-        await pushSettingsBranches(ctx, git, trackedNames);
+        // Ensures settings reach GitHub even if a task queue entry is lost. After
+        // the fetch, whose tips (`trackedTips`) let it skip a branch GitHub holds.
+        await pushSettingsBranches(ctx, git, trackedTips);
         if (stoppedForDrain(ctx, 'the base-branch refresh'))
             return;
         const baseRefresh = await refreshBaseBranchWorkspace(ctx);
@@ -410,7 +413,7 @@ export async function syncGit(ctx) {
         const report = ctx.ensureStatusReport();
         // [REDACT] Persisted to worker-status.json and served to the browser
         // by the admin panel -- a fetch/push failure's message can embed the
-        // bot token via buildGitHubUrl().
+        // bot token from the gateway's git URL.
         report.lastGitSyncError = {
             message: redactCredentials(getErrorMessage(err)),
             at: new Date().toISOString(),

package/dist/worker/github-auth.d.ts

@@ -1,8 +1,8 @@
 import type { CanopyOctokitAuthOptions, OctokitAuthStrategyOptions } from '../github-service.js';
 /**
  * How the worker authenticates to GitHub, for both halves of its access:
- * Octokit (the REST API) and git-over-HTTPS (push/fetch, which carries the
- * credential in the remote URL).
+ * Octokit (the REST API) and git-over-HTTPS (push/fetch, which the gateway
+ * hands the credential in a per-command config file).
  *
  * Two shapes are supported, and they are equals — nothing here deprecates,
  * warns on, or nudges away from the token.
@@ -18,7 +18,7 @@ import type { CanopyOctokitAuthOptions, OctokitAuthStrategyOptions } from '../gi
  *   a year, acts as the person who created it, and dies when they leave the
  *   organisation. The cost is that its installation tokens last about an
  *   hour, so the credential must be minted on demand rather than read once at
- *   boot — which is why `CmsWorker.buildGitHubUrl()` is async.
+ *   boot — which is why the gateway resolves it per operation (github-gateway.ts).
  */
 export interface GitHubAuthConfig {
     /**
@@ -68,8 +68,8 @@ export interface GitHubAuthConfig {
      *
      * Core's own backstop, not a substitute for one the provider keeps: a
      * failing publish retries on a 5s/10s/20s backoff (task-queue.ts), and
-     * `CmsWorker` calls `refreshCredential` after every failed task attempt AND
-     * every failed git sync, so a burst of failures would otherwise reach an
+     * the gateway calls `refreshCredential` after every operation that failed
+     * reaching GitHub other than with a 422, so a burst of failures would otherwise reach an
      * adopter-supplied `refreshGitHubToken` every few seconds. The AWS provider
      * (`packages/canopycms-cdk/worker/credential-refresh.ts`) already enforces
      * its own five-minute floor; an adopter's own provider has none unless they
@@ -165,7 +165,7 @@ export interface ResolvedGitHubAuth {
      * `refreshGitHubTokenMinIntervalMs`, and swaps the result in.
      *
      * Nothing needs rebuilding afterwards, on either path. Both consumers read
-     * the credential per use — `resolveGitToken` on every `buildGitHubUrl()`,
+     * the credential per use — `resolveGitToken` for every GitHub-bound git operation,
      * and Octokit through a strategy hook that reads it per request — so a
      * swapped token is live at the next use with no cache to invalidate.
      *
@@ -179,7 +179,7 @@ export interface ResolvedGitHubAuth {
 /**
  * Choose how this worker authenticates, ONCE, from its config.
  *
- * Called from `CmsWorker.ensureGitHubAuth()`, which start() invokes inside
+ * Called where `CmsWorker` creates its GitHub gateway, which start() does inside
  * its try — NOT from the constructor, so that a half-configured worker still
  * constructs and the throw lands where start()'s catch can record it in
  * worker-status.json. Resolved once, so both consumers (Octokit and the git

package/dist/worker/github-auth.js

@@ -38,7 +38,7 @@ function dynamicTokenAuth(getToken) {
 /**
  * Choose how this worker authenticates, ONCE, from its config.
  *
- * Called from `CmsWorker.ensureGitHubAuth()`, which start() invokes inside
+ * Called where `CmsWorker` creates its GitHub gateway, which start() does inside
  * its try — NOT from the constructor, so that a half-configured worker still
  * constructs and the throw lands where start()'s catch can record it in
  * worker-status.json. Resolved once, so both consumers (Octokit and the git
@@ -125,10 +125,10 @@ export function resolveWorkerGitHubAuth(config) {
             // Stamped BEFORE the await, not after, for the same reason
             // credential-refresh.ts's does: stamping after lets two overlapping
             // calls each see an unstamped clock and both reach the provider, which
-            // is the floor not holding. Overlap is real here -- the task loop and
-            // the git-sync loop both call `refreshCredential`, on separate loops
-            // `scheduleLoop` does not serialise against each other -- so this is
-            // what collapses them into one provider call. A provider that THROWS
+            // is the floor not holding. Overlap is real here -- the gateway stops
+            // waiting for a re-read after its timeout without cancelling it, and the
+            // next failure arms another -- so this is what collapses them into one
+            // provider call. A provider that THROWS
             // still counts as reached: the stamp already landed by the time the
             // rejection surfaces, so a failing provider is bounded by the floor
             // too, and this call is not counted in `refreshesStarted` below unless
@@ -137,16 +137,15 @@ export function resolveWorkerGitHubAuth(config) {
             const refresh = ++refreshesStarted;
             const refreshed = await config.refreshGitHubToken();
             // Falsy covers both "nothing rotated" (`undefined`) and an empty secret:
-            // an empty token would build `https://x-access-token:@github.com/…`,
-            // which git sends anonymously, so keeping the known-bad-but-real token
+            // an empty token would send an empty basic credential, which GitHub
+            // treats as anonymous, so keeping the known-bad-but-real token
             // fails more legibly than replacing it with nothing.
             if (!refreshed)
                 return;
             // A refresh that STARTED before one already applied read the store
-            // earlier, so its value can only be older. Refreshes do overlap: the task
-            // loop and the git-sync loop both call this, and
-            // CmsWorker.refreshGitHubCredential stops waiting after `taskTimeoutMs`
-            // without cancelling. Only a refresh that returned a value counts as
+            // earlier, so its value can only be older. Refreshes do overlap: the
+            // gateway stops waiting for one after `taskTimeoutMs` without cancelling
+            // it, and may start the next. Only a refresh that returned a value counts as
             // applied -- one that returned `undefined` (a provider's floor, say) says
             // nothing about how recent it is, so it must not block a slower real read.
             if (refresh < newestRefreshApplied)
@@ -219,9 +218,8 @@ async function mintInstallationToken(app, timeoutMs) {
     });
     const minted = await Promise.race([minting, timedOut]);
     if (!minted) {
-        // An empty token would build `https://x-access-token:@github.com/…`, which
-        // git sends as an anonymous request and GitHub answers with a 403 that
-        // says nothing about the credential.
+        // An empty token would send an empty basic credential, which GitHub
+        // answers as anonymous, with a 403 that says nothing about the credential.
         throw new Error('GitHub App authentication returned an empty installation token');
     }
     return minted;

package/dist/worker/github-gateway.d.ts

@@ -0,0 +1,144 @@
+import type { Octokit, RestEndpointMethodTypes } from '@octokit/rest';
+import type { BareRemoteRepackResult } from '../git-manager.js';
+import { type CreateOrUpdatePullRequestParams } from '../github-service.js';
+import { type ResolvedGitHubAuth } from './github-auth.js';
+import { type GitHubRefUpdate } from './github-mirror.js';
+/** What a {@link GitHubGateway.fetch} brought back. */
+interface GitHubFetchResult {
+    /** The objects the caller lacks, as a bundle to download; always null in-process. */
+    bundleId: string | null;
+}
+declare const inMirrorSession: unique symbol;
+/**
+ * Which GitHub branches reached each of a list of commits, at the last fetch, asked inside a
+ * mirror session that is already held. Branded so the gateway itself, whose own `onGitHub` takes
+ * that session, cannot be passed in its place: the session is not re-entrant.
+ */
+export interface GitHubReachability {
+    readonly [inMirrorSession]: true;
+    onGitHub(ids: readonly string[]): Promise<ReadonlySet<string>>;
+}
+interface GitHubPushRequest {
+    branch: string;
+    /** The commit to put at `refs/heads/<branch>` on GitHub, already in remote.git. */
+    sha: string;
+    /** The commit GitHub must still be at for the push to replace it (`--force-with-lease`). */
+    lease?: string;
+    /** Branches no push may name; GitHub's default branch is always added. */
+    protectedBranches: readonly string[];
+}
+/**
+ * What a push did to GitHub's ref, and whether it got there by the plain retry after GitHub
+ * refused a stale lease, which proves GitHub was not at the lease's commit.
+ */
+export type GitHubPushOutcome = GitHubRefUpdate & {
+    pastStaleLease: boolean;
+};
+/**
+ * A push to GitHub failed: `rejected` on the first attempt, `rejected-after-stale-lease` on the
+ * plain retry after GitHub refused a stale lease. The message is the failure's own (git's output,
+ * for a refusal); `cause` is the error itself. A {@link RefusedPushError} from the first attempt is
+ * thrown as itself.
+ */
+export declare class GitHubPushError extends Error {
+    readonly kind: 'rejected' | 'rejected-after-stale-lease';
+    readonly cause: unknown;
+    constructor(kind: 'rejected' | 'rejected-after-stale-lease', cause: unknown);
+}
+/** A moved ref for a log line: `<old7>..<new7>`, or `new branch at <new7>`. */
+export declare function describeMove(update: Extract<GitHubRefUpdate, {
+    moved: true;
+}>): string;
+/** The fields of a pull request the worker reads. */
+type GitHubPullRequest = Pick<RestEndpointMethodTypes['pulls']['get']['response']['data'], 'merged' | 'merged_at' | 'state' | 'node_id'>;
+type GitHubCreateOrUpdatePullRequest = Omit<CreateOrUpdatePullRequestParams, 'octokit' | 'owner' | 'repo'>;
+/**
+ * Everything the worker does with GitHub, and the only place the credential and Octokit are used.
+ * Octokit errors propagate unchanged (status, headers, response data), so the task runner's
+ * classifiers read them as they would Octokit's own. The gateway re-reads its own credential after
+ * a failure (`LocalGitHubGateway.credentialed`); the worker never asks it to.
+ */
+export interface GitHubGateway {
+    /**
+     * At startup, before anything uses the credential: prove a GitHub App credential works, refuse
+     * a state directory the Lambda could write, and create the mirror.
+     */
+    prepare(): Promise<void>;
+    /** GitHub's default branch. */
+    defaultBranch(signal?: AbortSignal): Promise<string>;
+    /**
+     * Fetch every GitHub branch, and copy them into remote.git's tracking namespace in the same
+     * mirror session, pruning the ones GitHub no longer has. `have` is ignored.
+     */
+    fetch(request: {
+        have: readonly string[];
+    }, signal?: AbortSignal): Promise<GitHubFetchResult>;
+    /** Of `ids`, the ones a GitHub branch contained at the last fetch. */
+    onGitHub(ids: readonly string[]): Promise<ReadonlySet<string>>;
+    /**
+     * Seed the bare repository at `gitDir` with every GitHub branch, in one mirror session: fetch
+     * GitHub, run `beforeSeed` (whose throw stops the seed), require `baseBranch` on GitHub, run
+     * `createRepository` to make the empty repository at `gitDir`, then push into it. `beforeSeed`
+     * runs inside that session, so it asks GitHub only through the object it is given, never
+     * through the gateway.
+     */
+    seedBareRepository(gitDir: string, options: {
+        baseBranch: string;
+        beforeSeed?: (github: GitHubReachability) => Promise<void>;
+        createRepository: () => Promise<void>;
+    }): Promise<void>;
+    /**
+     * Push `sha` to GitHub's `refs/heads/<branch>`, resolving with whether GitHub's ref moved. A
+     * refused lease is retried once without one, which succeeds only as a fast-forward. Throws
+     * {@link RefusedPushError} for a push the worker never makes, {@link GitHubPushError} when the
+     * push fails, and anything else as is.
+     */
+    push(request: GitHubPushRequest, signal?: AbortSignal): Promise<GitHubPushOutcome>;
+    createPullRequest(request: {
+        head: string;
+        base: string;
+        title: string;
+        body: string;
+    }, signal?: AbortSignal): Promise<{
+        number: number;
+        url: string;
+    }>;
+    updatePullRequest(number: number, update: {
+        title?: string;
+        body?: string;
+        state?: 'closed';
+    }, signal?: AbortSignal): Promise<void>;
+    getPullRequest(number: number, signal?: AbortSignal): Promise<GitHubPullRequest>;
+    createOrUpdatePullRequest(request: GitHubCreateOrUpdatePullRequest): Promise<{
+        number: number;
+        url: string;
+        created: boolean;
+    }>;
+    convertPullRequestToDraft(number: number, signal?: AbortSignal): Promise<void>;
+    deleteBranch(branch: string, signal?: AbortSignal): Promise<void>;
+    /** Mirror upkeep. */
+    maintain(): Promise<BareRemoteRepackResult>;
+}
+export interface LocalGitHubGatewayOptions {
+    githubOwner: string;
+    githubRepo: string;
+    auth: ResolvedGitHubAuth;
+    /** Whether `auth` is a GitHub App's, which `prepare()` proves before anything uses it. */
+    githubApp: boolean;
+    /** Holds the mirror; see `CmsWorkerConfig.stateDirectory`. */
+    stateDirectory: string;
+    workspacePath: string;
+    remoteGitPath: string;
+    /** simple-git's inactivity timeout, and the bound on a credential re-read. */
+    timeoutMs: number;
+    /**
+     * Test seam: the repository standing in for GitHub, resolved once per operation. Default:
+     * `https://github.com/<owner>/<repo>.git`, which never carries the token.
+     */
+    remoteUrl?: string | (() => string | Promise<string>);
+    /** Test seam: the Octokit client. Default: built from `auth`. */
+    octokit?: Octokit;
+}
+/** The in-process {@link GitHubGateway}. */
+export declare function createLocalGitHubGateway(options: LocalGitHubGatewayOptions): GitHubGateway;
+export {};