@osdlc/repo-cleaner 0.11.0 → 0.13.0

package/dist/cli.js

@@ -26,14 +26,16 @@ 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 { resolveBranch } from "./branches.js";
 import { VENDOR_DIRS } from "./devlink.js";
 import { ensureMirror, mirrorProblem } from "./remote-mirror.js";
 import { ApplyArgumentError, applyPlan, parseGrant, parseRowRef } from "./apply.js";
 import { PLAN_VERSION, fileStamp, parsePlan, planRepo, readPlan, writePlan, } from "./plan.js";
 import { RECEIPT_VERSION } from "./receipt.js";
-import { proposedCommands, renderCountsJson, renderCountsText, renderJson, renderReceipt, renderSummary, renderText, rowsActedOn, summarizeReceipt, } from "./render.js";
+import { PLAIN, proposedCommands, renderCountsJson, renderCountsText, renderJson, renderPreview, renderPreviewDrops, renderReceipt, renderStepFailure, renderSummary, renderText, rowsActedOn, summarizeReceipt, TERMINAL_STYLE, } from "./render.js";
 import { NO_STATUS_LINE, describeStep, describeSweep, statusLine, } from "./status-line.js";
+import { stepBoard } from "./step-board.js";
 import { sweepRepos } from "./sweep.js";
 const EXIT_NOTHING_TO_SWEEP = 10;
 const EXIT_STEP_FAILED = 11;
@@ -49,12 +51,16 @@ const SWEEP_FLAGS = {
     only: {
         kind: 'list',
         valueName: 'list',
-        help: `comma-separated: ${Object.keys(ONLY).join(', ')} (default: all)`,
+        help: `comma-separated: ${Object.keys(ONLY).join(', ')} (default: worktrees, branches; remotes with --remotes)`,
+    },
+    remotes: {
+        kind: 'boolean',
+        help: 'also sweep remote branches, which is slower: each one is compared with the default branch',
     },
     branch: {
         kind: 'string',
         valueName: 'name|HEAD',
-        help: 'only this branch of this repository: its worktree, local and remote branch',
+        help: 'only this branch of this repository: its worktree and local branch, and its remote branch with --remotes',
     },
     remote: {
         kind: 'string',
@@ -68,11 +74,15 @@ const SWEEP_FLAGS = {
         commaSeparated: false,
         help: 'sweep the branches of this remote with no checkout of your own, through a clone kept in the cache directory; repeatable',
     },
-    gh: { kind: 'boolean', negatable: true, help: 'classify on git evidence alone' },
+    gh: {
+        kind: 'boolean',
+        negatable: true,
+        help: 'with --remotes: classify on git evidence alone (without --remotes gh is never called)',
+    },
     fetch: {
         kind: 'boolean',
         negatable: true,
-        help: 'classify on the remote-tracking refs already on disk',
+        help: 'with --remotes: classify on the remote-tracking refs already on disk (without --remotes nothing is fetched)',
     },
     progress: {
         kind: 'boolean',
@@ -96,8 +106,9 @@ const OUTPUT = {
 };
 const statusCli = () => defineCli({
     name: NAME,
-    summary: 'Inventory branches, worktrees and remote branches, and say which have been merged into ' +
-        'the default branch. Fetches each remote first; deletes nothing.',
+    summary: 'Inventory local branches and worktrees (remote branches too with --remotes), and say ' +
+        'which have been merged into the default branch. Offline unless --remotes, which fetches ' +
+        'each remote first and asks gh about pull requests; deletes nothing.',
     positionals: PATHS,
     flags: {
         ...SWEEP_FLAGS,
@@ -117,7 +128,7 @@ swept as ./<name>.`,
 });
 const summaryCli = () => defineCli({
     name: `${NAME} summary`,
-    summary: 'Count local branches, worktrees and remote branches per repository: how many there are, ' +
+    summary: 'Count local branches and worktrees (and remote branches with --remotes) per repository: how many there are, ' +
         'how many are merged into the default branch, and how many would be deleted, pruned, reviewed or kept.',
     positionals: PATHS,
     flags: { ...SWEEP_FLAGS, output: OUTPUT },
@@ -160,6 +171,13 @@ const applyCli = () => defineCli({
             commaSeparated: false,
             help: 'apply only this row, e.g. local_branch:feat/x; repeatable (default: every row)',
         },
+        keep: {
+            kind: 'list',
+            valueName: 'remote_branch:id',
+            default: [],
+            commaSeparated: false,
+            help: 'keep this remote branch, but refuse the run if its tip moved since the plan, e.g. remote_branch:origin/feat/x; repeatable',
+        },
         allow: {
             kind: 'list',
             valueName: 'risk[=category:id]',
@@ -218,10 +236,31 @@ function failure(ctx, err) {
     ctx.io.stderr(`${NAME}: ${err instanceof Error ? err.message : String(err)}\n`);
     return EXIT.error;
 }
+/** Color for a report on `stream`, when it is a terminal that takes color. */
+function styleFor(ctx, stream) {
+    const level = detectColorLevel({ env: ctx.env, isTTY: ctx.terminal?.[stream] === true });
+    return level === 'none' ? PLAIN : TERMINAL_STYLE;
+}
+/** The note under a text report that left remote branches out, or '' when it did not. */
+function remotesNote(swept, style) {
+    if (swept.kind !== 'ok' || swept.scope.includes('remote-branches'))
+        return '';
+    if (!swept.result.repos.some((r) => r.repo?.remote != null))
+        return '';
+    return (style.muted('Local only: nothing fetched, no gh, remote branches not checked; add --remotes for all three.') + '\n');
+}
 /** Where `--remote-url` keeps its clones. */
 function mirrorCache(ctx) {
     return systemDirs(VENDOR_DIRS, { env: ctx.env }).standalone(NAME).cache().app('remotes').path;
 }
+/** Local work by default: remote branches only when asked for, with `--remotes` or `--only remotes`. */
+const LOCAL_SCOPE = ['worktrees', 'local-branches'];
+function sweepScope(only, remotes) {
+    const scope = only === undefined ? [...LOCAL_SCOPE] : only.map((s) => ONLY[s]);
+    if (remotes && !scope.includes('remote-branches'))
+        scope.push('remote-branches');
+    return scope;
+}
 /** Validate the sweep flags and run the sweep, or answer with the exit code. */
 function sweep(name, v, paths, ctx, status) {
     const only = v.only?.filter((s) => s !== '');
@@ -261,17 +300,20 @@ function sweep(name, v, paths, ctx, status) {
     catch (err) {
         return { kind: 'exit', code: failure(ctx, err) };
     }
+    const scope = urls.length > 0 ? ['remote-branches'] : sweepScope(only, v.remotes);
+    const online = scope.includes('remote-branches');
     const options = {
         baseDir: ctx.cwd,
         cwd: ctx.cwd,
-        noGh: !v.gh,
-        fetch: v.fetch,
+        // Local by default means offline: the fetch and gh go with remote branches.
+        noGh: !(online && v.gh),
+        fetch: online && v.fetch,
         branch,
         // Mid-walk, while the wait is happening — the summary comes too late to
         // explain why the tool appeared to hang.
         onWarn: (message) => ctx.io.stderr(`${NAME}: ${message}\n`),
         ...(v.progress ? { onProgress: (p) => status.update(describeSweep(p)) } : {}),
-        ...(only === undefined ? {} : { scope: only.map((s) => ONLY[s]) }),
+        scope,
         ...(v.remote === undefined ? {} : { remote: v.remote }),
     };
     let entries = paths.length > 0 ? [...paths] : [ctx.cwd];
@@ -288,7 +330,6 @@ function sweep(name, v, paths, ctx, status) {
             status.clear();
             return { kind: 'exit', code: failure(ctx, err) };
         }
-        options.scope = ['remote-branches'];
     }
     if (v.progress)
         status.update(`${NAME}: finding repositories`);
@@ -303,7 +344,7 @@ function sweep(name, v, paths, ctx, status) {
         return { kind: 'exit', code: failure(ctx, new Error(refused)) };
     if (result.repos.length === 0)
         return { kind: 'nothing', result };
-    return { kind: 'ok', result, branch, values: v };
+    return { kind: 'ok', result, branch, values: v, scope, noGh: options.noGh === true };
 }
 /**
  * Name each repository the sweep could not read, on stderr. True when there
@@ -319,13 +360,13 @@ function reportUnreadable(ctx, name, result) {
 function planOf(swept, now) {
     const opts = {
         remote: swept.values.remote ?? null,
-        noGh: !swept.values.gh,
+        noGh: swept.noGh,
         branch: swept.branch ?? null,
     };
     return {
         version: PLAN_VERSION,
         created_at: now.toISOString(),
-        repos: swept.result.repos.flatMap((s) => s.repo === null ? [] : [planRepo(s.repo.root, opts, s.items)]),
+        repos: swept.result.repos.flatMap((s) => s.repo === null ? [] : [planRepo(s.repo.root, { ...opts, fetch: s.repo.fetched }, s.items)]),
     };
 }
 function runStatus(argv, ctx, status) {
@@ -335,7 +376,8 @@ function runStatus(argv, ctx, status) {
     if (parsed.status === 'error')
         return usageError(ctx, NAME, parsed.message);
     const v = parsed.values;
-    const render = (r) => v.output === 'json' ? renderJson(r) : renderText(r, { keep: v.keep });
+    const style = styleFor(ctx, 'stdout');
+    const render = (r) => v.output === 'json' ? renderJson(r) : renderText(r, { keep: v.keep, style });
     const swept = sweep(NAME, v, parsed.positionals, ctx, status);
     if (swept.kind === 'exit')
         return swept.code;
@@ -350,6 +392,8 @@ function runStatus(argv, ctx, status) {
     }
     else {
         ctx.io.stdout(render(swept.result));
+        if (v.output === 'text')
+            ctx.io.stdout(remotesNote(swept, style));
     }
     return EXIT.ok;
 }
@@ -361,11 +405,14 @@ function runSummary(argv, ctx, status) {
     if (parsed.status === 'error')
         return usageError(ctx, name, parsed.message);
     const v = parsed.values;
-    const render = (r) => v.output === 'json' ? renderCountsJson(r) : renderCountsText(r);
+    const style = styleFor(ctx, 'stdout');
+    const render = (r) => v.output === 'json' ? renderCountsJson(r) : renderCountsText(r, style);
     const swept = sweep(name, v, parsed.positionals, ctx, status);
     if (swept.kind === 'exit')
         return swept.code;
     ctx.io.stdout(render(swept.result));
+    if (v.output === 'text')
+        ctx.io.stdout(remotesNote(swept, style));
     return swept.kind === 'nothing' ? EXIT_NOTHING_TO_SWEEP : EXIT.ok;
 }
 function runPlan(argv, ctx, status) {
@@ -386,7 +433,8 @@ function runPlan(argv, ctx, status) {
     }
     const plan = planOf(swept, new Date());
     const unreadable = reportUnreadable(ctx, name, swept.result);
-    ctx.io.stderr(renderSummary(swept.result) + '\n');
+    const style = styleFor(ctx, 'stderr');
+    ctx.io.stderr(renderSummary(swept.result, style) + '\n' + remotesNote(swept, style));
     if (v.out === '-') {
         ctx.io.stdout(`${JSON.stringify(plan, null, 2)}\n`);
     }
@@ -402,6 +450,7 @@ function receiptBeside(planPath, now) {
     const stem = basename(planPath).replace(/\.json$/i, '');
     return join(dirname(planPath), `${stem}.receipt-${fileStamp(now)}.json`);
 }
+const dropKey = (d) => JSON.stringify([d.repo, d.category, d.id]);
 /** Rows the run would delete or prune: one each, however many steps (an unlock, a remove) it takes. */
 function wouldRun(receipt) {
     return rowsActedOn(summarizeReceipt(receipt));
@@ -476,9 +525,11 @@ function runApply(argv, ctx, deps, status) {
     const v = parsed.values;
     const paths = parsed.positionals;
     let rows;
+    let keep;
     let grants;
     try {
         rows = v.row.map(parseRowRef);
+        keep = v.keep.map(parseRowRef);
         grants = v.allow.map(parseGrant);
     }
     catch (err) {
@@ -507,10 +558,14 @@ function runApply(argv, ctx, deps, status) {
     }
     const ok = () => (loaded.unreadable ? EXIT.error : EXIT.ok);
     const repoRoot = v.repoRoot === undefined ? undefined : resolve(ctx.cwd, v.repoRoot);
-    const print = (receipt, shownPath) => {
+    // On a terminal the run is shown live: every step first, then each one
+    // checked off as it finishes, with a bar on the status line.
+    const live = v.output === 'text' && ctx.terminal?.stdout === true;
+    const style = styleFor(ctx, 'stdout');
+    const print = (receipt, shownPath, steps = true) => {
         ctx.io.stdout(v.output === 'json'
             ? `${JSON.stringify({ receiptPath: shownPath, summary: summarizeReceipt(receipt), receipt }, null, 2)}\n`
-            : renderReceipt(receipt, shownPath));
+            : renderReceipt(receipt, shownPath, style, { steps }));
     };
     const planned = plan.repos.filter((r) => repoRoot === undefined || resolve(r.root) === resolve(repoRoot));
     if (repoRoot !== undefined && planned.length === 0) {
@@ -527,6 +582,7 @@ function runApply(argv, ctx, deps, status) {
         callerCwd: ctx.cwd,
         planPath: source,
         repoRoot,
+        keep,
         // An implicit selection runs only safe-to-delete rows, in the preview and
         // in the run it confirms, whose rows are passed explicitly.
         safeOnly: rows.length === 0,
@@ -548,11 +604,16 @@ function runApply(argv, ctx, deps, status) {
         });
     }
     catch (err) {
+        if (err instanceof ApplyArgumentError)
+            return usageError(ctx, name, err.message);
         return failure(ctx, err);
     }
     const count = wouldRun(preview);
     if (v.dryRun || count === 0) {
-        print(preview, null);
+        if (live)
+            ctx.io.stdout(renderPreview(preview, style));
+        else
+            print(preview, null);
         return ok();
     }
     if (!v.yes) {
@@ -560,10 +621,22 @@ function runApply(argv, ctx, deps, status) {
         if (declined !== null)
             return declined;
     }
+    else if (live) {
+        ctx.io.stdout(renderPreview(preview, style));
+    }
+    if (live)
+        ctx.io.stdout('\n');
     // Only what the preview showed: rows it dropped stay dropped.
     // Pinned to their repositories: a branch name two repositories share stays two rows.
-    const approved = preview.steps.flatMap((s) => s.row === null ? [] : [{ ...s.row, repo: s.repo }]);
+    // A kept row's tip check is not a selection; `keep` carries it again.
+    const approved = preview.steps.flatMap((s) => s.row === null || s.action === 'verify-remote' ? [] : [{ ...s.row, repo: s.repo }]);
     const approvedGrants = grants.filter((g) => g.row === null || approved.some((r) => r.category === g.row.category && r.id === g.row.id));
+    const size = deps.terminalSize ??
+        (() => ({
+            width: ctx.terminal?.columns || process.stdout.columns || 80,
+            height: process.stdout.rows || 24,
+        }));
+    let board;
     let receipt;
     try {
         receipt = applyPlan(plan, approved, approvedGrants, {
@@ -571,12 +644,40 @@ function runApply(argv, ctx, deps, status) {
             dryRun: false,
             receiptPath,
             dropped: preview.dropped,
+            ...(live
+                ? {
+                    // The board carries the run's progress; the status line stays clear.
+                    onStart: (steps) => {
+                        board = stepBoard(ctx.io.stdout, steps, size, style);
+                        board.draw(null);
+                    },
+                    onStep: (i) => board?.draw(i),
+                    onStepDone: (_i, _total, step) => {
+                        board?.draw(null);
+                        // Here rather than after the run: a receipt that then cannot be
+                        // saved must not take the step's own error with it.
+                        if (step.result === 'failed') {
+                            ctx.io.stdout(`\n${renderStepFailure(step, style)}\n`);
+                        }
+                    },
+                }
+                : {}),
         });
     }
     catch (err) {
         return failure(ctx, err);
     }
-    print(receipt, receiptPath);
+    status.clear();
+    if (live) {
+        // The run's own re-check can drop a row the preview showed, if it moved
+        // while the question was open: say which, since it gets no tick.
+        const seen = new Set(preview.dropped.map(dropKey));
+        const late = receipt.dropped.filter((d) => !seen.has(dropKey(d)));
+        if (late.length > 0)
+            ctx.io.stdout(`\n${renderPreviewDrops(late, style)}`);
+        ctx.io.stdout('\n');
+    }
+    print(receipt, receiptPath, !live);
     if (receiptPath === null) {
         ctx.io.stderr(`${name}: no receipt written; pass --receipt <file> to keep one\n`);
     }
@@ -589,7 +690,7 @@ function runApply(argv, ctx, deps, status) {
 function confirm(ctx, name, preview, count, json, deps) {
     // The preview is for the person answering, so it goes where the question does.
     const show = json ? ctx.io.stderr : ctx.io.stdout;
-    show(renderReceipt(preview, null));
+    show(renderPreview(preview, styleFor(ctx, json ? 'stderr' : 'stdout')));
     const answer = (deps.confirm ?? terminalConfirm)(`Delete ${count} item${count === 1 ? '' : 's'}?`);
     if (answer === null) {
         return usageError(ctx, name, 'refusing to delete without a terminal to ask; pass --yes');

package/dist/index.d.ts

@@ -18,7 +18,7 @@ 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, type RowSelection, parseGrant, parseRowRef, type ApplyOptions, type Grant, } from './apply.ts';
+export { ApplyArgumentError, ApplyRefused, applyPlan, type RowSelection, parseGrant, parseRowRef, type ApplyOptions, type Grant, } from './apply.ts';
 export type { Annotate, HostHooks } from './hooks.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';

package/dist/index.js

@@ -18,7 +18,7 @@ export { classifyLocalBranch, classifyRemoteBranch, gatherLocalBranches, gatherR
 export { classifyWorktree, gatherWorktrees, hasBlockers, worktreePruneCommand, worktreeRemoveCommand, worktreeUnlockCommand, } from "./worktrees.js";
 export { DiscoveryFailed, discoverRepo } from "./discover.js";
 export { assessLanding, patchEquivalent } from "./landing.js";
-export { ApplyArgumentError, applyPlan, parseGrant, parseRowRef, } from "./apply.js";
+export { ApplyArgumentError, ApplyRefused, applyPlan, parseGrant, parseRowRef, } from "./apply.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";

package/dist/plan.d.ts

@@ -29,6 +29,7 @@ export declare const PlanRepoSchema: z.ZodObject<{
     remote: z.ZodNullable<z.ZodString>;
     no_gh: z.ZodBoolean;
     branch: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    fetch: z.ZodDefault<z.ZodBoolean>;
     rows: z.ZodArray<z.ZodObject<{
         category: z.ZodEnum<{
             local_branch: "local_branch";
@@ -53,6 +54,7 @@ export declare const PlanSchema: z.ZodObject<{
         remote: z.ZodNullable<z.ZodString>;
         no_gh: z.ZodBoolean;
         branch: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        fetch: z.ZodDefault<z.ZodBoolean>;
         rows: z.ZodArray<z.ZodObject<{
             category: z.ZodEnum<{
                 local_branch: "local_branch";
@@ -89,6 +91,7 @@ export declare function planRepo(root: string, opts: {
     remote: string | null;
     noGh: boolean;
     branch?: string | null;
+    fetch?: boolean;
 }, 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;

package/dist/plan.js

@@ -23,6 +23,12 @@ export const PlanRepoSchema = z.object({
     no_gh: z.boolean(),
     /** The `branch` the sweep was narrowed to; the re-sweep uses the same. */
     branch: z.string().nullable().default(null),
+    /**
+     * Whether the sweep fetched before classifying. The re-sweep fetches too, so
+     * it judges against the remote's current default branch, as the sweep did.
+     * A plan written before this field reads as not fetched.
+     */
+    fetch: z.boolean().default(false),
     rows: z.array(PlanRowSchema),
 });
 export const PlanSchema = z.object({
@@ -78,7 +84,14 @@ export function planRepo(root, opts, items) {
             fingerprint: fingerprint(item),
         });
     }
-    return { root, remote: opts.remote, no_gh: opts.noGh, branch: opts.branch ?? null, rows };
+    return {
+        root,
+        remote: opts.remote,
+        no_gh: opts.noGh,
+        branch: opts.branch ?? null,
+        fetch: opts.fetch ?? false,
+        rows,
+    };
 }
 /** A UTC timestamp safe in a file name, e.g. `2026-10-04T12-30-05-123Z`. */
 export function fileStamp(d) {

package/dist/receipt.d.ts

@@ -26,6 +26,7 @@ export declare const DroppedSchema: z.ZodObject<{
         "facts-changed": "facts-changed";
         "not-authorized": "not-authorized";
         duplicate: "duplicate";
+        kept: "kept";
     }>;
     detail: z.ZodString;
 }, z.core.$strip>;
@@ -41,6 +42,7 @@ export declare const StepSchema: z.ZodObject<{
         id: z.ZodString;
     }, z.core.$strip>>;
     action: z.ZodEnum<{
+        "verify-remote": "verify-remote";
         "unlock-worktree": "unlock-worktree";
         "remove-worktree": "remove-worktree";
         "delete-local": "delete-local";
@@ -85,6 +87,7 @@ export declare const ReceiptSchema: z.ZodObject<{
             "facts-changed": "facts-changed";
             "not-authorized": "not-authorized";
             duplicate: "duplicate";
+            kept: "kept";
         }>;
         detail: z.ZodString;
     }, z.core.$strip>>;
@@ -99,6 +102,7 @@ export declare const ReceiptSchema: z.ZodObject<{
             id: z.ZodString;
         }, z.core.$strip>>;
         action: z.ZodEnum<{
+            "verify-remote": "verify-remote";
             "unlock-worktree": "unlock-worktree";
             "remove-worktree": "remove-worktree";
             "delete-local": "delete-local";

package/dist/receipt.js

@@ -13,6 +13,7 @@ export const DroppedSchema = RowRefSchema.extend({
         'facts-changed',
         'not-authorized',
         'duplicate',
+        'kept',
     ]),
     detail: z.string(),
 });
@@ -21,6 +22,7 @@ export const StepSchema = z.object({
     /** Null for the closing prune, which belongs to no row. */
     row: RowRefSchema.nullable(),
     action: z.enum([
+        'verify-remote',
         'unlock-worktree',
         'remove-worktree',
         'delete-local',

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, 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;