@osdlc/repo-cleaner 0.10.0 → 0.11.0

package/dist/cli.js

@@ -4,7 +4,7 @@
  * Four verbs over one set of sweep filters:
  *
  *   status  (the default) inventory and classify; read-only but for the fetch
- *   summary the same sweep as counts: totals, merged, delete, review, keep
+ *   summary the same sweep as counts: totals, merged, delete, prune, review, keep
  *   plan    write the deletable rows as a plan, to stdout or a file
  *   apply   re-check, show the steps, ask, then delete
  *
@@ -21,15 +21,18 @@
  *   10  nothing to sweep: no entry named a repository
  *   11  apply stopped at a failed step; the receipt says which
  */
-import { readSync } from 'node:fs';
-import { basename, dirname, join, resolve } from 'node:path';
+import { existsSync, readSync, realpathSync } from 'node:fs';
+import { basename, dirname, join, resolve, sep } from 'node:path';
 import { isatty } from 'node:tty';
-import { EXIT, askYesNo, canPrompt, defineCli } from '@osdlc/cli-tool';
+import { EXIT, askYesNo, canPrompt, defineCli, systemDirs } from '@osdlc/cli-tool';
 import { Git } from '@osdlc/typed-git';
 import { resolveBranch } from "./branches.js";
+import { VENDOR_DIRS } from "./devlink.js";
+import { ensureMirror, mirrorProblem } from "./remote-mirror.js";
 import { ApplyArgumentError, applyPlan, parseGrant, parseRowRef } from "./apply.js";
 import { PLAN_VERSION, fileStamp, parsePlan, planRepo, readPlan, writePlan, } from "./plan.js";
-import { proposedCommands, renderCountsJson, renderCountsText, renderJson, renderReceipt, renderSummary, renderText, } from "./render.js";
+import { RECEIPT_VERSION } from "./receipt.js";
+import { proposedCommands, renderCountsJson, renderCountsText, renderJson, renderReceipt, renderSummary, renderText, rowsActedOn, summarizeReceipt, } from "./render.js";
 import { NO_STATUS_LINE, describeStep, describeSweep, statusLine, } from "./status-line.js";
 import { sweepRepos } from "./sweep.js";
 const EXIT_NOTHING_TO_SWEEP = 10;
@@ -58,6 +61,13 @@ const SWEEP_FLAGS = {
         valueName: 'name',
         help: 'remote to measure against (default: origin)',
     },
+    remoteUrl: {
+        kind: 'list',
+        valueName: 'url',
+        default: [],
+        commaSeparated: false,
+        help: 'sweep the branches of this remote with no checkout of your own, through a clone kept in the cache directory; repeatable',
+    },
     gh: { kind: 'boolean', negatable: true, help: 'classify on git evidence alone' },
     fetch: {
         kind: 'boolean',
@@ -97,7 +107,7 @@ const statusCli = () => defineCli({
     },
     epilogue: `commands:
   ${NAME} [status]   this report (the default)
-  ${NAME} summary    counts per repository: total, merged, delete, review, keep
+  ${NAME} summary    counts per repository: total, merged, delete, prune, review, keep
   ${NAME} plan       write the deletable rows as a plan
   ${NAME} apply      re-check, show the steps, ask, delete
   ${NAME} dev        run ${NAME} from a development checkout
@@ -108,7 +118,7 @@ swept as ./<name>.`,
 const summaryCli = () => defineCli({
     name: `${NAME} summary`,
     summary: 'Count local branches, worktrees and remote branches per repository: how many there are, ' +
-        'how many are merged into the default branch, and how many would be deleted, reviewed or kept.',
+        'how many are merged into the default branch, and how many would be deleted, pruned, reviewed or kept.',
     positionals: PATHS,
     flags: { ...SWEEP_FLAGS, output: OUTPUT },
     epilogue: 'merged: the work is on the default branch. Rows kept for structure (the default ' +
@@ -160,7 +170,7 @@ const applyCli = () => defineCli({
         repoRoot: {
             kind: 'string',
             valueName: 'path',
-            help: 'apply only the plan repository rooted here',
+            help: 'with a plan of several repositories: apply only the one rooted here',
         },
         receipt: {
             kind: 'string',
@@ -208,28 +218,48 @@ function failure(ctx, err) {
     ctx.io.stderr(`${NAME}: ${err instanceof Error ? err.message : String(err)}\n`);
     return EXIT.error;
 }
+/** Where `--remote-url` keeps its clones. */
+function mirrorCache(ctx) {
+    return systemDirs(VENDOR_DIRS, { env: ctx.env }).standalone(NAME).cache().app('remotes').path;
+}
 /** Validate the sweep flags and run the sweep, or answer with the exit code. */
-function sweep(name, v, paths, ctx, render, status) {
+function sweep(name, v, paths, ctx, status) {
     const only = v.only?.filter((s) => s !== '');
     const unknown = (only ?? []).filter((s) => !(s in ONLY));
     if (unknown.length > 0) {
-        return {
-            ok: false,
-            code: usageError(ctx, name, `unknown --only value(s): ${unknown.join(', ')}`),
-        };
+        const message = `unknown --only value(s): ${unknown.join(', ')}`;
+        return { kind: 'exit', code: usageError(ctx, name, message) };
     }
     if (v.branch !== undefined && paths.length > 0) {
+        const message = '--branch sweeps this repository only; drop the paths';
+        return { kind: 'exit', code: usageError(ctx, name, message) };
+    }
+    // An empty URL is refused, not dropped: `--remote-url "$UNSET"` must not
+    // fall back to sweeping the checkout you are standing in.
+    if (v.remoteUrl.some((u) => u.trim() === '')) {
         return {
-            ok: false,
-            code: usageError(ctx, name, '--branch sweeps this repository only; drop the paths'),
+            kind: 'exit',
+            code: usageError(ctx, name, '--remote-url needs a URL; got an empty one'),
         };
     }
+    const urls = v.remoteUrl;
+    if (urls.length > 0) {
+        const conflict = paths.length > 0
+            ? '--remote-url sweeps a remote, not a checkout; drop the paths'
+            : v.branch !== undefined
+                ? '--branch reads the checkout you are in; it does not combine with --remote-url'
+                : (only ?? []).some((s) => s !== 'remotes')
+                    ? '--remote-url has remote branches only; drop --only or pass --only remotes'
+                    : null;
+        if (conflict !== null)
+            return { kind: 'exit', code: usageError(ctx, name, conflict) };
+    }
     let branch;
     try {
         branch = v.branch === undefined ? undefined : resolveBranch(v.branch, new Git(ctx.cwd));
     }
     catch (err) {
-        return { ok: false, code: failure(ctx, err) };
+        return { kind: 'exit', code: failure(ctx, err) };
     }
     const options = {
         baseDir: ctx.cwd,
@@ -244,22 +274,36 @@ function sweep(name, v, paths, ctx, render, status) {
         ...(only === undefined ? {} : { scope: only.map((s) => ONLY[s]) }),
         ...(v.remote === undefined ? {} : { remote: v.remote }),
     };
+    let entries = paths.length > 0 ? [...paths] : [ctx.cwd];
+    if (urls.length > 0) {
+        const cache = mirrorCache(ctx);
+        try {
+            entries = urls.map((url, i) => {
+                if (v.progress)
+                    status.update(`${NAME}: cloning remote ${i + 1}/${urls.length}`);
+                return ensureMirror(url, cache);
+            });
+        }
+        catch (err) {
+            status.clear();
+            return { kind: 'exit', code: failure(ctx, err) };
+        }
+        options.scope = ['remote-branches'];
+    }
     if (v.progress)
         status.update(`${NAME}: finding repositories`);
-    const result = sweepRepos(paths.length > 0 ? paths : [ctx.cwd], options);
+    const result = sweepRepos(entries, options);
     status.clear();
     if (branch !== undefined && result.repos.length > 1) {
         const err = new Error(`--branch sweeps one repository; ${result.repos.length} found under ${ctx.cwd}`);
-        return { ok: false, code: failure(ctx, err) };
+        return { kind: 'exit', code: failure(ctx, err) };
     }
     const refused = branch === undefined ? null : (result.repos[0]?.error ?? null);
     if (refused !== null)
-        return { ok: false, code: failure(ctx, new Error(refused)) };
-    if (result.repos.length === 0) {
-        ctx.io.stdout(render(result));
-        return { ok: false, code: EXIT_NOTHING_TO_SWEEP };
-    }
-    return { ok: true, result, branch, values: v };
+        return { kind: 'exit', code: failure(ctx, new Error(refused)) };
+    if (result.repos.length === 0)
+        return { kind: 'nothing', result };
+    return { kind: 'ok', result, branch, values: v };
 }
 /**
  * Name each repository the sweep could not read, on stderr. True when there
@@ -292,9 +336,13 @@ function runStatus(argv, ctx, status) {
         return usageError(ctx, NAME, parsed.message);
     const v = parsed.values;
     const render = (r) => v.output === 'json' ? renderJson(r) : renderText(r, { keep: v.keep });
-    const swept = sweep(NAME, v, parsed.positionals, ctx, render, status);
-    if (!swept.ok)
+    const swept = sweep(NAME, v, parsed.positionals, ctx, status);
+    if (swept.kind === 'exit')
         return swept.code;
+    if (swept.kind === 'nothing') {
+        ctx.io.stdout(render(swept.result));
+        return EXIT_NOTHING_TO_SWEEP;
+    }
     if (v.commands) {
         const commands = proposedCommands(swept.result);
         if (commands.length > 0)
@@ -314,11 +362,11 @@ function runSummary(argv, ctx, status) {
         return usageError(ctx, name, parsed.message);
     const v = parsed.values;
     const render = (r) => v.output === 'json' ? renderCountsJson(r) : renderCountsText(r);
-    const swept = sweep(name, v, parsed.positionals, ctx, render, status);
-    if (!swept.ok)
+    const swept = sweep(name, v, parsed.positionals, ctx, status);
+    if (swept.kind === 'exit')
         return swept.code;
     ctx.io.stdout(render(swept.result));
-    return EXIT.ok;
+    return swept.kind === 'nothing' ? EXIT_NOTHING_TO_SWEEP : EXIT.ok;
 }
 function runPlan(argv, ctx, status) {
     const name = `${NAME} plan`;
@@ -328,12 +376,14 @@ function runPlan(argv, ctx, status) {
     if (parsed.status === 'error')
         return usageError(ctx, name, parsed.message);
     const v = parsed.values;
-    const swept = sweep(name, v, parsed.positionals, ctx, (r) => {
-        ctx.io.stderr(renderSummary(r) + '\n');
-        return '';
-    }, status);
-    if (!swept.ok)
+    const swept = sweep(name, v, parsed.positionals, ctx, status);
+    if (swept.kind === 'exit')
         return swept.code;
+    // stdout carries only the plan, so the summary goes to stderr either way.
+    if (swept.kind === 'nothing') {
+        ctx.io.stderr(renderSummary(swept.result) + '\n');
+        return EXIT_NOTHING_TO_SWEEP;
+    }
     const plan = planOf(swept, new Date());
     const unreadable = reportUnreadable(ctx, name, swept.result);
     ctx.io.stderr(renderSummary(swept.result) + '\n');
@@ -352,8 +402,69 @@ function receiptBeside(planPath, now) {
     const stem = basename(planPath).replace(/\.json$/i, '');
     return join(dirname(planPath), `${stem}.receipt-${fileStamp(now)}.json`);
 }
+/** Rows the run would delete or prune: one each, however many steps (an unlock, a remove) it takes. */
 function wouldRun(receipt) {
-    return receipt.steps.filter((s) => s.row !== null).length;
+    return rowsActedOn(summarizeReceipt(receipt));
+}
+/** Sweep and plan in memory, or read `--plan`; or answer with the exit code. */
+function loadPlan(name, v, paths, ctx, deps, status, now) {
+    const receiptPath = v.receipt === undefined ? null : resolve(ctx.cwd, v.receipt);
+    if (v.plan === undefined) {
+        const swept = sweep(name, v, paths, ctx, status);
+        if (swept.kind === 'exit')
+            return swept.code;
+        if (swept.kind === 'nothing') {
+            ctx.io.stdout(v.output === 'json' ? renderJson(swept.result) : renderText(swept.result));
+            return EXIT_NOTHING_TO_SWEEP;
+        }
+        const items = new Map();
+        for (const r of swept.result.repos)
+            if (r.repo !== null)
+                items.set(r.repo.root, r.items);
+        return {
+            plan: planOf(swept, now),
+            source: '(swept)',
+            receiptPath,
+            unreadable: reportUnreadable(ctx, name, swept.result),
+            swept: items,
+        };
+    }
+    try {
+        if (v.plan === '-') {
+            const plan = parsePlan((deps.readStdin ?? readAllStdin)(), 'stdin');
+            return { plan, source: '(stdin)', receiptPath, unreadable: false, swept: undefined };
+        }
+        const source = resolve(ctx.cwd, v.plan);
+        const plan = readPlan(source);
+        return {
+            plan,
+            source,
+            receiptPath: receiptPath ?? receiptBeside(source, now),
+            unreadable: false,
+            swept: undefined,
+        };
+    }
+    catch (err) {
+        return failure(ctx, err);
+    }
+}
+/** The run's flags that contradict each other, as a usage message, or null. */
+function applyConflict(v, paths) {
+    if (v.plan !== undefined) {
+        const sweepFlags = [
+            paths.length > 0 ? 'paths' : null,
+            v.only !== undefined ? '--only' : null,
+            v.branch !== undefined ? '--branch' : null,
+            v.remote !== undefined ? '--remote' : null,
+            v.remoteUrl.length > 0 ? '--remote-url' : null,
+        ].filter((f) => f !== null);
+        if (sweepFlags.length > 0)
+            return `--plan fixes what is swept; drop ${sweepFlags.join(', ')}`;
+    }
+    if (v.plan === '-' && !v.yes && !v.dryRun) {
+        return '--plan - reads the plan from stdin, so it cannot ask; pass --yes or --dry-run';
+    }
+    return null;
 }
 function runApply(argv, ctx, deps, status) {
     const name = `${NAME} apply`;
@@ -375,57 +486,50 @@ function runApply(argv, ctx, deps, status) {
             return usageError(ctx, name, err.message);
         throw err;
     }
-    const fromStdin = v.plan === '-';
-    if (v.plan !== undefined) {
-        const sweepFlags = [
-            paths.length > 0 ? 'paths' : null,
-            v.only !== undefined ? '--only' : null,
-            v.branch !== undefined ? '--branch' : null,
-            v.remote !== undefined ? '--remote' : null,
-        ].filter((f) => f !== null);
-        if (sweepFlags.length > 0) {
-            return usageError(ctx, name, `--plan fixes what is swept; drop ${sweepFlags.join(', ')}`);
-        }
-    }
-    if (fromStdin && !v.yes && !v.dryRun) {
-        return usageError(ctx, name, '--plan - reads the plan from stdin, so it cannot ask; pass --yes or --dry-run');
-    }
+    const conflict = applyConflict(v, paths);
+    if (conflict !== null)
+        return usageError(ctx, name, conflict);
     const now = new Date();
-    let plan;
-    let planSource;
-    // A repository the sweep could not read contributes no rows; the run says so and exits 1.
-    let unreadable = false;
-    const ok = () => (unreadable ? EXIT.error : EXIT.ok);
-    let receiptPath = v.receipt === undefined ? null : resolve(ctx.cwd, v.receipt);
-    if (v.plan === undefined) {
-        const swept = sweep(name, v, paths, ctx, (r) => (v.output === 'json' ? renderJson(r) : renderText(r)), status);
-        if (!swept.ok)
-            return swept.code;
-        unreadable = reportUnreadable(ctx, name, swept.result);
-        plan = planOf(swept, now);
-        planSource = '(swept)';
-    }
-    else {
-        try {
-            if (fromStdin) {
-                plan = parsePlan((deps.readStdin ?? readAllStdin)(), 'stdin');
-                planSource = '(stdin)';
-            }
-            else {
-                planSource = resolve(ctx.cwd, v.plan);
-                plan = readPlan(planSource);
-                receiptPath ??= receiptBeside(planSource, now);
-            }
-        }
-        catch (err) {
-            return failure(ctx, err);
-        }
+    const loaded = loadPlan(name, v, paths, ctx, deps, status, now);
+    if (typeof loaded === 'number')
+        return loaded;
+    const { plan, source, receiptPath } = loaded;
+    // A plan from `--remote-url` names a clone in the cache. Its deletes are
+    // pushed from there, so the clone must still push only where it fetches from.
+    const cacheDir = mirrorCache(ctx);
+    const cache = (existsSync(cacheDir) ? realpathSync(cacheDir) : cacheDir) + sep;
+    for (const repo of plan.repos) {
+        if (!repo.root.startsWith(cache))
+            continue;
+        const problem = mirrorProblem(repo.root);
+        if (problem !== null)
+            return failure(ctx, new Error(`${problem}; refusing to apply`));
     }
+    const ok = () => (loaded.unreadable ? EXIT.error : EXIT.ok);
     const repoRoot = v.repoRoot === undefined ? undefined : resolve(ctx.cwd, v.repoRoot);
+    const print = (receipt, shownPath) => {
+        ctx.io.stdout(v.output === 'json'
+            ? `${JSON.stringify({ receiptPath: shownPath, summary: summarizeReceipt(receipt), receipt }, null, 2)}\n`
+            : renderReceipt(receipt, shownPath));
+    };
+    const planned = plan.repos.filter((r) => repoRoot === undefined || resolve(r.root) === resolve(repoRoot));
+    if (repoRoot !== undefined && planned.length === 0) {
+        return failure(ctx, new Error(`no plan repository at ${repoRoot}`));
+    }
+    if (rows.length === 0 && planned.every((r) => r.rows.length === 0)) {
+        if (v.output === 'json')
+            print(emptyReceipt(source, now, v.dryRun), null);
+        else
+            ctx.io.stdout('nothing to delete\n');
+        return ok();
+    }
     const base = {
         callerCwd: ctx.cwd,
-        planPath: planSource,
+        planPath: source,
         repoRoot,
+        // An implicit selection runs only safe-to-delete rows, in the preview and
+        // in the run it confirms, whose rows are passed explicitly.
+        safeOnly: rows.length === 0,
         ...(v.progress
             ? {
                 onSweepProgress: (p) => status.update(`re-checking ${describeSweep(p)}`),
@@ -433,25 +537,17 @@ function runApply(argv, ctx, deps, status) {
             }
             : {}),
     };
-    const print = (receipt, shownPath) => {
-        ctx.io.stdout(v.output === 'json'
-            ? `${JSON.stringify({ receiptPath: shownPath, receipt }, null, 2)}\n`
-            : renderReceipt(receipt, shownPath));
-    };
     let preview;
     try {
-        preview = applyPlan(plan, rows, grants, { ...base, dryRun: true, receiptPath: null });
+        // A sweep that just ran is the preview's re-check; the run that deletes sweeps again.
+        preview = applyPlan(plan, rows, grants, {
+            ...base,
+            dryRun: true,
+            receiptPath: null,
+            swept: loaded.swept,
+        });
     }
     catch (err) {
-        if (err instanceof ApplyArgumentError) {
-            if (rows.length === 0 && plan.repos.every((r) => r.rows.length === 0)) {
-                if (v.output === 'json')
-                    print(emptyReceipt(planSource, now), null);
-                else
-                    ctx.io.stdout('nothing to delete\n');
-                return ok();
-            }
-        }
         return failure(ctx, err);
     }
     const count = wouldRun(preview);
@@ -460,17 +556,9 @@ function runApply(argv, ctx, deps, status) {
         return ok();
     }
     if (!v.yes) {
-        // The preview is for the person answering, so it goes where the question does.
-        const show = v.output === 'json' ? ctx.io.stderr : ctx.io.stdout;
-        show(renderReceipt(preview, null));
-        const answer = (deps.confirm ?? terminalConfirm)(`Delete ${count} item${count === 1 ? '' : 's'}?`);
-        if (answer === null) {
-            return usageError(ctx, name, 'refusing to delete without a terminal to ask; pass --yes');
-        }
-        if (!answer) {
-            ctx.io.stderr('nothing deleted\n');
-            return EXIT.ok;
-        }
+        const declined = confirm(ctx, name, preview, count, v.output === 'json', deps);
+        if (declined !== null)
+            return declined;
     }
     // Only what the preview showed: rows it dropped stay dropped.
     // Pinned to their repositories: a branch name two repositories share stays two rows.
@@ -489,14 +577,35 @@ function runApply(argv, ctx, deps, status) {
         return failure(ctx, err);
     }
     print(receipt, receiptPath);
+    if (receiptPath === null) {
+        ctx.io.stderr(`${name}: no receipt written; pass --receipt <file> to keep one\n`);
+    }
     return receipt.status === 'failed' ? EXIT_STEP_FAILED : ok();
 }
-function emptyReceipt(plan, now) {
+/**
+ * Show the preview and ask. Null to go ahead; otherwise the exit code: 0 for
+ * a no, 2 when there is no one to ask.
+ */
+function confirm(ctx, name, preview, count, json, deps) {
+    // The preview is for the person answering, so it goes where the question does.
+    const show = json ? ctx.io.stderr : ctx.io.stdout;
+    show(renderReceipt(preview, null));
+    const answer = (deps.confirm ?? terminalConfirm)(`Delete ${count} item${count === 1 ? '' : 's'}?`);
+    if (answer === null) {
+        return usageError(ctx, name, 'refusing to delete without a terminal to ask; pass --yes');
+    }
+    if (!answer) {
+        ctx.io.stderr('nothing deleted\n');
+        return EXIT.ok;
+    }
+    return null;
+}
+function emptyReceipt(plan, now, dryRun) {
     const at = now.toISOString();
     return {
-        version: 1,
+        version: RECEIPT_VERSION,
         plan,
-        status: 'dry-run',
+        status: dryRun ? 'dry-run' : 'complete',
         started_at: at,
         finished_at: at,
         dropped: [],

package/dist/index.d.ts

@@ -21,10 +21,10 @@ export { assessLanding, patchEquivalent, type Landing, type LandingCheck } from
 export { ApplyArgumentError, applyPlan, type RowSelection, parseGrant, parseRowRef, type ApplyOptions, type Grant, } from './apply.ts';
 export type { Annotate, HostHooks } from './hooks.ts';
 export { PLAN_VERSION, PlanReadError, planRepo, parsePlan, readPlan, writePlan, type Plan, type PlanRepo, type PlannableRow, } from './plan.ts';
-export { ReceiptSchema, type Dropped, type Receipt, type RowRef, type Step } from './receipt.ts';
+export { RECEIPT_VERSION, ReceiptSchema, type Dropped, type Receipt, type RowRef, type Step, } from './receipt.ts';
 export { defaultProcessProbe, isIdleShell, parseLockOwner, parseLsofCwd, type DefaultProbeOptions, type LockOwner, type ProcessHolder, type ProcessProbe, } from './processes.ts';
 export { fetchPrs } from './prs.ts';
 export { expandTilde, isCheckoutRoot, resolveEntries, type Resolution, type ResolveOptions, } from './resolve.ts';
 export { sweepRepo, sweepRepos, type SweepOptions, type SweepReposOptions } from './sweep.ts';
-export { proposedCommands, renderJson, renderReceipt, renderRepo, renderScan, renderSummary, renderText, requiresNote, } from './render.ts';
+export { proposedCommands, renderJson, renderApplySummary, renderReceipt, summarizeReceipt, type ApplySummary, renderRepo, renderScan, renderSummary, renderText, requiresNote, } from './render.ts';
 export { ALL_SCOPES, AUTHORIZATIONS, authorizationsFor, emptyBucket, emptyScan, findDuplicateCheckouts, isUnfetched, makeItem, summarize, type Authorization, type Category, type Classification, type DuplicateCheckout, type PRInfo, type RepoInfo, type RepoSweep, type ScanStats, type Scope, type SummaryBucket, type SweepItem, type SweepProgress, type SweepResult, type UnresolvedEntry, } from './types.ts';

package/dist/index.js

@@ -20,10 +20,10 @@ export { DiscoveryFailed, discoverRepo } from "./discover.js";
 export { assessLanding, patchEquivalent } from "./landing.js";
 export { ApplyArgumentError, applyPlan, parseGrant, parseRowRef, } from "./apply.js";
 export { PLAN_VERSION, PlanReadError, planRepo, parsePlan, readPlan, writePlan, } from "./plan.js";
-export { ReceiptSchema } from "./receipt.js";
+export { RECEIPT_VERSION, ReceiptSchema, } from "./receipt.js";
 export { defaultProcessProbe, isIdleShell, parseLockOwner, parseLsofCwd, } from "./processes.js";
 export { fetchPrs } from "./prs.js";
 export { expandTilde, isCheckoutRoot, resolveEntries, } from "./resolve.js";
 export { sweepRepo, sweepRepos } from "./sweep.js";
-export { proposedCommands, renderJson, renderReceipt, renderRepo, renderScan, renderSummary, renderText, requiresNote, } from "./render.js";
+export { proposedCommands, renderJson, renderApplySummary, renderReceipt, summarizeReceipt, renderRepo, renderScan, renderSummary, renderText, requiresNote, } from "./render.js";
 export { ALL_SCOPES, AUTHORIZATIONS, authorizationsFor, emptyBucket, emptyScan, findDuplicateCheckouts, isUnfetched, makeItem, summarize, } from "./types.js";

package/dist/receipt.d.ts

@@ -1,5 +1,7 @@
 /** What `applyPlan` did, step by step, rewritten after every step. */
 import { z } from 'zod';
+/** The receipt format's version, written into every receipt. */
+export declare const RECEIPT_VERSION = 1;
 export declare const RowRefSchema: z.ZodObject<{
     category: z.ZodEnum<{
         local_branch: "local_branch";
@@ -23,6 +25,7 @@ export declare const DroppedSchema: z.ZodObject<{
         "needs-review": "needs-review";
         "facts-changed": "facts-changed";
         "not-authorized": "not-authorized";
+        duplicate: "duplicate";
     }>;
     detail: z.ZodString;
 }, z.core.$strip>;
@@ -81,6 +84,7 @@ export declare const ReceiptSchema: z.ZodObject<{
             "needs-review": "needs-review";
             "facts-changed": "facts-changed";
             "not-authorized": "not-authorized";
+            duplicate: "duplicate";
         }>;
         detail: z.ZodString;
     }, z.core.$strip>>;

package/dist/receipt.js

@@ -1,10 +1,19 @@
 /** What `applyPlan` did, step by step, rewritten after every step. */
 import { z } from 'zod';
 import { PLAN_CATEGORIES } from "./plan.js";
+/** The receipt format's version, written into every receipt. */
+export const RECEIPT_VERSION = 1;
 export const RowRefSchema = z.object({ category: z.enum(PLAN_CATEGORIES), id: z.string() });
 export const DroppedSchema = RowRefSchema.extend({
     repo: z.string(),
-    reason: z.enum(['gone', 'not-deletable', 'needs-review', 'facts-changed', 'not-authorized']),
+    reason: z.enum([
+        'gone',
+        'not-deletable',
+        'needs-review',
+        'facts-changed',
+        'not-authorized',
+        'duplicate',
+    ]),
     detail: z.string(),
 });
 export const StepSchema = z.object({
@@ -25,7 +34,7 @@ export const StepSchema = z.object({
     verification: z.string().nullable(),
 });
 export const ReceiptSchema = z.object({
-    version: z.literal(1),
+    version: z.literal(RECEIPT_VERSION),
     plan: z.string(),
     status: z.enum(['dry-run', 'applying', 'complete', 'failed']),
     started_at: z.string(),

package/dist/remote-mirror.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Sweep a remote with no checkout of your own: a clone of it, kept in
+ * repo-cleaner's cache directory, stands in for the checkout.
+ *
+ * The clone is `--no-checkout`, so no files are written outside `.git`. It is
+ * not a partial (`--filter=blob:none`) clone: the patch comparison that
+ * finds squash-merged branches reads file contents, and a partial clone
+ * fetches them over the network one comparison at a time, which made a sweep
+ * of a few hundred branches take minutes instead of seconds. It is kept
+ * rather than thrown away so a plan written from it can be applied later: the
+ * plan names the clone's directory, and `apply` re-sweeps and pushes deletes
+ * from there. A later run reuses it, and the sweep's fetch brings it up to
+ * date.
+ */
+import type { CommandRunner } from '@osdlc/command-seam';
+/** A remote URL that cannot be mirrored, or a mirror that cannot be made or reused. */
+export declare class RemoteMirrorError extends Error {
+    constructor(message: string);
+}
+/**
+ * `text` with every URL's credentials removed: the user-info before `@` in a
+ * `scheme://` URL, and any query string or fragment. For a message or a name
+ * that must not carry a token.
+ */
+export declare function redactUrl(text: string): string;
+/**
+ * The directory name for `url`'s mirror: readable `host-owner-repo`, then a
+ * hash of the whole URL so two URLs never share a mirror. The readable part
+ * is read from the URL with its credentials, query and fragment removed, so a
+ * token never reaches the name.
+ */
+export declare function mirrorName(url: string): string;
+/**
+ * Why `dir` is not a mirror of `url` — or of whatever it was cloned from, when
+ * `url` is omitted — or null when it is. A mirror's `origin` has one fetch URL
+ * and pushes to that URL alone, so a delete cannot be sent elsewhere.
+ */
+export declare function mirrorProblem(dir: string, url?: string, opts?: {
+    git?: CommandRunner | undefined;
+}): string | null;
+/**
+ * The directory of `url`'s mirror under `cacheDir`, cloned on first use. An
+ * existing mirror is reused as it is, once {@link mirrorProblem} finds
+ * nothing wrong with it; the sweep's own fetch brings it up to date. A first
+ * clone goes to a sibling directory and is renamed into place, so a clone
+ * that fails leaves nothing behind, and a run that loses a race to clone the
+ * same URL uses the winner's clone. Messages carry the URL with its
+ * credentials removed.
+ *
+ * @throws RemoteMirrorError when `url` is empty or looks like an option, when
+ *   the clone fails, or when the directory is not a mirror of `url`.
+ */
+export declare function ensureMirror(url: string, cacheDir: string, opts?: {
+    git?: CommandRunner | undefined;
+}): string;