rman 0.37.4 → 1.0.1

package/services/changelog.service.d.ts

@@ -0,0 +1,99 @@
+import type { Package } from '../core/package.js';
+import type { Repository } from '../core/repository.js';
+import { type PackageFilterOptions } from '../utils/package-filter.js';
+export declare namespace ChangelogService {
+    /** Injectable dependencies shared by `getEntries`/`generate` - currently just the npm registry lookup
+     *  `detectChangeHash` otherwise makes for itself; overridable so tests (and advanced callers)
+     *  aren't forced through a real network call. */
+    interface Deps {
+        npmViewVersion?: (name: string, cwd: string) => Promise<string | undefined>;
+    }
+    interface Options extends PackageFilterOptions {
+        /** Generate the changelog since this commit/hash - applied the same way to every package.
+         *  Default (also `"npm"` explicitly): auto-detect it per package instead, from that package's
+         *  currently-published npm version (see `detectChangeHash`); a package this can't be resolved
+         *  for (unpublished, no network, no matching tag) falls back to its own commits not yet
+         *  pushed to the current branch's upstream (same reference point `--changed`/
+         *  `--changed-since` use). */
+        from?: string;
+        /** Generate for the whole repository even when the current directory is inside a single
+         *  package (which otherwise scopes it to just that package) - see `Repository.currentPackage`. */
+        root?: boolean;
+        /** Where a package's changelog file lives, relative to *that package's own* directory -
+         *  default `'CHANGELOG.md'`. Applies the same way to every package; for a package that wants
+         *  its own filename instead, use `.rmanrc changelog.filePath` (cascaded, per-package
+         *  overridable) rather than this option - see `resolveFilePath`. Consulted even without
+         *  `write`: when auto-detecting, if this file already exists its own last-modifying commit
+         *  also lower-bounds the boundary, so a stale file (last updated for an older version than
+         *  what's actually published) doesn't get changes silently skipped over - see
+         *  `detectChangeHash`'s `catchUpFile`. */
+        filePath?: string;
+    }
+    /** One package's (root included) generated changelog entry - what `getEntries`/`generate`
+     *  return. */
+    interface Entry {
+        package: Package;
+        /** Display name for this entry's heading - `"<repo dir name> repository"` for the root
+         *  package, its own name otherwise (see `getEntries`'s doc comment on `{{package}}`). */
+        label: string;
+        /** Resolved from git tags, not package.json - see `resolveVersion`. */
+        version: string;
+        features: string[];
+        fixes: string[];
+        other: string[];
+        /** The fully rendered entry, via `.rmanrc changelog.template` (or the built-in default). */
+        content: string;
+        /** Where this entry would be (or, with `options.write`, was) written, relative to the
+         *  package's own directory - see `GetOptions.filePath`. */
+        filePath: string;
+    }
+    /**
+     * Same as `getEntries`, and additionally - for every returned entry, when `options.write` is
+     * set - prepends `entry.content` into that package's own changelog file (see `Entry.filePath`).
+     * Still pure with respect to console output: writing a file is a real, callable-for-its-own-
+     * sake side effect (a "save this" request), not presentation, so it stays here rather than in
+     * the CLI command - printing what happened is the command's job.
+     */
+    function generateToFile(repository: Repository, options?: Options, deps?: Deps): Promise<Entry[]>;
+    /**
+     * Computes a changelog entry per package (root included) from real commits only - either
+     * everything since a given `--from <hash>` (applied the same way to every package), or, by
+     * default, auto-detected per package instead (see `detectChangeHash`). Pure: returns the
+     * entries, never prints or touches `CHANGELOG.md` - see `generate` for that.
+     *
+     * A commit is attributed to every package its files fall under (root included, for anything
+     * outside every package) - unless it's broad enough to count as a repo-wide change (see
+     * `BROAD_COMMIT_THRESHOLD`/`ownersOf`), in which case it goes to root alone instead of being
+     * repeated verbatim across most of the repository. Subject lines are grouped ✨ Features/🐛 Bug
+     * Fixes/🔧 Other Changes on a best-effort Conventional Commits read; anything that doesn't parse
+     * just lands in Other Changes as-is, so a repo that doesn't follow that convention still gets a
+     * usable list. `.rmanrc changelog.ignoreTypes` (cascaded, e.g. `[chore, dev]`) drops commits of
+     * those types entirely instead - see `ignoreTypesConfig`. A bare version-bump commit
+     * (`"6.0.1"`) is always dropped outright, regardless of `ignoreTypes` - see
+     * `VERSION_BUMP_PATTERN`.
+     *
+     * By default (or with `--from npm` explicitly), the boundary is auto-detected per package
+     * instead of one shared one - see `detectChangeHash`. A package that can't be resolved this way
+     * (unpublished, no network, no matching tag) falls back to its own commits not yet pushed to
+     * the current branch's upstream (the same reference point `--changed`/`--changed-since` use
+     * elsewhere, via `GitHelper.listCommits`) - so the command still produces something useful even
+     * for a repo that's never been published or tagged at all. Packages that end up resolving to
+     * the same hash (an explicit one, or several packages sharing one tag under fixed versioning)
+     * only have their commits fetched once, not once per package.
+     *
+     * Formatting comes from `.rmanrc changelog.template` - a *path* to a template file (not the
+     * template text itself, to keep `.rmanrc` readable), with `{{package}}`/`{{version}}`/
+     * `{{date}}`/`{{commits}}` (the full grouped block) and `{{features}}`/`{{fixes}}`/`{{other}}`
+     * (their bullet lists alone, for templates that want their own headings/order) - see
+     * `resolveTemplate`. `{{package}}` for the repository root is `"<repo dir name> repository"`
+     * (e.g. "sqb repository"), not its raw package.json name - which is often a private,
+     * non-published placeholder (`"sqb.v4"`) that reads like a stray version marker rather than a
+     * recognizable label. `{{version}}` comes from git tags, not package.json (which can drift out
+     * of sync with what's actually been released) - see `resolveVersion`/`.rmanrc
+     * changelog.tagPattern`.
+     *
+     * Run from inside a single package's own directory, it only covers that package unless
+     * `options.root` says otherwise (see `Repository.currentPackage`).
+     */
+    function getEntries(repository: Repository, options?: Options, deps?: Deps): Promise<Entry[]>;
+}

package/services/changelog.service.js

@@ -0,0 +1,272 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { detectChangeHash, extractVersion, findLatestTag, tagPattern } from '../utils/change-hash.js';
+import { parseConventionalCommit, VERSION_BUMP_PATTERN } from '../utils/conventional-commits.js';
+import { GitHelper } from '../utils/git.js';
+import { filterPackages } from '../utils/package-filter.js';
+export var ChangelogService;
+(function (ChangelogService) {
+    /**
+     * Same as `getEntries`, and additionally - for every returned entry, when `options.write` is
+     * set - prepends `entry.content` into that package's own changelog file (see `Entry.filePath`).
+     * Still pure with respect to console output: writing a file is a real, callable-for-its-own-
+     * sake side effect (a "save this" request), not presentation, so it stays here rather than in
+     * the CLI command - printing what happened is the command's job.
+     */
+    async function generateToFile(repository, options = {}, deps = {}) {
+        const entries = await getEntries(repository, options, deps);
+        for (const entry of entries)
+            prependToChangelogFile(entry.package, entry.filePath, entry.content);
+        return entries;
+    }
+    ChangelogService.generateToFile = generateToFile;
+    /**
+     * Computes a changelog entry per package (root included) from real commits only - either
+     * everything since a given `--from <hash>` (applied the same way to every package), or, by
+     * default, auto-detected per package instead (see `detectChangeHash`). Pure: returns the
+     * entries, never prints or touches `CHANGELOG.md` - see `generate` for that.
+     *
+     * A commit is attributed to every package its files fall under (root included, for anything
+     * outside every package) - unless it's broad enough to count as a repo-wide change (see
+     * `BROAD_COMMIT_THRESHOLD`/`ownersOf`), in which case it goes to root alone instead of being
+     * repeated verbatim across most of the repository. Subject lines are grouped ✨ Features/🐛 Bug
+     * Fixes/🔧 Other Changes on a best-effort Conventional Commits read; anything that doesn't parse
+     * just lands in Other Changes as-is, so a repo that doesn't follow that convention still gets a
+     * usable list. `.rmanrc changelog.ignoreTypes` (cascaded, e.g. `[chore, dev]`) drops commits of
+     * those types entirely instead - see `ignoreTypesConfig`. A bare version-bump commit
+     * (`"6.0.1"`) is always dropped outright, regardless of `ignoreTypes` - see
+     * `VERSION_BUMP_PATTERN`.
+     *
+     * By default (or with `--from npm` explicitly), the boundary is auto-detected per package
+     * instead of one shared one - see `detectChangeHash`. A package that can't be resolved this way
+     * (unpublished, no network, no matching tag) falls back to its own commits not yet pushed to
+     * the current branch's upstream (the same reference point `--changed`/`--changed-since` use
+     * elsewhere, via `GitHelper.listCommits`) - so the command still produces something useful even
+     * for a repo that's never been published or tagged at all. Packages that end up resolving to
+     * the same hash (an explicit one, or several packages sharing one tag under fixed versioning)
+     * only have their commits fetched once, not once per package.
+     *
+     * Formatting comes from `.rmanrc changelog.template` - a *path* to a template file (not the
+     * template text itself, to keep `.rmanrc` readable), with `{{package}}`/`{{version}}`/
+     * `{{date}}`/`{{commits}}` (the full grouped block) and `{{features}}`/`{{fixes}}`/`{{other}}`
+     * (their bullet lists alone, for templates that want their own headings/order) - see
+     * `resolveTemplate`. `{{package}}` for the repository root is `"<repo dir name> repository"`
+     * (e.g. "sqb repository"), not its raw package.json name - which is often a private,
+     * non-published placeholder (`"sqb.v4"`) that reads like a stray version marker rather than a
+     * recognizable label. `{{version}}` comes from git tags, not package.json (which can drift out
+     * of sync with what's actually been released) - see `resolveVersion`/`.rmanrc
+     * changelog.tagPattern`.
+     *
+     * Run from inside a single package's own directory, it only covers that package unless
+     * `options.root` says otherwise (see `Repository.currentPackage`).
+     */
+    async function getEntries(repository, options = {}, deps = {}) {
+        const cwdScope = options.root ? undefined : repository.currentPackage;
+        const packages = repository.getPackages().filter(p => p !== repository.rootPackage);
+        const targets = cwdScope ? [cwdScope] : filterPackages([repository.rootPackage, ...packages], options);
+        const git = new GitHelper({ cwd: repository.dirname });
+        // dropped up front, not just while grouping - a package whose only commits are version bumps
+        // should get no entry at all, rather than a heading with nothing real underneath it.
+        const dropVersionBumps = (commits) => commits.filter(c => !VERSION_BUMP_PATTERN.test(c.subject));
+        // Several packages often resolve to the identical hash (an explicit --from <hash> applies to
+        // all of them the same way; under fixed versioning, npm auto-detection usually does too) - so
+        // the git fetch for a given hash is cached, run once no matter how many packages share it.
+        const commitsByHash = new Map();
+        const listCommitsCached = (hash) => {
+            const key = hash ?? '';
+            let promise = commitsByHash.get(key);
+            if (!promise) {
+                promise = git.listCommits({ hash }).then(dropVersionBumps);
+                commitsByHash.set(key, promise);
+            }
+            return promise;
+        };
+        const commitsByTarget = await Promise.all(targets.map(async (pkg) => {
+            const catchUpFile = path.join(pkg.dirname, resolveFilePath(pkg, options.filePath));
+            const from = await detectChangeHash(git, pkg, {
+                from: options.from,
+                npmViewVersion: deps.npmViewVersion,
+                catchUpFile: fs.existsSync(catchUpFile) ? catchUpFile : undefined,
+            });
+            return listCommitsCached(from);
+        }));
+        const entries = [];
+        for (let i = 0; i < targets.length; i++) {
+            const pkg = targets[i];
+            const ownCommits = commitsByTarget[i].filter(c => ownersOf(repository, c).has(pkg));
+            if (!ownCommits.length)
+                continue;
+            const grouped = groupCommits(ownCommits.map(c => c.subject), ignoreTypesConfig(pkg));
+            // every commit could have been dropped by ignoreTypes - skip this package's entry entirely
+            // rather than rendering a heading with nothing real underneath it.
+            if (!grouped.features.length && !grouped.fixes.length && !grouped.other.length)
+                continue;
+            const label = pkg === repository.rootPackage ? `${path.basename(repository.dirname)} repository` : pkg.name;
+            const { version, content } = await renderEntry(repository, pkg, label, grouped, git);
+            entries.push({
+                package: pkg,
+                label,
+                version,
+                features: grouped.features,
+                fixes: grouped.fixes,
+                other: grouped.other,
+                content,
+                filePath: resolveFilePath(pkg, options.filePath),
+            });
+        }
+        return entries;
+    }
+    ChangelogService.getEntries = getEntries;
+})(ChangelogService || (ChangelogService = {}));
+/** `.rmanrc changelog.ignoreTypes` (cascaded, per-package overridable) - Conventional Commits
+ *  `type`s to drop entirely (e.g. `[chore, dev]`), not just fold into "Other Changes". Only
+ *  applies to commits that actually parse as `type: ...` - a non-conventional message always
+ *  still lands in Other Changes, since it has no `type` to match against. */
+function ignoreTypesConfig(pkg) {
+    const v = pkg.config?.changelog?.ignoreTypes;
+    return new Set(Array.isArray(v) ? v.map(t => String(t).toLowerCase()) : []);
+}
+function groupCommits(subjects, ignoreTypes = new Set()) {
+    const grouped = { features: [], fixes: [], other: [] };
+    for (const subject of subjects) {
+        if (VERSION_BUMP_PATTERN.test(subject))
+            continue;
+        const parsed = parseConventionalCommit(subject);
+        if (!parsed) {
+            grouped.other.push(subject);
+            continue;
+        }
+        const { type, scope, description } = parsed;
+        if (ignoreTypes.has(type))
+            continue;
+        const line = scope ? `**${scope}:** ${description}` : description;
+        if (type === 'feat')
+            grouped.features.push(line);
+        else if (type === 'fix')
+            grouped.fixes.push(line);
+        else
+            grouped.other.push(subject);
+    }
+    return grouped;
+}
+function bulletList(lines) {
+    return lines.map(l => `- ${l}`).join('\n');
+}
+function renderCommitsBlock(grouped) {
+    const sections = [];
+    if (grouped.features.length)
+        sections.push(`### ✨ Features\n\n${bulletList(grouped.features)}`);
+    if (grouped.fixes.length)
+        sections.push(`### 🐛 Bug Fixes\n\n${bulletList(grouped.fixes)}`);
+    if (grouped.other.length)
+        sections.push(`### 🔧 Other Changes\n\n${bulletList(grouped.other)}`);
+    return sections.join('\n\n');
+}
+const DEFAULT_TEMPLATE = '## {{package}} {{version}} ({{date}})\n\n{{commits}}\n';
+/** `.rmanrc changelog.template` is a *path* to a template file (resolved relative to the
+ *  repository root, regardless of which level's `.rmanrc` declared it), not the template text
+ *  itself - keeping multi-line Markdown out of `.rmanrc` so it stays readable. Falls back to a
+ *  small built-in template when unset. */
+function resolveTemplate(repository, pkg) {
+    const templatePath = pkg.config?.changelog?.template;
+    if (typeof templatePath !== 'string' || !templatePath)
+        return DEFAULT_TEMPLATE;
+    const abs = path.resolve(repository.dirname, templatePath);
+    if (!fs.existsSync(abs)) {
+        throw new Error(`changelog.template not found for "${pkg.name}": "${templatePath}" (resolved to "${abs}")`);
+    }
+    return fs.readFileSync(abs, 'utf-8');
+}
+function render(template, values) {
+    return template.replace(/\{\{(\w+)\}\}/g, (_, key) => values[key] ?? '');
+}
+const DEFAULT_CHANGELOG_FILE = 'CHANGELOG.md';
+/** Where `write` prepends this package's entry, relative to its own directory. An explicit
+ *  `optionsFilePath` (`Changelog.Options.filePath`, CLI `--file-path`) applies the same way to
+ *  every package and wins over `.rmanrc changelog.filePath` (cascaded, per-package overridable),
+ *  which in turn wins over the default `'CHANGELOG.md'`. */
+function resolveFilePath(pkg, optionsFilePath) {
+    if (optionsFilePath)
+        return optionsFilePath;
+    const cfg = pkg.config?.changelog?.filePath;
+    return typeof cfg === 'string' && cfg ? cfg : DEFAULT_CHANGELOG_FILE;
+}
+/**
+ * This package's current version, from git tags rather than its (possibly stale - see the
+ * `{{version}}` doc on `Changelog.getEntries`) package.json. Falls back to package.json's version
+ * if no matching tag exists at all (never tagged, or a fresh package) - see `findLatestTag`.
+ */
+async function resolveVersion(git, pkg) {
+    const tag = await findLatestTag(git, pkg);
+    return tag ? extractVersion(tag, tagPattern(pkg).replace('{name}', pkg.name)) : pkg.version || '';
+}
+/** The most specific package whose directory contains `file` - the repository root itself as the
+ *  fallback for anything outside every package (e.g. root-level config files). Mirrors
+ *  `Repository.currentPackage`'s longest-prefix logic, but always resolves to *something*
+ *  (root), rather than `undefined`, since every file belongs to some changelog. */
+function owningPackage(repository, file) {
+    let best = repository.rootPackage;
+    for (const pkg of repository.packages) {
+        const rel = path.relative(pkg.dirname, file);
+        const isSelfOrDescendant = rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
+        if (isSelfOrDescendant && pkg.dirname.length > best.dirname.length)
+            best = pkg;
+    }
+    return best;
+}
+/** A commit touching more than this fraction of all packages (a repo-wide relicense, a doc
+ *  update stamped into every package's README, ...) is treated as a repo-wide change rather than
+ *  attributed to each of them - see `ownersOf`. Without this, one such commit would show up
+ *  verbatim in every single package's changelog, making them all look identical. */
+const BROAD_COMMIT_THRESHOLD = 0.5;
+/** ...but only once at least this many packages are actually touched - without a floor, a repo
+ *  with only 1 or 2 packages would have *every* normal commit look "broad" (100% > 50% of a
+ *  1-package repo is trivially true), wrongly attributing ordinary changes to root alone. */
+const BROAD_COMMIT_MIN_PACKAGES = 3;
+/**
+ * A commit can touch more than one package at once (or a package plus root-level files) - it's
+ * attributed to every package its files map to, not just one. The exception is a commit broad
+ * enough to touch at least `BROAD_COMMIT_MIN_PACKAGES` packages *and* more than
+ * `BROAD_COMMIT_THRESHOLD` of all of them: that's a repo-wide maintenance change (relicensing, a
+ * doc pass across every package, ...), not something that belongs in each package's own release
+ * notes individually - it's attributed to the root alone.
+ */
+function ownersOf(repository, commit) {
+    const owners = new Set();
+    for (const f of commit.files)
+        owners.add(owningPackage(repository, f));
+    const totalPackages = repository.packages.length;
+    const nonRootOwners = [...owners].filter(p => p !== repository.rootPackage).length;
+    if (totalPackages > 0 &&
+        nonRootOwners >= BROAD_COMMIT_MIN_PACKAGES &&
+        nonRootOwners > totalPackages * BROAD_COMMIT_THRESHOLD) {
+        return new Set([repository.rootPackage]);
+    }
+    return owners;
+}
+async function renderEntry(repository, pkg, label, grouped, git) {
+    const template = resolveTemplate(repository, pkg);
+    const version = await resolveVersion(git, pkg);
+    const content = render(template, {
+        package: label,
+        version,
+        date: new Date().toISOString().slice(0, 10),
+        commits: renderCommitsBlock(grouped),
+        features: bulletList(grouped.features),
+        fixes: bulletList(grouped.fixes),
+        other: bulletList(grouped.other),
+    });
+    return { version, content };
+}
+/** Prepends `content` right after the top-level "# Changelog" heading if the file already has
+ *  one, otherwise creates the file (and any missing parent directory - `relFilePath` can nest one,
+ *  e.g. `'docs/CHANGELOG.md'`) with one. Leaves everything already in the file untouched below it. */
+function prependToChangelogFile(pkg, relFilePath, content) {
+    const file = path.join(pkg.dirname, relFilePath);
+    const existing = fs.existsSync(file) ? fs.readFileSync(file, 'utf-8') : '';
+    const headerMatch = /^# Changelog\r?\n+/.exec(existing);
+    const header = headerMatch ? headerMatch[0] : '# Changelog\n\n';
+    const rest = headerMatch ? existing.slice(headerMatch[0].length) : existing;
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, header + content.trimEnd() + '\n\n' + rest);
+}

package/services/ci.service.d.ts

@@ -0,0 +1,40 @@
+import type { Repository } from '../core/repository.js';
+import { type LogLevel } from '../utils/logger.js';
+import { type PackageFilterOptions } from '../utils/package-filter.js';
+export declare namespace CiService {
+    type PackageManager = (typeof PACKAGE_MANAGERS)[number];
+    interface Options extends PackageFilterOptions {
+        packageManager?: PackageManager;
+        /** Show the live progress panel while running. Default true, same as `run`/`build`; auto-disabled
+         *  when stdout isn't a TTY. Doesn't affect what's printed once done - see `run`. */
+        progress?: boolean;
+        /** Verbosity of the classic per-step log (only applies when the live panel is off). Falls back to
+         *  the root's `.rmanrc logLevel`, then 'info' - see `resolveRootLogLevel`. */
+        logLevel?: LogLevel;
+    }
+    /** `.rmanrc packageManager` (root only) picks the package manager used for the final install;
+     *  explicit CLI value wins over it. Defaults to 'npm'. */
+    function resolvePackageManager(repository: Repository, cliValue?: PackageManager): PackageManager;
+    /** Deletes `node_modules` and any known lockfile directly under `dirname`. Returns the names
+     *  that actually existed (and were removed), so the caller can log only those. */
+    function wipe(dirname: string): Promise<string[]>;
+    /**
+     * `ci`: a from-scratch, reproducible install for CI pipelines. For every package (root
+     * included), deletes `node_modules` and any lockfile - or, if the package defines its own
+     * `"ci"` script, runs that instead. Once every package is clean, installs once at the root
+     * with the configured package manager (`npm`/`yarn`/`pnpm`/`bun`).
+     *
+     * Uses the same live progress panel as `run`/`build` (see `../utils/progress-panel.ts`) while it
+     * runs, falling back to a plain rmdir/clean/run/install log line per step when the panel is off.
+     *
+     * Unlike `run`/`build`, it does *not* end with a per-package success tally: `ci`'s packages don't
+     * have independently meaningful outcomes the way a build or test run does - wiping a package is
+     * trivial and the one step that can genuinely fail, the install, is a single operation for the
+     * whole repository. Counting "N succeeded" across packages would just be noise, so only actual
+     * failures get called out (by name, with whatever output they produced), followed by one plain
+     * completed/failed line.
+     */
+    function reinstall(repository: Repository, options?: Options): Promise<void>;
+}
+declare const PACKAGE_MANAGERS: readonly ["npm", "yarn", "pnpm", "bun"];
+export {};

package/services/ci.service.js

@@ -0,0 +1,204 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import colors from 'ansi-colors';
+import { exec } from '../utils/exec.js';
+import { Logger, resolveRootLogLevel } from '../utils/logger.js';
+import { filterPackages } from '../utils/package-filter.js';
+import { formatDuration, ProgressPanel } from '../utils/progress-panel.js';
+export var CiService;
+(function (CiService) {
+    /** `.rmanrc packageManager` (root only) picks the package manager used for the final install;
+     *  explicit CLI value wins over it. Defaults to 'npm'. */
+    function resolvePackageManager(repository, cliValue) {
+        if (cliValue)
+            return cliValue;
+        const configured = repository.config?.packageManager;
+        if (configured === undefined)
+            return 'npm';
+        if (PACKAGE_MANAGERS.includes(configured))
+            return configured;
+        throw new Error(`Invalid "packageManager" in .rmanrc: "${configured}" (expected one of: ${PACKAGE_MANAGERS.join(', ')})`);
+    }
+    CiService.resolvePackageManager = resolvePackageManager;
+    /** Deletes `node_modules` and any known lockfile directly under `dirname`. Returns the names
+     *  that actually existed (and were removed), so the caller can log only those. */
+    async function wipe(dirname) {
+        const removed = [];
+        for (const name of ['node_modules', ...LOCK_FILES]) {
+            const target = path.join(dirname, name);
+            const existed = await fs
+                .access(target)
+                .then(() => true)
+                .catch(() => false);
+            if (!existed)
+                continue;
+            await fs.rm(target, { recursive: true, force: true });
+            removed.push(name);
+        }
+        return removed;
+    }
+    CiService.wipe = wipe;
+    /**
+     * `ci`: a from-scratch, reproducible install for CI pipelines. For every package (root
+     * included), deletes `node_modules` and any lockfile - or, if the package defines its own
+     * `"ci"` script, runs that instead. Once every package is clean, installs once at the root
+     * with the configured package manager (`npm`/`yarn`/`pnpm`/`bun`).
+     *
+     * Uses the same live progress panel as `run`/`build` (see `../utils/progress-panel.ts`) while it
+     * runs, falling back to a plain rmdir/clean/run/install log line per step when the panel is off.
+     *
+     * Unlike `run`/`build`, it does *not* end with a per-package success tally: `ci`'s packages don't
+     * have independently meaningful outcomes the way a build or test run does - wiping a package is
+     * trivial and the one step that can genuinely fail, the install, is a single operation for the
+     * whole repository. Counting "N succeeded" across packages would just be noise, so only actual
+     * failures get called out (by name, with whatever output they produced), followed by one plain
+     * completed/failed line.
+     */
+    async function reinstall(repository, options = {}) {
+        const packageManager = resolvePackageManager(repository, options.packageManager);
+        const logger = new Logger(options.logLevel ?? resolveRootLogLevel(repository));
+        // root is handled separately below - for a non-monorepo, getPackages() would otherwise
+        // include it a second time (it doubles as "the" package).
+        const packages = filterPackages(repository.getPackages().filter(p => p !== repository.rootPackage), options);
+        const progress = options.progress ?? true;
+        const panel = new ProgressPanel('CI', !!process.stdout.isTTY && progress);
+        const runStartedAt = Date.now();
+        panel.start();
+        const items = [];
+        let failed = false;
+        try {
+            const results = await Promise.allSettled(packages.map(pkg => {
+                const item = panel.addItem(pkg.name);
+                items.push(item);
+                return ciForPackage(pkg, item, panel.enabled, logger);
+            }));
+            if (results.some(r => r.status === 'rejected'))
+                failed = true;
+            const rootItem = panel.addItem('root');
+            items.push(rootItem);
+            try {
+                await ciForRoot(repository, rootItem, panel.enabled, packageManager, logger);
+            }
+            catch {
+                failed = true;
+            }
+        }
+        finally {
+            panel.stop();
+        }
+        for (const item of items) {
+            if (item.status !== 'failed')
+                continue;
+            logger.error(colors.red.bold('X'), item.name);
+            if (item.log.length)
+                logger.error(colors.red(item.log.join('\n')));
+        }
+        const totalElapsed = formatDuration(Date.now() - runStartedAt);
+        const summary = [failed ? colors.red('ci failed') : colors.green('ci completed'), colors.gray(`(${totalElapsed})`)];
+        if (failed)
+            logger.error(...summary);
+        else
+            logger.info(...summary);
+        if (failed) {
+            const err = new Error('"ci" failed');
+            err.logged = true;
+            throw err;
+        }
+    }
+    CiService.reinstall = reinstall;
+})(CiService || (CiService = {}));
+const PACKAGE_MANAGERS = ['npm', 'yarn', 'pnpm', 'bun'];
+const LOCK_FILES = ['package-lock.json', 'yarn.lock', 'pnpm-lock.yaml', 'bun.lock', 'bun.lockb'];
+/** Runs a shell `command` in `cwd`, driving `item` for the live panel when it's on, or falling
+ *  back to the plain "classic" log line `logLine` prints first - the same split `run`'s classic
+ *  log uses. `logLine` is expected to go through a `Logger` (so it respects `--log-level`), not a
+ *  raw `console.log`. */
+async function runStep(item, panelEnabled, cwd, command, logLine) {
+    if (panelEnabled) {
+        await exec(command, {
+            cwd,
+            stdio: 'pipe',
+            onLine: line => {
+                item.log.push(line);
+                item.lastLine = line;
+            },
+        });
+    }
+    else {
+        logLine();
+        await exec(command, { cwd, stdio: 'inherit' });
+    }
+}
+/** Logs (or reflects onto the live panel) the outcome of a `wipe()` call - including the "nothing
+ *  to remove" case, which otherwise prints nothing at all in the classic log and can look like the
+ *  package was never processed (most workspace layouts hoist deps to the root's `node_modules`,
+ *  so an individual package legitimately has nothing of its own to wipe most of the time). */
+function logWipeResult(item, panelEnabled, logger, label, removed) {
+    if (panelEnabled) {
+        item.lastLine = removed.length ? `removed ${removed.join(', ')}` : 'already clean';
+        return;
+    }
+    if (!removed.length) {
+        logger.info(colors.gray('clean'), colors.cyan(label));
+        return;
+    }
+    for (const name of removed)
+        logger.info(colors.yellow('rmdir'), colors.cyan(label), name);
+}
+/** A package can opt out of the default wipe by defining its own `"ci"` npm script - if present,
+ *  that runs instead of the wipe, same as any other rman script. */
+async function ciForPackage(pkg, item, panelEnabled, logger) {
+    item.status = 'running';
+    item.startedAt = Date.now();
+    try {
+        const script = pkg.json.scripts?.ci;
+        if (typeof script === 'string' && script) {
+            item.currentStep = 'ci';
+            await runStep(item, panelEnabled, pkg.dirname, script, () => logger.info(colors.cyan('run'), colors.cyan(item.name), script));
+        }
+        else {
+            item.currentStep = 'wipe';
+            const removed = await CiService.wipe(pkg.dirname);
+            logWipeResult(item, panelEnabled, logger, item.name, removed);
+        }
+        item.status = 'success';
+    }
+    catch (e) {
+        item.status = 'failed';
+        throw e;
+    }
+    finally {
+        item.finishedAt = Date.now();
+    }
+}
+/** The root gets one extra step over a regular package once it isn't opting out with its own
+ *  `"ci"` script: after its own wipe, it installs once for the whole repository. */
+async function ciForRoot(repository, item, panelEnabled, packageManager, logger) {
+    item.status = 'running';
+    item.startedAt = Date.now();
+    try {
+        const script = repository.rootPackage.json.scripts?.ci;
+        if (typeof script === 'string' && script) {
+            item.currentStep = 'ci';
+            await runStep(item, panelEnabled, repository.dirname, script, () => logger.info(colors.cyan('run'), colors.cyan('root'), script));
+        }
+        else {
+            item.stepsTotal = 2;
+            item.stepIndex = 0;
+            item.currentStep = 'wipe';
+            const removed = await CiService.wipe(repository.dirname);
+            logWipeResult(item, panelEnabled, logger, 'root', removed);
+            item.stepIndex = 1;
+            item.currentStep = 'install';
+            await runStep(item, panelEnabled, repository.dirname, `${packageManager} install`, () => logger.info(colors.cyan('install'), `Running "${packageManager} install"`));
+        }
+        item.status = 'success';
+    }
+    catch (e) {
+        item.status = 'failed';
+        throw e;
+    }
+    finally {
+        item.finishedAt = Date.now();
+    }
+}

package/services/clean.service.d.ts

@@ -0,0 +1,42 @@
+import type { Repository } from '../core/repository.js';
+import { type LogLevel } from '../utils/logger.js';
+import { type PackageFilterOptions } from '../utils/package-filter.js';
+export declare namespace CleanService {
+    interface Options extends PackageFilterOptions {
+        /** Show the live progress panel. Default true; auto-disabled when stdout isn't a TTY. */
+        progress?: boolean;
+        /** Report what would be removed without actually removing anything. Default false. */
+        dryRun?: boolean;
+        /** Clean the whole repository even when the current directory is inside a single package
+         *  (which otherwise scopes cleaning to just that package - see `Repository.currentPackage`).
+         *  Has no effect when already at the repository root, or outside any known package. */
+        root?: boolean;
+        /** Verbosity of the classic per-item log (only applies when the live panel is off). Falls back
+         *  to the root's `.rmanrc logLevel`, then 'info' - see `resolveRootLogLevel`. */
+        logLevel?: LogLevel;
+    }
+    /**
+     * `clean`: removes build output across every package (root included) - the built-in replacement
+     * for `ts-cleanup`, plus whatever else `.rmanrc clean.include`/`clean.exclude` says to remove.
+     *
+     * For every package not opted out via its own (cascaded) `clean.skip: true`:
+     *  - deletes compiled `.js`/`.js.map`/`.d.ts` files under its `src`/`test` (see `cleanTsArtifacts`);
+     *  - deletes any `*.tsbuildinfo` incremental-build cache file anywhere in it;
+     *  - deletes anything matching its own (cascaded) `clean.include` glob(s), minus `clean.exclude`.
+     *
+     * `include`/`exclude` are resolved relative to *that* package's own directory - a root-level
+     * `.rmanrc` pattern like `packages/*\/build` is naturally evaluated from the repository root
+     * (spanning every package in one pass), while a package's own override in its own `.rmanrc`
+     * (e.g. `include: ./cache`) only ever reaches that one package, since a package normally
+     * overrides rather than merges with the root's value for the same key.
+     *
+     * Never touches `node_modules` - that's `ci`'s job, not this one.
+     *
+     * Run from inside a single package's own directory, it only cleans that package unless
+     * `options.root` says otherwise (see `Repository.currentPackage`).
+     *
+     * Uses the same live progress panel as `run`/`build` (see `../utils/progress-panel.ts`) - unlike
+     * `ci`, cleaning genuinely is independent per-package work, so the final per-package tally stays.
+     */
+    function clean(repository: Repository, options?: Options): Promise<void>;
+}