@osdlc/repo-cleaner 0.10.1 → 0.13.0

package/dist/remote-mirror.js

@@ -0,0 +1,123 @@
+/**
+ * Sweep a remote with no checkout of your own: a clone of it, kept in
+ * repo-cleaner's cache directory, stands in for the checkout.
+ *
+ * The clone is `--no-checkout`, so no files are written outside `.git`. It is
+ * not a partial (`--filter=blob:none`) clone: the patch comparison that
+ * finds squash-merged branches reads file contents, and a partial clone
+ * fetches them over the network one comparison at a time, which made a sweep
+ * of a few hundred branches take minutes instead of seconds. It is kept
+ * rather than thrown away so a plan written from it can be applied later: the
+ * plan names the clone's directory, and `apply` re-sweeps and pushes deletes
+ * from there. A later run reuses it, and the sweep's fetch brings it up to
+ * date.
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, 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. */
+export class RemoteMirrorError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'RemoteMirrorError';
+    }
+}
+/** Characters kept in a directory name; anything else becomes `-`. */
+const UNSAFE = /[^A-Za-z0-9._-]+/g;
+/**
+ * `text` with every URL's credentials removed: the user-info before `@` in a
+ * `scheme://` URL, and any query string or fragment. For a message or a name
+ * that must not carry a token.
+ */
+export function redactUrl(text) {
+    return text
+        .replace(/([a-z][a-z0-9+.-]*:\/\/)[^/@\s]*@/gi, '$1')
+        .replace(/([a-z][a-z0-9+.-]*:\/\/[^\s?#]*)[?#]\S*/gi, '$1');
+}
+/**
+ * The directory name for `url`'s mirror: readable `host-owner-repo`, then a
+ * hash of the whole URL so two URLs never share a mirror. The readable part
+ * is read from the URL with its credentials, query and fragment removed, so a
+ * token never reaches the name.
+ */
+export function mirrorName(url) {
+    const hash = createHash('sha256').update(url).digest('hex').slice(0, 12);
+    const parsed = parseRemoteRepo(redactUrl(url));
+    const readable = parsed === null
+        ? 'remote'
+        : `${parsed.host}-${parsed.owner}-${parsed.repo}`.replace(UNSAFE, '-');
+    return `${readable.replace(/^[.-]+/, '')}-${hash}`;
+}
+/**
+ * Why `dir` is not a mirror of `url` — or of whatever it was cloned from, when
+ * `url` is omitted — or null when it is. A mirror's `origin` has one fetch URL
+ * and pushes to that URL alone, so a delete cannot be sent elsewhere.
+ */
+export function mirrorProblem(dir, url, opts = {}) {
+    const git = new Git(dir, { runner: opts.git });
+    const fetch = git.try.remoteGetUrls('origin');
+    const push = git.try.remoteGetUrls('origin', { push: true });
+    if (!fetch.ok || !push.ok)
+        return `${dir} has no readable origin remote`;
+    const [from] = fetch.value;
+    if (fetch.value.length !== 1 || from === undefined) {
+        return `${dir} has ${fetch.value.length} origin URLs`;
+    }
+    if (url !== undefined && from !== url)
+        return `${dir} is a mirror of another URL`;
+    if (push.value.length !== 1 || push.value[0] !== from) {
+        return `${dir} pushes somewhere other than the URL it was cloned from`;
+    }
+    return null;
+}
+/**
+ * The directory of `url`'s mirror under `cacheDir`, cloned on first use. An
+ * existing mirror is reused as it is, once {@link mirrorProblem} finds
+ * nothing wrong with it; the sweep's own fetch brings it up to date. A first
+ * clone goes to a sibling directory and is renamed into place, so a clone
+ * that fails leaves nothing behind, and a run that loses a race to clone the
+ * same URL uses the winner's clone. Messages carry the URL with its
+ * credentials removed.
+ *
+ * @throws RemoteMirrorError when `url` is empty or looks like an option, when
+ *   the clone fails, or when the directory is not a mirror of `url`.
+ */
+export function ensureMirror(url, cacheDir, opts = {}) {
+    if (url === '' || url.startsWith('-')) {
+        throw new RemoteMirrorError(`not a remote URL: ${JSON.stringify(redactUrl(url))}`);
+    }
+    const shown = redactUrl(url);
+    const dir = join(cacheDir, mirrorName(url));
+    if (existsSync(dir)) {
+        const problem = mirrorProblem(dir, url, opts);
+        if (problem !== null) {
+            throw new RemoteMirrorError(`${problem}, not a mirror of ${shown}; remove the directory and run again`);
+        }
+        return dir;
+    }
+    mkdirSync(dirname(dir), { recursive: true });
+    const staging = `${dir}.partial-${process.pid}`;
+    rmSync(staging, { recursive: true, force: true });
+    try {
+        new Git(dirname(dir), { runner: opts.git }).rawChecked([
+            'clone',
+            '--quiet',
+            '--no-checkout',
+            '--',
+            url,
+            staging,
+        ]);
+        renameSync(staging, dir);
+    }
+    catch (err) {
+        rmSync(staging, { recursive: true, force: true });
+        // Another run cloned the same URL first and won the rename: use its clone.
+        if (existsSync(dir) && mirrorProblem(dir, url, opts) === null)
+            return dir;
+        const detail = err.failure?.detail ??
+            (err instanceof Error ? err.message : String(err));
+        throw new RemoteMirrorError(`cannot clone ${shown}: ${redactUrl(detail.split(url).join(shown)).trim()}`);
+    }
+    return dir;
+}

package/dist/render.d.ts

@@ -6,8 +6,31 @@
  * find. JSON carries everything the text report elides, including the facts
  * behind every verdict.
  */
-import type { Receipt } from './receipt.ts';
+import type { Receipt, Step } from './receipt.ts';
 import { type RepoSweep, type SweepItem, type SweepResult } from './types.ts';
+/**
+ * How a report colors its words. {@link PLAIN} leaves them as they are; the
+ * CLI passes {@link TERMINAL_STYLE} when the stream is a terminal that takes
+ * color.
+ */
+export interface Style {
+    /** What a run deletes. */
+    delete(text: string): string;
+    /** A stale link a run prunes. */
+    prune(text: string): string;
+    /** What a person has to look at: a review row, a dropped row. */
+    review(text: string): string;
+    /** What stays, or a step that succeeded. */
+    keep(text: string): string;
+    /** Detail under a row: commands, the receipt path. */
+    muted(text: string): string;
+    /** A heading or the line a person is asked to approve. */
+    strong(text: string): string;
+}
+/** No color. */
+export declare const PLAIN: Style;
+/** The basic terminal colors: red to delete, blue to prune, yellow to review, green to keep. */
+export declare const TERMINAL_STYLE: Style;
 /**
  * A row's authorizations for a report, e.g. `requires abandon-unmerged (drops 3
  * commits), confirm-open-pr`. Empty when the row needs none.
@@ -16,6 +39,7 @@ export declare function requiresNote(item: Pick<SweepItem, 'requires' | 'facts'>
 /** One repository's rows, indented under its header. */
 export declare function renderRepo(sweep: RepoSweep, opts?: {
     keep?: boolean;
+    style?: Style;
 }): string;
 /**
  * What the search cost, or null when nothing was searched — every entry
@@ -27,19 +51,20 @@ 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;
+export declare function renderSummary(result: SweepResult, style?: Style): string;
 /**
  * One repository as counts: a row per category with its total, how many are
- * merged, and how many the sweep would delete, review or keep.
+ * merged, and how many the sweep would delete, prune, review or keep.
  */
 export declare function renderCounts(sweep: RepoSweep): string;
 /** The whole run as counts: a table per repository, then the one-line summary. */
-export declare function renderCountsText(result: SweepResult): string;
+export declare function renderCountsText(result: SweepResult, style?: Style): string;
 /** The whole run's counts as JSON: no rows, no facts. */
 export declare function renderCountsJson(result: SweepResult): string;
 /** The whole run as text: duplicate checkouts, a section per repository, then the summary. */
 export declare function renderText(result: SweepResult, opts?: {
     keep?: boolean;
+    style?: Style;
 }): string;
 /**
  * The whole run as JSON, facts included. `extra` adds top-level keys, such as
@@ -71,5 +96,23 @@ export declare function summarizeReceipt(receipt: Receipt): ApplySummary;
 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[];
+/** The word a preview shows for a step: what it does to the row. */
+export declare const STEP_VERB: Record<Step['action'], string>;
+/**
+ * What `apply` is about to do, for the person asked to approve it: per
+ * repository, each row and the command that deletes it, the rows it will
+ * skip and why, then the counts. Terminal controls are stripped from what it
+ * shows, so a path or name cannot hide part of what is approved.
+ */
+export declare function renderPreview(receipt: Receipt, style?: Style): string;
+/** Rows dropped by a live run's own re-check, after the preview: each with why. */
+export declare function renderPreviewDrops(dropped: Receipt['dropped'], style?: Style): string;
+/**
+ * A failed step for a run shown live: `✗`, the row, and the error in full,
+ * which the step's row on the board is too narrow to hold.
+ */
+export declare function renderStepFailure(step: Step, style?: Style): string;
 /** An apply run as text: dropped rows, each step, a summary, then where the receipt is. */
-export declare function renderReceipt(receipt: Receipt, receiptPath: string | null): string;
+export declare function renderReceipt(receipt: Receipt, receiptPath: string | null, style?: Style, opts?: {
+    steps?: boolean;
+}): string;

package/dist/render.js

@@ -6,7 +6,8 @@
  * find. JSON carries everything the text report elides, including the facts
  * behind every verdict.
  */
-import { emptyBucket, isUnfetched, summarize, } from "./types.js";
+import { ansiColors, paint, stripControls } from '@osdlc/ux';
+import { emptyBucket, isPrune, isUnfetched, summarize, } from "./types.js";
 import { hasBlockers } from "./worktrees.js";
 /** Order categories consistently, whatever order they were gathered in. */
 const CATEGORY_ORDER = ['local_branch', 'worktree', 'remote_branch'];
@@ -17,6 +18,27 @@ const ACTION_LABEL = {
     'needs-investigation': 'review',
     'safe-to-keep': 'keep',
 };
+const same = (text) => text;
+/** No color. */
+export const PLAIN = {
+    delete: same,
+    prune: same,
+    review: same,
+    keep: same,
+    muted: same,
+    strong: same,
+};
+// The 16 basic colors, so the terminal's own theme decides the shades.
+const ANSI = ansiColors('ansi16', 'dark');
+/** The basic terminal colors: red to delete, blue to prune, yellow to review, green to keep. */
+export const TERMINAL_STYLE = {
+    delete: (t) => paint(t, ANSI['status-error']),
+    prune: (t) => paint(t, ANSI.accent),
+    review: (t) => paint(t, ANSI['status-warning']),
+    keep: (t) => paint(t, ANSI['status-success']),
+    muted: (t) => paint(t, ANSI['text-muted']),
+    strong: (t) => `\x1b[1m${t}\x1b[22m`,
+};
 function pad(s, width) {
     return s.length >= width ? s : s + ' '.repeat(width - s.length);
 }
@@ -54,11 +76,22 @@ function repoHeader(sweep) {
     ];
     return `${name}  (${bits.filter((b) => b !== null).join(', ')})`;
 }
+/** The color of a row's action word. */
+function actionStyle(style, action) {
+    if (action === 'delete')
+        return style.delete;
+    if (action === 'prune')
+        return style.prune;
+    if (action === 'review')
+        return style.review;
+    return style.keep;
+}
 /** One repository's rows, indented under its header. */
 export function renderRepo(sweep, opts = {}) {
-    const lines = [repoHeader(sweep)];
+    const style = opts.style ?? PLAIN;
+    const lines = [style.strong(repoHeader(sweep))];
     if (sweep.error !== null) {
-        lines.push(`  error: ${sweep.error}`);
+        lines.push(`  ${style.delete('error')}: ${sweep.error}`);
         return lines.join('\n');
     }
     const shown = sortItems(sweep.items).filter((item) => opts.keep === true || item.classification !== 'safe-to-keep');
@@ -69,13 +102,15 @@ export function renderRepo(sweep, opts = {}) {
     const idWidth = Math.min(38, Math.max(...shown.map((item) => ellipsize(item.id, 38).length)));
     const categoryWidth = Math.max(...shown.map((item) => item.category.length));
     for (const item of shown) {
-        const action = ACTION_LABEL[item.classification] ?? item.classification;
+        const action = isPrune(item)
+            ? 'prune'
+            : (ACTION_LABEL[item.classification] ?? item.classification);
         const note = requiresNote(item);
-        lines.push(`  ${pad(item.category, categoryWidth)}  ${pad(ellipsize(item.id, 38), idWidth)}  ${pad(action, 6)}  ${item.reason}${note ? `; ${note}` : ''}`);
+        lines.push(`  ${pad(item.category, categoryWidth)}  ${pad(ellipsize(item.id, 38), idWidth)}  ${actionStyle(style, action)(pad(action, 6))}  ${item.reason}${note ? `; ${note}` : ''}`);
         // A blocked row has no commands; what to do about each blocker goes there instead.
         const detail = hasBlockers(item) ? item.investigationParts : item.commands;
         for (const line of detail)
-            lines.push(`  ${' '.repeat(categoryWidth)}  ${line}`);
+            lines.push(`  ${' '.repeat(categoryWidth)}  ${style.muted(line)}`);
     }
     return lines.join('\n');
 }
@@ -86,6 +121,7 @@ function totals(result) {
             out.total += bucket.total;
             out.merged += bucket.merged;
             out['safe-to-delete'] += bucket['safe-to-delete'];
+            out.prune += bucket.prune;
             out['safe-to-keep'] += bucket['safe-to-keep'];
             out['needs-investigation'] += bucket['needs-investigation'];
         }
@@ -116,8 +152,12 @@ export function renderScan(result) {
         return line;
     return `${line} ${count(scan.depthLimited)} left unopened at the depth limit.`;
 }
+/** The `safe-to-delete` rows that delete something, not the ones that only prune a stale link. */
+function deleteOnly(bucket) {
+    return bucket['safe-to-delete'] - bucket.prune;
+}
 /** The one-line verdict a person reads first, and often only. */
-export function renderSummary(result) {
+export function renderSummary(result, style = PLAIN) {
     const counts = totals(result);
     const repos = `${result.repos.length} ${result.repos.length === 1 ? 'repository' : 'repositories'}`;
     const errors = result.repos.filter((sweep) => sweep.error !== null).length;
@@ -128,24 +168,28 @@ export function renderSummary(result) {
         tail.push(`${result.unresolved.length} ${result.unresolved.length === 1 ? 'entry' : 'entries'} unresolved`);
     }
     const suffix = tail.length > 0 ? ` (${tail.join(', ')})` : '';
-    return `${counts['safe-to-delete']} to delete, ${counts['needs-investigation']} to review, across ${repos}${suffix}.`;
+    const prune = counts.prune > 0 ? `${style.prune(`${counts.prune} to prune`)}, ` : '';
+    const del = style.delete(`${deleteOnly(counts)} to delete`);
+    const review = style.review(`${counts['needs-investigation']} to review`);
+    return `${del}, ${prune}${review}, across ${repos}${suffix}.`;
 }
 const COUNT_LABEL = {
     local_branch: 'local branches',
     worktree: 'worktrees',
     remote_branch: 'remote branches',
 };
+/** A count table's columns. `delete` leaves out the rows `prune` counts, so each row is in one of delete, prune, review and keep. */
 const COUNT_COLUMNS = [
-    'total',
-    'merged',
-    'safe-to-delete',
-    'needs-investigation',
-    'safe-to-keep',
+    { heading: 'total', of: (b) => b.total },
+    { heading: 'merged', of: (b) => b.merged },
+    { heading: 'delete', of: deleteOnly },
+    { heading: 'prune', of: (b) => b.prune },
+    { heading: 'review', of: (b) => b['needs-investigation'] },
+    { heading: 'keep', of: (b) => b['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.
+ * merged, and how many the sweep would delete, prune, review or keep.
  */
 export function renderCounts(sweep) {
     const lines = [repoHeader(sweep)];
@@ -156,16 +200,16 @@ export function renderCounts(sweep) {
     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('  ')}`);
+    lines.push(`  ${' '.repeat(labelWidth)}  ${COUNT_COLUMNS.map(({ heading }) => cell(heading, heading)).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]));
+        const cells = COUNT_COLUMNS.map(({ heading, of }) => cell(count(of(bucket)), heading));
         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) {
+export function renderCountsText(result, style = PLAIN) {
     const blocks = result.repos.map(renderCounts);
     if (result.unresolved.length > 0) {
         const lines = ['unresolved'];
@@ -175,7 +219,8 @@ export function renderCountsText(result) {
         blocks.push(lines.join('\n'));
     }
     const scan = renderScan(result);
-    blocks.push(scan === null ? renderSummary(result) : `${scan}\n${renderSummary(result)}`);
+    const summary = renderSummary(result, style);
+    blocks.push(scan === null ? summary : `${scan}\n${summary}`);
     return blocks.join('\n\n') + '\n';
 }
 /** The whole run's counts as JSON: no rows, no facts. */
@@ -219,7 +264,8 @@ export function renderText(result, opts = {}) {
         blocks.push(lines.join('\n'));
     }
     const scan = renderScan(result);
-    blocks.push(scan === null ? renderSummary(result) : `${scan}\n${renderSummary(result)}`);
+    const summary = renderSummary(result, opts.style);
+    blocks.push(scan === null ? summary : `${scan}\n${summary}`);
     return blocks.join('\n\n') + '\n';
 }
 /**
@@ -281,7 +327,9 @@ export function summarizeReceipt(receipt) {
         if (s.row === null)
             continue;
         if (s.result === 'pending') {
-            if (s.action !== 'unlock-worktree')
+            // Rows not reached are rows a run would have deleted; an unlock or a
+            // tip check deletes nothing.
+            if (s.action !== 'unlock-worktree' && s.action !== 'verify-remote')
                 out.notRun += 1;
             continue;
         }
@@ -331,22 +379,96 @@ export function renderApplySummary(receipt) {
     }
     return lines;
 }
+/** The word a preview shows for a step: what it does to the row. */
+export const STEP_VERB = {
+    'verify-remote': 'verify',
+    'unlock-worktree': 'unlock',
+    'remove-worktree': 'delete',
+    'delete-local': 'delete',
+    'delete-remote': 'delete',
+    'prune-worktrees': 'prune',
+};
+/** A step's result word, colored by what it says about the run. */
+function resultWord(step, style) {
+    const word = step.result.padEnd(8);
+    if (step.result === 'failed')
+        return style.delete(word);
+    if (step.result === 'ok')
+        return style.keep(word);
+    if (step.result === 'pending')
+        return style.muted(word);
+    return step.action === 'prune-worktrees' ? style.prune(word) : style.delete(word);
+}
+/**
+ * What `apply` is about to do, for the person asked to approve it: per
+ * repository, each row and the command that deletes it, the rows it will
+ * skip and why, then the counts. Terminal controls are stripped from what it
+ * shows, so a path or name cannot hide part of what is approved.
+ */
+export function renderPreview(receipt, style = PLAIN) {
+    const repos = [
+        ...new Set([...receipt.steps.map((s) => s.repo), ...receipt.dropped.map((d) => d.repo)]),
+    ];
+    const rows = [
+        ...receipt.steps.flatMap((s) => (s.row === null ? [] : [s.row])),
+        ...receipt.dropped,
+    ];
+    const categoryWidth = Math.max(0, ...rows.map((r) => r.category.length));
+    const row = (r) => r === null ? '' : `${pad(r.category, categoryWidth)}  ${ellipsize(stripControls(r.id), 60)}`;
+    const blocks = [];
+    for (const repo of repos) {
+        const lines = [style.strong(stripControls(repo))];
+        for (const s of receipt.steps.filter((s) => s.repo === repo)) {
+            const verb = STEP_VERB[s.action];
+            const color = actionStyle(style, verb === 'unlock' ? 'review' : verb);
+            lines.push(s.row === null ? `  ${color(verb)}` : `  ${color(pad(verb, 6))}  ${row(s.row)}`);
+            lines.push(`          ${style.muted(stripControls(s.command))}`);
+        }
+        for (const d of receipt.dropped.filter((d) => d.repo === repo)) {
+            lines.push(`  ${style.review(pad('skip', 6))}  ${row(d)}`);
+            lines.push(`          ${d.reason}: ${stripControls(d.detail)}`);
+        }
+        blocks.push(lines.join('\n'));
+    }
+    const [counts = '', ...rest] = renderApplySummary(receipt);
+    blocks.push([style.strong(counts), ...rest.map(style.review)].join('\n'));
+    return blocks.join('\n\n') + '\n';
+}
+/** Rows dropped by a live run's own re-check, after the preview: each with why. */
+export function renderPreviewDrops(dropped, style = PLAIN) {
+    return dropped
+        .map((d) => `  ${style.review('skip')}  ${stripControls(`${d.category}  ${ellipsize(d.id, 60)}`)}\n      ${style.review(stripControls(`${d.reason}: ${d.detail}`))}\n`)
+        .join('');
+}
+/**
+ * A failed step for a run shown live: `✗`, the row, and the error in full,
+ * which the step's row on the board is too narrow to hold.
+ */
+export function renderStepFailure(step, style = PLAIN) {
+    const verb = STEP_VERB[step.action];
+    const row = step.row === null ? '' : `${step.row.category}  ${ellipsize(step.row.id, 60)}`;
+    const line = stripControls(`${pad(verb, 6)}  ${row}`.trimEnd());
+    return `  ${style.delete('✗')} ${line}\n      ${style.delete(stripControls(step.error ?? 'failed'))}`;
+}
 /** An apply run as text: dropped rows, each step, a summary, then where the receipt is. */
-export function renderReceipt(receipt, receiptPath) {
+export function renderReceipt(receipt, receiptPath, style = PLAIN, opts = {}) {
     const lines = [];
-    for (const d of receipt.dropped) {
-        lines.push(`dropped  ${d.category}:${d.id} — ${d.reason} (${d.detail})`);
+    // A run shown live has printed its dropped rows and steps already.
+    for (const d of opts.steps === false ? [] : receipt.dropped) {
+        const shown = stripControls(`${d.category}:${d.id} — ${d.reason} (${d.detail})`);
+        lines.push(`${style.review('dropped  ')}${shown}`);
     }
-    for (const s of receipt.steps) {
+    for (const s of opts.steps === false ? [] : receipt.steps) {
         const what = s.row === null ? s.command : `${s.row.category}:${s.row.id} — ${s.command}`;
         const tail = s.error ?? s.verification;
-        lines.push(`${s.result.padEnd(8)} ${what}${tail ? ` (${tail})` : ''}`);
+        lines.push(`${resultWord(s, style)} ${stripControls(`${what}${tail ? ` (${tail})` : ''}`)}`);
     }
     if (lines.length > 0)
         lines.push('');
-    lines.push(...renderApplySummary(receipt));
-    lines.push(receiptPath === null
+    const [counts = '', ...rest] = renderApplySummary(receipt);
+    lines.push(style.strong(counts), ...rest.map(style.review));
+    lines.push(style.muted(receiptPath === null
         ? `status: ${receipt.status}`
-        : `receipt: ${receiptPath} (${receipt.status})`);
+        : `receipt: ${stripControls(receiptPath)} (${receipt.status})`));
     return lines.join('\n') + '\n';
 }

package/dist/status-line.d.ts

@@ -5,12 +5,14 @@
  */
 import type { Step } from './receipt.ts';
 import type { SweepProgress } from './types.ts';
+/** A bar `width` cells wide, filled for `done` of `total`, e.g. `█████░░░░░`. */
+export declare function progressBar(done: number, total: number, width?: number): string;
 /**
- * A sweep step as one line, e.g. `[2/5] checking remote branches 37/427 · ~/work/api`.
+ * 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`. */
+/** 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`. */

package/dist/status-line.js

@@ -17,19 +17,26 @@ const STEP_TEXT = {
 function tilde(path, home) {
     return path === home ? '~' : path.startsWith(`${home}/`) ? `~${path.slice(home.length)}` : path;
 }
+/** A bar `width` cells wide, filled for `done` of `total`, e.g. `█████░░░░░`. */
+export function progressBar(done, total, width = 20) {
+    const filled = total <= 0 ? width : Math.min(width, Math.round((done / total) * width));
+    return '█'.repeat(filled) + '░'.repeat(width - filled);
+}
 /**
- * A sweep step as one line, e.g. `[2/5] checking remote branches 37/427 · ~/work/api`.
+ * 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}`;
+    const count = p.done === undefined || p.total === undefined
+        ? ''
+        : ` ${progressBar(p.done, p.total)} ${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`. */
+/** 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}`;
+    return `deleting ${progressBar(index, total)} ${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) {

package/dist/step-board.d.ts

@@ -0,0 +1,34 @@
+/**
+ * `apply`'s steps as a vertical list redrawn in place on a terminal: one row
+ * per step with its own bar, empty while it waits, half full while it runs,
+ * full and ticked when it is done, and a bar for the whole run under the
+ * list. The run is synchronous, so the board moves between steps, not on a
+ * timer.
+ */
+import type { Step } from './receipt.ts';
+import { type Style } from './render.ts';
+/**
+ * The board's lines, each at most `width` columns, and at most `height - 1`
+ * of them: the cursor sits on the row under the last line, which must stay
+ * on screen. That is the run's bar under the rows that fit; a list longer
+ * than that shows a window that keeps the running step in view, with a line
+ * for the rows above and below it when there is room for one.
+ */
+export declare function boardLines(steps: readonly Step[], running: number | null, size: {
+    width: number;
+    height: number;
+}, style?: Style): string[];
+export interface StepBoard {
+    /** Draw with `running` as the step under way, or null between steps. */
+    draw(running: number | null): void;
+}
+/**
+ * A board on `write`. The first draw prints its lines; each later one moves
+ * the cursor back to the board's first line and rewrites them, erasing any
+ * line an earlier, taller frame left below. Lines are cut to one column
+ * short of the width, so none wraps and the line count stays right.
+ */
+export declare function stepBoard(write: (text: string) => void, steps: readonly Step[], size: () => {
+    width: number;
+    height: number;
+}, style?: Style): StepBoard;