@osdlc/repo-cleaner 0.9.2 → 0.10.1

package/dist/devlink.d.ts

@@ -7,4 +7,9 @@
  * `REPO_CLEANER_HOME` or `repo-cleaner dev link` hand off to a checkout.
  */
 import { type ToolSpec } from '@osdlc/cli-tool/devlink';
+/** Whose directories devlink's state lives under: vendor `repo-cleaner`, moved by the `REPO_CLEANER_*` override variables. */
+export declare const VENDOR_DIRS: {
+    vendor: string;
+    envVars: import("@osdlc/tiered-dirs").EnvVars;
+};
 export declare const DEVLINK_SPEC: ToolSpec;

package/dist/devlink.js

@@ -6,8 +6,10 @@
  * checkout runs `src/bin.ts` under Bun. The cwd layer stays off: only
  * `REPO_CLEANER_HOME` or `repo-cleaner dev link` hand off to a checkout.
  */
+import { envVars } from '@osdlc/cli-tool';
 import { validateSpec } from '@osdlc/cli-tool/devlink';
-import { VENDOR_DIRS } from "./config.js";
+/** Whose directories devlink's state lives under: vendor `repo-cleaner`, moved by the `REPO_CLEANER_*` override variables. */
+export const VENDOR_DIRS = { vendor: 'repo-cleaner', envVars: envVars('REPO_CLEANER') };
 export const DEVLINK_SPEC = validateSpec({
     name: 'repo-cleaner',
     marker: 'src/cli.ts',

package/dist/index.d.ts

@@ -18,14 +18,13 @@ export { classifyLocalBranch, classifyRemoteBranch, gatherLocalBranches, gatherR
 export { classifyWorktree, gatherWorktrees, hasBlockers, worktreePruneCommand, worktreeRemoveCommand, worktreeUnlockCommand, type WorktreeBlocker, } from './worktrees.ts';
 export { DiscoveryFailed, discoverRepo } from './discover.ts';
 export { assessLanding, patchEquivalent, type Landing, type LandingCheck } from './landing.ts';
-export { ApplyArgumentError, applyPlan, parseGrant, parseRowRef, type ApplyOptions, type Grant, } from './apply.ts';
+export { ApplyArgumentError, applyPlan, type RowSelection, parseGrant, parseRowRef, type ApplyOptions, type Grant, } from './apply.ts';
 export type { Annotate, HostHooks } from './hooks.ts';
-export { PLAN_VERSION, PlanReadError, planRepo, readPlan, stampedPath, writePlan, type Plan, type PlanRepo, type PlannableRow, } from './plan.ts';
-export { ReceiptSchema, type Dropped, type Receipt, type RowRef, type Step } from './receipt.ts';
+export { PLAN_VERSION, PlanReadError, planRepo, parsePlan, readPlan, writePlan, type Plan, type PlanRepo, type PlannableRow, } from './plan.ts';
+export { RECEIPT_VERSION, ReceiptSchema, type Dropped, type Receipt, type RowRef, type Step, } from './receipt.ts';
 export { defaultProcessProbe, isIdleShell, parseLockOwner, parseLsofCwd, type DefaultProbeOptions, type LockOwner, type ProcessHolder, type ProcessProbe, } from './processes.ts';
 export { fetchPrs } from './prs.ts';
 export { expandTilde, isCheckoutRoot, resolveEntries, type Resolution, type ResolveOptions, } from './resolve.ts';
 export { sweepRepo, sweepRepos, type SweepOptions, type SweepReposOptions } from './sweep.ts';
-export { proposedCommands, renderJson, renderReceipt, renderRepo, renderScan, renderSummary, renderText, requiresNote, } from './render.ts';
-export { CONFIG_ENV, DEFAULT_CONFIG, RepoCleanerConfigSchema, TOOL, clearConfigCache, configPath, configuredRepos, loadConfig, type RepoCleanerConfig, } from './config.ts';
-export { ALL_SCOPES, AUTHORIZATIONS, authorizationsFor, emptyBucket, emptyScan, findDuplicateCheckouts, isUnfetched, makeItem, summarize, type Authorization, type Category, type Classification, type DuplicateCheckout, type PRInfo, type RepoInfo, type RepoSweep, type ScanStats, type Scope, type SummaryBucket, type SweepItem, type SweepResult, type UnresolvedEntry, } from './types.ts';
+export { proposedCommands, renderJson, renderApplySummary, renderReceipt, summarizeReceipt, type ApplySummary, renderRepo, renderScan, renderSummary, renderText, requiresNote, } from './render.ts';
+export { ALL_SCOPES, AUTHORIZATIONS, authorizationsFor, emptyBucket, emptyScan, findDuplicateCheckouts, isUnfetched, makeItem, summarize, type Authorization, type Category, type Classification, type DuplicateCheckout, type PRInfo, type RepoInfo, type RepoSweep, type ScanStats, type Scope, type SummaryBucket, type SweepItem, type SweepProgress, type SweepResult, type UnresolvedEntry, } from './types.ts';

package/dist/index.js

@@ -19,12 +19,11 @@ export { classifyWorktree, gatherWorktrees, hasBlockers, worktreePruneCommand, w
 export { DiscoveryFailed, discoverRepo } from "./discover.js";
 export { assessLanding, patchEquivalent } from "./landing.js";
 export { ApplyArgumentError, applyPlan, parseGrant, parseRowRef, } from "./apply.js";
-export { PLAN_VERSION, PlanReadError, planRepo, readPlan, stampedPath, writePlan, } from "./plan.js";
-export { ReceiptSchema } from "./receipt.js";
+export { PLAN_VERSION, PlanReadError, planRepo, parsePlan, readPlan, writePlan, } from "./plan.js";
+export { RECEIPT_VERSION, ReceiptSchema, } from "./receipt.js";
 export { defaultProcessProbe, isIdleShell, parseLockOwner, parseLsofCwd, } from "./processes.js";
 export { fetchPrs } from "./prs.js";
 export { expandTilde, isCheckoutRoot, resolveEntries, } from "./resolve.js";
 export { sweepRepo, sweepRepos } from "./sweep.js";
-export { proposedCommands, renderJson, renderReceipt, renderRepo, renderScan, renderSummary, renderText, requiresNote, } from "./render.js";
-export { CONFIG_ENV, DEFAULT_CONFIG, RepoCleanerConfigSchema, TOOL, clearConfigCache, configPath, configuredRepos, loadConfig, } from "./config.js";
+export { proposedCommands, renderJson, renderApplySummary, renderReceipt, summarizeReceipt, renderRepo, renderScan, renderSummary, renderText, requiresNote, } from "./render.js";
 export { ALL_SCOPES, AUTHORIZATIONS, authorizationsFor, emptyBucket, emptyScan, findDuplicateCheckouts, isUnfetched, makeItem, summarize, } from "./types.js";

package/dist/plan.d.ts

@@ -78,8 +78,8 @@ export declare function isPlanCategory(category: string): category is PlanCatego
 /**
  * The facts a row's verdict rests on. A branch: its sha and its PR's number
  * and state. A worktree: HEAD, branch, how much unlanded work it holds and
- * whether its lock was stale, so a lock taken or revived after planning drops
- * the row.
+ * whether its lock was stale and whether it is on disk, so a lock taken or
+ * revived after planning, or a directory that came back, drops the row.
  */
 export declare function fingerprint(item: PlannableRow): Record<string, unknown>;
 /** Equal fingerprints, treating a missing key as null. */
@@ -92,10 +92,14 @@ export declare function planRepo(root: string, opts: {
 }, items: readonly PlannableRow[]): PlanRepo;
 /** A UTC timestamp safe in a file name, e.g. `2026-10-04T12-30-05-123Z`. */
 export declare function fileStamp(d: Date): string;
-export declare function stampedPath(dir: string, d: Date): string;
 export declare function writePlan(path: string, plan: Plan): void;
 /** A plan file that cannot be read or does not match {@link PlanSchema}. */
 export declare class PlanReadError extends Error {
 }
+/**
+ * Parse a plan's JSON text. `source` names where it came from, for the error.
+ * @throws PlanReadError
+ */
+export declare function parsePlan(text: string, source: string): Plan;
 /** @throws PlanReadError */
 export declare function readPlan(path: string): Plan;

package/dist/plan.js

@@ -4,7 +4,6 @@
  * whose fingerprint no longer matches.
  */
 import { readFileSync } from 'node:fs';
-import { join } from 'node:path';
 import { z } from 'zod';
 import { AUTHORIZATIONS } from "./types.js";
 import { writeJsonAtomic } from "./write-json.js";
@@ -37,8 +36,8 @@ export function isPlanCategory(category) {
 /**
  * The facts a row's verdict rests on. A branch: its sha and its PR's number
  * and state. A worktree: HEAD, branch, how much unlanded work it holds and
- * whether its lock was stale, so a lock taken or revived after planning drops
- * the row.
+ * whether its lock was stale and whether it is on disk, so a lock taken or
+ * revived after planning, or a directory that came back, drops the row.
  */
 export function fingerprint(item) {
     const f = item.facts;
@@ -49,6 +48,9 @@ export function fingerprint(item) {
             dirty_files: f['dirty_files'] ?? null,
             unpushed_commits: f['unpushed_commits'] ?? null,
             stale_lock: f['stale_lock'] ?? null,
+            // Prune or remove: a directory that came back between plan and apply
+            // must not turn a prune into a remove.
+            on_disk: f['on_disk'] ?? null,
         };
     }
     const pr = f['pr'];
@@ -82,26 +84,37 @@ export function planRepo(root, opts, items) {
 export function fileStamp(d) {
     return d.toISOString().replace(/[:.]/g, '-');
 }
-export function stampedPath(dir, d) {
-    return join(dir, `${fileStamp(d)}.json`);
-}
 export function writePlan(path, plan) {
     writeJsonAtomic(path, plan);
 }
 /** A plan file that cannot be read or does not match {@link PlanSchema}. */
 export class PlanReadError extends Error {
 }
-/** @throws PlanReadError */
-export function readPlan(path) {
+/**
+ * Parse a plan's JSON text. `source` names where it came from, for the error.
+ * @throws PlanReadError
+ */
+export function parsePlan(text, source) {
     let raw;
     try {
-        raw = JSON.parse(readFileSync(path, 'utf-8'));
+        raw = JSON.parse(text);
     }
     catch (err) {
-        throw new PlanReadError(`cannot read plan ${path}: ${err instanceof Error ? err.message : String(err)}`);
+        throw new PlanReadError(`cannot read plan ${source}: ${err instanceof Error ? err.message : String(err)}`);
     }
     const parsed = PlanSchema.safeParse(raw);
     if (!parsed.success)
-        throw new PlanReadError(`bad plan ${path}: ${parsed.error.message}`);
+        throw new PlanReadError(`bad plan ${source}: ${parsed.error.message}`);
     return parsed.data;
 }
+/** @throws PlanReadError */
+export function readPlan(path) {
+    let text;
+    try {
+        text = readFileSync(path, 'utf-8');
+    }
+    catch (err) {
+        throw new PlanReadError(`cannot read plan ${path}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    return parsePlan(text, path);
+}

package/dist/receipt.d.ts

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

package/dist/receipt.js

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

package/dist/render.d.ts

@@ -28,6 +28,15 @@ export declare function renderRepo(sweep: RepoSweep, opts?: {
 export declare function renderScan(result: SweepResult): string | null;
 /** The one-line verdict a person reads first, and often only. */
 export declare function renderSummary(result: SweepResult): string;
+/**
+ * One repository as counts: a row per category with its total, how many are
+ * merged, and how many the sweep would delete, 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): 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;
@@ -39,5 +48,28 @@ export declare function renderText(result: SweepResult, opts?: {
 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[];
-/** An apply run as text: dropped rows, each step, then where the receipt is. */
+/** 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. */
+    pruned: number;
+    /** Dropped rows by reason. */
+    dropped: Record<string, number>;
+    /** Steps that failed: 0 or 1, since the first failure stops the run. */
+    failed: number;
+    /** 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, dropped and could not finish. */
+export declare function renderApplySummary(receipt: Receipt): string[];
+/** An apply run as text: dropped rows, each step, a summary, then where the receipt is. */
 export declare function renderReceipt(receipt: Receipt, receiptPath: string | null): string;

package/dist/render.js

@@ -84,6 +84,7 @@ function totals(result) {
     for (const sweep of result.repos) {
         for (const bucket of Object.values(summarize(sweep.items))) {
             out.total += bucket.total;
+            out.merged += bucket.merged;
             out['safe-to-delete'] += bucket['safe-to-delete'];
             out['safe-to-keep'] += bucket['safe-to-keep'];
             out['needs-investigation'] += bucket['needs-investigation'];
@@ -129,6 +130,68 @@ export function renderSummary(result) {
     const suffix = tail.length > 0 ? ` (${tail.join(', ')})` : '';
     return `${counts['safe-to-delete']} to delete, ${counts['needs-investigation']} to review, across ${repos}${suffix}.`;
 }
+const COUNT_LABEL = {
+    local_branch: 'local branches',
+    worktree: 'worktrees',
+    remote_branch: 'remote branches',
+};
+const COUNT_COLUMNS = [
+    'total',
+    'merged',
+    'safe-to-delete',
+    'needs-investigation',
+    'safe-to-keep',
+];
+const COUNT_HEADINGS = ['total', 'merged', 'delete', 'review', 'keep'];
+/**
+ * One repository as counts: a row per category with its total, how many are
+ * merged, and how many the sweep would delete, review or keep.
+ */
+export function renderCounts(sweep) {
+    const lines = [repoHeader(sweep)];
+    if (sweep.error !== null) {
+        lines.push(`  error: ${sweep.error}`);
+        return lines.join('\n');
+    }
+    const buckets = summarize(sweep.items);
+    const labelWidth = Math.max(...Object.values(COUNT_LABEL).map((l) => l.length));
+    const cell = (text, heading) => text.padStart(Math.max(heading.length, 5));
+    lines.push(`  ${' '.repeat(labelWidth)}  ${COUNT_HEADINGS.map((h) => cell(h, h)).join('  ')}`);
+    for (const category of CATEGORY_ORDER) {
+        const bucket = buckets[category] ?? emptyBucket();
+        const cells = COUNT_COLUMNS.map((col, i) => cell(count(bucket[col]), COUNT_HEADINGS[i]));
+        lines.push(`  ${pad(COUNT_LABEL[category], labelWidth)}  ${cells.join('  ')}`);
+    }
+    return lines.join('\n');
+}
+/** The whole run as counts: a table per repository, then the one-line summary. */
+export function renderCountsText(result) {
+    const blocks = result.repos.map(renderCounts);
+    if (result.unresolved.length > 0) {
+        const lines = ['unresolved'];
+        const width = Math.max(...result.unresolved.map((row) => row.entry.length));
+        for (const row of result.unresolved)
+            lines.push(`  ${pad(row.entry, width)}   ${row.reason}`);
+        blocks.push(lines.join('\n'));
+    }
+    const scan = renderScan(result);
+    blocks.push(scan === null ? renderSummary(result) : `${scan}\n${renderSummary(result)}`);
+    return blocks.join('\n\n') + '\n';
+}
+/** The whole run's counts as JSON: no rows, no facts. */
+export function renderCountsJson(result) {
+    return (JSON.stringify({
+        repos: result.repos.map((sweep) => ({
+            path: sweep.path,
+            error: sweep.error,
+            repo: sweep.repo,
+            summary: summarize(sweep.items),
+        })),
+        unresolved: result.unresolved,
+        scan: result.scan,
+        summary: totals(result),
+    }, null, 2) + '\n');
+}
 /** The "Duplicate checkouts" section, or null when there are none. */
 function renderDuplicates(duplicates) {
     if (duplicates.length === 0)
@@ -201,7 +264,74 @@ export function proposedCommands(result) {
     }
     return out;
 }
-/** An apply run as text: dropped rows, each step, then where the receipt is. */
+/** Count a receipt's outcome. A dry run's `would-run` steps count as done. */
+export function summarizeReceipt(receipt) {
+    const out = {
+        deleted: { worktree: 0, local_branch: 0, remote_branch: 0 },
+        pruned: 0,
+        dropped: {},
+        failed: 0,
+        notRun: 0,
+    };
+    for (const d of receipt.dropped)
+        out.dropped[d.reason] = (out.dropped[d.reason] ?? 0) + 1;
+    for (const s of receipt.steps) {
+        if (s.result === 'failed')
+            out.failed += 1;
+        if (s.row === null)
+            continue;
+        if (s.result === 'pending') {
+            if (s.action !== 'unlock-worktree')
+                out.notRun += 1;
+            continue;
+        }
+        if (s.result !== 'ok' && s.result !== 'would-run')
+            continue;
+        if (s.action === 'remove-worktree')
+            out.deleted.worktree += 1;
+        else if (s.action === 'prune-worktrees')
+            out.pruned += 1;
+        else if (s.action === 'delete-local')
+            out.deleted.local_branch += 1;
+        else if (s.action === 'delete-remote')
+            out.deleted.remote_branch += 1;
+    }
+    return out;
+}
+/** Rows a receipt deletes or prunes, which is what a person is asked to approve. */
+export function rowsActedOn(summary) {
+    const d = summary.deleted;
+    return d.worktree + d.local_branch + d.remote_branch + summary.pruned;
+}
+const plural = (n, one, many) => `${n} ${n === 1 ? one : many}`;
+/** The closing lines of an apply run: what it deleted, dropped and could not finish. */
+export function renderApplySummary(receipt) {
+    const s = summarizeReceipt(receipt);
+    const dry = receipt.status === 'dry-run';
+    const parts = [
+        s.deleted.worktree > 0 ? plural(s.deleted.worktree, 'worktree', 'worktrees') : null,
+        s.deleted.local_branch > 0
+            ? plural(s.deleted.local_branch, 'local branch', 'local branches')
+            : null,
+        s.deleted.remote_branch > 0
+            ? plural(s.deleted.remote_branch, 'remote branch', 'remote branches')
+            : null,
+        s.pruned > 0 ? `${plural(s.pruned, 'stale worktree', 'stale worktrees')} pruned` : null,
+    ].filter((p) => p !== null);
+    const lines = [
+        `${dry ? 'would delete' : 'deleted'}: ${parts.length > 0 ? parts.join(', ') : 'nothing'}`,
+    ];
+    const dropped = Object.entries(s.dropped);
+    if (dropped.length > 0) {
+        const total = dropped.reduce((n, [, c]) => n + c, 0);
+        lines.push(`dropped ${total}: ${dropped.map(([reason, c]) => `${c} ${reason}`).join(', ')}`);
+    }
+    if (s.failed > 0) {
+        lines.push(`stopped at a failed step; ${plural(s.notRun, 'row', 'rows')} not run`);
+    }
+    return lines;
+}
+/** An apply run as text: dropped rows, each step, a summary, then where the receipt is. */
 export function renderReceipt(receipt, receiptPath) {
     const lines = [];
     for (const d of receipt.dropped) {
@@ -212,6 +342,9 @@ export function renderReceipt(receipt, receiptPath) {
         const tail = s.error ?? s.verification;
         lines.push(`${s.result.padEnd(8)} ${what}${tail ? ` (${tail})` : ''}`);
     }
+    if (lines.length > 0)
+        lines.push('');
+    lines.push(...renderApplySummary(receipt));
     lines.push(receiptPath === null
         ? `status: ${receipt.status}`
         : `receipt: ${receiptPath} (${receipt.status})`);

package/dist/status-line.d.ts

@@ -0,0 +1,24 @@
+/**
+ * One self-overwriting line on stderr saying what a run is doing, for a
+ * terminal. The sweep is synchronous, so the line moves between steps and
+ * between the items of a long step, not on a timer.
+ */
+import type { Step } from './receipt.ts';
+import type { SweepProgress } from './types.ts';
+/**
+ * A sweep step as one line, e.g. `[2/5] checking remote branches 37/427 · ~/work/api`.
+ * The path goes last, so a line cut to the terminal's width loses its tail first.
+ */
+export declare function describeSweep(p: SweepProgress, home?: string): string;
+/** An apply step as one line, e.g. `deleting 3/7: delete-remote origin/feat/x`. */
+export declare function describeStep(index: number, total: number, step: Step): string;
+export interface StatusLine {
+    /** Replace the line with `text`. */
+    update(text: string): void;
+    /** Erase the line, so other output starts on a clean row. Idempotent. */
+    clear(): void;
+}
+/** A line drawn with `\r` and erase-line, controls stripped, cut to `columns() - 1` display columns so it never wraps. */
+export declare function statusLine(write: (text: string) => void, columns: () => number): StatusLine;
+/** A status line that draws nothing. */
+export declare const NO_STATUS_LINE: StatusLine;

package/dist/status-line.js

@@ -0,0 +1,54 @@
+/**
+ * One self-overwriting line on stderr saying what a run is doing, for a
+ * terminal. The sweep is synchronous, so the line moves between steps and
+ * between the items of a long step, not on a timer.
+ */
+import { homedir } from 'node:os';
+import { fitWidth, stripControls } from '@osdlc/ux';
+const STEP_TEXT = {
+    discover: 'reading the repository',
+    fetch: 'fetching',
+    prs: 'listing pull requests (gh)',
+    worktrees: 'checking worktrees',
+    'local-branches': 'checking local branches',
+    'remote-branches': 'checking remote branches',
+};
+/** `~/x` for a path under the home directory. */
+function tilde(path, home) {
+    return path === home ? '~' : path.startsWith(`${home}/`) ? `~${path.slice(home.length)}` : path;
+}
+/**
+ * A sweep step as one line, e.g. `[2/5] checking remote branches 37/427 · ~/work/api`.
+ * The path goes last, so a line cut to the terminal's width loses its tail first.
+ */
+export function describeSweep(p, home = homedir()) {
+    const where = p.of > 1 ? `[${p.index}/${p.of}] ` : '';
+    const count = p.done === undefined ? '' : ` ${p.done + 1}/${p.total}`;
+    return `${where}${STEP_TEXT[p.step]}${count} · ${tilde(p.repo, home)}`;
+}
+/** An apply step as one line, e.g. `deleting 3/7: delete-remote origin/feat/x`. */
+export function describeStep(index, total, step) {
+    const what = step.row === null ? step.repo : step.row.id;
+    return `deleting ${index + 1}/${total}: ${step.action} ${what}`;
+}
+/** A line drawn with `\r` and erase-line, controls stripped, cut to `columns() - 1` display columns so it never wraps. */
+export function statusLine(write, columns) {
+    let shown = false;
+    return {
+        update(text) {
+            // Paths come off the disk: a name holding an escape or a newline must not
+            // reach the terminal, and a wide character must not wrap the line.
+            const width = Math.max(10, columns() - 1);
+            write(`\r\x1b[2K${fitWidth(stripControls(text), width)}`);
+            shown = true;
+        },
+        clear() {
+            if (!shown)
+                return;
+            write('\r\x1b[2K');
+            shown = false;
+        },
+    };
+}
+/** A status line that draws nothing. */
+export const NO_STATUS_LINE = { update() { }, clear() { } };

package/dist/sweep.d.ts

@@ -7,7 +7,7 @@
  */
 import type { CommandRunner } from '@osdlc/command-seam';
 import { type ProcessProbe } from './processes.ts';
-import { type RepoSweep, type Scope, type SweepResult } from './types.ts';
+import { type RepoSweep, type Scope, type SweepProgress, type SweepResult } from './types.ts';
 export interface SweepOptions {
     /** Which categories to gather. Defaults to all of them. */
     scope?: Iterable<Scope | string>;
@@ -43,6 +43,13 @@ export interface SweepOptions {
      * repository, over `ps` and `lsof`.
      */
     probe?: ProcessProbe | undefined;
+    /** Told before each step, and before each item of a step that walks many. For a status line. */
+    onProgress?: ((progress: SweepProgress) => void) | undefined;
+    /** Where this repository sits in a run of several, for {@link onProgress}. Defaults to 1 of 1. */
+    position?: {
+        index: number;
+        of: number;
+    } | undefined;
 }
 /**
  * Inventory one repository.

package/dist/sweep.js

@@ -34,6 +34,15 @@ export function sweepRepo(path, opts = {}) {
     const scope = scopeSet(opts.scope);
     const { git, gh } = clients(path, opts);
     const only = opts.branch;
+    const at = opts.position ?? { index: 1, of: 1 };
+    const report = (step, done, total) => opts.onProgress?.({
+        repo: path,
+        ...at,
+        step,
+        ...(done === undefined || total === undefined ? {} : { done, total }),
+    });
+    const ticker = (step) => (done, total) => report(step, done, total);
+    report('discover');
     let repo;
     try {
         repo = discoverRepo(path, {
@@ -53,6 +62,7 @@ export function sweepRepo(path, opts = {}) {
     }
     const cwd = only === undefined ? (opts.cwd ?? process.cwd()) : repo.root;
     if (opts.fetch === true && repo.remote !== null) {
+        report('fetch');
         const fetched = git
             .at(repo.root)
             .try.fetch(repo.remote, undefined, { prune: true, quiet: true, noWriteFetchHead: true });
@@ -67,6 +77,8 @@ export function sweepRepo(path, opts = {}) {
         repo = { ...repo, fetched: true };
     }
     try {
+        if (repo.hasGh && repo.ghAuthenticated)
+            report('prs');
         const prs = fetchPrs(repo, gh, only);
         const items = [];
         // Worktrees are gathered whenever local branches are, even if they are not
@@ -75,7 +87,7 @@ export function sweepRepo(path, opts = {}) {
         let worktreeBranches = new Set();
         if (scope.has('worktrees') || scope.has('local-branches')) {
             ;
-            [worktreeItems, worktreeBranches] = gatherWorktrees(repo, prs, cwd, git, only, opts.probe ?? defaultProcessProbe());
+            [worktreeItems, worktreeBranches] = gatherWorktrees(repo, prs, cwd, git, only, opts.probe ?? defaultProcessProbe(), ticker('worktrees'));
         }
         if (scope.has('worktrees'))
             items.push(...worktreeItems);
@@ -86,13 +98,13 @@ export function sweepRepo(path, opts = {}) {
                 : new Set(worktreeItems
                     .filter((item) => !item.deletable)
                     .map((item) => String(item.facts['branch'])));
-            const localItems = gatherLocalBranches(repo, prs, pinned, git, only);
+            const localItems = gatherLocalBranches(repo, prs, pinned, git, only, ticker('local-branches'));
             localBranchNames = new Set(localItems.map((item) => item.id));
             if (scope.has('local-branches'))
                 items.push(...localItems);
         }
         if (scope.has('remote-branches')) {
-            items.push(...gatherRemoteBranches(repo, prs, localBranchNames, git, only));
+            items.push(...gatherRemoteBranches(repo, prs, localBranchNames, git, only, ticker('remote-branches')));
         }
         return { repo, path, items, error: null };
     }
@@ -119,7 +131,8 @@ export function sweepRepos(entries, opts = {}) {
         ...(opts.baseDir === undefined ? {} : { baseDir: opts.baseDir }),
         ...(opts.onWarn === undefined ? {} : { onWarn: opts.onWarn }),
     });
-    const repos = resolution.repos.map((root) => sweepRepo(root, opts));
+    const of = resolution.repos.length;
+    const repos = resolution.repos.map((root, i) => sweepRepo(root, { ...opts, position: { index: i + 1, of } }));
     return {
         repos,
         unresolved: resolution.unresolved,

package/dist/types.d.ts

@@ -9,6 +9,19 @@
 export type Classification = 'safe-to-delete' | 'safe-to-keep' | 'needs-investigation';
 /** The kinds of thing a sweep inventories. */
 export type Category = 'local_branch' | 'worktree' | 'remote_branch';
+/**
+ * What a sweep is doing, for a status line. `repo` is the path being swept;
+ * `index` and `of` place it among the run's repositories. `done` and `total`
+ * count items within a step that walks many.
+ */
+export interface SweepProgress {
+    repo: string;
+    index: number;
+    of: number;
+    step: 'discover' | 'fetch' | 'prs' | 'worktrees' | 'local-branches' | 'remote-branches';
+    done?: number;
+    total?: number;
+}
 /** Which categories to gather. */
 export declare const ALL_SCOPES: readonly ["local-branches", "worktrees", "remote-branches"];
 export type Scope = (typeof ALL_SCOPES)[number];
@@ -139,6 +152,8 @@ export declare function findDuplicateCheckouts(repos: readonly ({
 export declare function emptyScan(): ScanStats;
 export interface SummaryBucket {
     total: number;
+    /** Rows whose work is on the default branch (`facts.merged`). Rows kept for structure are not judged. */
+    merged: number;
     'safe-to-delete': number;
     'safe-to-keep': number;
     'needs-investigation': number;

package/dist/types.js

@@ -48,7 +48,7 @@ export function emptyScan() {
     return { containers: 0, directoriesScanned: 0, depthLimited: 0, checkoutsFound: 0 };
 }
 export function emptyBucket() {
-    return { total: 0, 'safe-to-delete': 0, 'safe-to-keep': 0, 'needs-investigation': 0 };
+    return { total: 0, merged: 0, 'safe-to-delete': 0, 'safe-to-keep': 0, 'needs-investigation': 0 };
 }
 /** Per-category counts over `items`. */
 export function summarize(items) {
@@ -56,6 +56,8 @@ export function summarize(items) {
     for (const item of items) {
         const bucket = (out[item.category] ??= emptyBucket());
         bucket.total += 1;
+        if (item.facts['merged'] === true)
+            bucket.merged += 1;
         bucket[item.classification] += 1;
     }
     return out;