@osdlc/repo-cleaner 0.9.1 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,50 @@
 # @osdlc/repo-cleaner
 
+## 0.10.0
+
+### Minor Changes
+
+- 6e4284b: **Breaking:** repo-cleaner no longer reads a config file. It sweeps the repository you are in, or the paths you pass, which can be directories holding checkouts. `--all` and `--config` are removed: pass the directories instead (`repo-cleaner ~/Developer ~/work`), or keep them in a shell alias. Removed from the library: `CONFIG_ENV`, `DEFAULT_CONFIG`, `RepoCleanerConfigSchema`, `TOOL`, `clearConfigCache`, `configPath`, `configuredRepos`, `loadConfig` and `RepoCleanerConfig`. `REPO_CLEANER_MACHINE_CONFIG` is no longer read. The package no longer depends on `@osdlc/config-layers`.
+- 6e4284b: A status line on stderr while a run works: which repository (`[2/5]` in a run of several), and which step — reading the repository, fetching, listing pull requests (gh), checking worktrees, local or remote branches with a count (`37/427`) — and, in `apply`, the re-check and each delete step. It is drawn only when stderr is a terminal, erased before any other output, and turned off with `--no-progress`.
+  
+  Library: `SweepOptions.onProgress` receives a `SweepProgress` before each step and each item; `ApplyOptions.onSweepProgress` and `onStep` do the same for `applyPlan`.
+- 6e4284b: New `repo-cleaner summary`: a table per repository counting local branches, worktrees and remote branches, with how many are merged into the default branch and how many the sweep would delete, review or keep. `--output json` gives the counts without the rows.
+  
+  Each row now records `facts.merged`: true when its work is on the default branch by ancestry, an exact-head merged PR or a patch match. A branch checked out in a worktree, or at HEAD, is judged by ancestry or PR alone. The default branch and the primary or current worktree carry none. `SummaryBucket` gains `merged`, so the JSON report's `summary` counts it too.
+- 6e4284b: **Breaking:** the CLI is three commands over one set of sweep options, and `apply` asks before it deletes.
+  
+  - `repo-cleaner [status]` is the report, as before.
+  - `repo-cleaner plan` writes the plan to stdout, or to a file with `-o <file>`. It replaces `--write-plan` and `--plan-out`. Plans no longer go to a hidden directory by default.
+  - `repo-cleaner apply` sweeps and plans in memory, or reads `--plan <file>` (`-` reads stdin). With no `--row` it applies every row the re-check judges `safe-to-delete`, and drops a row to review with the new reason `needs-review`; name a review row with `--row` to apply it. It re-checks each row, prints the steps and asks `Delete N items? [y/N]`. `--yes` (`-y`) skips the question. With no terminal and no `--yes` it refuses with exit 2. `--plan -` needs `--yes` or `--dry-run`. On yes it runs only the steps it showed.
+  - `--only worktrees,branches,remotes` replaces `--scope local-branches,worktrees,remote-branches`, and works on every command.
+  - `--allow <risk>[=<category>:<id>]` replaces `--authorize`.
+  - Receipts go beside a `--plan` file as `<plan>.receipt-<timestamp>.json`, or to `--receipt <file>`. `--receipt-dir` and the default receipts directory are removed. A run that swept, or read stdin, writes a receipt only with `--receipt`.
+  
+  Library: `applyPlan` with an empty row list selects every row of the plan and drops each one not judged `safe-to-delete` (`needs-review`), and `receiptPath` may be `null` to write no receipt. New `parsePlan(text, source)`. `stampedPath` is removed; use `fileStamp`.
+
+### Patch Changes
+
+- 6e4284b: A registered worktree whose directory still exists but whose `.git` is gone (git lists it as prunable) no longer makes the whole repository unreadable with `git status: This is not a git repository`. It is a `safe-to-delete` row whose command is `git worktree prune`, which drops the registration and leaves the directory; `facts.directory_left` is true.
+- 6e4284b: `apply` fixes: a branch name two repositories share applies in both instead of failing as ambiguous; a repository the sweep could not read (such as a failed fetch) is named on stderr and exits 1 instead of reading as "nothing to delete", and `plan` does the same; the receipt file records the rows the preview dropped; a worktree's fingerprint includes `on_disk`, so a prune row whose directory came back is dropped rather than removed. The status line strips terminal controls from paths and fits wide characters to the terminal's width. A worktree's `facts.merged` counts a patch match the same way a branch's does.
+  
+  Library: `applyPlan` takes `RowSelection` rows (a row with an optional `repo`) and `ApplyOptions.dropped`.
+
+## 0.9.3
+
+### Patch Changes
+
+- e0aaba5: A remote branch delete the remote refuses now fails its step with git's reason and what it means, such as `[remote rejected] (pre-receive hook declined): A hook on the remote refused the push.`, read from typed-git's per-ref push report instead of stderr.
+- Updated dependencies [e0aaba5]
+  - @osdlc/typed-git@0.12.0
+  - @osdlc/typed-gh@0.14.1
+
+## 0.9.2
+
+### Patch Changes
+
+- Updated dependencies [c58f58b]
+  - @osdlc/typed-gh@0.14.0
+
 ## 0.9.1
 
 ### Patch Changes

package/README.md

@@ -7,9 +7,9 @@ remote branches, classifying each as `safe-to-delete`, `safe-to-keep` or
 `needs-investigation` — with the evidence behind the verdict and the literal
 command that would act on it.
 
-The sweep never deletes anything. It emits commands, and can write the
-deletable rows as a plan. `repo-cleaner apply` deletes the plan rows you
-select, after checking each one again.
+`repo-cleaner` (or `repo-cleaner status`) never deletes anything. It prints
+the commands that would. `repo-cleaner apply` deletes: it checks each row
+again, shows you the steps and asks before it runs them.
 
 ```console
 $ repo-cleaner
@@ -201,13 +201,40 @@ approves them by name:
 A row kept for structure (default branch, current HEAD, a branch held by a
 worktree, the primary or caller's worktree) has `deletable: false`.
 
+## Commands
+
+```bash
+repo-cleaner [status]   # the report: what is merged, what can go (the default)
+repo-cleaner summary    # counts per repository: total, merged, delete, review, keep
+repo-cleaner plan       # the deletable rows as a plan, to stdout or -o <file>
+repo-cleaner apply      # re-check, show the steps, ask, delete
+```
+
+All four take the same paths and sweep options.
+
+```console
+$ repo-cleaner summary
+/Users/me/work/api  (acme/api, default main, origin)
+                   total  merged  delete  review   keep
+  local branches      12       8       6       1      5
+  worktrees            4       3       2       1      1
+  remote branches     40      31      30       6      4
+
+38 to delete, 8 to review, across 1 repository.
+```
+
+`merged` counts rows whose work is on the default branch: by ancestry, by a
+merged PR at the branch's head, or by a patch match. A branch checked out in a
+worktree counts as merged by ancestry or PR alone. The default branch and the
+primary worktree are counted in `total` but not judged. Each row's verdict is
+in its `facts.merged`.
+
 ## Scope is opt-in
 
 ```bash
 repo-cleaner                        # the repository you are standing in
 repo-cleaner ~/work/api ~/work/web  # named repositories
 repo-cleaner ~/Developer            # every checkout under it
-repo-cleaner --all                  # every repository in the config file
 ```
 
 A bare invocation never fans out. What an argument names is read off the disk
@@ -233,88 +260,74 @@ one that says which it could not find.
 
 ## Options
 
+Every command that sweeps takes these:
+
 | Flag | Effect |
 | --- | --- |
-| `--all` | Sweep the repositories named in the config file |
-| `--config <path>` | Config file to read |
-| `--scope <list>` | `local-branches`, `worktrees`, `remote-branches` |
+| `--only <list>` | `worktrees`, `branches`, `remotes` (default: all three) |
+| `--branch <name\|HEAD>` | One branch of this repository: its worktree, local and remote branch. Refuses the default branch |
 | `--remote <name>` | Remote to measure against (default `origin`) |
 | `--no-gh` | Classify on git evidence alone |
 | `--no-fetch` | Skip the fetch; the header then says `not fetched` |
+
+`status` also takes:
+
+| Flag | Effect |
+| --- | --- |
 | `--keep` | Include `safe-to-keep` rows in the report |
 | `--commands` | Print the proposed commands of rows that need no authorization, and nothing else |
 | `--output json` | The full inventory, facts included |
-| `--branch <name\|HEAD>` | Sweep one branch of this repository: its worktree, local and remote branch. Refuses the default branch |
-| `--write-plan` | Write the deletable rows as a plan for `apply` |
-| `--plan-out <path>` | Write the plan here; implies `--write-plan` |
-| `--version` | Print `repo-cleaner <version>` and exit; it must be the first argument |
 
-A checkout directory named `apply` is swept as `./apply`, and one named `dev` as
-`./dev`: `dev` runs the tool from a checkout (see Running from a checkout).
+`--version` prints `repo-cleaner <version>` and exits; it must be the first
+argument. A checkout directory named like a command (`status`, `summary`,
+`plan`, `apply`, `dev`) is swept as `./status` and so on: `dev` runs the tool from a
+checkout (see Running from a checkout).
 
 ## Plan and apply
 
 ```bash
-repo-cleaner --branch HEAD --plan-out plan.json
-repo-cleaner apply --plan plan.json --row worktree:/path/to/wt --row local_branch:feat/x
+repo-cleaner apply                          # sweep, show the steps, ask, delete
+repo-cleaner apply --only worktrees --yes   # no question
+repo-cleaner plan -o plan.json              # save the plan to review or edit
+repo-cleaner apply --plan plan.json --row local_branch:feat/x
+repo-cleaner plan | repo-cleaner apply --plan - --yes
 ```
 
 A plan holds each deletable row with a fingerprint of the facts behind its
-verdict. `apply` sweeps again and drops a selected row that is gone, no longer
-deletable, whose facts moved, or whose `requires` was not granted with
-`--authorize <name>` (every row) or `--authorize <name>=<category>:<id>` (one
-row). It then removes worktrees, deletes local branches, deletes remote
-branches and prunes, in that order. Branch deletes are compare-and-swap, every
-step is verified, and the first failure stops the run.
-
-A receipt records every step and is rewritten after each one. Plans and receipts go under
-`repo-cleaner/plans/` and `repo-cleaner/receipts/` in
-[`@osdlc/tiered-dirs`](https://www.npmjs.com/package/@osdlc/tiered-dirs)' standalone durable home
-(`repo-cleaner` directory, `REPO_CLEANER_*` override variables), unless `--plan-out` or `--receipt-dir` says
-otherwise. `--dry-run` checks again and prints the steps without writing anything.
+verdict. `apply` either sweeps and plans in memory, or reads a plan with
+`--plan <file>` (`-` reads stdin). With no `--row` it applies every row judged
+`safe-to-delete` and drops each row to review as `needs-review`. Name a row
+with `--row <category>:<id>` to apply it, review rows included.
+
+Before it deletes anything, `apply` sweeps again and drops a row that is gone,
+no longer deletable, whose facts moved, or that carries a risk you did not
+accept with `--allow <risk>` (every row) or `--allow <risk>=<category>:<id>`
+(one row). It prints the steps it would run and asks `Delete N items? [y/N]`.
+`--yes` skips the question. With no terminal to ask on and no `--yes`, it
+refuses with exit 2 rather than deleting. `--plan -` needs `--yes` or
+`--dry-run`, because stdin carries the plan. `--dry-run` prints the steps and
+stops.
+
+On yes it runs only the steps it showed: worktrees first, then local branches,
+remote branches and a prune, in that order. Branch deletes are
+compare-and-swap, every step is verified, and the first failure stops the run.
+
+A receipt records every step and is rewritten after each one. With
+`--plan plan.json` it goes beside the plan, as
+`plan.receipt-<timestamp>.json`. `--receipt <file>` puts it anywhere. A run
+that swept, or read its plan from stdin, writes a receipt only when
+`--receipt` names one; the printed steps are its record.
 
 ## Exit codes
 
 | Code | Meaning |
 | --- | --- |
-| `0` | Swept; or every selected row was applied or dropped with a reason |
-| `1` | Failed against the state it found: a `{name}` token nothing defines, an unreadable plan, a row not in the plan |
-| `2` | Cannot run as typed: an unknown flag, a malformed `--row`, `--branch` with `--all` or a path |
+| `0` | Swept; or `apply` ran, was declined, or had nothing to run |
+| `1` | Failed against the state it found: an unreadable plan, a row not in the plan |
+| `2` | Cannot run as typed: an unknown flag, a malformed `--row`, `--branch` with a path, `apply` with nobody to ask and no `--yes` |
 | `10` | Nothing to sweep: no entry named a repository |
 | `11` | `apply` stopped at a failed step; the receipt says which |
 
-## Configuration
-
-Only the CLI reads a config file. The library takes repositories as an
-argument, so a host that already knows where its repositories are passes them
-in.
-
-```yaml
-paths:
-  dev: ~/Developer
-repos:
-  - '{dev}'
-  - ~/work/api
-```
-
-`paths:` names a directory once; any `repos:` entry then refers to it as
-`{name}`. A token nothing defines is an error, not an empty path.
-
-The file is [`@osdlc/config-layers`](https://www.npmjs.com/package/@osdlc/config-layers)'s machine config — `config.yaml` in the host
-OS's config home, resolved through
-[`@osdlc/tiered-dirs`](https://www.npmjs.com/package/@osdlc/tiered-dirs)' standalone tier (`repo-cleaner`
-directory, `REPO_CLEANER_*` override variables):
-
-| OS | Path |
-| --- | --- |
-| macOS | `~/Library/Application Support/repo-cleaner/config.yaml` |
-| Linux and other | `$XDG_CONFIG_HOME/repo-cleaner/config.yaml`, else `~/.config/repo-cleaner/config.yaml` |
-| Windows | `%APPDATA%\repo-cleaner\config.yaml` |
-
-`REPO_CLEANER_MACHINE_CONFIG`, or `--config <path>`, relocates it. A missing,
-unreadable or malformed file degrades to no repositories rather than failing
-the run.
-
 ## As a library
 
 ```ts

package/dist/apply.d.ts

@@ -18,8 +18,8 @@ import type { CommandRunner } from '@osdlc/command-seam';
 import type { HostHooks } from './hooks.ts';
 import { type ProcessProbe } from './processes.ts';
 import { type Plan } from './plan.ts';
-import type { Receipt, RowRef } from './receipt.ts';
-import { type Authorization } from './types.ts';
+import type { Dropped, Receipt, RowRef, Step } from './receipt.ts';
+import { type Authorization, type SweepProgress } from './types.ts';
 /** An authorization the caller gave, for one row or (`row: null`) for all. */
 export interface Grant {
     name: Authorization;
@@ -38,13 +38,19 @@ export interface ApplyOptions extends HostHooks {
     /** The caller's directory; the sweep never offers the worktree holding it. */
     callerCwd: string;
     dryRun: boolean;
-    /** Where the receipt goes. Unused under `dryRun`. */
-    receiptPath: string;
-    /** Shown in the receipt. */
+    /** Where the receipt is written after each step; null writes none. Unused under `dryRun`. */
+    receiptPath: string | null;
+    /** Where the plan came from, shown in the receipt. */
     planPath: string;
     /** Limit the run to the plan repository rooted here. */
     repoRoot?: string | undefined;
     now?: () => Date;
+    /** Rows dropped before this run, such as by a preview; recorded first in the receipt. */
+    dropped?: readonly Dropped[] | undefined;
+    /** Passed to the re-sweep's `onProgress`, for a status line. */
+    onSweepProgress?: ((progress: SweepProgress) => void) | undefined;
+    /** Told before each step runs: its 0-based index, the step count and the step. Not called under `dryRun`. */
+    onStep?: ((index: number, total: number, step: Step) => void) | undefined;
 }
 /** A selection or grant the plan cannot satisfy. Nothing has been touched. */
 export declare class ApplyArgumentError extends Error {
@@ -54,9 +60,20 @@ export declare function parseRowRef(text: string): RowRef;
 /** `<name>` for every row, or `<name>=<category>:<id>` for one. */
 export declare function parseGrant(text: string): Grant;
 /**
- * Apply the `requested` rows of `plan` under `grants`. A row named twice runs once.
+ * A row to apply, optionally pinned to the plan repository rooted at `repo`.
+ * Without `repo`, a row id that two plan repositories share is ambiguous.
+ */
+export type RowSelection = RowRef & {
+    repo?: string;
+};
+/**
+ * Apply the `requested` rows of `plan` under `grants`. An empty `requested`
+ * selects every row of the plan (of `repoRoot`'s repository, when given) and
+ * then drops each one the re-sweep does not judge `safe-to-delete`: a row to
+ * review runs only when it is named. A row named twice runs once. A row whose
+ * `requires` was not granted is dropped, never run.
  *
  * @throws ApplyArgumentError before touching anything, when a row or grant does
  *   not fit the plan.
  */
-export declare function applyPlan(plan: Plan, requested: readonly RowRef[], grants: readonly Grant[], opts: ApplyOptions): Receipt;
+export declare function applyPlan(plan: Plan, requested: readonly RowSelection[], grants: readonly Grant[], opts: ApplyOptions): Receipt;

package/dist/apply.js

@@ -16,7 +16,7 @@
  */
 import { existsSync } from 'node:fs';
 import { resolve } from 'node:path';
-import { CommandFailed, Git } from '@osdlc/typed-git';
+import { CommandFailed, Git, PUSH_REJECTIONS } from '@osdlc/typed-git';
 import { localDeleteCommand, remoteDeleteCommand } from "./branches.js";
 import { busyHolders, defaultProcessProbe, parseLockOwner } from "./processes.js";
 import { PLAN_CATEGORIES, fingerprint, isPlanCategory, sameFingerprint, } from "./plan.js";
@@ -53,6 +53,8 @@ function errorText(err) {
         return err.detail.trim() || err.message;
     return err instanceof Error ? err.message : String(err);
 }
+const sameSelection = (a, b) => sameRow(a, b) &&
+    (a.repo === undefined ? '' : resolve(a.repo)) === (b.repo === undefined ? '' : resolve(b.repo));
 /** Each selected row's plan repository. Unknown and ambiguous rows are errors. */
 function locate(plan, rows, repoRoot) {
     const repos = repoRoot === undefined
@@ -60,8 +62,9 @@ function locate(plan, rows, repoRoot) {
         : plan.repos.filter((r) => resolve(r.root) === resolve(repoRoot));
     if (repos.length === 0)
         throw new ApplyArgumentError(`no plan repository at ${repoRoot}`);
-    return rows.map((ref) => {
-        const hits = repos.filter((r) => r.rows.some((row) => sameRow(row, ref)));
+    return rows.map(({ repo, ...ref }) => {
+        const hits = repos.filter((r) => (repo === undefined || resolve(r.root) === resolve(repo)) &&
+            r.rows.some((row) => sameRow(row, ref)));
         if (hits.length === 0)
             throw new ApplyArgumentError(`row ${label(ref)} is not in the plan`);
         if (hits.length > 1) {
@@ -83,6 +86,7 @@ function resweep(repo, opts) {
         git: opts.git,
         gh: opts.gh,
         probe: opts.probe,
+        onProgress: opts.onSweepProgress,
     });
     if (sweep.repo === null || sweep.error !== null) {
         throw new Error(sweep.error ?? `could not read repository: ${repo.root}`);
@@ -90,7 +94,7 @@ function resweep(repo, opts) {
     return opts.annotate === undefined ? sweep.items : opts.annotate(sweep.repo, sweep.items);
 }
 /** Re-sweep, then split the selection into rows to run and rows dropped. */
-function recheck(selected, grants, opts) {
+function recheck(selected, grants, implicit, opts) {
     const swept = new Map();
     for (const { repo } of selected) {
         if (!swept.has(repo))
@@ -112,6 +116,10 @@ function recheck(selected, grants, opts) {
             drop('not-deletable', item.reason);
             continue;
         }
+        if (implicit && item.classification !== 'safe-to-delete') {
+            drop('needs-review', `${item.reason}; name it with --row to apply it`);
+            continue;
+        }
         const now = fingerprint(item);
         if (!sameFingerprint(planned.fingerprint, now)) {
             drop('facts-changed', `planned ${JSON.stringify(planned.fingerprint)}, now ${JSON.stringify(now)}`);
@@ -234,7 +242,14 @@ function execute(step, row, git, probe) {
         case 'delete-remote': {
             const remote = String(row.item.facts['remote']);
             const ref = `refs/heads/${String(row.item.facts['branch'])}`;
-            at.push(remote, `:${ref}`, { forceWithLease: { ref, expect: step.expected_sha } });
+            const report = at.push(remote, `:${ref}`, {
+                forceWithLease: { ref, expect: step.expected_sha },
+            });
+            const refused = report.refs.find((r) => r.flag === '!');
+            if (refused?.flag === '!') {
+                const why = refused.rawReason === null ? '' : ` (${refused.rawReason})`;
+                throw new Error(`${refused.summary}${why}: ${PUSH_REJECTIONS[refused.rejection].message}`);
+            }
             if (at.lsRemote(remote, ref).some((r) => r.ref === ref)) {
                 throw new Error(`ls-remote still lists ${ref}`);
             }
@@ -243,20 +258,31 @@ function execute(step, row, git, probe) {
     }
 }
 /**
- * Apply the `requested` rows of `plan` under `grants`. A row named twice runs once.
+ * Apply the `requested` rows of `plan` under `grants`. An empty `requested`
+ * selects every row of the plan (of `repoRoot`'s repository, when given) and
+ * then drops each one the re-sweep does not judge `safe-to-delete`: a row to
+ * review runs only when it is named. A row named twice runs once. A row whose
+ * `requires` was not granted is dropped, never run.
  *
  * @throws ApplyArgumentError before touching anything, when a row or grant does
  *   not fit the plan.
  */
 export function applyPlan(plan, requested, grants, opts) {
     const now = opts.now ?? (() => new Date());
-    const rows = requested.filter((row, i) => requested.findIndex((other) => sameRow(other, row)) === i);
+    // Every row of the plan keeps its repository, so a branch name two
+    // repositories share is two rows, not an ambiguity.
+    const wanted = requested.length > 0
+        ? requested
+        : plan.repos
+            .filter((r) => opts.repoRoot === undefined || resolve(r.root) === resolve(opts.repoRoot))
+            .flatMap((r) => r.rows.map((row) => ({ category: row.category, id: row.id, repo: r.root })));
+    const rows = wanted.filter((row, i) => wanted.findIndex((other) => sameSelection(other, row)) === i);
     if (rows.length === 0)
-        throw new ApplyArgumentError('no rows selected');
+        throw new ApplyArgumentError('the plan has no rows to apply');
     const selected = locate(plan, rows, opts.repoRoot);
     for (const grant of grants) {
         if (grant.row !== null && !rows.some((r) => sameRow(r, grant.row))) {
-            throw new ApplyArgumentError(`--authorize names unselected row ${label(grant.row)}`);
+            throw new ApplyArgumentError(`--allow names unselected row ${label(grant.row)}`);
         }
     }
     const receipt = {
@@ -268,8 +294,8 @@ export function applyPlan(plan, requested, grants, opts) {
         dropped: [],
         steps: [],
     };
-    const { accepted, dropped } = recheck(selected, grants, opts);
-    receipt.dropped = dropped;
+    const { accepted, dropped } = recheck(selected, grants, requested.length === 0, opts);
+    receipt.dropped = [...(opts.dropped ?? []), ...dropped];
     const ordered = PLAN_CATEGORIES.flatMap((category) => accepted.filter((row) => row.item.category === category));
     const plannedSteps = ordered.flatMap((row) => stepsFor(row).map((step) => [step, row]));
     for (const repo of new Set(ordered.map((row) => row.repo))) {
@@ -282,14 +308,19 @@ export function applyPlan(plan, requested, grants, opts) {
         receipt.finished_at = now().toISOString();
         return receipt;
     }
-    const save = () => writeJsonAtomic(opts.receiptPath, receipt);
+    const receiptPath = opts.receiptPath;
+    const save = () => {
+        if (receiptPath !== null)
+            writeJsonAtomic(receiptPath, receipt);
+    };
     save();
     const git = new Git(opts.callerCwd, { runner: opts.git });
     const probe = opts.probe ?? defaultProcessProbe();
     // Worktrees whose lock this run cleared. typed-git has no `worktree lock`
     // verb, so a failed remove cannot put the lock back; the receipt says so.
     const unlocked = new Set();
-    for (const [step, row] of plannedSteps) {
+    for (const [i, [step, row]] of plannedSteps.entries()) {
+        opts.onStep?.(i, plannedSteps.length, step);
         try {
             step.verification = execute(step, row, git, probe);
             step.result = 'ok';

package/dist/branches.d.ts

@@ -38,7 +38,7 @@ export declare function resolveBranch(value: string, git: Git): string;
 export declare function localDeleteCommand(name: string, sha: string): string;
 /** Delete `remote`'s branch `name` only while it still points at `sha`. */
 export declare function remoteDeleteCommand(remote: string, name: string, sha: string): string;
-export declare function gatherLocalBranches(repo: RepoInfo, prs: Map<string, PRInfo>, worktreeBranches: ReadonlySet<string>, git: Git, only?: string): SweepItem[];
+export declare function gatherLocalBranches(repo: RepoInfo, prs: Map<string, PRInfo>, worktreeBranches: ReadonlySet<string>, git: Git, only?: string, tick?: (done: number, total: number) => void): SweepItem[];
 export declare function classifyLocalBranch(opts: {
     name: string;
     upstream: string;
@@ -50,7 +50,7 @@ export declare function classifyLocalBranch(opts: {
     worktreeBranches: ReadonlySet<string>;
     git: Git;
 }): SweepItem;
-export declare function gatherRemoteBranches(repo: RepoInfo, prs: Map<string, PRInfo>, localBranchNames: ReadonlySet<string>, git: Git, only?: string): SweepItem[];
+export declare function gatherRemoteBranches(repo: RepoInfo, prs: Map<string, PRInfo>, localBranchNames: ReadonlySet<string>, git: Git, only?: string, tick?: (done: number, total: number) => void): SweepItem[];
 export declare function classifyRemoteBranch(opts: {
     name: string;
     sha: string;

package/dist/branches.js

@@ -95,10 +95,11 @@ export function remoteDeleteCommand(remote, name, sha) {
     ]);
 }
 // ── local branches ─────────────────────────────────────────────────────────
-export function gatherLocalBranches(repo, prs, worktreeBranches, git, only) {
+export function gatherLocalBranches(repo, prs, worktreeBranches, git, only, tick) {
     const rows = git.at(repo.root).forEachRef('refs/heads/', { format: LOCAL_FORMAT });
     const items = [];
-    for (const line of rows) {
+    for (const [i, line] of rows.entries()) {
+        tick?.(i, rows.length);
         const parts = line.split('\t');
         if (parts.length !== 5)
             continue;
@@ -140,10 +141,20 @@ export function classifyLocalBranch(opts) {
     const pinned = (reason) => keep(reason, { deletable: false });
     if (name === repo.mainBranch)
         return pinned('default branch');
-    if (name === repo.currentBranch)
-        return pinned('current HEAD');
-    if (worktreeBranches.has(name))
-        return pinned('checked out in a worktree (handle via that worktree)');
+    const held = name === repo.currentBranch
+        ? 'current HEAD'
+        : worktreeBranches.has(name)
+            ? 'checked out in a worktree (handle via that worktree)'
+            : null;
+    if (held !== null) {
+        // Never deletable here, but still counted as merged or not: by ancestry or
+        // an exact-head merged PR, without the patch checks a deletable row gets.
+        // `soft`: a missing default ref reads as not merged.
+        const pr = prs.get(name);
+        const { landed } = recordPr(facts, pr, sha, repo);
+        facts['merged'] = landed || git.at(repo.root).soft.isAncestor(sha, landedRef(repo));
+        return pinned(held);
+    }
     // Work merged only into an unpushed local default has not landed. A missing
     // remote-tracking ref exits 128: ancestry unknown (null).
     const compareRef = landedRef(repo);
@@ -161,6 +172,8 @@ export function classifyLocalBranch(opts) {
         recordLanding(facts, patch);
     const patchLanded = patch !== null && patch.check !== null;
     const unmerged = !landed && !isAncestor && !landingConfirmed(patch);
+    // Merged: the work is on the default branch, by ancestry, an exact-head merged PR or a patch match.
+    facts['merged'] = landed || isAncestor || patchLanded;
     if (!landed && !isAncestor) {
         facts['unique_commits'] = git.at(repo.root).aheadBehind(repo.mainBranch, sha).ahead;
     }
@@ -230,7 +243,7 @@ export function classifyLocalBranch(opts) {
     });
 }
 // ── remote branches ────────────────────────────────────────────────────────
-export function gatherRemoteBranches(repo, prs, localBranchNames, git, only) {
+export function gatherRemoteBranches(repo, prs, localBranchNames, git, only, tick) {
     if (repo.remote === null)
         return [];
     // Default door: an unreachable remote throws rather than rendering as "the
@@ -238,7 +251,8 @@ export function gatherRemoteBranches(repo, prs, localBranchNames, git, only) {
     const pattern = only === undefined ? undefined : `refs/heads/${only}`;
     const rows = git.at(repo.root).lsRemote(repo.remote, pattern, { heads: true });
     const items = [];
-    for (const { sha, ref } of rows) {
+    for (const [i, { sha, ref }] of rows.entries()) {
+        tick?.(i, rows.length);
         if (!ref.startsWith('refs/heads/'))
             continue;
         const name = ref.slice('refs/heads/'.length);
@@ -283,6 +297,8 @@ export function classifyRemoteBranch(opts) {
         recordLanding(facts, patch);
     const patchLanded = patch !== null && patch.check !== null;
     const unmerged = !landed && !isAncestor && !landingConfirmed(patch);
+    // Merged: the work is on the default branch, by ancestry, an exact-head merged PR or a patch match.
+    facts['merged'] = landed || isAncestor || patchLanded;
     if (!landed && !isAncestor) {
         // Unknown (null) when the clone lacks `sha` or `remoteMain`, as above.
         const counted = git.at(repo.root).try.aheadBehind(remoteMain, sha);

package/dist/cli.d.ts

@@ -1,19 +1,38 @@
 /**
  * `repo-cleaner` — what has been merged, and what can go away.
  *
- * Two commands. A bare invocation sweeps: it inventories, fetching each
- * remote first unless `--no-fetch`, and writes nothing but an optional plan.
- * `repo-cleaner apply` deletes the rows of a plan that were selected and
- * authorized. Scope is opt-in: the sweep covers the repository you are
- * standing in unless `--all` or a path says otherwise.
+ * 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
+ *   plan    write the deletable rows as a plan, to stdout or a file
+ *   apply   re-check, show the steps, ask, then delete
+ *
+ * `apply` works from a saved plan (`--plan`) or sweeps first. Either way it
+ * re-checks every row, prints the steps it would run and asks before deleting;
+ * `--yes` skips the question. Without a terminal and without `--yes` it
+ * refuses rather than deleting. Scope is opt-in: the sweep covers the
+ * repository you are standing in unless a path says otherwise.
  *
  * Exit codes:
- *   0   swept; or every selected row was applied or dropped with a reason
+ *   0   swept; or apply ran, was declined, or had nothing to run
  *   1   failed against the state it found
  *   2   cannot run as typed
  *   10  nothing to sweep: no entry named a repository
  *   11  apply stopped at a failed step; the receipt says which
  */
 import { type CliContext } from '@osdlc/cli-tool';
+/**
+ * Asks a yes/no question, or returns null when there is no one to ask. `main`
+ * takes it as a parameter so a test can answer.
+ */
+export type Confirm = (question: string) => boolean | null;
+export interface MainDeps {
+    confirm?: Confirm;
+    /** Reads `--plan -`. Defaults to stdin. */
+    readStdin?: () => string;
+    /** Whether stderr is a terminal, so a status line may be drawn. Defaults to `isatty(2)`. */
+    stderrIsTerminal?: boolean;
+}
 /** `main(argv, ctx)`: returns an exit code, never exits. */
-export declare function main(argv: readonly string[], ctx: CliContext): number;
+export declare function main(argv: readonly string[], ctx: CliContext, deps?: MainDeps): number;