@osdlc/repo-cleaner 0.10.0 → 0.11.0

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # @osdlc/repo-cleaner
 
+## 0.11.0
+
+### Minor Changes
+
+- 14d4351: A worktree row whose directory is gone, or is no longer a checkout, now reads `prune` instead of `delete` in the report, and `summary` counts those rows in a `prune` column (and a `prune` count in each JSON bucket, a part of `safe-to-delete`). The row's `action` is `prune`.
+  
+  New `--remote-url <url>` on every sweeping command: sweep a remote's branches with no checkout of your own. The URL is cloned once (`--no-checkout`) under the cache directory and reused; deletes are pushed from that clone, so a plan written with `--remote-url` can be applied later from anywhere.
+
+### Patch Changes
+
+- Updated dependencies [14d4351]
+- Updated dependencies [dd2265e]
+  - @osdlc/cli-tool@0.13.0
+
+## 0.10.1
+
+### Patch Changes
+
+- cde11b5: `apply` fixes:
+  
+  - The run a confirmation approves keeps the safe-to-delete guard: a row that turned into a review row between the preview and the yes is dropped as `needs-review`, not run.
+  - Two clones of one remote no longer delete its branches twice. The second row is dropped as the new reason `duplicate`, naming the clone that deletes it; before, the second push was rejected and the run stopped with exit 11. Remotes are compared by the push URLs git uses (`url.*.insteadOf` applied), a network URL in any form (`git@host:o/r`, `ssh://`, `https://`) as `host/path`, and a local path as written.
+  - A swept `apply` re-checks once before asking, from the sweep it just ran, instead of sweeping again; the run that deletes still sweeps afresh.
+  - A run that deletes without a receipt file says so on stderr.
+  - Every run ends with a summary: `deleted: 1 worktree, 3 local branches, 2 remote branches`, the dropped rows by reason, and how many rows a failed run did not reach. A preview says `would delete:`. `--output json` adds a `summary` object.
+  - The prompt's `Delete N items?` counts rows, not steps: a stale-locked worktree is one item, not two.
+  - `--repo-root` naming no repository in the plan exits 1 instead of reporting nothing to delete.
+  - An empty plan's JSON receipt says `complete`, not `dry-run`, unless the run was `--dry-run`.
+  
+  Library: `ApplyOptions.safeOnly` and `ApplyOptions.swept`, the `duplicate` drop reason, `RECEIPT_VERSION`, and `summarizeReceipt`, `renderApplySummary` and `ApplySummary`.
+
 ## 0.10.0
 
 ### Minor Changes

package/README.md

@@ -205,7 +205,7 @@ worktree, the primary or caller's worktree) has `deletable: false`.
 
 ```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 summary    # counts per repository: total, merged, delete, prune, 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
 ```
@@ -215,14 +215,21 @@ 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
+                   total  merged  delete  prune  review   keep
+  local branches      12       8       6      0       1      5
+  worktrees            4       3       1      1       1      1
+  remote branches     40      31      30      0       6      4
 
-38 to delete, 8 to review, across 1 repository.
+37 to delete, 1 to prune, 8 to review, across 1 repository.
 ```
 
+`prune` counts worktree rows whose directory is gone, or is no longer a
+checkout: deleting one runs `git worktree prune` to drop the stale link, and
+a directory that is still there stays. The report labels those rows `prune`
+rather than `delete`. In `--output json` they are `safe-to-delete` with
+`action: "prune"`, and each summary bucket has a `prune` count, a part of its
+`safe-to-delete` count.
+
 `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
@@ -258,6 +265,34 @@ An entry that resolves to nothing is reported rather than dropped. A worklist
 that silently sweeps four of the five repositories it was given is worse than
 one that says which it could not find.
 
+### A remote with no checkout
+
+```bash
+repo-cleaner --remote-url git@github.com:acme/api.git
+repo-cleaner apply --remote-url git@github.com:acme/api.git
+```
+
+`--remote-url <url>` sweeps a remote's branches when you have no checkout of
+it. It clones the URL once, with `--no-checkout`, into
+`repo-cleaner/remotes/` under the cache directory (`~/Library/Caches` on
+macOS, `$XDG_CACHE_HOME` or `~/.cache` on Linux, `REPO_CLEANER_CACHE_DIR`
+to move it), and sweeps that clone. Later runs reuse the clone and fetch. Only remote branches
+are swept: the clone's own branches and worktree are not yours. Deletes are
+pushed to the URL from the clone, compare-and-swap as always.
+
+The clone is kept, not deleted after the run, so a plan written with
+`--remote-url` can be applied later from anywhere: the plan names the clone's
+directory. Remove the directory to drop it. The clone is a full one, not
+`--filter=blob:none`: the patch check reads file contents, and a partial
+clone fetches them one branch at a time.
+
+The flag repeats for several remotes. It does not combine with paths,
+`--branch` or `--plan`, `--only` may only name `remotes`, and an empty URL is
+refused. A clone is reused only while its `origin` fetches from that URL and
+pushes to it alone; `apply --plan` checks the same of a plan's clone before
+deleting. The clone's directory name and every message carry the URL with
+its credentials, query and fragment removed.
+
 ## Options
 
 Every command that sweeps takes these:
@@ -267,6 +302,7 @@ Every command that sweeps takes these:
 | `--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`) |
+| `--remote-url <url>` | Sweep this remote's branches with no checkout of your own (see [A remote with no checkout](#a-remote-with-no-checkout)); repeatable |
 | `--no-gh` | Classify on git evidence alone |
 | `--no-fetch` | Skip the fetch; the header then says `not fetched` |
 
@@ -312,6 +348,20 @@ 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.
 
+Every run ends with what it did:
+
+```text
+deleted: 1 worktree, 3 local branches, 2 remote branches, 1 stale worktree pruned
+dropped 2: 1 needs-review, 1 duplicate
+status: complete
+```
+
+The preview says `would delete:`, and a run that stops at a failed step says
+how many rows it did not reach. `--output json` carries the same counts as
+`summary`. Two clones of one remote list the same remote branches; `apply`
+deletes each once and drops the other clone's row as `duplicate`. Remotes are
+compared by the push URL git uses, with `url.*.insteadOf` applied.
+
 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

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 { Dropped, Receipt, RowRef, Step } from './receipt.ts';
-import { type Authorization, type SweepProgress } from './types.ts';
+import { type Dropped, type Receipt, type RowRef, type Step } from './receipt.ts';
+import { type Authorization, type SweepItem, type SweepProgress } from './types.ts';
 /** An authorization the caller gave, for one row or (`row: null`) for all. */
 export interface Grant {
     name: Authorization;
@@ -45,6 +45,20 @@ export interface ApplyOptions extends HostHooks {
     /** Limit the run to the plan repository rooted here. */
     repoRoot?: string | undefined;
     now?: () => Date;
+    /**
+     * Drop each selected row the re-check does not judge `safe-to-delete`.
+     * Defaults to true when no rows are requested, so a row to review runs only
+     * when it is named. Pass it to keep that guard on a run whose rows came
+     * from such a selection, such as the run a preview confirmed.
+     */
+    safeOnly?: boolean | undefined;
+    /**
+     * Items to re-check against instead of sweeping again, keyed by repository
+     * root, already annotated: the hook is not applied to them again. For a
+     * preview straight after a sweep; the run that deletes should always sweep
+     * again.
+     */
+    swept?: ReadonlyMap<string, readonly SweepItem[]> | undefined;
     /** 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. */
@@ -66,6 +80,13 @@ export declare function parseGrant(text: string): Grant;
 export type RowSelection = RowRef & {
     repo?: string;
 };
+/**
+ * A network URL as `host[:port]/path`, the same for `git@host:o/r.git`,
+ * `ssh://git@host/o/r` and `https://host/o/r/`; the whole path is kept, so
+ * nested groups stay apart. Null for a path on this machine, including
+ * `file://` and a Windows drive path.
+ */
+export declare function networkRemoteKey(url: string): string | null;
 /**
  * Apply the `requested` rows of `plan` under `grants`. An empty `requested`
  * selects every row of the plan (of `repoRoot`'s repository, when given) and

package/dist/apply.js

@@ -20,6 +20,7 @@ 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";
+import { RECEIPT_VERSION } from "./receipt.js";
 import { sweepRepo } from "./sweep.js";
 import { AUTHORIZATIONS } from "./types.js";
 import { worktreePruneCommand, worktreeRemoveCommand, worktreeUnlockCommand } from "./worktrees.js";
@@ -78,6 +79,10 @@ function granted(grants, ref, name) {
 }
 /** The plan repository's rows as they stand now, with the host's overlay applied. */
 function resweep(repo, opts) {
+    const given = opts.swept?.get(repo.root);
+    if (given !== undefined) {
+        return [...given];
+    }
     const sweep = sweepRepo(repo.root, {
         remote: repo.remote,
         noGh: repo.no_gh,
@@ -257,6 +262,73 @@ function execute(step, row, git, probe) {
         }
     }
 }
+/**
+ * A network URL as `host[:port]/path`, the same for `git@host:o/r.git`,
+ * `ssh://git@host/o/r` and `https://host/o/r/`; the whole path is kept, so
+ * nested groups stay apart. Null for a path on this machine, including
+ * `file://` and a Windows drive path.
+ */
+export function networkRemoteKey(url) {
+    const u = url.trim();
+    if (/^[a-z]:[\\/]/i.test(u) || /^file:/i.test(u))
+        return null;
+    const uri = /^[a-z][a-z0-9+.-]*:\/\/(?:[^@/]+@)?([^/:]+)(?::(\d+))?(\/.*)?$/i.exec(u);
+    const scp = uri === null ? /^(?:[^@/:]+@)?([^/:]+):(?!\/\/)(.+)$/.exec(u) : null;
+    const host = uri?.[1] ?? scp?.[1];
+    if (host === undefined)
+        return null;
+    const port = uri?.[2] === undefined ? '' : `:${uri[2]}`;
+    const path = (uri?.[3] ?? scp?.[2] ?? '').replace(/^\/+|\/+$/g, '').replace(/\.git$/, '');
+    return `${host.toLowerCase()}${port}/${path}`;
+}
+/**
+ * One string per remote repository, so two clones that push to the same one
+ * agree. Built from the push URLs git would use (`remote get-url --push
+ * --all`, which applies `url.*.insteadOf` and `pushInsteadOf`): a network URL
+ * by {@link networkRemoteKey}, a local path resolved against the repository
+ * and kept as written, `.git` and all. Null when git reports no URL; such a
+ * row is never treated as a duplicate.
+ */
+function remoteKey(git, repo, remote) {
+    const urls = git.at(repo).try.remoteGetUrls(remote, { push: true });
+    if (!urls.ok || urls.value === null || urls.value.length === 0)
+        return null;
+    const keys = urls.value.map((url) => networkRemoteKey(url) ?? resolve(repo, url.trim().replace(/^file:\/\/(localhost)?/i, '')));
+    return [...new Set(keys)].sort().join('\n');
+}
+/**
+ * Keep the first row for each remote branch. Two clones of one remote each
+ * list its branches; deleting one twice fails the second push and stops the
+ * run, so the later row is dropped as `duplicate`.
+ */
+function onePerRemoteBranch({ accepted, dropped }, git) {
+    const seen = new Map();
+    const kept = [];
+    const extra = [];
+    for (const row of accepted) {
+        if (row.item.category !== 'remote_branch') {
+            kept.push(row);
+            continue;
+        }
+        const remote = remoteKey(git, row.repo, String(row.item.facts['remote']));
+        const key = remote === null ? null : `${remote}\0${String(row.item.facts['branch'])}`;
+        const first = key === null ? undefined : seen.get(key);
+        if (first !== undefined) {
+            extra.push({
+                repo: row.repo,
+                category: row.item.category,
+                id: row.item.id,
+                reason: 'duplicate',
+                detail: `the same remote branch is deleted from ${first}`,
+            });
+            continue;
+        }
+        if (key !== null)
+            seen.set(key, row.repo);
+        kept.push(row);
+    }
+    return { accepted: kept, dropped: [...dropped, ...extra] };
+}
 /**
  * Apply the `requested` rows of `plan` under `grants`. An empty `requested`
  * selects every row of the plan (of `repoRoot`'s repository, when given) and
@@ -286,7 +358,7 @@ export function applyPlan(plan, requested, grants, opts) {
         }
     }
     const receipt = {
-        version: 1,
+        version: RECEIPT_VERSION,
         plan: opts.planPath,
         status: opts.dryRun ? 'dry-run' : 'applying',
         started_at: now().toISOString(),
@@ -294,7 +366,8 @@ export function applyPlan(plan, requested, grants, opts) {
         dropped: [],
         steps: [],
     };
-    const { accepted, dropped } = recheck(selected, grants, requested.length === 0, opts);
+    const rechecked = recheck(selected, grants, opts.safeOnly ?? requested.length === 0, opts);
+    const { accepted, dropped } = onePerRemoteBranch(rechecked, new Git(opts.callerCwd, { runner: opts.git }));
     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]));

package/dist/branches.d.ts

@@ -27,6 +27,16 @@ export declare function recordPr(facts: Record<string, unknown>, pr: PRInfo | un
 };
 /** One sentence on why a merged PR did not count, for `investigationParts`. */
 export declare function gapSentence(pr: PRInfo, gap: PrEvidenceGap, repo: RepoInfo): string;
+/**
+ * `facts.merged`: the work is on the default branch, by an exact-head merged
+ * PR, by ancestry or by a patch match. Every category records it this way, so
+ * `summary` counts one definition.
+ */
+export declare function mergedFact(e: {
+    landed: boolean;
+    ancestor: boolean;
+    patchLanded: boolean;
+}): boolean;
 /** `HEAD` as the branch checked out at `git`'s directory; any other name as given. */
 export declare function resolveBranch(value: string, git: Git): string;
 /**

package/dist/branches.js

@@ -59,6 +59,14 @@ export function gapSentence(pr, gap, repo) {
         ? `PR #${pr.number} merged into \`${pr.baseRef}\`, not \`${repo.mainBranch}\`, so it is not landing proof (other-base).`
         : `PR #${pr.number} merged at head ${pr.headOid ?? '(unknown)'}, which is not this tip, so it is not landing proof (head-moved).`;
 }
+/**
+ * `facts.merged`: the work is on the default branch, by an exact-head merged
+ * PR, by ancestry or by a patch match. Every category records it this way, so
+ * `summary` counts one definition.
+ */
+export function mergedFact(e) {
+    return e.landed || e.ancestor || e.patchLanded;
+}
 /** What deleting a branch needs: its unlanded commits, and its open PR. */
 function branchRequires(unmerged, pr) {
     return authorizationsFor({
@@ -152,7 +160,11 @@ export function classifyLocalBranch(opts) {
         // `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));
+        facts['merged'] = mergedFact({
+            landed,
+            ancestor: git.at(repo.root).soft.isAncestor(sha, landedRef(repo)),
+            patchLanded: false,
+        });
         return pinned(held);
     }
     // Work merged only into an unpushed local default has not landed. A missing
@@ -172,8 +184,7 @@ 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;
+    facts['merged'] = mergedFact({ landed, ancestor: isAncestor, patchLanded });
     if (!landed && !isAncestor) {
         facts['unique_commits'] = git.at(repo.root).aheadBehind(repo.mainBranch, sha).ahead;
     }
@@ -297,8 +308,7 @@ 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;
+    facts['merged'] = mergedFact({ landed, ancestor: 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

@@ -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
  *