@osdlc/repo-cleaner 0.17.2 → 0.18.0

package/dist/receipt.d.ts

@@ -1,56 +1,53 @@
-/** What `applyPlan` did, step by step, rewritten after every step. */
+/** What a run 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";
-        worktree: "worktree";
-        remote_branch: "remote_branch";
-    }>;
-    id: z.ZodString;
-}, z.core.$strip>;
-export type RowRef = z.infer<typeof RowRefSchema>;
+export declare const RECEIPT_VERSION = 2;
+/**
+ * Why a row did not run:
+ *
+ *   `gone`         no longer in the sweep
+ *   `blocked`      the sweep now finds a blocker
+ *   `keep`         the sweep keeps it for structure; it has no action
+ *   `held`         a branch whose worktree this run does not remove
+ *   `needs-pick`   not judged `delete`; it runs only when picked
+ *   `changed`      its evidence moved since the plan
+ *   `not-allowed`  it carries a risk that was not allowed
+ *   `duplicate`    another checkout of the same remote deletes the same branch
+ *   `spared`       the same remote branch is spared through another checkout
+ */
+export declare const DROP_REASONS: readonly ["gone", "blocked", "keep", "held", "needs-pick", "changed", "not-allowed", "duplicate", "spared"];
+export type DropReason = (typeof DROP_REASONS)[number];
 export declare const DroppedSchema: z.ZodObject<{
-    category: z.ZodEnum<{
-        local_branch: "local_branch";
-        worktree: "worktree";
-        remote_branch: "remote_branch";
-    }>;
-    id: z.ZodString;
     repo: z.ZodString;
+    row: z.ZodCustom<`worktree:${string}` | `branch:${string}` | `remote:${string}`, `worktree:${string}` | `branch:${string}` | `remote:${string}`>;
     reason: z.ZodEnum<{
+        keep: "keep";
+        blocked: "blocked";
         gone: "gone";
-        "not-deletable": "not-deletable";
-        "needs-review": "needs-review";
-        "facts-changed": "facts-changed";
-        "not-authorized": "not-authorized";
+        held: "held";
+        "needs-pick": "needs-pick";
+        changed: "changed";
+        "not-allowed": "not-allowed";
         duplicate: "duplicate";
-        kept: "kept";
+        spared: "spared";
     }>;
     detail: z.ZodString;
 }, z.core.$strip>;
 export type Dropped = z.infer<typeof DroppedSchema>;
+export declare const STEP_ACTIONS: readonly ["verify-remote", "unlock-worktree", "remove-worktree", "delete-branch", "delete-remote", "prune-worktrees"];
 export declare const StepSchema: z.ZodObject<{
     repo: z.ZodString;
-    row: z.ZodNullable<z.ZodObject<{
-        category: z.ZodEnum<{
-            local_branch: "local_branch";
-            worktree: "worktree";
-            remote_branch: "remote_branch";
-        }>;
-        id: z.ZodString;
-    }, z.core.$strip>>;
+    row: z.ZodCustom<`worktree:${string}` | `branch:${string}` | `remote:${string}`, `worktree:${string}` | `branch:${string}` | `remote:${string}`>;
     action: z.ZodEnum<{
         "verify-remote": "verify-remote";
         "unlock-worktree": "unlock-worktree";
         "remove-worktree": "remove-worktree";
-        "delete-local": "delete-local";
+        "delete-branch": "delete-branch";
         "delete-remote": "delete-remote";
         "prune-worktrees": "prune-worktrees";
     }>;
     command: z.ZodString;
-    expected_sha: z.ZodNullable<z.ZodString>;
+    expectedSha: z.ZodNullable<z.ZodString>;
     result: z.ZodEnum<{
         pending: "pending";
         "would-run": "would-run";
@@ -62,55 +59,45 @@ export declare const StepSchema: z.ZodObject<{
 }, z.core.$strip>;
 export type Step = z.infer<typeof StepSchema>;
 export declare const ReceiptSchema: z.ZodObject<{
-    version: z.ZodLiteral<1>;
+    version: z.ZodLiteral<2>;
     plan: z.ZodString;
     status: z.ZodEnum<{
         failed: "failed";
         "dry-run": "dry-run";
-        applying: "applying";
+        running: "running";
         complete: "complete";
     }>;
-    started_at: z.ZodString;
-    finished_at: z.ZodNullable<z.ZodString>;
+    startedAt: z.ZodString;
+    finishedAt: z.ZodNullable<z.ZodString>;
     dropped: z.ZodArray<z.ZodObject<{
-        category: z.ZodEnum<{
-            local_branch: "local_branch";
-            worktree: "worktree";
-            remote_branch: "remote_branch";
-        }>;
-        id: z.ZodString;
         repo: z.ZodString;
+        row: z.ZodCustom<`worktree:${string}` | `branch:${string}` | `remote:${string}`, `worktree:${string}` | `branch:${string}` | `remote:${string}`>;
         reason: z.ZodEnum<{
+            keep: "keep";
+            blocked: "blocked";
             gone: "gone";
-            "not-deletable": "not-deletable";
-            "needs-review": "needs-review";
-            "facts-changed": "facts-changed";
-            "not-authorized": "not-authorized";
+            held: "held";
+            "needs-pick": "needs-pick";
+            changed: "changed";
+            "not-allowed": "not-allowed";
             duplicate: "duplicate";
-            kept: "kept";
+            spared: "spared";
         }>;
         detail: z.ZodString;
     }, z.core.$strip>>;
     steps: z.ZodArray<z.ZodObject<{
         repo: z.ZodString;
-        row: z.ZodNullable<z.ZodObject<{
-            category: z.ZodEnum<{
-                local_branch: "local_branch";
-                worktree: "worktree";
-                remote_branch: "remote_branch";
-            }>;
-            id: z.ZodString;
-        }, z.core.$strip>>;
+        row: z.ZodCustom<`worktree:${string}` | `branch:${string}` | `remote:${string}`, `worktree:${string}` | `branch:${string}` | `remote:${string}`>;
         action: z.ZodEnum<{
             "verify-remote": "verify-remote";
             "unlock-worktree": "unlock-worktree";
             "remove-worktree": "remove-worktree";
-            "delete-local": "delete-local";
+            "delete-branch": "delete-branch";
             "delete-remote": "delete-remote";
             "prune-worktrees": "prune-worktrees";
         }>;
         command: z.ZodString;
-        expected_sha: z.ZodNullable<z.ZodString>;
+        expectedSha: z.ZodNullable<z.ZodString>;
         result: z.ZodEnum<{
             pending: "pending";
             "would-run": "would-run";

package/dist/receipt.js

@@ -1,46 +1,64 @@
-/** What `applyPlan` did, step by step, rewritten after every step. */
+/** What a run did, step by step, rewritten after every step. */
 import { z } from 'zod';
-import { PLAN_CATEGORIES } from "./plan.js";
+import { RowIdSchema } 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({
+export const RECEIPT_VERSION = 2;
+/**
+ * Why a row did not run:
+ *
+ *   `gone`         no longer in the sweep
+ *   `blocked`      the sweep now finds a blocker
+ *   `keep`         the sweep keeps it for structure; it has no action
+ *   `held`         a branch whose worktree this run does not remove
+ *   `needs-pick`   not judged `delete`; it runs only when picked
+ *   `changed`      its evidence moved since the plan
+ *   `not-allowed`  it carries a risk that was not allowed
+ *   `duplicate`    another checkout of the same remote deletes the same branch
+ *   `spared`       the same remote branch is spared through another checkout
+ */
+export const DROP_REASONS = [
+    'gone',
+    'blocked',
+    'keep',
+    'held',
+    'needs-pick',
+    'changed',
+    'not-allowed',
+    'duplicate',
+    'spared',
+];
+export const DroppedSchema = z.object({
     repo: z.string(),
-    reason: z.enum([
-        'gone',
-        'not-deletable',
-        'needs-review',
-        'facts-changed',
-        'not-authorized',
-        'duplicate',
-        'kept',
-    ]),
+    row: RowIdSchema,
+    reason: z.enum(DROP_REASONS),
     detail: z.string(),
 });
+export const STEP_ACTIONS = [
+    'verify-remote',
+    'unlock-worktree',
+    'remove-worktree',
+    'delete-branch',
+    'delete-remote',
+    'prune-worktrees',
+];
 export const StepSchema = z.object({
     repo: z.string(),
-    /** Null for the closing prune, which belongs to no row. */
-    row: RowRefSchema.nullable(),
-    action: z.enum([
-        'verify-remote',
-        'unlock-worktree',
-        'remove-worktree',
-        'delete-local',
-        'delete-remote',
-        'prune-worktrees',
-    ]),
+    /** The row the step acts on. */
+    row: RowIdSchema,
+    action: z.enum(STEP_ACTIONS),
     command: z.string(),
-    expected_sha: z.string().nullable(),
+    expectedSha: z.string().nullable(),
     result: z.enum(['pending', 'would-run', 'ok', 'failed']),
     error: z.string().nullable(),
     verification: z.string().nullable(),
 });
 export const ReceiptSchema = z.object({
     version: z.literal(RECEIPT_VERSION),
+    /** Where the plan came from: a path, `(stdin)`, or `(swept)`. */
     plan: z.string(),
-    status: z.enum(['dry-run', 'applying', 'complete', 'failed']),
-    started_at: z.string(),
-    finished_at: z.string().nullable(),
+    status: z.enum(['dry-run', 'running', 'complete', 'failed']),
+    startedAt: z.string(),
+    finishedAt: z.string().nullable(),
     dropped: z.array(DroppedSchema),
     steps: z.array(StepSchema),
 });

package/dist/reference.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The full reference `--help --extended` prints: what every option means,
+ * the words the report uses, and which combinations are refused. The README
+ * says the same in its own layout; keep the two in step.
+ */
+/** The extended help for each command: its own options, then the shared vocabulary. */
+export declare const REFERENCE: {
+    readonly report: string;
+    readonly plan: string;
+    readonly clean: string;
+    readonly cache: "repo-cleaner cache [list | remove <url>... | remove --all]\n  Lists or removes the clones kept for remote URL targets. A removed clone is\n  cloned again by the next sweep of its URL; a plan that names it cannot run.";
+};

package/dist/reference.js

@@ -0,0 +1,148 @@
+/**
+ * The full reference `--help --extended` prints: what every option means,
+ * the words the report uses, and which combinations are refused. The README
+ * says the same in its own layout; keep the two in step.
+ */
+const TARGETS = `Targets
+  A target is what to sweep:
+    a checkout            that repository; a linked worktree sweeps the repository it belongs to
+    a directory           every checkout found under it, three levels deep at most
+    a remote URL          its remote branches only, through a clone kept in the cache
+                          directory (https://, ssh://, file://, or user@host:path)
+  No target sweeps the checkout you are in. A target never fans out further than
+  it says.`;
+const SWEEP = `Sweep options (the report, plan and clean)
+  --remote                Also judge remote branches. Turns on the network: fetches
+                          each remote first and asks GitHub or GitLab about pull
+                          requests. Slower.
+  --offline               With --remote: do not fetch; judge against the
+                          remote-tracking refs already on disk.
+  --only <kinds>          Only these kinds of row: worktree, branch, remote,
+                          comma-separated. Default: worktree,branch, plus remote with
+                          --remote. Naming remote implies --remote.
+  --branch <name|HEAD>    Only the rows of one branch: its worktree, its local branch,
+                          and its remote branch with --remote. HEAD is the branch
+                          checked out at the target. Never the default branch.
+  --against <remote>      The remote whose default branch counts as "merged into".
+                          Default: origin, then the first remote.
+  --provider <name>       With --remote: where pull requests come from. auto (by the
+                          remote's host), github, gitlab, or none to judge on git
+                          evidence alone.
+  --no-progress           No progress line on stderr.`;
+const REPORT = `The report: repo-cleaner [target...]
+  Deletes nothing. Lists each row with its verdict, why, the risks it carries,
+  and the command that would delete it.
+  --all                   Also show keep rows. By default only delete, review and
+                          blocked rows are listed. Only with --format text.
+  --format text           The report. The default.
+  --format summary        Counts per repository: total, merged, delete, prune,
+                          review, blocked, keep.
+  --format commands       Only the commands of delete rows that carry no risk.
+  --format json           Everything, evidence included, for scripts.`;
+const PLAN = `repo-cleaner plan [target...]
+  Sweeps and saves every row, each with a fingerprint of the evidence behind its
+  verdict, so it can be reviewed now and run later with clean --plan.
+  -o, --out <file>        Where the plan goes; - (the default) is stdout.`;
+const CLEAN = `repo-cleaner clean [target...]
+  Sweeps (or reads --plan), checks every row again, shows the steps, asks, then
+  deletes, compare-and-swap, verifying each step and stopping at the first failure.
+  Without --pick it runs every row judged delete.
+  --pick <row>            Work on exactly these rows. Narrows the run to them, and opts
+                          in review rows and kept rows with an action (an open pull
+                          request), which never run otherwise. A picked row still
+                          needs --allow for its risks. A blocked row is skipped.
+                          Repeatable.
+  --spare <row>           Leave this row alone, and make sure it is what you saw. A
+                          spared row is not deleted, even if it is judged delete. A
+                          spared remote branch is still checked: if it is gone or its
+                          tip moved since the plan, the run stops before deleting
+                          anything. Sparing a worktree also spares its branch.
+                          Repeatable.
+  --allow <risk>          Accept this risk for every row that carries it.
+  --allow <risk>=<row>    Accept it for that one row only.
+  --plan <file|->         Run a saved plan instead of sweeping now (- reads stdin).
+                          Rows whose evidence changed since the plan are dropped.
+  -y, --yes               Do not ask. Without it, and with no terminal to ask on,
+                          clean refuses.
+  --dry-run               Check and show the steps, then stop.
+  --receipt <file>        Write a record of every step, rewritten after each one.
+                          Default: next to a --plan file; none otherwise.
+  --format text|json      How the steps and the outcome are shown.`;
+const CACHE = `repo-cleaner cache [list | remove <url>... | remove --all]
+  Lists or removes the clones kept for remote URL targets. A removed clone is
+  cloned again by the next sweep of its URL; a plan that names it cannot run.`;
+const WORDS = `Rows
+  One thing that could be deleted, named <kind>:<name>:
+    worktree:<path>         a linked worktree: removed with git worktree remove, or,
+                            when its directory is already gone, its record pruned
+    branch:<name>           a local branch, deleted with git update-ref -d <sha>
+    remote:<remote>/<name>  a branch on a remote, deleted by a push with a lease
+  A bare name or path works when only one row has it.
+
+Verdicts
+  delete    Its work is on the default branch, or it is otherwise safe to lose.
+            clean deletes it, once its risks are allowed.
+  review    The signals are mixed, or it holds work. Deleted only when picked and
+            its risks are allowed.
+  blocked   Something rules removal out: a lock, a running process, a submodule
+            that cannot be read, hidden index flags, a nested repository, a branch
+            checked out twice. Never deleted; fix the cause and sweep again.
+  keep      Structural (the default branch, the current checkout, the primary
+            worktree): never deleted. Or in use (an open pull request): deleted
+            only when picked and confirm-open-pr is allowed.
+  prune     Shown for a delete row whose worktree directory is already gone: only
+            the stale record goes.
+
+Risks (approve each by name with --allow)
+  abandon-unmerged   Commits that are not on the default branch, or a worktree's
+                     (or its submodules') commits and stashes that no remote has.
+  discard-changes    Uncommitted or untracked files in the worktree or any of its
+                     submodules.
+  confirm-open-pr    The branch has an open pull request; deleting the remote branch
+                     closes it.
+  A worktree's submodules are part of it: one --allow on the worktree row covers
+  the same risk in every submodule.`;
+const CONFLICTS = `Refused before anything is deleted (exit 2)
+  A combination is refused when it contradicts itself, or when one of its options
+  would have no effect. Most are refused before anything is swept; a row named
+  two ways (a bare name and its id), and an --allow for a row, are checked
+  against the plan, after the sweep.
+    the same row in --pick and --spare
+    --allow <risk>=<row> for a spared row, or for a row outside --pick
+    a picked or spared row of a kind --only leaves out
+    a picked or spared row that is not one of --branch's rows
+    --branch with more than one target, or with a remote URL, or the default branch
+    --plan with targets or sweep options: the plan already fixed them
+    --plan - without --yes or --dry-run: stdin carries the plan, so nothing can ask
+    --yes with --dry-run
+    --receipt with --dry-run
+    --offline or --provider without --remote
+    --remote with an --only that leaves remote out
+    a remote URL target with --only worktree or --only branch, with --offline, or
+      mixed with checkout targets
+    --all with any --format but text
+
+Refused after the sweep, before deleting (exit 1)
+    a picked, spared or allowed row the plan does not have
+    a row name that matches rows in more than one repository
+    a spared remote branch that is gone or moved since the plan
+
+Allowed, because nothing contradicts
+    the same row picked twice: it runs once
+    --allow <risk> with --allow <risk>=<row>: the broader one covers it
+    --allow for a risk no row that runs carries: the preview lists it as unused
+    picking a blocked or keep row: it is skipped and shown with the reason
+    --only remote without --remote: asking for remote branches implies the network`;
+const EXIT = `Exit codes
+  0    swept; or clean ran, was declined, or had nothing to do
+  1    failed against the state it found: an unreadable plan, a row not in it
+  2    cannot run as typed: an unknown flag, a malformed row, a refused combination
+  10   no target named a repository
+  11   clean stopped at a failed step; the receipt says which`;
+/** The extended help for each command: its own options, then the shared vocabulary. */
+export const REFERENCE = {
+    report: [TARGETS, SWEEP, REPORT, WORDS, CONFLICTS, EXIT].join('\n\n'),
+    plan: [TARGETS, SWEEP, PLAN, WORDS, EXIT].join('\n\n'),
+    clean: [TARGETS, SWEEP, CLEAN, WORDS, CONFLICTS, EXIT].join('\n\n'),
+    cache: CACHE,
+};

package/dist/remote-mirror.d.ts

@@ -77,3 +77,11 @@ export declare function listMirrors(cacheDir: string, opts?: {
  * given, credentials included.
  */
 export declare function cachedMirrorOf(url: string, cacheDir: string): string | null;
+/**
+ * True when `target` names a remote rather than a directory: a URL with a
+ * scheme (`https://`, `ssh://`, `file://`), or the scp form `user@host:path`
+ * that names no directory on disk. A Windows drive path is never one.
+ */
+export declare function isRemoteUrl(target: string, exists: (path: string) => boolean): boolean;
+/** Where remote URL targets' clones are kept: `repo-cleaner/remotes` under the user's cache directory. */
+export declare function defaultCacheDir(env?: Record<string, string | undefined>): string;

package/dist/remote-mirror.js

@@ -15,7 +15,9 @@
 import { createHash } from 'node:crypto';
 import { existsSync, lstatSync, mkdirSync, readdirSync, renameSync, rmSync } from 'node:fs';
 import { dirname, join } from 'node:path';
+import { systemDirs } from '@osdlc/cli-tool';
 import { Git, parseRemoteRepo } from '@osdlc/typed-git';
+import { VENDOR_DIRS } from "./devlink.js";
 /** A remote URL that cannot be mirrored, or a mirror that cannot be made or reused. */
 export class RemoteMirrorError extends Error {
     constructor(message) {
@@ -163,3 +165,19 @@ export function cachedMirrorOf(url, cacheDir) {
     const dir = join(cacheDir, mirrorName(url));
     return existsSync(dir) ? dir : null;
 }
+/**
+ * True when `target` names a remote rather than a directory: a URL with a
+ * scheme (`https://`, `ssh://`, `file://`), or the scp form `user@host:path`
+ * that names no directory on disk. A Windows drive path is never one.
+ */
+export function isRemoteUrl(target, exists) {
+    if (/^[a-z][a-z0-9+.-]*:\/\//i.test(target))
+        return true;
+    if (/^[a-z]:[\\/]/i.test(target))
+        return false;
+    return /^(?:[^@/:\\]+@)?[^/:\\]+:(?!\/\/).+$/.test(target) && !exists(target);
+}
+/** Where remote URL targets' clones are kept: `repo-cleaner/remotes` under the user's cache directory. */
+export function defaultCacheDir(env = process.env) {
+    return systemDirs(VENDOR_DIRS, { env }).standalone('repo-cleaner').cache().app('remotes').path;
+}

package/dist/render.d.ts

@@ -1,13 +1,14 @@
 /**
- * Rendering a sweep for a terminal, and for a program.
+ * Rendering a sweep and a run, for a terminal and for a program.
  *
  * The text report is columnar because it is read by eye across repositories:
- * the eye finds a column, and a line-per-item paragraph gives it nothing to
- * find. JSON carries everything the text report elides, including the facts
- * behind every verdict.
+ * the eye finds a column, and a line-per-row paragraph gives it nothing to
+ * find. JSON carries everything the text report leaves out, the evidence
+ * behind every verdict included.
  */
-import type { Receipt, Step } from './receipt.ts';
-import { type RepoSweep, type SweepItem, type SweepResult } from './types.ts';
+import type { Preview } from './clean.ts';
+import type { Dropped, Receipt, Step } from './receipt.ts';
+import { type Kind, type RepoSweep, type Sweep } from './types.ts';
 /**
  * How a report colors its words. {@link PLAIN} leaves them as they are; the
  * CLI passes {@link TERMINAL_STYLE} when the stream is a terminal that takes
@@ -31,57 +32,38 @@ export interface Style {
 export declare const PLAIN: Style;
 /** The basic terminal colors: red to delete, blue to prune, yellow to review, green to keep. */
 export declare const TERMINAL_STYLE: Style;
-/**
- * A row's authorizations for a report, e.g. `requires abandon-unmerged (drops 3
- * commits), confirm-open-pr`. Empty when the row needs none.
- */
-export declare function requiresNote(item: Pick<SweepItem, 'requires' | 'facts'>): string;
-/** One repository's rows, indented under its header. */
+/** One repository's rows, indented under its header. `all` shows `keep` rows too. */
 export declare function renderRepo(sweep: RepoSweep, opts?: {
-    keep?: boolean;
+    all?: boolean;
     style?: Style;
 }): string;
 /**
- * What the search cost, or null when nothing was searched — every entry
+ * What the search cost, or null when nothing was searched — every target
  * named a checkout outright.
  *
- * Worth a line because the numbers are how a person catches an entry
+ * Worth a line because the numbers are how a person catches a target
  * pointing at the wrong directory: thousands of directories read for three
- * repositories says the entry is a home directory, not a workspace.
+ * repositories says the target is a home directory, not a workspace.
  */
-export declare function renderScan(result: SweepResult): string | null;
+export declare function renderScan(sweep: Pick<Sweep, 'scan'>): string | null;
 /** The one-line verdict a person reads first, and often only. */
-export declare function renderSummary(result: SweepResult, style?: Style): string;
-/**
- * One repository as counts: a row per category with its total, how many are
- * merged, and how many the sweep would delete, prune, review or keep.
- */
-export declare function renderCounts(sweep: RepoSweep): string;
-/** The whole run as counts: a table per repository, then the one-line summary. */
-export declare function renderCountsText(result: SweepResult, style?: Style): string;
-/** The whole run's counts as JSON: no rows, no facts. */
-export declare function renderCountsJson(result: SweepResult): string;
-/** The whole run as text: duplicate checkouts, a section per repository, then the summary. */
-export declare function renderText(result: SweepResult, opts?: {
-    keep?: boolean;
+export declare function renderTotals(sweep: Sweep, style?: Style): string;
+/** The sweep as counts (`--format summary`): a table per repository, then the totals line. */
+export declare function renderSummary(sweep: Sweep, style?: Style): string;
+/** The sweep as text: duplicate checkouts, a section per repository, then the totals. */
+export declare function renderText(sweep: Sweep, opts?: {
+    all?: boolean;
     style?: Style;
 }): string;
-/**
- * The whole run as JSON, facts included. `extra` adds top-level keys, such as
- * the path of a plan the run wrote.
- */
-export declare function renderJson(result: SweepResult, extra?: Record<string, unknown>): string;
-/** Every command a `safe-to-delete` row that needs no authorization proposes, in report order. */
-export declare function proposedCommands(result: SweepResult): string[];
-/** What an apply run did, or would do, counted by kind. */
-export interface ApplySummary {
-    /** Rows deleted (or, in a dry run, that would be), by category. Pruned worktrees are not counted here. */
-    deleted: {
-        worktree: number;
-        local_branch: number;
-        remote_branch: number;
-    };
-    /** Worktrees whose stale registration was pruned; their directories were gone or left alone. */
+/** The sweep as JSON: every row with its evidence, the counts, and what was swept. */
+export declare function renderJson(sweep: Sweep, extra?: Record<string, unknown>): string;
+/** Every command of a `delete` row that carries no risk, in report order (`--format commands`). */
+export declare function renderCommands(sweep: Sweep): string[];
+/** What a run did, or would do, counted by kind. */
+export interface RunSummary {
+    /** Rows deleted (or, in a preview, that would be), by kind. Pruned worktrees are counted apart. */
+    deleted: Record<Kind, number>;
+    /** Worktrees whose stale record was pruned; their directories were gone or left alone. */
     pruned: number;
     /** Dropped rows by reason. */
     dropped: Record<string, number>;
@@ -90,29 +72,47 @@ export interface ApplySummary {
     /** Row steps never reached because a step failed. */
     notRun: number;
 }
-/** Count a receipt's outcome. A dry run's `would-run` steps count as done. */
-export declare function summarizeReceipt(receipt: Receipt): ApplySummary;
-/** Rows a receipt deletes or prunes, which is what a person is asked to approve. */
-export declare function rowsActedOn(summary: ApplySummary): number;
-/** The closing lines of an apply run: what it deleted, skipped and could not finish. */
-export declare function renderApplySummary(receipt: Receipt): string[];
+/** Count what `steps` did and `dropped` left out. A preview's `would-run` steps count as done. */
+export declare function summarizeRun(r: {
+    steps: readonly Step[];
+    dropped: readonly Dropped[];
+}): RunSummary;
+/** Rows a run deletes or prunes, which is what a person is asked to approve. */
+export declare function rowsActedOn(summary: RunSummary): number;
+/** The closing lines of a run or preview: what it deleted, skipped and could not finish. */
+export declare function renderRunSummary(r: {
+    steps: readonly Step[];
+    dropped: readonly Dropped[];
+}, opts?: {
+    preview?: boolean;
+}): string[];
 /** The word a preview shows for a step: what it does to the row. */
 export declare const STEP_VERB: Record<Step['action'], string>;
 /**
- * What `apply` is about to do, for the person asked to approve it: per
- * repository, each row and the command that deletes it, the rows it will
- * skip and why, then the counts. Terminal controls are stripped from what it
- * shows, so a path or name cannot hide part of what is approved.
+ * What a run is about to do, for the person asked to approve it: per
+ * repository, each row and the command that deletes it, the rows it will skip
+ * and why, the allows no row needed, then the counts. Terminal controls are
+ * stripped from what it shows, so a path or name cannot hide part of what is
+ * approved.
  */
-export declare function renderPreview(receipt: Receipt, style?: Style): string;
-/** Rows dropped by a live run's own re-check, after the preview: each with why. */
-export declare function renderPreviewDrops(dropped: Receipt['dropped'], style?: Style): string;
+export declare function renderPreview(p: Pick<Preview, 'steps' | 'dropped'> & Partial<Pick<Preview, 'unusedAllows'>>, style?: Style): string;
+/** Rows dropped by a run's own re-check after the preview, each with why. */
+export declare function renderLateDrops(dropped: readonly Dropped[], style?: Style): string;
 /**
  * A failed step for a run shown live: `✗`, the row, and the error in full,
- * which the step's row on the board is too narrow to hold.
+ * which the step's line on the board is too narrow to hold.
  */
 export declare function renderStepFailure(step: Step, style?: Style): string;
-/** An apply run as text: dropped rows, each step, a summary, then where the receipt is. */
+/** A run as text: dropped rows, each step, a summary, then where the receipt is. */
 export declare function renderReceipt(receipt: Receipt, receiptPath: string | null, style?: Style, opts?: {
     steps?: boolean;
 }): string;
+/** The renderers a library user needs: the CLI's own formats. */
+export declare const render: {
+    text: typeof renderText;
+    json: typeof renderJson;
+    summary: typeof renderSummary;
+    commands: typeof renderCommands;
+    preview: typeof renderPreview;
+    receipt: typeof renderReceipt;
+};