rman 0.38.0 → 1.0.2

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>;
+}

package/services/clean.service.js

@@ -0,0 +1,226 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import colors from 'ansi-colors';
+import fg from 'fast-glob';
+import { Logger, resolveRootLogLevel } from '../utils/logger.js';
+import { filterPackages } from '../utils/package-filter.js';
+import { ProgressPanel } from '../utils/progress-panel.js';
+export var CleanService;
+(function (CleanService) {
+    /**
+     * `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.
+     */
+    async function clean(repository, options = {}) {
+        /** Standing inside a single package's own directory scopes cleaning to just that package
+         *  (root's own artifacts included) unless `--root` asks for the whole repository anyway - a
+         *  no-op when already at the root, or outside any known package. */
+        const cwdScope = options.root ? undefined : repository.currentPackage;
+        const packages = repository.getPackages().filter(p => p !== repository.rootPackage);
+        const allTargets = cwdScope ? [cwdScope] : [repository.rootPackage, ...packages];
+        const targets = filterPackages(allTargets, options).filter(pkg => !cleanConfig(pkg).skip);
+        const dryRun = options.dryRun ?? false;
+        const progress = options.progress ?? true;
+        const logger = new Logger(options.logLevel ?? resolveRootLogLevel(repository));
+        const panel = new ProgressPanel(dryRun ? 'CLEAN (dry-run)' : 'CLEAN', !!process.stdout.isTTY && progress);
+        panel.start();
+        let failed = false;
+        try {
+            const results = await Promise.allSettled(targets.map(pkg => {
+                const label = pkg === repository.rootPackage ? 'root' : pkg.name;
+                return cleanPackage(pkg, panel.addItem(label), panel.enabled, dryRun, logger);
+            }));
+            if (results.some(r => r.status === 'rejected'))
+                failed = true;
+        }
+        finally {
+            panel.stop();
+        }
+        panel.printSummary();
+        if (failed) {
+            const err = new Error('"clean" failed');
+            err.logged = true;
+            throw err;
+        }
+    }
+    CleanService.clean = clean;
+})(CleanService || (CleanService = {}));
+/** Directories a package's TypeScript output gets cleaned from, mirroring `ts-cleanup -s src`
+ *  and `-s test` (the only way it was ever actually invoked in this project's own scripts). */
+const TS_SOURCE_DIRS = ['src', 'test'];
+/** A package's (cascaded) `.rmanrc clean.include`/`clean.exclude`/`clean.skip` - a package that
+ *  declares its own `clean` block replaces the root's entirely for itself (same as any other
+ *  rman config key), rather than combining with it. `include`/`exclude` accept a single glob
+ *  string or an array of them. */
+function cleanConfig(pkg) {
+    const cfg = pkg.config?.clean;
+    const normalize = (v) => {
+        if (Array.isArray(v))
+            return v.map(String);
+        return typeof v === 'string' && v ? [v] : [];
+    };
+    return { include: normalize(cfg?.include), exclude: normalize(cfg?.exclude), skip: cfg?.skip === true };
+}
+/** Deletes `file`, unless `dryRun` - either way the caller treats it as removed for reporting. */
+async function remove(file, dryRun) {
+    if (!dryRun)
+        await fs.promises.rm(file, { force: true });
+}
+/** Removes now-empty directories under `dir`, deepest first (so a parent left empty once its
+ *  only child is removed gets caught in the same pass). Also removes `dir` itself once empty
+ *  when `includeSelf` is set - used when `dir` is itself something the user asked to delete
+ *  (e.g. an `include: build` match), as opposed to a source root like `src`/`test` that should
+ *  stay even if everything inside it was cleaned out. No-op in dry-run mode: nothing was actually
+ *  deleted, so there's nothing that could have been left empty. */
+function pruneEmptyDirs(dir, includeSelf, dryRun) {
+    if (dryRun || !fs.existsSync(dir))
+        return;
+    const entries = fg.sync('**', { cwd: dir, onlyDirectories: true, dot: true });
+    entries.sort((a, b) => b.split(path.sep).length - a.split(path.sep).length);
+    for (const rel of entries) {
+        const abs = path.join(dir, rel);
+        if (fs.existsSync(abs) && fs.readdirSync(abs).length === 0)
+            fs.rmdirSync(abs);
+    }
+    if (includeSelf && fs.readdirSync(dir).length === 0)
+        fs.rmdirSync(dir);
+}
+/**
+ * Deletes every path matched by `include` (minus `exclude`) under `dirname` - files and
+ * directories alike, gulp-`src()`-style. Returns what was actually removed (or, in dry-run mode,
+ * what *would* be), relative to `dirname`, so the caller only logs what really happened.
+ *
+ * `exclude` protects at two levels: a pattern matching a whole `include` result directly (e.g.
+ * `packages/pkg1/*` against a matched `packages/pkg1/build` directory) drops that result before
+ * anything under it is touched; a finer pattern (e.g. `build/*.json`) instead protects just the
+ * matching files *inside* an otherwise-deleted directory, leaving the rest of it gone and the
+ * protected files (and their now non-empty parent) in place.
+ */
+async function cleanGlobs(dirname, include, exclude, dryRun) {
+    if (!include.length)
+        return [];
+    const matches = await fg(include, { cwd: dirname, ignore: exclude, onlyFiles: false, dot: true, absolute: true });
+    const protectedFiles = exclude.length
+        ? new Set(await fg(exclude, { cwd: dirname, onlyFiles: true, dot: true, absolute: true }))
+        : new Set();
+    const removed = [];
+    for (const m of matches) {
+        const stat = await fs.promises.stat(m).catch(() => undefined);
+        if (!stat)
+            continue;
+        if (stat.isDirectory()) {
+            const filesInside = await fg('**', { cwd: m, onlyFiles: true, dot: true, absolute: true });
+            for (const f of filesInside) {
+                if (protectedFiles.has(f))
+                    continue;
+                await remove(f, dryRun);
+                removed.push(path.relative(dirname, f));
+            }
+            pruneEmptyDirs(m, true, dryRun);
+        }
+        else if (!protectedFiles.has(m)) {
+            await remove(m, dryRun);
+            removed.push(path.relative(dirname, m));
+        }
+    }
+    return removed;
+}
+/**
+ * Removes compiled TypeScript output (`.js`, `.js.map`, `.d.ts`) sitting next to its `.ts`
+ * source under `src`/`test` - the same job `ts-cleanup -s <dir> --all` did (the only mode this
+ * project ever actually used it in). A `.d.ts` with no matching `.ts`/`.tsx` is left alone - it's
+ * presumably a hand-written declaration file, not build output. Prunes directories left empty
+ * afterward.
+ */
+async function cleanTsArtifacts(dirname, dryRun) {
+    const removed = [];
+    for (const sub of TS_SOURCE_DIRS) {
+        const dir = path.join(dirname, sub);
+        if (!fs.existsSync(dir))
+            continue;
+        const files = await fg('**/*.{js,js.map,d.ts}', { cwd: dir, onlyFiles: true, dot: true, absolute: true });
+        for (const f of files) {
+            if (f.endsWith('.d.ts')) {
+                const base = f.slice(0, -'.d.ts'.length);
+                if (!fs.existsSync(base + '.ts') && !fs.existsSync(base + '.tsx'))
+                    continue;
+            }
+            await remove(f, dryRun);
+            removed.push(path.relative(dirname, f));
+        }
+        pruneEmptyDirs(dir, false, dryRun);
+    }
+    return removed;
+}
+/**
+ * Removes TypeScript's incremental-build cache files (`*.tsbuildinfo`) anywhere under `dirname` -
+ * `tsc --build`/`composite`/`incremental` output that `ts-cleanup` never touched, but which can
+ * leave a project in a stale state if a clean rebuild is expected to start from nothing. Skips
+ * `node_modules` (dependencies may ship their own, irrelevant to this package's own build).
+ */
+async function cleanTsBuildInfo(dirname, dryRun) {
+    const files = await fg('**/*.tsbuildinfo', {
+        cwd: dirname,
+        ignore: ['**/node_modules/**'],
+        onlyFiles: true,
+        dot: true,
+        absolute: true,
+    });
+    for (const f of files)
+        await remove(f, dryRun);
+    return files.map(f => path.relative(dirname, f));
+}
+async function cleanPackage(pkg, item, panelEnabled, dryRun, logger) {
+    item.status = 'running';
+    item.startedAt = Date.now();
+    try {
+        item.currentStep = 'ts';
+        const tsRemoved = await cleanTsArtifacts(pkg.dirname, dryRun);
+        const buildInfoRemoved = await cleanTsBuildInfo(pkg.dirname, dryRun);
+        item.currentStep = 'glob';
+        const { include, exclude } = cleanConfig(pkg);
+        const globRemoved = await cleanGlobs(pkg.dirname, include, exclude, dryRun);
+        const removed = [...tsRemoved, ...buildInfoRemoved, ...globRemoved];
+        const verb = dryRun ? 'would rm' : 'rm';
+        if (panelEnabled) {
+            item.lastLine = removed.length
+                ? `${dryRun ? 'would remove' : 'removed'} ${removed.length} item(s)`
+                : 'already clean';
+        }
+        else if (removed.length) {
+            for (const r of removed)
+                logger.info(colors.yellow(verb), colors.cyan(item.name), r);
+        }
+        else {
+            logger.info(colors.gray('clean'), colors.cyan(item.name));
+        }
+        item.status = 'success';
+    }
+    catch (e) {
+        item.status = 'failed';
+        item.log.push(e?.message ?? String(e));
+        throw e;
+    }
+    finally {
+        item.finishedAt = Date.now();
+    }
+}

package/services/exec.service.d.ts

@@ -0,0 +1,35 @@
+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 ExecService {
+    interface Options extends PackageFilterOptions {
+        /** Max packages at once: `true`/omitted = CPU count, a number = that many, `false` = serial (1). */
+        parallel?: boolean | number;
+        /** Respect the package dependency graph: a package waits for its dependencies and is skipped
+         *  if one fails. Default true. Set false to run in every matching package independently,
+         *  alphabetically, regardless of the dependency graph. */
+        topo?: boolean;
+        bail?: boolean;
+        changed?: boolean;
+        changedSince?: string;
+        /** Show the live progress panel. Default true; auto-disabled when stdout isn't a TTY. */
+        progress?: boolean;
+        /** Verbosity of the classic per-package log (only applies when the live panel is off). Falls
+         *  back to the root's `.rmanrc logLevel`, then 'info' - see `resolveRootLogLevel`. */
+        logLevel?: LogLevel;
+        /** Run across the whole repository even when the current directory is inside a single package
+         *  (which otherwise scopes the run to just that package). Has no effect when already at the
+         *  repository root, or outside any known package. */
+        root?: boolean;
+    }
+    /**
+     * `exec`: runs `command` (an arbitrary shell command, not an npm script) directly in every
+     * matching package's own directory - unlike `run`, there's no `package.json` script to resolve
+     * and no `pre<script>`/`post<script>` npm lifecycle convention to honor, since the command isn't
+     * tied to any script name at all. Everything else about how packages are selected and scheduled
+     * matches `run`: topological order and per-package bail by default, the same live progress panel
+     * (falling back to a classic one-line-per-package log when it's off), and the same
+     * `--scope`/`--ignore`/`--deps`/`--dependents`/`--changed` package filtering.
+     */
+    function exec(repository: Repository, command: string, options?: Options): Promise<void>;
+}

package/services/exec.service.js

@@ -0,0 +1,114 @@
+import os from 'node:os';
+import colors from 'ansi-colors';
+import { Task } from 'power-tasks';
+import { exec as execCommand } from '../utils/exec.js';
+import { Logger, resolveRootLogLevel } from '../utils/logger.js';
+import { filterPackages } from '../utils/package-filter.js';
+import { ProgressPanel } from '../utils/progress-panel.js';
+export var ExecService;
+(function (ExecService) {
+    /**
+     * `exec`: runs `command` (an arbitrary shell command, not an npm script) directly in every
+     * matching package's own directory - unlike `run`, there's no `package.json` script to resolve
+     * and no `pre<script>`/`post<script>` npm lifecycle convention to honor, since the command isn't
+     * tied to any script name at all. Everything else about how packages are selected and scheduled
+     * matches `run`: topological order and per-package bail by default, the same live progress panel
+     * (falling back to a classic one-line-per-package log when it's off), and the same
+     * `--scope`/`--ignore`/`--deps`/`--dependents`/`--changed` package filtering.
+     */
+    async function exec(repository, command, options = {}) {
+        const logLevelDefault = resolveRootLogLevel(repository);
+        const logger = new Logger(options.logLevel ?? logLevelDefault);
+        const cwdScope = options.root ? undefined : repository.currentPackage;
+        const topo = options.topo ?? true;
+        let packages = repository.getPackages({ toposort: topo, scope: cwdScope?.name });
+        if (!topo)
+            packages = [...packages].sort((a, b) => a.name.localeCompare(b.name));
+        packages = filterPackages(packages, options);
+        if (options.changed || options.changedSince) {
+            const status = await repository.listStatus({ hash: options.changedSince });
+            packages = packages.filter(p => status[p.name] !== 'clean');
+        }
+        if (!packages.length) {
+            logger.info(colors.gray('No package matched.'));
+            return;
+        }
+        const concurrency = options.parallel === false
+            ? 1
+            : typeof options.parallel === 'number'
+                ? options.parallel
+                : options.parallel === true
+                    ? os.cpus().length
+                    : os.cpus().length;
+        const progress = options.progress ?? true;
+        const panel = new ProgressPanel('EXEC', !!process.stdout.isTTY && progress);
+        const bail = options.bail ?? true;
+        let rootTask;
+        const names = new Set(packages.map(p => p.name));
+        const children = packages.map(pkg => {
+            const ctx = panel.addItem(pkg.name);
+            const dependencies = topo ? pkg.dependencies.filter(d => names.has(d)) : [];
+            return new Task(() => execForPackage(ctx, panel.enabled, pkg.dirname, command, logger, bail ? () => rootTask?.abort() : () => { }), { name: pkg.name, dependencies });
+        });
+        panel.start();
+        let failed = false;
+        try {
+            /** bail:false here - each item's own task decides whether to call `rootTask.abort()`
+             *  itself (see `execForPackage`), mirroring `run`'s own reasoning: power-tasks' own `bail`
+             *  is a single blanket policy, it can't be conditional on `options.bail`. `toPromise()`
+             *  still rejects on any child's failure regardless, whether or not it triggered an abort. */
+            rootTask = new Task(children, { concurrency, bail: false });
+            await rootTask.toPromise();
+        }
+        catch {
+            failed = true;
+        }
+        finally {
+            panel.stop();
+        }
+        panel.printSummary();
+        if (failed) {
+            const err = new Error('"exec" failed');
+            err.logged = true;
+            throw err;
+        }
+    }
+    ExecService.exec = exec;
+})(ExecService || (ExecService = {}));
+async function execForPackage(ctx, panelEnabled, cwd, command, logger, abort) {
+    ctx.status = 'running';
+    ctx.startedAt = Date.now();
+    try {
+        if (panelEnabled) {
+            await execCommand(command, {
+                cwd,
+                stdio: 'pipe',
+                onLine: line => {
+                    ctx.log.push(line);
+                    ctx.lastLine = line;
+                },
+            });
+        }
+        else {
+            logger.info(colors.cyan('exec'), colors.cyan(ctx.name), command);
+            const t = Date.now();
+            try {
+                await execCommand(command, { cwd, stdio: 'inherit' });
+                logger.info(colors.green('success'), colors.cyan(ctx.name), colors.yellow(`(${Date.now() - t} ms)`));
+            }
+            catch (e) {
+                logger.error(colors.red('failed'), colors.cyan(ctx.name), colors.yellow(`(${Date.now() - t} ms)`));
+                throw e;
+            }
+        }
+        ctx.status = 'success';
+    }
+    catch (e) {
+        ctx.status = 'failed';
+        abort();
+        throw e;
+    }
+    finally {
+        ctx.finishedAt = Date.now();
+    }
+}

package/services/import.service.d.ts

@@ -0,0 +1,30 @@
+import type { Repository } from '../core/repository.js';
+export declare namespace ImportService {
+    interface Options {
+        /** Subdirectory (relative to the repository root) the new package is placed under - default `'packages'`. */
+        dest?: string;
+    }
+    interface Result {
+        /** The imported package's name (from its own `package.json`, or its directory basename). */
+        name: string;
+        /** Where it was placed, absolute. */
+        targetDir: string;
+        commitCount: number;
+    }
+    /**
+     * Imports `sourcePath` (a local clone of some other git repository) as a new package under this
+     * repository, preserving its **entire commit history** - every original commit, author, date and
+     * message stays intact, just as if the package had always lived at its new path. Unlike copying
+     * the files over and making one "import" commit, `git blame`/`git log --follow` keep working on
+     * the imported files afterward.
+     *
+     * How: every commit reachable from `sourcePath`'s HEAD is turned into a patch (`git format-patch
+     * --root`, oldest first), each patch's file paths are rewritten to be prefixed with the new
+     * subdirectory, then replayed onto this repository via `git am` (preserving authorship). A
+     * source repo with merge commits or binary-file renames can still trip up a patch here or there -
+     * same caveat `lerna import` has, since both use this same replay approach rather than a real
+     * merge (which real `git subtree` would give, at the cost of far less predictable behavior
+     * across git versions - the reason this - and lerna - avoid it).
+     */
+    function importRepo(repository: Repository, sourcePath: string, options?: Options): Promise<Result>;
+}