@osdlc/repo-cleaner 0.14.2 → 0.15.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @osdlc/repo-cleaner
 
+## 0.15.0
+
+### Minor Changes
+
+- cbb7007: A full sweep no longer holds back the branch of a worktree it can remove. When a worktree is `safe-to-delete`, its branch is judged on its own and can be deleted in the same run: `apply` removes the worktree, then deletes the branch. Before, the branch stayed `keep` ("checked out in a worktree") until the next run. The branch row records the worktree in `facts.worktree`, and `apply` skips the branch as `not-deletable` unless the same run removes that worktree. This also fixes `--branch`, which could plan a branch delete while skipping its worktree; that delete then failed with "refused: checked out".
+- 41439a6: `repo-cleaner cache` lists the clones `--remote-url` keeps, with their URL and size, and `cache remove <url>` or `cache remove --all` removes them, a clone left by a stopped run included. A checkout directory named `cache` is now swept as `./cache`. `apply`'s question no longer takes its answer from keys typed while the sweep ran (through `@osdlc/cli-tool`'s `askYesNo`). The README's install section covers a global install that the shell cannot find, fish with a Node version manager included.
+
+### Patch Changes
+
+- Updated dependencies [41439a6]
+  - @osdlc/cli-tool@0.16.0
+
 ## 0.14.2
 
 ### Patch Changes

package/README.md

@@ -68,6 +68,28 @@ npm install @osdlc/repo-cleaner
 
 ESM only. Compiled JavaScript with type declarations, for Node 22 or newer.
 
+For the command, install it globally:
+
+```sh
+npm install -g @osdlc/repo-cleaner
+```
+
+If the shell then says `Unknown command` or `command not found`, npm put the
+command in a directory that is not on `PATH`. `npm prefix -g` prints where
+it went; the command is in its `bin`. This is common with a Node version
+manager (proto, nvm, fnm, volta): each Node version has its own global
+directory, and a shell setup that names one version's `bin` directly misses
+the others. Let the manager set `PATH` instead. In fish, with proto:
+
+```fish
+# ~/.config/fish/config.fish, in place of a fish_add_path …/node/<version>/bin line
+proto activate fish | source
+```
+
+nvm users in fish can use a fish port such as `nvm.fish`; fnm has
+`fnm env --use-on-cd --shell fish | source`. Then open a new shell and check
+with `type repo-cleaner`.
+
 ## How it decides
 
 Three signals settle most items. The first two are enough alone; the third needs a content check too (see [Patch equivalence](#patch-equivalence)):
@@ -248,6 +270,12 @@ 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`.
 
+A branch whose worktree is `safe-to-delete` is not held by it: the sweep judges
+the branch on its own and records the worktree's path in `facts.worktree`, so
+one run removes the worktree and then deletes the branch. `apply` deletes such
+a branch only when the same run removes its worktree, and skips it otherwise.
+With `--only branches` no worktree is swept, so the branch stays held.
+
 ## Commands
 
 ```bash
@@ -255,9 +283,15 @@ repo-cleaner [status]   # the report: what is merged, what can go (the default)
 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
+repo-cleaner cache      # list or remove the clones --remote-url keeps
 ```
 
-All four take the same paths and sweep options.
+The first four take the same paths and sweep options. A checkout directory
+named like a command is swept as `./<name>`.
+
+`apply` asks before deleting, and throws away anything typed while the sweep
+ran, so a key pressed early cannot answer the question. It says so when it
+did.
 
 ```console
 $ repo-cleaner summary --remotes
@@ -329,7 +363,10 @@ 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
+directory. `repo-cleaner cache` lists the clones with their URL and size;
+`repo-cleaner cache remove <url>` drops one, and `cache remove --all` drops
+every one, a clone left by a stopped run included. A plan whose clone was
+removed cannot be applied; sweep again. 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.
 

package/dist/apply.js

@@ -174,7 +174,22 @@ function recheck(selected, kept, grants, implicit, opts) {
         }
         accepted.push({ repo: repo.root, item, force: granted(grants, ref, 'discard-changes') });
     }
-    return { accepted, dropped, verified };
+    // A branch freed by its worktree's removal goes only with that worktree.
+    const leaving = new Set(accepted.filter((row) => row.item.category === 'worktree').map((row) => row.item.id));
+    const held = accepted.filter((row) => {
+        const worktree = row.item.facts['worktree'];
+        return typeof worktree === 'string' && !leaving.has(worktree);
+    });
+    for (const { repo, item } of held) {
+        dropped.push({
+            repo,
+            category: item.category,
+            id: item.id,
+            reason: 'not-deletable',
+            detail: `checked out in ${String(item.facts['worktree'])}, which this run does not remove`,
+        });
+    }
+    return { accepted: accepted.filter((row) => !held.includes(row)), dropped, verified };
 }
 function pending(repo, row, action, command, expectedSha = null) {
     return {

package/dist/cli.d.ts

@@ -8,6 +8,8 @@
  *   plan    write the deletable rows as a plan, to stdout or a file
  *   apply   re-check, show the steps, ask, then delete
  *
+ * and `cache`, which lists and removes the clones `--remote-url` keeps.
+ *
  * `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

package/dist/cli.js

@@ -8,6 +8,8 @@
  *   plan    write the deletable rows as a plan, to stdout or a file
  *   apply   re-check, show the steps, ask, then delete
  *
+ * and `cache`, which lists and removes the clones `--remote-url` keeps.
+ *
  * `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
@@ -21,15 +23,15 @@
  *   10  nothing to sweep: no entry named a repository
  *   11  apply stopped at a failed step; the receipt says which
  */
-import { existsSync, readSync, realpathSync } from 'node:fs';
+import { existsSync, readSync, realpathSync, rmSync } from 'node:fs';
 import { basename, dirname, join, resolve, sep } from 'node:path';
 import { isatty } from 'node:tty';
 import { EXIT, askYesNo, canPrompt, defineCli, systemDirs } from '@osdlc/cli-tool';
 import { Git } from '@osdlc/typed-git';
-import { detectColorLevel } from '@osdlc/ux';
+import { detectColorLevel, stripControls } from '@osdlc/ux';
 import { resolveBranch } from "./branches.js";
 import { VENDOR_DIRS } from "./devlink.js";
-import { ensureMirror, mirrorProblem } from "./remote-mirror.js";
+import { cachedMirrorOf, ensureMirror, listMirrors, mirrorProblem, redactUrl, } from "./remote-mirror.js";
 import { ApplyArgumentError, applyPlan, parseGrant, parseRowRef } from "./apply.js";
 import { PLAN_VERSION, fileStamp, parsePlan, planRepo, readPlan, writePlan, } from "./plan.js";
 import { PROVIDER_CHOICES } from "./providers/index.js";
@@ -128,6 +130,7 @@ const statusCli = () => defineCli({
   ${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} cache      list or remove the clones --remote-url keeps
   ${NAME} dev        run ${NAME} from a development checkout
 
 Each command takes --help. A checkout directory named like a command is
@@ -209,6 +212,25 @@ const applyCli = () => defineCli({
     epilogue: `risks: abandon-unmerged, discard-changes, confirm-open-pr
 A row that carries a risk you did not --allow is skipped, never deleted.`,
 });
+const cacheCli = () => defineCli({
+    name: `${NAME} cache`,
+    summary: 'List the clones --remote-url keeps in the cache directory, or remove them. ' +
+        'A removed clone is cloned again by the next --remote-url run.',
+    positionals: [
+        { name: 'verb', help: 'list (the default) or remove' },
+        {
+            name: 'url',
+            variadic: true,
+            help: 'with remove: the URL whose clone to remove, as given to --remote-url',
+        },
+    ],
+    flags: {
+        all: { kind: 'boolean', help: 'with remove: remove every clone' },
+        output: OUTPUT,
+    },
+    epilogue: 'A plan written with --remote-url names its clone. Removing the clone means that plan ' +
+        'can no longer be applied; sweep again instead.',
+});
 const terminalConfirm = (question) => (canPrompt() ? askYesNo(question) : null);
 const PAUSE = new Int32Array(new SharedArrayBuffer(4));
 /**
@@ -714,6 +736,120 @@ function confirm(ctx, name, preview, count, json, deps) {
     }
     return null;
 }
+/** `bytes` as a short size: `512 B`, `3.4 MB`. */
+function sizeText(bytes) {
+    const units = ['B', 'KB', 'MB', 'GB', 'TB'];
+    let value = bytes;
+    let unit = 0;
+    while (value >= 1024 && unit < units.length - 1) {
+        value /= 1024;
+        unit++;
+    }
+    return unit === 0 ? `${value} B` : `${value.toFixed(1)} ${units[unit]}`;
+}
+function cacheLine(m) {
+    const why = m.partial ? 'left by a stopped clone' : m.problem;
+    const note = why === null ? '' : `  (${why})`;
+    // A URL, directory name or git message is outside text: no terminal controls.
+    return (stripControls(`${sizeText(m.bytes).padStart(9)}  ${m.url ?? '(no origin)'}  ${m.dir}${note}`) +
+        '\n');
+}
+function runCache(argv, ctx) {
+    const name = `${NAME} cache`;
+    const parsed = cacheCli().parse(argv, ctx.io);
+    if (parsed.status === 'help')
+        return EXIT.ok;
+    if (parsed.status === 'error')
+        return usageError(ctx, name, parsed.message);
+    const v = parsed.values;
+    const [verb = 'list', ...urls] = parsed.positionals;
+    const dir = mirrorCache(ctx);
+    const json = v.output === 'json';
+    if (verb === 'list') {
+        if (urls.length > 0 || v.all)
+            return usageError(ctx, name, 'list takes no URLs and no --all');
+        return cacheList(ctx, dir, json);
+    }
+    if (verb === 'remove') {
+        const hasUrls = urls.length > 0;
+        if (hasUrls === v.all) {
+            return usageError(ctx, name, 'remove takes URLs or --all, not both and not neither');
+        }
+        return cacheRemove(ctx, name, dir, v.all ? null : urls, json);
+    }
+    return usageError(ctx, name, `unknown verb ${JSON.stringify(verb)}; use list or remove`);
+}
+function cacheList(ctx, dir, json) {
+    const mirrors = listMirrors(dir);
+    if (json) {
+        ctx.io.stdout(`${JSON.stringify({ cache: dir, mirrors }, null, 2)}\n`);
+        return EXIT.ok;
+    }
+    if (mirrors.length === 0) {
+        ctx.io.stdout(`no clones in ${dir}\n`);
+        return EXIT.ok;
+    }
+    for (const m of mirrors)
+        ctx.io.stdout(cacheLine(m));
+    const total = mirrors.reduce((sum, m) => sum + m.bytes, 0);
+    const count = `${mirrors.length} clone${mirrors.length === 1 ? '' : 's'}`;
+    ctx.io.stdout(`${count}, ${sizeText(total)}, in ${dir}\n`);
+    return EXIT.ok;
+}
+/**
+ * The clones to remove: those of `urls`, or every entry when `urls` is null,
+ * each with the URL to name it by (credentials removed), and the URLs that
+ * have none.
+ */
+function cacheTargets(dir, urls) {
+    if (urls === null) {
+        const targets = listMirrors(dir).map((m) => ({ dir: m.dir, label: m.url ?? '(no origin)' }));
+        return { targets, missing: [] };
+    }
+    const targets = [];
+    const missing = [];
+    for (const url of urls) {
+        const shown = redactUrl(url);
+        const found = cachedMirrorOf(url, dir);
+        if (found === null)
+            missing.push(shown);
+        else
+            targets.push({ dir: found, label: shown });
+    }
+    return { targets, missing };
+}
+/**
+ * Remove the clones of `urls`, or every entry when `urls` is null. A URL with
+ * no clone, or a clone that cannot be removed, is reported and the rest still
+ * go; either makes the exit 1.
+ */
+function cacheRemove(ctx, name, dir, urls, json) {
+    const { targets, missing } = cacheTargets(dir, urls);
+    const removed = [];
+    const failed = [];
+    for (const t of targets) {
+        try {
+            rmSync(t.dir, { recursive: true, force: true });
+            removed.push(t.dir);
+            if (!json)
+                ctx.io.stdout(stripControls(`removed ${t.label}  ${t.dir}`) + '\n');
+        }
+        catch (err) {
+            const error = err instanceof Error ? err.message : String(err);
+            failed.push({ dir: t.dir, error });
+            ctx.io.stderr(stripControls(`${name}: cannot remove ${t.label}  ${t.dir}: ${error}`) + '\n');
+        }
+    }
+    for (const url of missing)
+        ctx.io.stderr(stripControls(`${name}: no clone of ${url}`) + '\n');
+    if (json) {
+        ctx.io.stdout(`${JSON.stringify({ cache: dir, removed, missing, failed }, null, 2)}\n`);
+    }
+    else if (targets.length === 0 && missing.length === 0) {
+        ctx.io.stdout(`no clones in ${dir}\n`);
+    }
+    return missing.length > 0 || failed.length > 0 ? EXIT.error : EXIT.ok;
+}
 function emptyReceipt(plan, now, dryRun) {
     const at = now.toISOString();
     return {
@@ -752,6 +888,8 @@ export function main(argv, ctx, deps = {}) {
             return runPlan(rest, c, status);
         if (sub === 'apply')
             return runApply(rest, c, deps, status);
+        if (sub === 'cache')
+            return runCache(rest, c);
         if (sub === 'status')
             return runStatus(rest, c, status);
         return runStatus(argv, c, status);

package/dist/remote-mirror.d.ts

@@ -53,3 +53,27 @@ export declare function mirrorProblem(dir: string, url?: string, opts?: {
 export declare function ensureMirror(url: string, cacheDir: string, opts?: {
     git?: CommandRunner | undefined;
 }): string;
+/** One entry of the mirror cache, as `cache list` reports it. */
+export interface CachedMirror {
+    /** The entry's directory. */
+    dir: string;
+    /** The URL it was cloned from, credentials removed; null when there is none to read. */
+    url: string | null;
+    /** Bytes on disk, every file under the directory counted. */
+    bytes: number;
+    /** A clone left behind by a run that stopped before it finished. */
+    partial: boolean;
+    /** What {@link mirrorProblem} found; null for a usable mirror and for a partial clone. */
+    problem: string | null;
+}
+/** Every entry under `cacheDir`, sorted by directory; none when the cache does not exist. */
+export declare function listMirrors(cacheDir: string, opts?: {
+    git?: CommandRunner | undefined;
+}): CachedMirror[];
+/**
+ * The mirror directory `url` would use under `cacheDir`, when there is one;
+ * null when there is none. The lookup is by name, the same one
+ * {@link ensureMirror} clones to, so the URL must be the one the sweep was
+ * given, credentials included.
+ */
+export declare function cachedMirrorOf(url: string, cacheDir: string): string | null;

package/dist/remote-mirror.js

@@ -13,7 +13,7 @@
  * date.
  */
 import { createHash } from 'node:crypto';
-import { existsSync, mkdirSync, renameSync, rmSync } from 'node:fs';
+import { existsSync, lstatSync, mkdirSync, readdirSync, renameSync, rmSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { Git, parseRemoteRepo } from '@osdlc/typed-git';
 /** A remote URL that cannot be mirrored, or a mirror that cannot be made or reused. */
@@ -121,3 +121,45 @@ export function ensureMirror(url, cacheDir, opts = {}) {
     }
     return dir;
 }
+const PARTIAL = /\.partial-\d+$/;
+/** Bytes under `path`, symlinks counted as themselves, not followed. */
+function sizeOf(path) {
+    const stat = lstatSync(path, { throwIfNoEntry: false });
+    if (stat === undefined)
+        return 0;
+    if (!stat.isDirectory())
+        return stat.size;
+    let total = 0;
+    for (const name of readdirSync(path))
+        total += sizeOf(join(path, name));
+    return total;
+}
+/** Every entry under `cacheDir`, sorted by directory; none when the cache does not exist. */
+export function listMirrors(cacheDir, opts = {}) {
+    if (!existsSync(cacheDir))
+        return [];
+    return readdirSync(cacheDir, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => entry.name)
+        .sort()
+        .map((name) => {
+        const dir = join(cacheDir, name);
+        const bytes = sizeOf(dir);
+        if (PARTIAL.test(name))
+            return { dir, url: null, bytes, partial: true, problem: null };
+        const problem = mirrorProblem(dir, undefined, opts);
+        const urls = new Git(dir, { runner: opts.git }).try.remoteGetUrls('origin');
+        const url = urls.ok && urls.value.length > 0 ? redactUrl(urls.value[0]) : null;
+        return { dir, url, bytes, partial: false, problem };
+    });
+}
+/**
+ * The mirror directory `url` would use under `cacheDir`, when there is one;
+ * null when there is none. The lookup is by name, the same one
+ * {@link ensureMirror} clones to, so the URL must be the one the sweep was
+ * given, credentials included.
+ */
+export function cachedMirrorOf(url, cacheDir) {
+    const dir = join(cacheDir, mirrorName(url));
+    return existsSync(dir) ? dir : null;
+}

package/dist/sweep.js

@@ -99,12 +99,27 @@ export function sweepRepo(path, opts = {}) {
             items.push(...worktreeItems);
         let localBranchNames = new Set();
         if (scope.has('local-branches') || scope.has('remote-branches')) {
-            const pinned = only === undefined
-                ? worktreeBranches
-                : new Set(worktreeItems
-                    .filter((item) => !item.deletable)
-                    .map((item) => String(item.facts['branch'])));
+            // A branch whose worktree goes in the same plan is judged on its own:
+            // apply removes worktrees before it deletes branches. A full sweep frees
+            // the branch of a safe-to-delete worktree; a branch-scoped sweep frees
+            // the named branch when its worktree is deletable at all.
+            const freed = new Map();
+            if (scope.has('worktrees')) {
+                for (const item of worktreeItems) {
+                    const branch = item.facts['branch'];
+                    const goes = item.deletable && (only !== undefined || item.classification === 'safe-to-delete');
+                    if (goes && typeof branch === 'string')
+                        freed.set(branch, item.id);
+                }
+            }
+            const pinned = new Set([...worktreeBranches].filter((name) => !freed.has(name)));
             const localItems = gatherLocalBranches(repo, prs, pinned, git, only, ticker('local-branches'));
+            // Apply drops a freed branch unless the same run removes its worktree.
+            for (const item of localItems) {
+                const worktree = freed.get(item.id);
+                if (worktree !== undefined)
+                    item.facts['worktree'] = worktree;
+            }
             localBranchNames = new Set(localItems.map((item) => item.id));
             if (scope.has('local-branches'))
                 items.push(...localItems);

package/dist/version.generated.d.ts

@@ -1,2 +1,2 @@
 /** This package's version, from its package.json when it was built. */
-export declare const VERSION = "0.14.2";
+export declare const VERSION = "0.15.0";

package/dist/version.generated.js

@@ -1,3 +1,3 @@
 // Generated by cli-tool-stamp-version from package.json. Do not edit.
 /** This package's version, from its package.json when it was built. */
-export const VERSION = '0.14.2';
+export const VERSION = '0.15.0';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@osdlc/repo-cleaner",
-  "version": "0.14.2",
+  "version": "0.15.0",
   "description": "What has been merged into the default branch, and what can go away. Inventories local branches, worktrees and remote branches across one repository or many, classifying each with the evidence behind the verdict and the command that would act on it. Plans and applies approved deletes, compare-and-swap.",
   "license": "MIT OR Apache-2.0",
   "author": "sksizer",
@@ -49,11 +49,11 @@
   },
   "dependencies": {
     "zod": "^4.6.6",
-    "@osdlc/cli-tool": "^0.15.0",
-    "@osdlc/path-guard": "^0.3.1",
+    "@osdlc/cli-tool": "^0.16.0",
     "@osdlc/command-seam": "^0.14.0",
     "@osdlc/typed-gh": "^0.14.1",
     "@osdlc/typed-git": "^0.12.0",
+    "@osdlc/path-guard": "^0.3.1",
     "@osdlc/ux": "^0.1.1"
   },
   "devDependencies": {