canopycms 0.9.0 → 0.11.0

package/dist/api/archived-branches.js

@@ -0,0 +1,146 @@
+import { z } from 'zod';
+import { ageDeletionHold, archivedBefore, archivedCutoff, deletableByAge, } from '../branch-archive.js';
+import { deleteBranchWorkspace } from '../branch-delete.js';
+import { buildUnmergedArchiveUpdate, getBranchMetadataFileManager } from '../branch-metadata.js';
+import { clientOperatingStrategy, operatingStrategy } from '../operating-mode/index.js';
+import { isSettingsBranchName } from '../paths/index.js';
+import { getBranchProtection } from '../authorization/index.js';
+import { getErrorMessage } from '../utils/error.js';
+import { defineEndpoint } from './route-builder.js';
+import { branchNameSchema } from './validators.js';
+const archiveBranchParamsSchema = z.object({ branch: branchNameSchema });
+const archiveBranchHandler = async (gc, _ctx) => {
+    const { branchContext } = gc;
+    const name = branchContext.branch.name;
+    const meta = getBranchMetadataFileManager(branchContext.branchRoot, branchContext.baseRoot);
+    const archived = await meta.update((current) => current?.branch.name === name &&
+        current.branch.status !== 'archived' &&
+        current.branch.pullRequestState === 'closed'
+        ? { branch: buildUnmergedArchiveUpdate() }
+        : null);
+    if (archived === null) {
+        return {
+            ok: false,
+            status: 409,
+            error: 'Only a branch whose pull request closed without merging can be archived this way.',
+        };
+    }
+    return { ok: true, status: 200, data: { branch: { name, status: 'archived' } } };
+};
+/**
+ * Archive a branch whose PR closed without merging. A close never changes the status by itself,
+ * so this is an admin's decision that the work is abandoned. The handler's checks run on the
+ * branch.json read under its lock, where a reopened PR or a resubmit since the guard read refuses
+ * it. They also cover the base branch, which has no PR.
+ */
+const archiveBranch = defineEndpoint({
+    namespace: 'workflow',
+    name: 'archive',
+    method: 'POST',
+    path: '/:branch/archive',
+    params: archiveBranchParamsSchema,
+    responseType: 'BranchMergeResponse',
+    response: {},
+    defaultMockData: { branch: { name: 'test-branch', status: 'archived' } },
+    guards: ['admin', 'branch'],
+    handler: archiveBranchHandler,
+});
+export const ARCHIVE_BRANCH_ROUTES = { archive: archiveBranch };
+/**
+ * Wall-clock budget for starting deletes, well inside the CMS Lambda's default 60 s timeout
+ * (`DEFAULT_CMS_LAMBDA_TIMEOUT` in canopycms-cdk), so one slow `rm` can still finish. A Lambda
+ * killed in an `rm` costs nothing: the branch is already gone, and the worker sweeps what is left.
+ * @internal Exported for tests.
+ */
+export const DELETE_ARCHIVED_BUDGET_MS = 25_000;
+const deleteArchivedBranchesBodySchema = z.object({
+    olderThanDays: z.number().int().min(1),
+    branches: z.array(z.string()),
+});
+/** @internal Exported for tests. */
+export const deleteArchivedBranchesHandler = async (_gc, ctx, _req, body) => {
+    const { config, registry } = ctx.services;
+    if (!clientOperatingStrategy(config.mode).supportsBranching()) {
+        return { ok: false, status: 400, error: 'Cannot delete branches in this operating mode' };
+    }
+    if (!registry) {
+        return {
+            ok: false,
+            status: 400,
+            error: 'Branch registry not initialized — ensure the workspace has been initialized',
+        };
+    }
+    const startedAt = Date.now();
+    const cutoff = archivedCutoff(body.olderThanDays, startedAt);
+    const settingsBranch = operatingStrategy(config.mode).getSettingsBranchName(config);
+    const old = (await registry.list()).filter(({ branch }) => archivedBefore(branch, cutoff) &&
+        !isSettingsBranchName(branch.name, settingsBranch) &&
+        !getBranchProtection(config, branch.name, branch.baseBranch).isProtected);
+    const confirmed = new Set(body.branches);
+    const due = old.filter(({ branch }) => deletableByAge(branch, cutoff) && confirmed.has(branch.name));
+    const heldFor = (hold) => old.filter(({ branch }) => ageDeletionHold(branch) === hold).map(({ branch }) => branch.name);
+    const data = {
+        deleted: [],
+        skipped: { notMerged: heldFor('not-merged'), unpublished: heldFor('unpublished') },
+        failed: [],
+        remaining: 0,
+        warnings: [],
+    };
+    for (const [index, context] of due.entries()) {
+        if (Date.now() - startedAt > DELETE_ARCHIVED_BUDGET_MS) {
+            data.remaining = due.length - index;
+            break;
+        }
+        const name = context.branch.name;
+        try {
+            const outcome = await deleteBranchWorkspace({
+                context,
+                registry,
+                stillWanted: (current) => current.name === name && deletableByAge(current, cutoff),
+            });
+            if (outcome.kind === 'deleted') {
+                data.deleted.push(name);
+                if (outcome.cleanupWarning)
+                    data.warnings.push(`${name}: ${outcome.cleanupWarning}`);
+            }
+            else {
+                data.failed.push(name);
+            }
+        }
+        catch (err) {
+            console.error(`CanopyCMS: Failed to delete archived branch ${name}:`, getErrorMessage(err));
+            data.failed.push(name);
+        }
+    }
+    // Gone or changed since the admin confirmed them: reported, so nothing reads as deleted.
+    const listed = new Set(old.map(({ branch }) => branch.name));
+    data.failed.push(...[...confirmed].filter((name) => !listed.has(name)));
+    return { ok: true, status: 200, data };
+};
+/**
+ * Delete merged, archived branches older than a number of days, by the rule the retention sweep
+ * uses. Takes the editor's copy only (`deleteBranchWorkspace`'s `remoteCopies`).
+ * Here rather than queued for the worker so the admin gets the answer, and so it works where no
+ * worker runs.
+ */
+const deleteArchivedBranches = defineEndpoint({
+    namespace: 'admin',
+    name: 'deleteArchivedBranches',
+    method: 'POST',
+    path: '/admin/archived-branches/delete',
+    body: deleteArchivedBranchesBodySchema,
+    bodyType: 'DeleteArchivedBranchesBody',
+    responseType: 'DeleteArchivedBranchesResponse',
+    response: {},
+    defaultMockData: {
+        deleted: [],
+        skipped: { notMerged: [], unpublished: [] },
+        failed: [],
+        remaining: 0,
+        warnings: [],
+    },
+    clientTimeout: 'long',
+    guards: ['admin'],
+    handler: deleteArchivedBranchesHandler,
+});
+export const ADMIN_ARCHIVED_BRANCH_ROUTES = { deleteArchivedBranches };

package/dist/api/branch-merge.js

@@ -27,6 +27,7 @@ const markAsMergedHandler = async (gc, ctx, _req, params) => {
             error: 'Cannot mark as merged: no pull request associated with this branch',
         };
     }
+    let verifiedMerged = false;
     if (ctx.services.githubService) {
         try {
             const pr = await ctx.services.githubService.getPullRequest(branchContext.branch.pullRequestNumber);
@@ -37,6 +38,7 @@ const markAsMergedHandler = async (gc, ctx, _req, params) => {
                     error: `Cannot mark as merged: PR #${branchContext.branch.pullRequestNumber} is not merged on GitHub`,
                 };
             }
+            verifiedMerged = true;
         }
         catch (err) {
             console.error(`CanopyCMS: Failed to verify PR merge status for ${branchName}:`, err);
@@ -45,7 +47,20 @@ const markAsMergedHandler = async (gc, ctx, _req, params) => {
     }
     // Update branch status to 'archived'
     const meta = getBranchMetadataFileManager(branchContext.branchRoot, branchContext.baseRoot);
-    await meta.update((current) => current === null ? null : { branch: buildMergedBranchUpdate(current.branch) });
+    const saved = await meta.update((current) => current === null ||
+        (current.branch.pullRequestState === 'closed' && !verifiedMerged) ||
+        (current.branch.status !== 'submitted' && current.branch.status !== 'approved')
+        ? null
+        : { branch: buildMergedBranchUpdate(current.branch) });
+    // `mergedAt` is what lets a branch be deleted by age (branch-archive.ts), so a branch GitHub
+    // reported closed unmerged never takes one on an admin's word.
+    if (saved === null) {
+        return {
+            ok: false,
+            status: 409,
+            error: 'Cannot mark as merged: its pull request was closed without merging, or its status changed. Archive the branch instead.',
+        };
+    }
     // Optionally delete remote branch (disabled by default for safety)
     // if (ctx.services.githubService && req.body?.deleteRemoteBranch) {
     //   try {

package/dist/api/branch-status.d.ts

@@ -23,6 +23,17 @@ declare const submitBranchBodySchema: z.ZodOptional<z.ZodObject<{
 /** The submit request body. */
 export type SubmitBranchBody = z.infer<typeof submitBranchBodySchema>;
 export declare const WORKFLOW_ROUTES: {
+    readonly archive: import("./route-builder.js").RouteDefinition<z.ZodObject<{
+        branch: z.ZodType<import("../paths/index.js").BranchName, z.ZodTypeDef, import("../paths/index.js").BranchName>;
+    }, "strip", z.ZodTypeAny, {
+        branch: string & {
+            readonly __brand: "BranchName";
+        };
+    }, {
+        branch: string & {
+            readonly __brand: "BranchName";
+        };
+    }>, undefined, import("./branch-merge.js").BranchMergeResponse>;
     readonly getStatus: import("./route-builder.js").RouteDefinition<z.ZodObject<{
         branch: z.ZodType<import("../paths/index.js").BranchName, z.ZodTypeDef, import("../paths/index.js").BranchName>;
     }, "strip", z.ZodTypeAny, {

package/dist/api/branch-status.js

@@ -5,6 +5,7 @@ import { getBranchMetadataFileManager } from '../branch-metadata.js';
 import { withdrawBranch } from './branch-withdraw.js';
 import { requestChanges, approveBranch } from './branch-review.js';
 import { markAsMerged } from './branch-merge.js';
+import { ARCHIVE_BRANCH_ROUTES } from './archived-branches.js';
 import { defineEndpoint } from './route-builder.js';
 import { canPerformWorkflowAction, getBranchProtection, isAdmin } from '../authorization/index.js';
 import { syncSubmitPr } from './github-sync.js';
@@ -277,4 +278,5 @@ export const WORKFLOW_ROUTES = {
     requestChanges: requestChanges,
     approve: approveBranch,
     markMerged: markAsMerged,
+    ...ARCHIVE_BRANCH_ROUTES,
 };

package/dist/api/branch-withdraw.js

@@ -28,7 +28,7 @@ const withdrawBranchHandler = async (gc, ctx, req, _params) => {
     // non-'editing' status blocks content writes, and a raw workflow.submit would
     // discard the approval, which the submit status gate refuses (api/branch-status.ts).
     //
-    // 'archived' stays refused: the PR is merged and there is nothing to return to.
+    // 'archived' stays refused: an archive is the end of the branch, merged or not.
     const status = branchContext.branch.status;
     if (status !== 'submitted' && status !== 'approved') {
         return {

package/dist/api/branch.js

@@ -1,18 +1,18 @@
-import fs from 'node:fs/promises';
 import path from 'node:path';
 import { z } from 'zod';
 import { BranchWorkspaceManager } from '../branch-workspace.js';
-import { BranchDirOccupiedError, BranchProvisioningBusyError, deletingDirName, removeLeftoverDir, } from '../branch-provisioning.js';
+import { BranchDirOccupiedError, BranchProvisioningBusyError } from '../branch-provisioning.js';
+import { deleteBranchWorkspace } from '../branch-delete.js';
 import { getBranchMetadataFileManager } from '../branch-metadata.js';
-import { withOccFileLock } from '../utils/occ-json-write.js';
 import { isCreatorsRecentBranch } from './branch-create-window.js';
 import { defineEndpoint } from './route-builder.js';
 import { createDebugLogger } from '../utils/debug.js';
 import { clientOperatingStrategy } from '../operating-mode/index.js';
-import { isNotFoundError, getErrorMessage, sanitizeErrorMessage } from '../utils/error.js';
+import { DELETE_NEEDS_ADMIN_REASON } from '../editor/copy.js';
+import { getErrorMessage } from '../utils/error.js';
 import { filePathExists } from '../utils/fs.js';
 import { isNetworkRemoteUrl } from '../utils/git.js';
-import { parseCreatedBranchName, sanitizeBranchName, RESERVED_SETTINGS_BRANCH_PREFIX, isSettingsBranchName, } from '../paths/index.js';
+import { parseCreatedBranchName, sanitizeBranchName, isSettingsBranchName } from '../paths/index.js';
 import { GitManager } from '../git-manager.js';
 import { syncDeleteRemoteBranch } from './github-sync.js';
 import { branchNameSchema, branchParamSchema } from './validators.js';
@@ -86,7 +86,7 @@ export const canCreateBranch = (user, pathPermissions) => {
  * being avoided, so it has no read-only equivalent here.
  *
  * Shared by createBranchHandler (create-time collision check against the
- * mirror) and deleteBranchHandler (removing the deleted branch's stale local
+ * mirror) and remoteCopiesOf (removing the deleted branch's stale local
  * head from the mirror) -- the two halves of the same lifecycle: what create
  * checks, delete must clean up.
  */
@@ -137,7 +137,9 @@ export const toBranchListItem = (config, branch, viewer) => {
         : !inReview
             ? branch.unpublishedAtMerge
                 ? { kind: 'unpublished-at-merge' }
-                : undefined
+                : branch.status === 'archived' && branch.rewrittenOnGitHub !== undefined
+                    ? { kind: 'rewritten-at-merge' }
+                    : undefined
             : branch.submitUnfinished
                 ? {
                     kind: 'submit-unfinished',
@@ -367,7 +369,7 @@ export const createBranchHandler = async (ctx, req, body) => {
                 // No collision: GitHub does not have this name. Clear any STALE local
                 // head the mirror still carries for it, so this new branch's first
                 // publish can't be rejected non-fast-forward against a leftover tip.
-                // deleteBranchHandler's cleanup (below) handles the common case, but
+                // remoteCopiesOf's cleanup (below) handles the common case, but
                 // cannot cover every ordering: when the branch still existed on
                 // GitHub at editor-delete time, the sync loop's reconcile re-creates
                 // the local head from GitHub's branch within a cycle, and once the
@@ -529,6 +531,9 @@ const branchListResponse = async (ctx, req, branches, defaultBranch) => {
         },
     };
 };
+/** A person's delete, as deletion by age never does, can take commits only the branch still has. */
+const mayHoldLostCommits = (branch) => branch.unpublishedAtMerge === true ||
+    (branch.status === 'archived' && branch.rewrittenOnGitHub !== undefined);
 /** @internal Exported for tests. */
 export const canDeleteBranch = (user, branchContext) => {
     if (isAdmin(user.groups)) {
@@ -594,106 +599,9 @@ export const deleteBranchHandler = async (ctx, req, params) => {
     }
     // It may hold the only copy of commits the merge left out, and deleting it would drop the alert
     // that says so.
-    if (branchContext.branch.unpublishedAtMerge && !isAdmin(req.user.groups)) {
-        return {
-            ok: false,
-            status: 409,
-            error: 'This branch may hold changes that never reached GitHub. Ask an admin to check it before deleting it.',
-        };
-    }
-    // The branch directory leaves its name by one rename, under the same
-    // server-enforced lockfile branch-metadata saves hold (see
-    // utils/occ-json-write.ts), so a save() that reaches that lock after the
-    // rename fails rather than recreating the tree, and a process killed during
-    // the `rm` leaves
-    // only a `.deleting-*` directory the worker sweeps, never residue under a
-    // name that may be created again.
-    const metadataFile = path.join(branchContext.branchRoot, '.canopy-meta', 'branch.json');
-    let cleanupWarning;
-    let deletingPath;
-    try {
-        await withOccFileLock(metadataFile, async () => {
-            if (branchContext.branchRoot === branchContext.baseRoot) {
-                await fs.unlink(metadataFile).catch((err) => {
-                    if (!isNotFoundError(err))
-                        throw err;
-                });
-                return;
-            }
-            const target = path.join(branchContext.baseRoot, deletingDirName(path.basename(branchContext.branchRoot)));
-            try {
-                await fs.rename(branchContext.branchRoot, target);
-                deletingPath = target;
-            }
-            catch (err) {
-                if (isNotFoundError(err))
-                    return;
-                // Still deleted logically: without branch.json the branch is unlisted,
-                // and the worker quarantines what is left.
-                await fs.unlink(metadataFile).catch(() => { });
-                // [REDACT] Returned to the browser; the console line keeps the path.
-                cleanupWarning = `Failed to remove branch directory: ${sanitizeErrorMessage(getErrorMessage(err))}`;
-                console.error(`CanopyCMS: Failed to move branch directory for ${branchName} aside:`, getErrorMessage(err));
-            }
-        });
-    }
-    catch (err) {
-        // Lock acquisition failed (e.g. contention past the retry budget) —
-        // surface as an error rather than silently skipping the delete.
-        return {
-            ok: false,
-            status: 409,
-            error: `Branch is busy, try again: ${getErrorMessage(err)}`,
-        };
+    if (mayHoldLostCommits(branchContext.branch) && !isAdmin(req.user.groups)) {
+        return { ok: false, status: 409, error: DELETE_NEEDS_ADMIN_REASON };
     }
-    if (deletingPath)
-        await removeLeftoverDir(deletingPath);
-    // Also delete the branch's local head from the remote.git mirror (the
-    // deployment's local origin). The sync loop's reconcileTrackedBranches
-    // removes a head only once GitHub no longer has its branch, so while GitHub
-    // does, THIS is the path that removes it -- without this, the head outlives
-    // the branch, and reusing the name after the GitHub side is gone (e.g. a
-    // squash-merged PR with auto-delete) has the reused branch's first publish
-    // rejected non-fast-forward against the stale old tip: a permanent,
-    // misleading 409 -- and a retried submit would then ship the STALE head to
-    // GitHub as an apparent success (see GitManager.deleteBareRemoteHead's doc
-    // comment for the full trace). The tracking ref is deliberately left
-    // alone: while the branch still exists on GitHub, the create-time
-    // collision check SHOULD keep matching it.
-    //
-    // Best-effort, same as the directory removal above: the branch is already
-    // logically deleted; a mirror we can't reach/write just leaves today's
-    // status quo behind (with a warning), it must not fail the delete.
-    const strategy = operatingStrategy(operatingMode);
-    const mirrorPath = resolveReadOnlyMirrorPath(ctx, strategy);
-    const sanitizedDeleted = sanitizeBranchName(branchContext.branch.name);
-    // Defense-in-depth only -- isProtected above already rejects the base
-    // branch, and settings branches never resolve through getBranchContext.
-    const sanitizedBase = sanitizeBranchName(branchContext.branch.baseBranch ?? baseBranchOf(ctx.services.config));
-    const deletableHead = sanitizedDeleted !== sanitizedBase &&
-        !sanitizedDeleted.startsWith(RESERVED_SETTINGS_BRANCH_PREFIX);
-    if (deletableHead &&
-        mirrorPath &&
-        !isNetworkRemoteUrl(mirrorPath) &&
-        (await filePathExists(mirrorPath))) {
-        try {
-            await GitManager.deleteBareRemoteHead(mirrorPath, branchContext.branch.name);
-        }
-        catch (err) {
-            // Client-facing copy is sanitized (API-H2 — no absolute EFS paths);
-            // the console line keeps the raw detail for server logs.
-            const warning = `Failed to remove the deleted branch's head from the local mirror: ${sanitizeErrorMessage(getErrorMessage(err))}`;
-            cleanupWarning = cleanupWarning ? `${cleanupWarning}; ${warning}` : warning;
-            console.warn(`CanopyCMS: failed to remove deleted branch's mirror head (branch ${branchContext.branch.name}, mirror ${mirrorPath}): ${getErrorMessage(err)}`);
-        }
-    }
-    // `branchContext` was read before the delete, so it still carries the PR number this gates on.
-    if (deletableHead) {
-        const warning = await syncDeleteRemoteBranch(ctx, branchContext);
-        if (warning)
-            cleanupWarning = cleanupWarning ? `${cleanupWarning}; ${warning}` : warning;
-    }
-    // Invalidate registry cache so next list() will regenerate without this branch
     if (!ctx.services.registry) {
         return {
             ok: false,
@@ -701,13 +609,43 @@ export const deleteBranchHandler = async (ctx, req, params) => {
             error: 'Branch registry not initialized — ensure the workspace has been initialized',
         };
     }
-    await ctx.services.registry.invalidate();
+    const outcome = await deleteBranchWorkspace({
+        context: branchContext,
+        registry: ctx.services.registry,
+        remoteCopies: remoteCopiesOf(ctx, branchContext),
+    });
+    if (outcome.kind !== 'deleted') {
+        const detail = outcome.kind === 'busy' ? outcome.error : 'it is already being deleted';
+        return { ok: false, status: 409, error: `Branch is busy, try again: ${detail}` };
+    }
+    const { cleanupWarning } = outcome;
     return {
         ok: true,
         status: 200,
         data: { deleted: true, ...(cleanupWarning && { cleanupWarning }) },
     };
 };
+/**
+ * A person's delete also takes the branch off GitHub and the mirror: the sync loop's
+ * reconcileTrackedBranches removes a head only once GitHub no longer has its branch, so while
+ * GitHub does, this is the path that removes it. Without it the head outlives the branch, and
+ * reusing the name after the GitHub side is gone has the reused branch's first publish rejected
+ * non-fast-forward against the stale tip, and a retried submit ship that stale head to GitHub as
+ * an apparent success (see GitManager.deleteBareRemoteHead). The tracking ref stays: while the
+ * branch still exists on GitHub, the create-time collision check should keep matching it.
+ * `branchContext` was read before the delete, so it still carries the PR number GitHub's delete
+ * gates on.
+ */
+const remoteCopiesOf = (ctx, branchContext) => ({
+    baseBranch: branchContext.branch.baseBranch ?? baseBranchOf(ctx.services.config),
+    deleteMirrorHead: async () => {
+        const mirrorPath = resolveReadOnlyMirrorPath(ctx, operatingStrategy(ctx.services.config.mode));
+        if (mirrorPath && !isNetworkRemoteUrl(mirrorPath) && (await filePathExists(mirrorPath))) {
+            await GitManager.deleteBareRemoteHead(mirrorPath, branchContext.branch.name);
+        }
+    },
+    deleteOnGitHub: () => syncDeleteRemoteBranch(ctx, branchContext),
+});
 /** @internal Exported for tests. */
 export const canModifyBranchAccess = (user, branchContext) => {
     if (isAdmin(user.groups)) {

package/dist/api/client.d.ts

@@ -12,6 +12,7 @@ import type { BranchDeleteResponse, BranchListItemResponse, BranchListResponse,
 import type { BranchChangesResponse } from './branch-changes.js';
 import type { BranchEntryChangeResponse } from './branch-entry-changes.js';
 import type { BranchMergeResponse, RequestChangesBody, SubmitBranchBody, SubmitBranchResponse } from './branch-status.js';
+import type { AdminDeleteTaskResponse, AdminRetryTaskResponse, AdminStatusResponse, AdminTasksResponse, BranchHealthResponse, DeleteArchivedBranchesBody, DeleteArchivedBranchesResponse, DismissUnpublishedResponse, PurgeBranchDirResponse, RepairBranchDirResponse, RepairContentDuplicatesResponse } from './admin.js';
 import type { AddCommentBody, AddCommentResponse, CommentsResponse, ResolveCommentResponse } from './comments.js';
 import type { ContentReadResponse, ContentWriteResponse, ReferenceValidationResponse, RenameEntryBody, RenameEntryResponse, ValidateReferencesBody, WriteContentBody } from './content.js';
 import type { ReferenceOptionsResponse } from './reference-options.js';
@@ -23,7 +24,6 @@ import type { ExternalGroupsResponse, InternalGroupsResponse, UpdateInternalGrou
 import type { UserInfoResponse } from './user.js';
 import type { AddEntryTypeApiResponse, CreateCollectionApiResponse, DeleteCollectionApiResponse, GetCollectionApiResponse, GetSchemaApiResponse, InvalidateSchemaCacheApiResponse, RemoveEntryTypeApiResponse, UpdateCollectionApiResponse, UpdateEntryTypeApiResponse, UpdateOrderApiResponse, UpdateOrderBody } from './schema.js';
 import type { CreateCollectionInput, CreateEntryTypeInput, UpdateCollectionInput, UpdateEntryTypeInput } from './../schema/schema-store-types.js';
-import type { AdminDeleteTaskResponse, AdminRetryTaskResponse, AdminStatusResponse, AdminTasksResponse, BranchHealthResponse, DismissUnpublishedResponse, PurgeBranchDirResponse, RepairBranchDirResponse, RepairContentDuplicatesResponse } from './admin.js';
 /** Options for {@link createApiClient}. */
 export interface ApiClientOptions {
     /** Base URL for API requests. Defaults to '/api/canopycms'. */
@@ -102,11 +102,35 @@ export declare class CanopyApiClient {
         approve: (params: Record<string, string>, options?: RequestOptions) => Promise<BranchListItemResponse>;
         /** POST /:branch/mark-merged */
         markMerged: (params: Record<string, string>, options?: RequestOptions) => Promise<BranchMergeResponse>;
+        /** POST /:branch/archive */
+        archive: (params: Record<string, string>, options?: RequestOptions) => Promise<BranchMergeResponse>;
         /** GET /:branch/status */
         getStatus: (params: Record<string, string>, options?: RequestOptions) => Promise<BranchListItemResponse>;
         /** POST /:branch/submit */
         submit: (params: Record<string, string>, body: SubmitBranchBody, options?: RequestOptions) => Promise<SubmitBranchResponse>;
     };
+    readonly admin: {
+        /** POST /admin/archived-branches/delete */
+        deleteArchivedBranches: (body: DeleteArchivedBranchesBody, options?: RequestOptions) => Promise<DeleteArchivedBranchesResponse>;
+        /** GET /admin/branch-health */
+        branchHealth: (params: Record<string, string>, options?: RequestOptions) => Promise<BranchHealthResponse>;
+        /** POST /admin/branch-dirs/:dirName/purge */
+        purgeBranchDir: (params: Record<string, string>, options?: RequestOptions) => Promise<PurgeBranchDirResponse>;
+        /** POST /admin/branch-dirs/:dirName/repair-metadata */
+        repairBranchDir: (params: Record<string, string>, options?: RequestOptions) => Promise<RepairBranchDirResponse>;
+        /** POST /admin/branch-dirs/:dirName/dismiss-unpublished */
+        dismissUnpublished: (params: Record<string, string>, options?: RequestOptions) => Promise<DismissUnpublishedResponse>;
+        /** POST /admin/branch-dirs/:dirName/repair-content-duplicates */
+        repairContentDuplicates: (params: Record<string, string>, options?: RequestOptions) => Promise<RepairContentDuplicatesResponse>;
+        /** GET /admin/status */
+        status: (options?: RequestOptions) => Promise<AdminStatusResponse>;
+        /** GET /admin/tasks/:status */
+        listTasks: (params: Record<string, string>, options?: RequestOptions) => Promise<AdminTasksResponse>;
+        /** POST /admin/tasks/:taskId/retry */
+        retryTask: (params: Record<string, string>, options?: RequestOptions) => Promise<AdminRetryTaskResponse>;
+        /** DELETE /admin/tasks/:status/:fileName */
+        deleteTask: (params: Record<string, string>, options?: RequestOptions) => Promise<AdminDeleteTaskResponse>;
+    };
     readonly comments: {
         /** GET /:branch/comments */
         list: (params: Record<string, string>, options?: RequestOptions) => Promise<CommentsResponse>;
@@ -199,26 +223,6 @@ export declare class CanopyApiClient {
         /** POST /:branch/schema/invalidate-cache */
         invalidateSchemaCache: (params: Record<string, string>, options?: RequestOptions) => Promise<InvalidateSchemaCacheApiResponse>;
     };
-    readonly admin: {
-        /** GET /admin/branch-health */
-        branchHealth: (params: Record<string, string>, options?: RequestOptions) => Promise<BranchHealthResponse>;
-        /** POST /admin/branch-dirs/:dirName/purge */
-        purgeBranchDir: (params: Record<string, string>, options?: RequestOptions) => Promise<PurgeBranchDirResponse>;
-        /** POST /admin/branch-dirs/:dirName/repair-metadata */
-        repairBranchDir: (params: Record<string, string>, options?: RequestOptions) => Promise<RepairBranchDirResponse>;
-        /** POST /admin/branch-dirs/:dirName/dismiss-unpublished */
-        dismissUnpublished: (params: Record<string, string>, options?: RequestOptions) => Promise<DismissUnpublishedResponse>;
-        /** POST /admin/branch-dirs/:dirName/repair-content-duplicates */
-        repairContentDuplicates: (params: Record<string, string>, options?: RequestOptions) => Promise<RepairContentDuplicatesResponse>;
-        /** GET /admin/status */
-        status: (options?: RequestOptions) => Promise<AdminStatusResponse>;
-        /** GET /admin/tasks/:status */
-        listTasks: (params: Record<string, string>, options?: RequestOptions) => Promise<AdminTasksResponse>;
-        /** POST /admin/tasks/:taskId/retry */
-        retryTask: (params: Record<string, string>, options?: RequestOptions) => Promise<AdminRetryTaskResponse>;
-        /** DELETE /admin/tasks/:status/:fileName */
-        deleteTask: (params: Record<string, string>, options?: RequestOptions) => Promise<AdminDeleteTaskResponse>;
-    };
     constructor(options?: ApiClientOptions);
     private buildPath;
     /** One API call, 429 resends included, under the deadline `timeout` and `options` give it. */

package/dist/api/client.js

@@ -68,6 +68,10 @@ export class CanopyApiClient {
             markMerged: (params, options) => {
                 return this.request('POST', this.buildPath('/:branch/mark-merged', params), undefined, 'standard', options);
             },
+            /** POST /:branch/archive */
+            archive: (params, options) => {
+                return this.request('POST', this.buildPath('/:branch/archive', params), undefined, 'standard', options);
+            },
             /** GET /:branch/status */
             getStatus: (params, options) => {
                 return this.request('GET', this.buildPath('/:branch/status', params), undefined, 'standard', options);
@@ -77,6 +81,48 @@ export class CanopyApiClient {
                 return this.request('POST', this.buildPath('/:branch/submit', params), body, 'long', options);
             },
         };
+        this.admin = {
+            /** POST /admin/archived-branches/delete */
+            deleteArchivedBranches: (body, options) => {
+                return this.request('POST', '/admin/archived-branches/delete', body, 'long', options);
+            },
+            /** GET /admin/branch-health */
+            branchHealth: (params, options) => {
+                return this.request('GET', this.buildPath('/admin/branch-health', params), undefined, 'long', options);
+            },
+            /** POST /admin/branch-dirs/:dirName/purge */
+            purgeBranchDir: (params, options) => {
+                return this.request('POST', this.buildPath('/admin/branch-dirs/:dirName/purge', params), undefined, 'long', options);
+            },
+            /** POST /admin/branch-dirs/:dirName/repair-metadata */
+            repairBranchDir: (params, options) => {
+                return this.request('POST', this.buildPath('/admin/branch-dirs/:dirName/repair-metadata', params), undefined, 'long', options);
+            },
+            /** POST /admin/branch-dirs/:dirName/dismiss-unpublished */
+            dismissUnpublished: (params, options) => {
+                return this.request('POST', this.buildPath('/admin/branch-dirs/:dirName/dismiss-unpublished', params), undefined, 'standard', options);
+            },
+            /** POST /admin/branch-dirs/:dirName/repair-content-duplicates */
+            repairContentDuplicates: (params, options) => {
+                return this.request('POST', this.buildPath('/admin/branch-dirs/:dirName/repair-content-duplicates', params), undefined, 'long', options);
+            },
+            /** GET /admin/status */
+            status: (options) => {
+                return this.request('GET', '/admin/status', undefined, 'standard', options);
+            },
+            /** GET /admin/tasks/:status */
+            listTasks: (params, options) => {
+                return this.request('GET', this.buildPath('/admin/tasks/:status', params), undefined, 'standard', options);
+            },
+            /** POST /admin/tasks/:taskId/retry */
+            retryTask: (params, options) => {
+                return this.request('POST', this.buildPath('/admin/tasks/:taskId/retry', params), undefined, 'standard', options);
+            },
+            /** DELETE /admin/tasks/:status/:fileName */
+            deleteTask: (params, options) => {
+                return this.request('DELETE', this.buildPath('/admin/tasks/:status/:fileName', params), undefined, 'standard', options);
+            },
+        };
         this.comments = {
             /** GET /:branch/comments */
             list: (params, options) => {
@@ -246,44 +292,6 @@ export class CanopyApiClient {
                 return this.request('POST', this.buildPath('/:branch/schema/invalidate-cache', params), undefined, 'standard', options);
             },
         };
-        this.admin = {
-            /** GET /admin/branch-health */
-            branchHealth: (params, options) => {
-                return this.request('GET', this.buildPath('/admin/branch-health', params), undefined, 'long', options);
-            },
-            /** POST /admin/branch-dirs/:dirName/purge */
-            purgeBranchDir: (params, options) => {
-                return this.request('POST', this.buildPath('/admin/branch-dirs/:dirName/purge', params), undefined, 'long', options);
-            },
-            /** POST /admin/branch-dirs/:dirName/repair-metadata */
-            repairBranchDir: (params, options) => {
-                return this.request('POST', this.buildPath('/admin/branch-dirs/:dirName/repair-metadata', params), undefined, 'long', options);
-            },
-            /** POST /admin/branch-dirs/:dirName/dismiss-unpublished */
-            dismissUnpublished: (params, options) => {
-                return this.request('POST', this.buildPath('/admin/branch-dirs/:dirName/dismiss-unpublished', params), undefined, 'standard', options);
-            },
-            /** POST /admin/branch-dirs/:dirName/repair-content-duplicates */
-            repairContentDuplicates: (params, options) => {
-                return this.request('POST', this.buildPath('/admin/branch-dirs/:dirName/repair-content-duplicates', params), undefined, 'long', options);
-            },
-            /** GET /admin/status */
-            status: (options) => {
-                return this.request('GET', '/admin/status', undefined, 'standard', options);
-            },
-            /** GET /admin/tasks/:status */
-            listTasks: (params, options) => {
-                return this.request('GET', this.buildPath('/admin/tasks/:status', params), undefined, 'standard', options);
-            },
-            /** POST /admin/tasks/:taskId/retry */
-            retryTask: (params, options) => {
-                return this.request('POST', this.buildPath('/admin/tasks/:taskId/retry', params), undefined, 'standard', options);
-            },
-            /** DELETE /admin/tasks/:status/:fileName */
-            deleteTask: (params, options) => {
-                return this.request('DELETE', this.buildPath('/admin/tasks/:status/:fileName', params), undefined, 'standard', options);
-            },
-        };
         this.baseUrl = options.baseUrl ?? '/api/canopycms';
         // An unbound fetch throws "Illegal invocation" in browsers; Node has no window.
         this.fetchFn = options.fetch ?? (typeof window !== 'undefined' ? fetch.bind(window) : fetch);

package/dist/branch-archive.d.ts

@@ -0,0 +1,19 @@
+import type { BranchMetadata } from './types.js';
+type ArchiveFields = Pick<BranchMetadata, 'status' | 'archivedAt' | 'mergedAt' | 'unpublishedAtMerge' | 'rewrittenOnGitHub'>;
+/** When the branch was archived, or undefined for one that records neither time. */
+export declare const archivedTime: (branch: ArchiveFields) => number | undefined;
+/** Archived before `cutoffMs`. `updatedAt` is no clock: any metadata write moves it. */
+export declare const archivedBefore: (branch: ArchiveFields, cutoffMs: number) => boolean;
+/** Why deletion by age leaves a branch for a person to delete. */
+export type AgeDeletionHold = 'not-merged' | 'unpublished';
+/**
+ * What keeps a branch from deletion by age, past any age: one archived without merging holds work
+ * that reached no base branch, and one merged with an unfinished submit, or rewritten on GitHub,
+ * may hold the only copy of commits the merge left out.
+ */
+export declare const ageDeletionHold: (branch: ArchiveFields) => AgeDeletionHold | undefined;
+/** The one rule the retention sweep and the admin bulk delete both select by. */
+export declare const deletableByAge: (branch: ArchiveFields, cutoffMs: number) => boolean;
+/** `now` less `days`, as the cutoff the functions above take. */
+export declare const archivedCutoff: (days: number, now: number) => number;
+export {};