rman 0.38.0 → 1.0.2

package/utils/git.js

@@ -0,0 +1,276 @@
+import { execFile } from 'node:child_process';
+import path from 'node:path';
+import { promisify } from 'node:util';
+export class GitHelper {
+    cwd;
+    constructor(options) {
+        this.cwd = options?.cwd || process.cwd();
+    }
+    /** The current branch name, or `undefined` in detached HEAD state (or outside a git repository) -
+     *  what `branch-guard.ts` checks `allowBranch`/`ignoreBranch` against. */
+    async currentBranch() {
+        try {
+            const { stdout } = await execFileAsync('git', ['rev-parse', '--abbrev-ref', 'HEAD'], { cwd: this.cwd });
+            const branch = stdout.trim();
+            return branch && branch !== 'HEAD' ? branch : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /** Files with uncommitted local changes (working tree + index). */
+    async listDirtyFiles(options) {
+        let stdout;
+        try {
+            ({ stdout } = await execFileAsync('git', ['status', '--porcelain'], { cwd: this.cwd }));
+        }
+        catch {
+            return [];
+        }
+        /** Don't trim the whole output first - porcelain lines have a fixed-width status
+         *  prefix (e.g. " M "), and trimming would eat the leading space of the first line. */
+        const lines = stdout.split(/\r?\n/).filter(Boolean);
+        const files = lines.map(line => line.slice(3).trim());
+        return options?.absolute ? files.map(f => path.join(this.cwd, f)) : files;
+    }
+    /** Files committed on the current branch but not yet in its upstream. */
+    async listCommittedFiles(options) {
+        let shaList;
+        try {
+            ({ stdout: shaList } = await execFileAsync('git', ['cherry'], { cwd: this.cwd }));
+        }
+        catch {
+            /** No upstream configured, or not a git repository - nothing to report. */
+            return [];
+        }
+        const shas = Array.from(shaList.matchAll(/[a-f0-9]{7,40}/gi)).map(m => m[0]);
+        const files = [];
+        for (const sha of shas) {
+            const { stdout } = await execFileAsync('git', ['show', sha, '--name-only', '--pretty=format:'], {
+                cwd: this.cwd,
+            });
+            files.push(...(stdout.trim() ? stdout.trim().split(/\r?\n/) : []));
+        }
+        return options?.absolute ? files.map(f => path.join(this.cwd, f)) : files;
+    }
+    /** Files changed since `hash` (committed diffs plus any uncommitted local changes). */
+    async listChangedSince(hash, options) {
+        let stdout;
+        try {
+            ({ stdout } = await execFileAsync('git', ['diff', '--name-only', hash], { cwd: this.cwd }));
+        }
+        catch (e) {
+            throw new Error(`Unable to compute changes since "${hash}": ${e.message}`, { cause: e });
+        }
+        const files = stdout.trim() ? stdout.trim().split(/\r?\n/) : [];
+        return options?.absolute ? files.map(f => path.join(this.cwd, f)) : files;
+    }
+    /**
+     * Real commits only (never uncommitted/dirty changes - those have no message and can't be
+     * described in a changelog), oldest first: with `hash`, everything committed since that ref;
+     * without one, whatever's committed on the current branch but not yet in its upstream (same
+     * source as `listCommittedFiles`, via `git cherry`).
+     */
+    async listCommits(options) {
+        const hash = options?.hash;
+        let shas;
+        if (hash) {
+            let stdout;
+            try {
+                ({ stdout } = await execFileAsync('git', ['log', '--reverse', '--format=%H', `${hash}..HEAD`], {
+                    cwd: this.cwd,
+                }));
+            }
+            catch (e) {
+                throw new Error(`Unable to list commits since "${hash}": ${e.message}`, { cause: e });
+            }
+            shas = stdout.trim() ? stdout.trim().split(/\r?\n/) : [];
+        }
+        else {
+            let cherryOut;
+            try {
+                ({ stdout: cherryOut } = await execFileAsync('git', ['cherry'], { cwd: this.cwd }));
+            }
+            catch {
+                return [];
+            }
+            shas = Array.from(cherryOut.matchAll(/[a-f0-9]{7,40}/gi)).map(m => m[0]);
+        }
+        return this._commitInfoFor(shas);
+    }
+    /** Every commit reachable from HEAD, oldest first - for a boundary-free "everything so far"
+     *  view (e.g. a package that's never been tagged/released at all, so there's no "since" ref to
+     *  measure from and `listCommits()`'s own no-hash fallback, upstream push status, doesn't apply -
+     *  a repo with no configured remote at all is common and shouldn't read as "nothing happened"). */
+    async listAllCommits() {
+        let stdout;
+        try {
+            ({ stdout } = await execFileAsync('git', ['log', '--reverse', '--format=%H'], { cwd: this.cwd }));
+        }
+        catch {
+            return [];
+        }
+        const shas = stdout.trim() ? stdout.trim().split(/\r?\n/) : [];
+        return this._commitInfoFor(shas);
+    }
+    async _commitInfoFor(shas) {
+        const commits = [];
+        for (const sha of shas) {
+            // subject and body in one call (NUL-separated, since a commit message itself never
+            // contains one) - halves the process-spawns per commit compared to two separate `git show`s.
+            const { stdout: header } = await execFileAsync('git', ['show', sha, '--no-patch', '--format=%s%x00%b'], {
+                cwd: this.cwd,
+            });
+            const [subject = '', body = ''] = header.split('\0');
+            const { stdout: filesOut } = await execFileAsync('git', ['show', sha, '--name-only', '--pretty=format:'], {
+                cwd: this.cwd,
+            });
+            const files = filesOut.trim() ? filesOut.trim().split(/\r?\n/) : [];
+            commits.push({
+                sha,
+                subject: subject.trim(),
+                body: body.trim(),
+                files: files.map(f => path.join(this.cwd, f)),
+            });
+        }
+        return commits;
+    }
+    /** Tag names matching the glob `pattern` (e.g. `"v*"`, `"pkg-a@*"`), newest version first. */
+    async listTags(pattern) {
+        try {
+            const { stdout } = await execFileAsync('git', ['tag', '--list', pattern, '--sort=-v:refname'], {
+                cwd: this.cwd,
+            });
+            return stdout.trim() ? stdout.trim().split(/\r?\n/) : [];
+        }
+        catch {
+            return [];
+        }
+    }
+    /** Whether `tag` exists as an exact git tag name (not a glob - a literal ref check). */
+    async tagExists(tag) {
+        try {
+            await execFileAsync('git', ['rev-parse', '--verify', '--quiet', `refs/tags/${tag}`], { cwd: this.cwd });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /** The most recent commit that changed `file` (tracked history only) - `undefined` if it has
+     *  never been committed. Answers "since when has this file last been updated", independent of
+     *  any tag/version scheme - e.g. to check whether a changelog file has fallen behind. */
+    async lastCommitTouching(file) {
+        try {
+            const { stdout } = await execFileAsync('git', ['log', '-1', '--format=%H', '--', file], { cwd: this.cwd });
+            return stdout.trim() || undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /** The best common ancestor of `a` and `b` - `undefined` if none exists (unrelated histories,
+     *  an invalid ref, ...). */
+    async mergeBase(a, b) {
+        try {
+            const { stdout } = await execFileAsync('git', ['merge-base', a, b], { cwd: this.cwd });
+            return stdout.trim() || undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /** The most recent tag matching the glob `pattern` that HEAD actually descends from (unlike
+     *  `listTags`, this follows commit ancestry rather than just sorting tag names - the right
+     *  choice for a single repo-wide tag scheme, where a package has no tag of its own). */
+    async describeTag(pattern) {
+        try {
+            const { stdout } = await execFileAsync('git', ['describe', '--tags', '--abbrev=0', '--match', pattern], {
+                cwd: this.cwd,
+            });
+            return stdout.trim() || undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /** Stages and commits exactly `files` (relative to `cwd`, or absolute) with `message` - never a
+     *  blanket `git add -A`, so the commit only ever contains what the caller explicitly asked for. */
+    async commit(files, message) {
+        try {
+            await execFileAsync('git', ['add', '--', ...files], { cwd: this.cwd });
+            await execFileAsync('git', ['commit', '-m', message], { cwd: this.cwd });
+        }
+        catch (e) {
+            throw new Error(`Unable to commit ${files.join(', ')}: ${e.message}`, { cause: e });
+        }
+    }
+    /** Creates an annotated tag `name` pointing at HEAD, with `message` (defaults to `name`).
+     *  Throws if a tag with that name already exists - callers wanting idempotent tagging should
+     *  check `tagExists` first. */
+    async createTag(name, message) {
+        try {
+            await execFileAsync('git', ['tag', '-a', name, '-m', message ?? name], { cwd: this.cwd });
+        }
+        catch (e) {
+            throw new Error(`Unable to create tag "${name}": ${e.message}`, { cause: e });
+        }
+    }
+    /** Pushes the current branch to `remote` (default `"origin"`), and its tags too unless
+     *  `options.tags` is `false`. */
+    async push(options) {
+        const remote = options?.remote ?? 'origin';
+        try {
+            await execFileAsync('git', ['push', remote], { cwd: this.cwd });
+            if (options?.tags !== false)
+                await execFileAsync('git', ['push', remote, '--tags'], { cwd: this.cwd });
+        }
+        catch (e) {
+            throw new Error(`Unable to push to "${remote}": ${e.message}`, { cause: e });
+        }
+    }
+    /** Raw `git diff <hash>..HEAD` text (committed changes plus any uncommitted local ones, same as
+     *  plain `git diff <hash>`) - unlike `listChangedSince`, the actual patch content, not just
+     *  which files changed. `pathspec`, if given, narrows it to just that file/directory. */
+    async diff(hash, pathspec) {
+        const args = ['diff', hash];
+        if (pathspec)
+            args.push('--', pathspec);
+        try {
+            const { stdout } = await execFileAsync('git', args, { cwd: this.cwd, maxBuffer: 64 * 1024 * 1024 });
+            return stdout;
+        }
+        catch (e) {
+            throw new Error(`Unable to diff since "${hash}": ${e.message}`, { cause: e });
+        }
+    }
+    /** `git format-patch --root -o <outputDir> HEAD` - one `.patch` file per commit reachable from
+     *  HEAD (oldest first), `--root` included so the very first commit gets one too. Returns the
+     *  patch file paths, in commit order - what `import` replays into another repository. */
+    async formatPatches(outputDir) {
+        try {
+            const { stdout } = await execFileAsync('git', ['format-patch', '--root', '-o', outputDir, 'HEAD'], {
+                cwd: this.cwd,
+                maxBuffer: 64 * 1024 * 1024,
+            });
+            return stdout.trim() ? stdout.trim().split(/\r?\n/) : [];
+        }
+        catch (e) {
+            throw new Error(`Unable to format patches: ${e.message}`, { cause: e });
+        }
+    }
+    /** Applies `patchFiles` (as produced by `formatPatches`, in order) via `git am`, preserving each
+     *  original commit's author/date/message. `--3way` lets a patch that no longer applies cleanly
+     *  fall back to a content-level three-way merge instead of failing outright. */
+    async applyPatches(patchFiles) {
+        if (!patchFiles.length)
+            return;
+        try {
+            await execFileAsync('git', ['am', '--3way', ...patchFiles], { cwd: this.cwd, maxBuffer: 64 * 1024 * 1024 });
+        }
+        catch (e) {
+            throw new Error(`Unable to apply patches: ${e.message}`, { cause: e });
+        }
+    }
+}
+const execFileAsync = promisify(execFile);

package/utils/live-region.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Renders a fixed block of lines at the bottom of the terminal that gets
+ * redrawn in place (cursor-up + clear-line) instead of scrolling, the way
+ * Turborepo/pnpm show "currently running" status without flooding the log.
+ *
+ * No-op when stdout isn't a TTY (CI, piped output) - cursor-movement escape
+ * codes are meaningless there and would just corrupt the log.
+ */
+export declare class LiveRegion {
+    private lineCount;
+    readonly enabled: boolean;
+    constructor(enabled?: boolean);
+    render(lines: string[]): void;
+    /** Erases the block entirely, leaving the cursor where it started. */
+    clear(): void;
+}

package/utils/live-region.js

@@ -0,0 +1,59 @@
+/**
+ * Renders a fixed block of lines at the bottom of the terminal that gets
+ * redrawn in place (cursor-up + clear-line) instead of scrolling, the way
+ * Turborepo/pnpm show "currently running" status without flooding the log.
+ *
+ * No-op when stdout isn't a TTY (CI, piped output) - cursor-movement escape
+ * codes are meaningless there and would just corrupt the log.
+ */
+export class LiveRegion {
+    lineCount = 0;
+    enabled;
+    constructor(enabled = !!process.stdout.isTTY) {
+        this.enabled = enabled;
+    }
+    render(lines) {
+        if (!this.enabled)
+            return;
+        const width = process.stdout.columns || 80;
+        /** Measure by visible length, not raw length - a heavily-colored line has far more
+         *  bytes than visible characters, and slicing the raw string would cut mid-escape-code. */
+        let clipped = lines.map(l => {
+            if (visibleLength(l) <= width)
+                return l;
+            return l.replace(ANSI_PATTERN, '').slice(0, Math.max(0, width - 1));
+        });
+        /** A block taller than the terminal breaks the cursor-up math below: once printing it
+         *  scrolls the screen, "move up N rows" can't actually get back N rows, and every
+         *  redraw lands lower than the last, leaving a trail instead of a single updating block.
+         *  Callers should size their own content to fit, but this is a hard backstop. */
+        const maxRows = Math.max(1, (process.stdout.rows || 24) - 1);
+        if (clipped.length > maxRows)
+            clipped = clipped.slice(0, maxRows);
+        let out = this.lineCount ? `\x1b[${this.lineCount}A` : '';
+        for (const line of clipped)
+            out += `\r\x1b[2K${line}\n`;
+        for (let i = clipped.length; i < this.lineCount; i++)
+            out += '\r\x1b[2K\n';
+        if (clipped.length < this.lineCount)
+            out += `\x1b[${this.lineCount - clipped.length}A`;
+        process.stdout.write(out);
+        this.lineCount = clipped.length;
+    }
+    /** Erases the block entirely, leaving the cursor where it started. */
+    clear() {
+        if (!this.enabled || !this.lineCount)
+            return;
+        let out = `\x1b[${this.lineCount}A`;
+        for (let i = 0; i < this.lineCount; i++)
+            out += '\r\x1b[2K\n';
+        out += `\x1b[${this.lineCount}A`;
+        process.stdout.write(out);
+        this.lineCount = 0;
+    }
+}
+// eslint-disable-next-line no-control-regex
+const ANSI_PATTERN = /\x1b\[[0-9;]*m/g;
+function visibleLength(s) {
+    return s.replace(ANSI_PATTERN, '').length;
+}

package/utils/logger.d.ts

@@ -0,0 +1,24 @@
+import type { Repository } from '../core/repository.js';
+export type LogLevel = 'silent' | 'error' | 'info' | 'verbose';
+export declare const LOG_LEVELS: LogLevel[];
+/**
+ * Gates console output by verbosity (`--log-level`/`.rmanrc logLevel`) so a command's routine
+ * narration can be turned down without losing failure output - the same semantics `run`'s own
+ * classic per-step log already used (see `resolveLogLevel` in `commands/run.ts`), centralized here
+ * so every command can respect `--log-level` instead of reimplementing the checks, or ignoring it
+ * altogether via plain `console.log`.
+ */
+export declare class Logger {
+    level: LogLevel;
+    constructor(level: LogLevel);
+    /** Routine narration - hidden at 'silent'/'error', shown at 'info'/'verbose'. */
+    info(...args: unknown[]): void;
+    /** Extra detail, shown only at 'verbose'. */
+    verbose(...args: unknown[]): void;
+    /** A real failure - hidden only at 'silent', shown at every other level regardless of 'info'/'verbose'. */
+    error(...args: unknown[]): void;
+}
+/** The root's own `.rmanrc logLevel` (a plain top-level key) - the base default a command falls
+ *  back to once no explicit `--log-level`/option override applies. An invalid value is ignored,
+ *  falling back to 'info' rather than failing the whole command. */
+export declare function resolveRootLogLevel(repository: Repository): LogLevel;

package/utils/logger.js

@@ -0,0 +1,39 @@
+export const LOG_LEVELS = ['silent', 'error', 'info', 'verbose'];
+/**
+ * Gates console output by verbosity (`--log-level`/`.rmanrc logLevel`) so a command's routine
+ * narration can be turned down without losing failure output - the same semantics `run`'s own
+ * classic per-step log already used (see `resolveLogLevel` in `commands/run.ts`), centralized here
+ * so every command can respect `--log-level` instead of reimplementing the checks, or ignoring it
+ * altogether via plain `console.log`.
+ */
+export class Logger {
+    level;
+    constructor(level) {
+        this.level = level;
+    }
+    /** Routine narration - hidden at 'silent'/'error', shown at 'info'/'verbose'. */
+    info(...args) {
+        if (LOG_LEVELS.indexOf(this.level) < LOG_LEVELS.indexOf('info'))
+            return;
+        console.log(...args);
+    }
+    /** Extra detail, shown only at 'verbose'. */
+    verbose(...args) {
+        if (LOG_LEVELS.indexOf(this.level) < LOG_LEVELS.indexOf('verbose'))
+            return;
+        console.log(...args);
+    }
+    /** A real failure - hidden only at 'silent', shown at every other level regardless of 'info'/'verbose'. */
+    error(...args) {
+        if (this.level === 'silent')
+            return;
+        console.log(...args);
+    }
+}
+/** The root's own `.rmanrc logLevel` (a plain top-level key) - the base default a command falls
+ *  back to once no explicit `--log-level`/option override applies. An invalid value is ignored,
+ *  falling back to 'info' rather than failing the whole command. */
+export function resolveRootLogLevel(repository) {
+    const v = repository.config?.logLevel;
+    return typeof v === 'string' && LOG_LEVELS.includes(v) ? v : 'info';
+}

package/utils/npm-run-path.d.ts

@@ -63,5 +63,5 @@ export declare function npmRunPath(options?: RunPathOptions): string;
  ```
  */
 export declare function npmRunPathEnv(options?: EnvOptions): {
-    [key: string]: string | undefined;
+    [x: string]: string | undefined;
 };

package/utils/npm-run-path.js

@@ -32,16 +32,6 @@ export function npmRunPath(options = {}) {
     result.push(path.resolve(cwd, execPath, '..'));
     return [...result, path_].join(path.delimiter);
 }
-function pathKey(options) {
-    const env = options?.env || process.env;
-    const platform = options?.platform || process.platform;
-    if (platform !== 'win32') {
-        return 'PATH';
-    }
-    return (Object.keys(env)
-        .reverse()
-        .find(key => key.toUpperCase() === 'PATH') || 'Path');
-}
 /**
  @returns The augmented [`process.env`](https://nodejs.org/api/process.html#process_process_env) object.
  @example
@@ -61,3 +51,13 @@ export function npmRunPathEnv(options = {}) {
     env[path_] = npmRunPath(opts);
     return env;
 }
+function pathKey(options) {
+    const env = options?.env || process.env;
+    const platform = options?.platform || process.platform;
+    if (platform !== 'win32') {
+        return 'PATH';
+    }
+    return (Object.keys(env)
+        .reverse()
+        .find(key => key.toUpperCase() === 'PATH') || 'Path');
+}

package/utils/package-filter.d.ts

@@ -0,0 +1,32 @@
+import type { Argv } from 'yargs';
+import type { Package } from '../core/package.js';
+/** Shared by every command that iterates packages (`run`/`build`/`test`/`exec`, `list`, `ci`,
+ *  `clean`, `version`, `publish`, `changelog`) - narrows *which* packages a command applies to,
+ *  independent of what the command actually does to them. */
+export interface PackageFilterOptions {
+    /** Only include packages whose name matches at least one of these globs (e.g. `@scope/*`). */
+    scope?: string | string[];
+    /** Exclude packages whose name matches at least one of these globs - applied after `scope`. */
+    ignore?: string | string[];
+    /** Also include every package the matched set depends on (transitively) - e.g. to build
+     *  everything a scoped app actually needs. */
+    deps?: boolean;
+    /** Also include every package that depends on the matched set (transitively) - e.g. to test
+     *  everything that could be affected by a scoped library's change. */
+    dependents?: boolean;
+}
+/** `--scope`/`--ignore`/`--deps`/`--dependents`, the same shape and describe text in every command
+ *  that supports them - mirrors `run.command.ts`'s own `applyRunOptions`. */
+export declare function applyPackageFilterOptions<T>(cmd: Argv<T>): Argv<T>;
+export declare function readPackageFilterOptions(args: any): PackageFilterOptions;
+/**
+ * Narrows `packages` (the full, already-resolved list - toposort order, if any, is preserved)
+ * down to what `options` selects. `scope`/`ignore` match against each package's bare name (glob
+ * syntax via `micromatch` - `*`, `**`, `{a,b}`, ...); `ignore` is applied after `scope`, on
+ * whatever it left. `deps`/`dependents` then each independently expand *that* matched set along
+ * `Package.dependencies` (already the full transitive closure - see
+ * `Repository`'s own `_updateDependencies`) and their results are unioned in - so `--deps
+ * --dependents` together never re-expands one direction's additions through the other, which
+ * would otherwise tend to blow up toward "the whole repository" for any reasonably-connected graph.
+ */
+export declare function filterPackages(packages: Package[], options: PackageFilterOptions): Package[];

package/utils/package-filter.js

@@ -0,0 +1,73 @@
+import micromatch from 'micromatch';
+/** `--scope`/`--ignore`/`--deps`/`--dependents`, the same shape and describe text in every command
+ *  that supports them - mirrors `run.command.ts`'s own `applyRunOptions`. */
+export function applyPackageFilterOptions(cmd) {
+    return cmd
+        .option('scope', {
+        describe: 'Only include packages whose name matches this glob (repeatable)',
+        // Deliberately 'string', not 'array': an array-typed option greedily swallows every
+        // following bare word as its own value, which would eat "exec"'s [command..] positional
+        // whole. yargs still collects repeated "--scope a --scope b" into an array either way.
+        type: 'string',
+    })
+        .option('ignore', {
+        describe: 'Exclude packages whose name matches this glob (repeatable) - applied after --scope',
+        type: 'string',
+    })
+        .option('deps', {
+        describe: 'Also include every package the matched set depends on',
+        type: 'boolean',
+    })
+        .option('dependents', {
+        describe: 'Also include every package that depends on the matched set',
+        type: 'boolean',
+    });
+}
+export function readPackageFilterOptions(args) {
+    return {
+        scope: args.scope,
+        ignore: args.ignore,
+        deps: args.deps,
+        dependents: args.dependents,
+    };
+}
+/**
+ * Narrows `packages` (the full, already-resolved list - toposort order, if any, is preserved)
+ * down to what `options` selects. `scope`/`ignore` match against each package's bare name (glob
+ * syntax via `micromatch` - `*`, `**`, `{a,b}`, ...); `ignore` is applied after `scope`, on
+ * whatever it left. `deps`/`dependents` then each independently expand *that* matched set along
+ * `Package.dependencies` (already the full transitive closure - see
+ * `Repository`'s own `_updateDependencies`) and their results are unioned in - so `--deps
+ * --dependents` together never re-expands one direction's additions through the other, which
+ * would otherwise tend to blow up toward "the whole repository" for any reasonably-connected graph.
+ */
+export function filterPackages(packages, options) {
+    let matched = packages;
+    if (options.scope) {
+        const patterns = toArray(options.scope);
+        matched = matched.filter(p => micromatch.isMatch(p.name, patterns));
+    }
+    if (options.ignore) {
+        const patterns = toArray(options.ignore);
+        matched = matched.filter(p => !micromatch.isMatch(p.name, patterns));
+    }
+    if (!options.deps && !options.dependents)
+        return matched;
+    const included = new Set(matched.map(p => p.name));
+    if (options.deps) {
+        for (const p of matched)
+            for (const dep of p.dependencies)
+                included.add(dep);
+    }
+    if (options.dependents) {
+        const matchedNames = new Set(matched.map(p => p.name));
+        for (const p of packages) {
+            if (p.dependencies.some(d => matchedNames.has(d)))
+                included.add(p.name);
+        }
+    }
+    return packages.filter(p => included.has(p.name));
+}
+function toArray(value) {
+    return Array.isArray(value) ? value : [value];
+}

package/utils/progress-panel.d.ts

@@ -0,0 +1,59 @@
+import { LiveRegion } from './live-region.js';
+export type ProgressStatus = 'pending' | 'running' | 'success' | 'failed' | 'skipped';
+export interface ProgressItem {
+    readonly name: string;
+    status: ProgressStatus;
+    /** Label of the step currently running, for work with more than one step (e.g. `run`'s
+     *  npm-script steps) - omit `stepsTotal` entirely for single-step work like a plain command. */
+    currentStep?: string;
+    stepIndex?: number;
+    stepsTotal?: number;
+    /** Last captured output line, shown dimmed under the item while it's running. */
+    lastLine?: string;
+    startedAt?: number;
+    finishedAt?: number;
+    /** Captured output, printed back out if the item ends up failing. */
+    log: string[];
+}
+export interface ProgressSummary {
+    successCount: number;
+    failedCount: number;
+    skippedCount: number;
+}
+export declare function formatDuration(ms: number): string;
+/**
+ * Shared live progress panel for any command that fans work out across packages: a spinner
+ * header (progress bar, running/failed counts, elapsed time) plus one or two lines per
+ * currently-running item, redrawn in place instead of scrolling - the same panel `run`/`build`
+ * use, pulled out so other package-fanning commands (e.g. `ci`) can reuse it instead of
+ * reimplementing it.
+ *
+ * Renders nothing when `enabled` is false (a non-TTY, or a command's own `--no-progress`) -
+ * callers are expected to fall back to their own plain logging in that case, the way `run`
+ * falls back to its "classic" per-step log.
+ */
+export declare class ProgressPanel {
+    private readonly title;
+    readonly live: LiveRegion;
+    private readonly items;
+    private renderLoop?;
+    private spinnerFrame;
+    private startedAt;
+    constructor(title: string, enabled: boolean);
+    get enabled(): boolean;
+    /** Registers an item and returns it - callers mutate the returned object directly (`status`,
+     *  `currentStep`, `lastLine`, ...) to drive the next render tick. */
+    addItem(name: string, stepsTotal?: number): ProgressItem;
+    /** Starts the redraw loop. No-op (and no timer) when disabled. */
+    start(): void;
+    private render;
+    /** Stops the redraw loop and erases the panel, leaving the cursor where it started. */
+    stop(): void;
+    /**
+     * Prints the final per-item recap (✓/X/○) and the "N succeeded, M failed (Xs)" summary line,
+     * and returns the tally. Any item still 'pending' is counted (and printed) as 'skipped'. The
+     * per-item recap lines are only printed when the live panel was actually on - with it off, the
+     * caller's own plain logging already showed each item's outcome as it happened.
+     */
+    printSummary(): ProgressSummary;
+}