canopycms 0.9.0 → 0.10.0

package/dist/worker/archived-sweep.js

@@ -0,0 +1,137 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { archivedCutoff, archivedTime, deletableByAge } from '../branch-archive.js';
+import { deleteBranchWorkspace } from '../branch-delete.js';
+import { BranchMetadataCorruptError, BranchMetadataFileManager } from '../branch-metadata.js';
+import { BranchRegistry } from '../branch-registry.js';
+import { isSettingsBranchName, sanitizeBranchName } from '../paths/branch-name.js';
+import { getErrorMessage, isNotFoundError, sanitizeErrorMessage } from '../utils/error.js';
+import { escapeForLog } from '../utils/escape-text.js';
+import { workerLog, workerLogError, workerLogWarn } from './log.js';
+import { holdProvisionedWorkspace, releaseProvisionedWorkspace } from './provisioned-workspace.js';
+/**
+ * The most branches one cycle deletes, oldest first: turning retention on over a long backlog must
+ * not stall the sync loop. The rest wait for the next cycle.
+ * @internal Exported for tests.
+ */
+export const MAX_ARCHIVED_SWEEP_PER_CYCLE = 25;
+/** Branches past the cutoff, oldest first. Reads disk: a stale registry must not choose them. */
+async function listDueBranches(ctx, cutoff) {
+    const settingsBranch = ctx.ensureSettingsBranch();
+    const due = [];
+    const entries = await fs.readdir(ctx.contentBranchesPath, { withFileTypes: true });
+    for (const entry of entries) {
+        const dirName = entry.name;
+        if (!entry.isDirectory() || dirName.startsWith('.'))
+            continue;
+        if (dirName === ctx.sanitizedBaseBranch || isSettingsBranchName(dirName, settingsBranch)) {
+            continue;
+        }
+        let branch;
+        try {
+            const metaFile = await BranchMetadataFileManager.loadOnly(path.join(ctx.contentBranchesPath, dirName));
+            branch = metaFile?.branch;
+        }
+        catch (err) {
+            // One unreadable directory costs only itself. System health lists a corrupt branch.json.
+            if (!(err instanceof BranchMetadataCorruptError)) {
+                workerLogWarn(`Skipping ${dirName} in the archived sweep: ${getErrorMessage(err)}`);
+            }
+        }
+        if (branch !== undefined &&
+            sanitizeBranchName(branch.name) === dirName &&
+            (branch.baseBranch === undefined || sanitizeBranchName(branch.baseBranch) !== dirName) &&
+            deletableByAge(branch, cutoff)) {
+            due.push({ dirName, branch });
+        }
+    }
+    return due.sort((a, b) => (archivedTime(a.branch) ?? 0) - (archivedTime(b.branch) ?? 0));
+}
+/**
+ * Delete merged, archived branches past `archivedBranchRetentionDays`, oldest first, through the
+ * one delete path (branch-delete.ts). Off unless the deployment set that.
+ *
+ * Each branch is held by its provisioning lock, zero-retry as everywhere in the sync loop, and the
+ * selection is decided again under the lock the delete takes, from a fresh read.
+ *
+ * Takes the editor's copy only: `remoteCopies` in branch-delete.ts says why, and reconcile prunes
+ * a head no workspace holds once GitHub drops it (stale-mirror.ts).
+ *
+ * Never throws, and one branch's failure costs only that branch, which the next cycle retries. A
+ * kill past the rename leaves a `.deleting-*` directory `sweepProvisioningLeftovers` clears.
+ */
+export async function sweepArchivedBranches(ctx, now = Date.now()) {
+    if (ctx.archivedBranchRetentionDays === undefined)
+        return undefined;
+    const cutoff = archivedCutoff(ctx.archivedBranchRetentionDays, now);
+    let due;
+    try {
+        due = await listDueBranches(ctx, cutoff);
+    }
+    catch (err) {
+        if (!isNotFoundError(err)) {
+            workerLogError('Could not list archived branches to sweep:', getErrorMessage(err));
+        }
+        return undefined;
+    }
+    if (due.length === 0)
+        return undefined;
+    const report = {
+        deleted: [],
+        skippedLocked: [],
+        failed: [],
+        deferred: Math.max(0, due.length - MAX_ARCHIVED_SWEEP_PER_CYCLE),
+        warnings: [],
+    };
+    const registry = new BranchRegistry(ctx.contentBranchesPath);
+    for (const { dirName, branch } of due.slice(0, MAX_ARCHIVED_SWEEP_PER_CYCLE)) {
+        if (ctx.isDraining())
+            break;
+        const { name } = branch;
+        try {
+            const hold = await holdProvisionedWorkspace(ctx.contentBranchesPath, dirName);
+            if (hold.kind === 'locked') {
+                report.skippedLocked.push(name);
+                continue;
+            }
+            if (hold.kind === 'not-provisioned')
+                continue;
+            try {
+                if (hold.isCompromised()) {
+                    report.skippedLocked.push(name);
+                    continue;
+                }
+                const outcome = await deleteBranchWorkspace({
+                    context: {
+                        baseRoot: ctx.contentBranchesPath,
+                        branchRoot: path.join(ctx.contentBranchesPath, dirName),
+                        branch,
+                    },
+                    registry,
+                    stillWanted: (current) => current.name === name && deletableByAge(current, cutoff),
+                });
+                if (outcome.kind === 'deleted') {
+                    report.deleted.push(name);
+                    workerLog(`  Deleted archived branch ${escapeForLog(name)}: past the retention period`);
+                    if (outcome.cleanupWarning)
+                        report.warnings.push(`${name}: ${outcome.cleanupWarning}`);
+                }
+                else if (outcome.kind === 'busy') {
+                    report.failed.push({ branch: name, error: sanitizeErrorMessage(outcome.error) });
+                }
+            }
+            finally {
+                await releaseProvisionedWorkspace(hold.release, dirName);
+            }
+        }
+        catch (err) {
+            report.failed.push({ branch: name, error: sanitizeErrorMessage(getErrorMessage(err)) });
+        }
+    }
+    for (const { branch, error } of report.failed) {
+        workerLogWarn(`  Could not delete archived branch ${escapeForLog(branch)}: ${error}`);
+    }
+    for (const warning of report.warnings)
+        workerLogWarn(`  ${escapeForLog(warning)}`);
+    return report;
+}

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

@@ -54,6 +54,11 @@ export interface CmsWorkerConfig extends GitHubAuthConfig {
     gitSyncInterval?: number;
     /** Auth cache refresh interval in ms (default: 15 * 60 * 1000) */
     authCacheRefreshInterval?: number;
+    /**
+     * Delete a merged branch's workspace, metadata and comments this many days after it was archived
+     * (worker/archived-sweep.ts). A positive integer; unset keeps archived branches.
+     */
+    archivedBranchRetentionDays?: number;
     /** Base branch name (default: detected at start(); see `resolveBaseBranch`) */
     baseBranch?: string;
     /**
@@ -190,6 +195,7 @@ export declare class CmsWorker {
     private maxTasksPerCycle;
     private taskTimeoutMs;
     private gitSyncIntervalMs;
+    private readonly archivedBranchRetentionDays;
     private maxRetries;
     private lockFilePath;
     private lockStaleMs;

package/dist/worker/cms-worker.js

@@ -261,6 +261,11 @@ export class CmsWorker {
         this.maxTasksPerCycle = config.maxTasksPerCycle ?? 10;
         this.taskTimeoutMs = config.taskTimeoutMs ?? DEFAULT_TASK_TIMEOUT;
         this.gitSyncIntervalMs = config.gitSyncInterval ?? 5 * 60_000;
+        const retentionDays = config.archivedBranchRetentionDays;
+        if (retentionDays !== undefined && !(Number.isInteger(retentionDays) && retentionDays > 0)) {
+            throw new Error(`archivedBranchRetentionDays must be a positive whole number of days, not ${retentionDays}`);
+        }
+        this.archivedBranchRetentionDays = retentionDays;
         this.maxRetries = config.maxRetries ?? DEFAULT_MAX_RETRIES;
         this.lockFilePath = path.join(config.workspacePath, '.tasks', '.worker-lock');
         this.lockStaleMs = config.lockStaleMs ?? DEFAULT_LOCK_STALE_MS;
@@ -282,6 +287,7 @@ export class CmsWorker {
                 workerVersion: CANOPYCMS_VERSION,
                 startedAt: now,
                 updatedAt: now,
+                archivedBranchRetentionDays: this.archivedBranchRetentionDays,
             };
         }
         return this.statusReport;
@@ -334,6 +340,7 @@ export class CmsWorker {
             contentBranchesPath: this.contentBranchesPath,
             contentRoot: this.contentRoot,
             schemaHoldMaxMs: this.schemaHoldMaxMs,
+            archivedBranchRetentionDays: this.archivedBranchRetentionDays,
             taskTimeoutMs: this.taskTimeoutMs,
             gitSyncIntervalMs: this.gitSyncIntervalMs,
             maxTasksPerCycle: this.maxTasksPerCycle,

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

@@ -16,8 +16,8 @@ import type { WorkerContext } from './worker-context.js';
  * says the serving editor lacks a schema the incoming content names), push this
  * deployment's own settings
  * branch, fast-forward the base branch's workspace, ask the gateway for its branch policy,
- * rebase every branch that is behind it (rebase.ts), then sweep old tasks and expired trashed
- * branch directories.
+ * rebase every branch that is behind it (rebase.ts), then sweep old tasks, expired trashed
+ * branch directories and, where retention is on, expired archived branches.
  *
  * One ordering is load-bearing and nothing enforces it: `runRebaseCycle` MUST
  * follow `reconcileTrackedBranches`. Branch clones fetch the base tip from
@@ -26,13 +26,13 @@ import type { WorkerContext } from './worker-context.js';
  * reorder them and every branch rebases onto the PREVIOUS cycle's
  * base tip -- not corrupting, but silently a cycle behind.
  * (`pushSettingsBranches` consuming the fetch's tips is a DATA dependency its
- * signature already enforces; `refreshBaseBranchWorkspace` and the two sweeps
+ * signature already enforces; `refreshBaseBranchWorkspace` and the 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' | 'github' | 'ensureSettingsBranch' | 'ensureStatusReport' | 'warnedDivergences' | 'isRunning' | 'isDraining' | 'shutdownSignal'> & RebaseContext;
+export type GitSyncContext = Pick<WorkerContext, 'baseBranch' | 'sanitizedBaseBranch' | 'contentBranchesPath' | 'remoteGitPath' | 'schemaHoldMaxMs' | 'archivedBranchRetentionDays' | 'taskDir' | 'taskTimeoutMs' | 'log' | 'github' | 'ensureSettingsBranch' | 'ensureStatusReport' | 'warnedDivergences' | 'isRunning' | 'isDraining' | 'shutdownSignal'> & RebaseContext;
 /**
  * Push THIS deployment's own settings branch (`ensureSettingsBranch()`) from
  * remote.git to GitHub. Non-fatal. Skipped when `trackedTips`, GitHub's tips

package/dist/worker/git-sync.js

@@ -13,6 +13,7 @@ import { getErrorMessage, isNodeError, redactCredentials } from '../utils/error.
 import { escapeForLog } from '../utils/escape-text.js';
 import { CANOPY_META_DIR, isCanopyInternalPath, isNonFastForwardRejection } from '../utils/git.js';
 import { MAX_REPORTED_PATHS, TRACKED_CANOPY_STATE_FIX, isUntracked, listTrackedCanopyState, restoreRetiredSchemaCache, splitByUpstreamTracking, untrackInIndex, } from './canopy-state.js';
+import { sweepArchivedBranches } from './archived-sweep.js';
 import { hasPendingHistoryRewrite, recordSeenOnGitHub } from './history-rewrite.js';
 import { runRebaseCycle } from './rebase.js';
 import { describeMove } from './github-gateway.js';
@@ -545,6 +546,7 @@ export async function syncGit(ctx) {
         if (trashRemoved > 0) {
             workerLog(`Removed ${trashRemoved} expired trashed branch dir(s)`);
         }
+        const archivedSweep = await sweepArchivedBranches(ctx);
         const report = ctx.ensureStatusReport();
         report.lastGitSyncAt = new Date().toISOString();
         delete report.lastGitSyncError;
@@ -555,6 +557,7 @@ export async function syncGit(ctx) {
         report.lastGitSync = {
             durationMs: Date.now() - cycleStartedAt,
             rebased: rebaseSummary.rebased,
+            ...(archivedSweep && { archivedSweep }),
             skippedDirty: baseRefresh.outcome === 'skipped-dirty'
                 ? [ctx.sanitizedBaseBranch, ...rebaseSummary.skippedDirty]
                 : rebaseSummary.skippedDirty,

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

@@ -9,8 +9,8 @@ import type { WorkerContext } from './worker-context.js';
  * `remote.git` to them, but branch clones never fetch their own branch, so without this step the
  * clone's next rebase or commit diverges from `remote.git` and every submit after that is refused.
  *
- * Runs once per cycle for every branch this deployment has published, in every status but
- * archived, under the provisioning and content-write locks the caller holds, ahead of the rebase.
+ * Brings them in once per cycle for every branch this deployment has published, in every status
+ * but archived, under the provisioning and content-write locks the caller holds, ahead of the rebase.
  * It never forces anything: a clone behind GitHub fast-forwards, and a clone with commits GitHub
  * lacks gets a real merge (branch-merge.ts), which keeps every commit on both sides.
  *

package/dist/worker/github-commits.js

@@ -41,13 +41,16 @@ export async function bringInGitHubCommits(ctx, args) {
     const { git, branchRef, metaFile, dirty, gatewayPolicy } = args;
     const { branch } = metaFile;
     // A branch.json naming another ref is that branch's, which shares this directory's name.
-    if (branch.name !== branchRef || !isPublished(metaFile))
+    if (branch.name !== branchRef)
         return { kind: 'in-step' };
     const gitHubTip = args.gitHub?.tips.get(branchRef);
-    // No GitHub branch leaves nothing a push could restore.
+    // No GitHub branch leaves nothing a push could restore. Ahead of `isPublished`: withdrawing drops
+    // a closed PR's number, which can be all that marked the branch published.
     if (args.gitHub !== undefined && gitHubTip === undefined && branch.rewrittenOnGitHub) {
         await clearRewritten(ctx, args);
     }
+    if (!isPublished(metaFile))
+        return { kind: 'in-step' };
     const published = await readPublishedSha(ctx, branchRef);
     const tip = gitHubTip ?? published;
     if (tip === null)

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

@@ -362,13 +362,13 @@ export declare const fetchPoll: z.ZodDiscriminatedUnion<"state", [z.ZodObject<{
     bundleId: z.ZodNullable<z.ZodString>;
 }, "strict", z.ZodTypeAny, {
     state: "done";
-    progress: number;
     refs: [string, string][];
+    progress: number;
     bundleId: string | null;
 }, {
     state: "done";
-    progress: number;
     refs: [string, string][];
+    progress: number;
     bundleId: string | null;
 }>]>;
 export declare const pushAnswer: z.ZodUnion<[z.ZodObject<{

package/dist/worker/rebase.js

@@ -525,7 +525,11 @@ async function bringInCommitsForBranchInReview(ctx, branchDir, branchPath, metaF
         if (gitHubTip === undefined) {
             if (gitHub === undefined)
                 return { kind: 'none' };
-            const { rebaseFailure, rewrittenOnGitHub } = metaFile.branch;
+            const { rebaseFailure, rewrittenOnGitHub, pullRequestNumber } = metaFile.branch;
+            // A merge can delete the head branch, so with a PR recorded a rewrite stays for the
+            // merge poll to find: it is what holds the branch from deletion by age (branch-archive.ts).
+            if (rewrittenOnGitHub !== undefined && pullRequestNumber !== undefined)
+                return { kind: 'none' };
             if (rebaseFailure !== undefined || rewrittenOnGitHub !== undefined) {
                 await clearRebaseFailure(ctx, branchPath, branchRef);
             }
@@ -747,7 +751,7 @@ async function rebaseOneBranch(ctx, branchDir, branchPath, isProvisioningLockCom
         // - submitted/approved: in review, so never rewrite history under an active
         //   PR -- but do poll GitHub for the PR's resolution, since nothing else
         //   tells the worker a merge/close happened;
-        // - archived: already merged, with no PR left to poll.
+        // - archived: finished, with no PR left to poll.
         if (metaFile !== null && (branchStatus === 'submitted' || branchStatus === 'approved')) {
             workerLog(`  Skipping ${branchDir} (${branchStatus})`);
             const outcome = await bringInCommitsForBranchInReview(ctx, branchDir, branchPath, metaFile, isProvisioningLockCompromised, gatewayPolicy, gitHub);

package/dist/worker/task-runner.js

@@ -1,5 +1,6 @@
 import fs from 'node:fs/promises';
 import { completeTask, dequeueTask, failTask, recoverOrphanedTasks, releaseTask, retryTask, } from '../task-queue/cms-task-queue.js';
+import { filePathExists } from '../utils/fs.js';
 import { isNoCommitsBetweenError, isRefAlreadyGoneError } from '../github-service.js';
 import { BranchMetadataCorruptError, BranchMetadataFileManager, awaitsSubmitRetry, getBranchMetadataFileManager, } from '../branch-metadata.js';
 import { sanitizeBranchName, RESERVED_SETTINGS_BRANCH_PREFIX } from '../paths/branch-name.js';
@@ -507,12 +508,14 @@ async function isSupersededSubmit(ctx, task, branch) {
     if (typeof submittedAt !== 'string')
         return false;
     const live = await BranchMetadataFileManager.loadOnly(ctx.branchWorkspacePath(branch));
+    const firstRun = !task.retryCount && requeuedFrom === undefined;
+    // A retry with no workspace at all: its branch was deleted since. A first run proceeds, since a
+    // quarantine's rename can hide a live workspace for a moment.
     if (live === null)
-        return false;
+        return !firstRun && !(await filePathExists(ctx.branchWorkspacePath(branch)));
     const { status, submittedAt: recorded } = live.branch;
     if (status === 'archived')
         return true;
-    const firstRun = !task.retryCount && requeuedFrom === undefined;
     if (firstRun && (recorded === undefined || recorded < submittedAt))
         return false;
     return (status !== 'submitted' && status !== 'approved') || recorded !== submittedAt;
@@ -606,7 +609,7 @@ export async function updateBranchMetadata(ctx, task, result) {
             // A pull request opened as the branch merged is not this branch's, whose record is the merge.
             const archived = existing.branch.status === 'archived';
             if (archived && result.prNumber) {
-                workerLogWarn(`Not recording pull request #${result.prNumber} on merged ${branch}`);
+                workerLogWarn(`Not recording pull request #${result.prNumber} on archived ${branch}`);
             }
             if (result.prUrl && !archived)
                 updates.pullRequestUrl = result.prUrl;
@@ -683,7 +686,7 @@ async function updateBranchMetadataOnFailure(ctx, task, error, options) {
                 // merge already set stands, for an admin to dismiss.
                 if (options.unlock || task.action !== SUBMIT_ACTION)
                     return { branch: failed };
-                // Merged while this ran: nothing is left to finish it, as buildMergedBranchUpdate records.
+                // Archived while this ran: nothing is left to finish it, as buildMergedBranchUpdate records.
                 if (existing.branch.status === 'archived') {
                     return { branch: { ...failed, unpublishedAtMerge: true } };
                 }

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

@@ -48,6 +48,8 @@ export interface WorkerContext {
     readonly contentRoot: string;
     /** Longest the schema gate holds the base branch before advancing anyway (worker/schema-gate.ts). */
     readonly schemaHoldMaxMs: number;
+    /** Days after archiving that the sync loop deletes a merged branch; undefined leaves them all. */
+    readonly archivedBranchRetentionDays: number | undefined;
     /** Per-task timeout in ms; also simple-git's inactivity block timeout. */
     readonly taskTimeoutMs: number;
     /** How long the sync loop rests between cycles, in ms. */

package/package.json

@@ -1,7 +1,7 @@
 {
   "//": "@codemirror/language, @lezer/highlight: workaround — @mdxeditor/editor uses cm6-theme-basic-light which peer-requires these but mdxeditor doesn't declare them as dependencies",
   "name": "canopycms",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "CanopyCMS core package: schema-driven content, branch-aware editing, and editor UI for Next.js.",
   "license": "MIT",
   "repository": {