canopycms 0.0.65 → 0.0.66-int.82

package/dist/worker/cms-worker.d.ts

@@ -1,3 +1,4 @@
+export { PermanentTaskError, isPermanentTaskFailure } from './task-runner.js';
 export { workerLog, workerLogWarn, workerLogError, installWorkerLogger } from './log.js';
 /**
  * Auth cache refresh function type.
@@ -63,37 +64,6 @@ export interface CmsWorkerConfig {
      */
     lockStaleMs?: number;
 }
-/**
- * An error inherent to the task itself (malformed payload, unknown action):
- * retrying can never succeed, so the task should fail fast instead of
- * burning its retry budget.
- */
-export declare class PermanentTaskError extends Error {
-}
-/**
- * Classify a task failure as permanent (fail fast) or transient (retry).
- *
- * Transient — worth retrying with backoff:
- * - network errors / anything without an HTTP status (git failures included:
- *   most push/fetch failures are connectivity or contention and the retry
- *   budget bounds the pathological cases)
- * - HTTP 408 (request timeout) and 429 (rate limited)
- * - HTTP 403 that carries a rate-limit signal (see `isRateLimitSignal403`):
- *   GitHub returns 403, not 429, for both primary and secondary/abuse rate
- *   limits. The throttling plugin (see github-service.ts createCanopyOctokit)
- *   proactively retries short waits, but this carve-out remains the safety
- *   net for waits the plugin gives up on (`shouldRetryRateLimit`/
- *   `shouldRetrySecondaryRateLimit`) and for errors it never sees — without
- *   it a rate-limited push-and-create-or-update-pr task would fail
- *   permanently and wedge the branch (`sync-failed`, no retry).
- * - HTTP 5xx (server-side, usually recovers)
- *
- * Permanent — retrying the identical request cannot succeed:
- * - PermanentTaskError (malformed payload, unknown action)
- * - other HTTP 4xx (e.g. 401/404/422): the request itself is bad
- * - plain HTTP 403 with no rate-limit signal: a real permission denial
- */
-export declare function isPermanentTaskFailure(err: unknown): boolean;
 /**
  * CMS Worker daemon.
  * Handles operations that Lambda (with no internet) cannot perform:
@@ -165,6 +135,21 @@ export declare class CmsWorker {
      * resolver is pure, so a later call returns the identical string.
      */
     private ensureSettingsBranch;
+    /**
+     * Build the {@link WorkerContext} handed to the extracted clusters
+     * (task-runner.ts, git-sync.ts, rebase.ts, history-rewrite.ts).
+     *
+     * Built FRESH on every call rather than once in the constructor, and the
+     * instance-backed members are functions rather than copied values. Both
+     * choices exist for the same reason: the test suite drives this class by
+     * replacing `octokit` and `buildGitHubUrl` ON THE INSTANCE, by setting
+     * `running` directly, and by subclassing to override the two rebase test
+     * hooks. A context that captured any of those at construction time would hand
+     * the extracted code the pre-test value -- which for `buildGitHubUrl` means a
+     * test's push going to github.com for real instead of its local fixture repo.
+     * See WorkerContext's doc comment for the full list.
+     */
+    private ctx;
     start(): Promise<void>;
     stop(): Promise<void>;
     /**
@@ -255,47 +240,10 @@ export declare class CmsWorker {
      * guard existed.
      */
     private ensureRemoteGit;
-    /**
-     * Staleness threshold for recoverOrphanedTasks, derived from the
-     * configured task timeout rather than fixed: the safety argument for
-     * running recovery on every poll cycle is "no legitimately in-flight task
-     * can be this old, because executeTaskWithTimeout bounds every attempt by
-     * taskTimeoutMs" -- which is only true if this threshold scales with
-     * taskTimeoutMs. 2x leaves the same comfortable margin the defaults have
-     * (60s timeout vs 5min threshold); the 5-minute floor preserves the
-     * long-standing default for a replacement instance's boot window.
-     */
-    private orphanRecoveryMaxAgeMs;
-    /**
-     * Process queued tasks from Lambda.
-     * Polls .tasks/pending/ directory and executes each task.
-     * Processes up to maxTasksPerCycle tasks per invocation.
-     * Retries transient failures with exponential backoff.
-     */
     processTaskQueue(): Promise<void>;
-    /**
-     * Execute a task bounded by taskTimeoutMs (DEP-H1). Two layers:
-     * - An AbortSignal cancels Octokit HTTP calls promptly.
-     * - A Promise.race rejects when the timeout fires, so work that cannot
-     *   observe the signal (git subprocesses via simple-git) still fails the
-     *   attempt and the worker moves on instead of stalling forever.
-     * pushBranchToGitHub additionally kills stalled git processes via
-     * simple-git's block timeout, so a hung push doesn't leak a process.
-     */
-    private executeTaskWithTimeout;
     private executeTask;
-    /**
-     * Update branch metadata after successful task completion.
-     * Writes PR URL/number and sets syncStatus to 'synced'.
-     */
     private updateBranchMetadata;
-    /**
-     * Update branch metadata after permanent task failure.
-     * Sets syncStatus to 'sync-failed' and records `error` (already redacted
-     * by the caller, processTaskQueue -- see [HIGH-1] there) as
-     * syncFailureReason, so the editor can show WHY, not just that it failed.
-     */
-    private updateBranchMetadataOnFailure;
+    private pushBranchToGitHub;
     private buildGitHubUrl;
     /**
      * The workspace directory for a branch named by its GIT REF name -- the
@@ -314,225 +262,6 @@ export declare class CmsWorker {
      * is sanitized.
      */
     private branchWorkspacePath;
-    /**
-     * What `remote.git` currently holds for `branchRef`, or null when this
-     * branch was never published there (never submitted) or the ref is
-     * unreadable.
-     *
-     * Uses the same explicit `--git-dir` shape as verifyBaseBranchExists()
-     * above: reading a bare repo that way does not depend on
-     * `safe.bareRepository` being permissive, which is why prod code takes
-     * this route rather than the config override the test-only `openBareRepo`
-     * helper uses.
-     */
-    private readPublishedSha;
-    /**
-     * Record that this worker rewrote `expectedSha` out of a branch's already
-     * published history (see BranchMetadata.historyRewrittenFrom).
-     *
-     * Set-once: if a marker is already present it is LEFT ALONE. Across two
-     * rebases before any GitHub push lands, GitHub still holds the commit the
-     * FIRST rebase replaced, so advancing the marker would aim the lease at a
-     * commit GitHub never had and permanently wedge the branch.
-     *
-     * Re-reads metadata rather than trusting the caller's loop-top snapshot:
-     * the task loop runs concurrently with syncGit() (see scheduleLoop) and may
-     * have cleared the marker while this branch was rebasing.
-     */
-    private markHistoryRewritten;
-    /**
-     * Clear the marker once GitHub is confirmed to hold the rewritten history.
-     *
-     * Best-effort only in the sense that a failure here destroys nothing: the
-     * lease still refuses anything unexpected, and the plain-push fallback only
-     * ever fast-forwards. It is NOT harmless. A marker that outlives its
-     * episode can wedge the NEXT one -- if the base advances before the stale
-     * marker is revisited, the queued push leases a commit GitHub has already
-     * moved off, falls back to a plain push of a rebased (non-ancestor)
-     * history, and fails permanently with a "something else moved it on
-     * GitHub" diagnosis that is false: we did.
-     *
-     * Tracked, with the concurrent-clear race that can drop a marker
-     * mid-arming, in
-     * .claude/future-tasks/worker-history-rewrite-marker-races.md.
-     */
-    private clearHistoryRewrittenMarker;
-    /**
-     * Publish a branch clone's rebased history into `remote.git`, replacing
-     * EXACTLY `expectedSha` and nothing else.
-     *
-     * The lease is the entire safety argument. `--force-with-lease=<ref>:<sha>`
-     * refuses unless `remote.git` still stands at `<sha>`, so this can only
-     * ever undo the commit our own rebase rewrote away. Callers must never pass
-     * "whatever remote.git currently holds" -- see the arming guard in
-     * rebaseActiveBranches() for the interleaving where that would silently
-     * delete a reviewer's direct push.
-     *
-     * Returns whether the push landed. A refused lease means a concurrent
-     * Lambda push moved the ref; that is logged and retried by the self-heal
-     * pass on a later cycle, never thrown.
-     */
-    private forcePublishToLocalRemote;
-    /**
-     * Queue the GitHub hop for a branch whose rewritten history now sits in
-     * `remote.git`, so an open PR's head follows the rebase within a cycle
-     * instead of waiting for the editor's next submit.
-     *
-     * Deliberately NOT skipped when a marker is already set: inferring "a task
-     * must already be queued" from the marker starves this hop whenever a task
-     * was lost, failed permanently, or was never written. Duplicate push tasks
-     * are bounded by base-branch advances and are idempotent (a repeat push is
-     * a no-op once GitHub holds the tip).
-     */
-    private enqueueGitHubPush;
-    /**
-     * Complete a rewrite this worker started but did not finish: get the
-     * rebased history into `remote.git` and queued for GitHub.
-     *
-     * Runs from the rebase loop for any branch carrying a marker, whether or
-     * not it is behind base this cycle, so an interrupted publish converges
-     * without waiting for the next base-branch advance.
-     *
-     * Always leases on the MARKER, never on remote.git's current tip -- the
-     * marker is the one commit we know our own rebase replaced.
-     */
-    private reconcilePendingRewrite;
-    private pushBranchToGitHub;
-    /**
-     * 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.
-     */
-    private pushSettingsBranches;
-    /**
-     * 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.
-     */
-    private reconcileTrackedBranches;
-    /**
-     * Whether this branch carries a pending history rewrite -- the rebase loop
-     * rewrote already-published history and the GitHub push has not landed yet
-     * (see BranchMetadata.historyRewrittenFrom).
-     *
-     * `branchName` is a git ref name; branch workspaces are directories named
-     * with the sanitized form, hence the conversion. Best-effort: a settings
-     * branch (no workspace at all), a missing directory or an unreadable
-     * branch.json all mean "no known rewrite", which is the conservative
-     * answer -- it keeps the branch in the louder `diverged` bucket.
-     */
-    private hasPendingHistoryRewrite;
-    syncGit(): 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.
-     */
-    private cleanupTrashedBranchDirs;
-    /**
-     * 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.
-     */
-    private refreshBaseBranchWorkspace;
-    /**
-     * Poll GitHub for a submitted/approved branch's PR resolution.
-     *
-     * submitted/approved branches sit outside the rebase loop and get no
-     * other signal that their PR resolved on GitHub -- nothing pushes a
-     * merge/close webhook back into the branch workspace. merged ->
-     * auto-archive via buildMergedBranchUpdate (shared with the manual
-     * markAsMerged API so both paths produce identical archived-branch
-     * metadata). closed-without-merge -> record pullRequestState only; an
-     * admin decides the workflow transition from there. Best-effort: any
-     * failure here is logged and swallowed, retried next sync cycle.
-     */
-    private pollMergeState;
-    /**
-     * Persist a per-branch rebase failure to branch.json (PR-W2), bounded to
-     * roughly one save per failing branch per hour: a branch stuck failing
-     * every cycle must not turn into unbounded save-per-cycle x N-failing-
-     * branches write amplification -- save() eager-regenerates the branch
-     * registry (branch-metadata.ts's invalidateRegistry(), O(branch count) EFS
-     * reads), the same concern the `alreadyClean` no-op guard above exists
-     * for.
-     *
-     * Best-effort and non-fatal like every other metadata write in this
-     * loop's error paths: a corrupt branch.json, a lock-contention error, or
-     * any other save failure here must never abort the per-branch iteration.
-     * This matters doubly at the two call sites -- one is inside the outer
-     * per-branch catch, with no further catch of its own around this call --
-     * so the whole method is wrapped, not just the load.
-     */
-    private recordRebaseFailure;
     /**
      * Test-only seam: awaited inside `rebaseActiveBranches()`'s conflict round,
      * after `git rebase` reported conflicted files and BEFORE the
@@ -555,5 +284,10 @@ export declare class CmsWorker {
      */
     protected afterRebaseCompletedForTesting(): Promise<void>;
     private rebaseActiveBranches;
+    syncGit(): Promise<void>;
+    private pushSettingsBranches;
+    private refreshBaseBranchWorkspace;
+    private cleanupTrashedBranchDirs;
+    private pollMergeState;
     refreshAuthCache(): Promise<void>;
 }