@osdlc/repo-cleaner 0.11.0 → 0.14.0

package/dist/cli.js

@@ -26,14 +26,17 @@ 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 { PROVIDER_CHOICES } from "./providers/index.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 +52,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 +75,21 @@ 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, the same as --provider none (without --remotes no provider is asked)',
+    },
+    provider: {
+        kind: 'enum',
+        choices: PROVIDER_CHOICES,
+        valueName: 'name',
+        help: 'with --remotes: where pull requests come from: auto (by remote host), github (gh), gitlab (glab), none',
+    },
     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 +113,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 +135,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 +178,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 +243,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 !== '');
@@ -254,6 +300,10 @@ function sweep(name, v, paths, ctx, status) {
         if (conflict !== null)
             return { kind: 'exit', code: usageError(ctx, name, conflict) };
     }
+    if (!v.gh && v.provider !== undefined && v.provider !== 'none') {
+        const message = `--no-gh asks no provider; drop it or --provider ${v.provider}`;
+        return { kind: 'exit', code: usageError(ctx, name, message) };
+    }
     let branch;
     try {
         branch = v.branch === undefined ? undefined : resolveBranch(v.branch, new Git(ctx.cwd));
@@ -261,17 +311,21 @@ 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.
+        noProvider: !(online && v.gh) || v.provider === 'none',
+        fetch: online && v.fetch,
+        provider: v.provider,
         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 +342,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 +356,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, noProvider: options.noProvider === true };
 }
 /**
  * Name each repository the sweep could not read, on stderr. True when there
@@ -319,13 +372,14 @@ function reportUnreadable(ctx, name, result) {
 function planOf(swept, now) {
     const opts = {
         remote: swept.values.remote ?? null,
-        noGh: !swept.values.gh,
+        noProvider: swept.noProvider,
+        provider: swept.values.provider,
         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 +389,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 +405,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 +418,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 +446,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 +463,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 +538,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 +571,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 +595,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 +617,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 +634,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 +657,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 +703,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/discover.d.ts

@@ -1,10 +1,12 @@
 /**
  * What the sweep must know about a repository before it can classify anything:
  * where its main checkout is, what its default branch is called, which remote
- * to measure against, and whether `gh` can be asked about pull requests.
+ * to measure against, and which provider can be asked about pull requests.
  */
 import { type Git } from '@osdlc/typed-git';
+import type { CommandRunner } from '@osdlc/command-seam';
 import type { Gh } from '@osdlc/typed-gh';
+import { type PrProvider, type ProviderChoice, type ProviderName } from './providers/index.ts';
 import type { RepoInfo } from './types.ts';
 /**
  * Thrown when a path names no repository, or names one whose default branch
@@ -26,7 +28,14 @@ export declare class DiscoveryFailed extends Error {
  */
 export declare function discoverRepo(hint: string, opts: {
     remote?: string | null;
-    allowGh?: boolean;
+    /** False is `provider: 'none'`, whatever `provider` says. */
+    allowProvider?: boolean;
+    /** Which provider to ask for pull requests. Defaults to `auto`, by the remote's host. */
+    provider?: ProviderChoice | undefined;
     git: Git;
     gh: Gh;
+    /** The `glab` runner for the GitLab provider. Defaults to the real binary. */
+    glab?: CommandRunner | undefined;
+    /** The providers to choose from. Defaults to {@link providers} over `gh` and `glab`. */
+    providers?: Record<ProviderName, PrProvider> | undefined;
 }): RepoInfo;

package/dist/discover.js

@@ -1,9 +1,10 @@
 /**
  * What the sweep must know about a repository before it can classify anything:
  * where its main checkout is, what its default branch is called, which remote
- * to measure against, and whether `gh` can be asked about pull requests.
+ * to measure against, and which provider can be asked about pull requests.
  */
 import { parseRemoteRepo } from '@osdlc/typed-git';
+import { forgeTarget, probeProvider, providers, } from "./providers/index.js";
 /**
  * Thrown when a path names no repository, or names one whose default branch
  * cannot be determined. A single-repository caller lets it propagate; a
@@ -28,7 +29,7 @@ export class DiscoveryFailed extends Error {
 export function discoverRepo(hint, opts) {
     const { git, gh } = opts;
     const remoteHint = opts.remote ?? null;
-    const allowGh = opts.allowGh ?? true;
+    const allowProvider = opts.allowProvider ?? true;
     // `topLevel()` answers null for exit 128 only — "this is not a repository",
     // which is the answer to the question. Any other git failure throws.
     const top = git.at(hint).topLevel();
@@ -70,14 +71,24 @@ export function discoverRepo(hint, opts) {
         throw new DiscoveryFailed(`could not determine the default branch of ${root}`);
     // A short name for the report's header, so a fan-out over long paths stays
     // readable. It also keys duplicate checkouts.
-    const slug = remote === null ? null : remoteSlugOf(git.at(root).try.remoteGetUrl(remote));
+    const url = remote === null ? null : git.at(root).try.remoteGetUrl(remote);
+    const slug = url === null ? null : remoteSlugOf(url);
+    const remoteUrl = url?.ok === true && typeof url.value === 'string' ? url.value : null;
     const currentBranch = git.at(root).headRef() ?? '';
-    // The two halves separately, not `ready()`: the report says "gh not
-    // available" and "gh not authenticated" differently, because they send a
-    // person somewhere different.
-    const hasGh = allowGh && gh.at(root).installed();
-    const ghAuthenticated = hasGh && gh.at(root).authenticated();
-    return { root, slug, mainBranch, remote, currentBranch, hasGh, ghAuthenticated, fetched: false };
+    // Installed and signed in are probed separately: "not installed" and "not
+    // authenticated" send a person somewhere different.
+    const choice = allowProvider ? (opts.provider ?? 'auto') : 'none';
+    const target = forgeTarget(remoteUrl);
+    const provider = probeProvider(choice, root, target, opts.providers ?? providers({ gh, glab: opts.glab }));
+    return {
+        root,
+        slug,
+        mainBranch,
+        remote,
+        currentBranch,
+        provider,
+        fetched: false,
+    };
 }
 /**
  * `owner/name` for a github.com remote, `host/owner/name` for any other, or

package/dist/index.d.ts

@@ -18,12 +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, 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';
 export { defaultProcessProbe, isIdleShell, parseLockOwner, parseLsofCwd, type DefaultProbeOptions, type LockOwner, type ProcessHolder, type ProcessProbe, } from './processes.ts';
 export { fetchPrs } from './prs.ts';
+export { PROVIDER_CHOICES, PROVIDER_NAMES, chooseProvider, forgeTarget, githubProvider, gitlabProvider, probeProvider, providers, type ForgeTarget, type PrProvider, type ProviderChoice, type ProviderName, type ProviderStatus, } from './providers/index.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, renderApplySummary, renderReceipt, summarizeReceipt, type ApplySummary, renderRepo, renderScan, renderSummary, renderText, requiresNote, } from './render.ts';

package/dist/index.js

@@ -18,11 +18,12 @@ 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";
 export { fetchPrs } from "./prs.js";
+export { PROVIDER_CHOICES, PROVIDER_NAMES, chooseProvider, forgeTarget, githubProvider, gitlabProvider, probeProvider, providers, } from "./providers/index.js";
 export { expandTilde, isCheckoutRoot, resolveEntries, } from "./resolve.js";
 export { sweepRepo, sweepRepos } from "./sweep.js";
 export { proposedCommands, renderJson, renderApplySummary, renderReceipt, summarizeReceipt, renderRepo, renderScan, renderSummary, renderText, requiresNote, } from "./render.js";

package/dist/plan.d.ts

@@ -4,6 +4,7 @@
  * whose fingerprint no longer matches.
  */
 import { z } from 'zod';
+import { type ProviderChoice } from './providers/types.ts';
 import { type SweepItem } from './types.ts';
 export declare const PLAN_VERSION = 1;
 /** The categories a plan can hold, in the order apply runs them. */
@@ -28,7 +29,14 @@ export declare const PlanRepoSchema: z.ZodObject<{
     root: z.ZodString;
     remote: z.ZodNullable<z.ZodString>;
     no_gh: z.ZodBoolean;
+    provider: z.ZodOptional<z.ZodEnum<{
+        github: "github";
+        gitlab: "gitlab";
+        auto: "auto";
+        none: "none";
+    }>>;
     branch: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    fetch: z.ZodDefault<z.ZodBoolean>;
     rows: z.ZodArray<z.ZodObject<{
         category: z.ZodEnum<{
             local_branch: "local_branch";
@@ -52,7 +60,14 @@ export declare const PlanSchema: z.ZodObject<{
         root: z.ZodString;
         remote: z.ZodNullable<z.ZodString>;
         no_gh: z.ZodBoolean;
+        provider: z.ZodOptional<z.ZodEnum<{
+            github: "github";
+            gitlab: "gitlab";
+            auto: "auto";
+            none: "none";
+        }>>;
         branch: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        fetch: z.ZodDefault<z.ZodBoolean>;
         rows: z.ZodArray<z.ZodObject<{
             category: z.ZodEnum<{
                 local_branch: "local_branch";
@@ -87,8 +102,10 @@ export declare function sameFingerprint(a: Record<string, unknown>, b: Record<st
 /** One repository's plan entry: its deletable rows. */
 export declare function planRepo(root: string, opts: {
     remote: string | null;
-    noGh: boolean;
+    noProvider: boolean;
     branch?: string | null;
+    fetch?: boolean;
+    provider?: ProviderChoice | undefined;
 }, 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

@@ -5,6 +5,7 @@
  */
 import { readFileSync } from 'node:fs';
 import { z } from 'zod';
+import { PROVIDER_CHOICES } from "./providers/types.js";
 import { AUTHORIZATIONS } from "./types.js";
 import { writeJsonAtomic } from "./write-json.js";
 export const PLAN_VERSION = 1;
@@ -20,9 +21,22 @@ export const PlanRepoSchema = z.object({
     root: z.string(),
     /** The `remote` the sweep ran with; the re-sweep uses the same. */
     remote: z.string().nullable(),
+    /**
+     * True when the sweep asked no provider for pull requests. The name is the
+     * plan format's, from when GitHub was the only provider; renaming it would
+     * break every plan already written.
+     */
     no_gh: z.boolean(),
+    /** The provider choice the sweep ran with; absent is `auto`. `no_gh` wins over it. */
+    provider: z.enum(PROVIDER_CHOICES).optional(),
     /** 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 +92,15 @@ 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.noProvider,
+        ...(opts.provider === undefined || opts.provider === 'auto' ? {} : { provider: opts.provider }),
+        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/providers/github.d.ts

@@ -0,0 +1,10 @@
+/** Pull requests from GitHub, through `gh`. */
+import type { Gh } from '@osdlc/typed-gh';
+import type { PrProvider } from './types.ts';
+/** The most PRs one listing reads. */
+export declare const PR_LIMIT = 300;
+/**
+ * A provider over `gh pr list`. `gh` picks the repository from the checkout's
+ * remotes, so `target` is not consulted.
+ */
+export declare function githubProvider(gh: Gh): PrProvider;

package/dist/providers/github.js

@@ -0,0 +1,56 @@
+/** Pull requests from GitHub, through `gh`. */
+/** The fields classification consults. Asking for more costs latency. */
+const FIELDS = [
+    'number',
+    'state',
+    'mergedAt',
+    'headRefName',
+    'headRefOid',
+    'baseRefName',
+    'isCrossRepository',
+    'title',
+    'url',
+];
+/** The most PRs one listing reads. */
+export const PR_LIMIT = 300;
+/**
+ * A provider over `gh pr list`. `gh` picks the repository from the checkout's
+ * remotes, so `target` is not consulted.
+ */
+export function githubProvider(gh) {
+    return {
+        name: 'github',
+        words: { tool: 'gh', noun: 'PR', listing: 'gh pr list' },
+        probe(root) {
+            const available = gh.at(root).installed();
+            return { available, authenticated: available && gh.at(root).authenticated() };
+        },
+        listPrs(root, _target, branch) {
+            const rows = gh.at(root).prList({
+                state: 'all',
+                limit: PR_LIMIT,
+                fields: FIELDS,
+                head: branch,
+            });
+            if (rows === null)
+                return null;
+            const prs = [];
+            for (const row of rows.rows) {
+                // A fork's head branch is not this repository's branch, whatever its name.
+                if (!row.headRefName || row.isCrossRepository)
+                    continue;
+                prs.push({
+                    number: row.number,
+                    state: row.state,
+                    mergedAt: row.mergedAt,
+                    headRef: row.headRefName,
+                    headOid: row.headRefOid,
+                    baseRef: row.baseRefName,
+                    title: row.title,
+                    url: row.url,
+                });
+            }
+            return prs;
+        },
+    };
+}