rman 2.8.0 → 2.9.0

package/builtins/platforms/node/node-manifest.provider.d.ts

@@ -9,6 +9,11 @@ export declare class NodeManifestProvider implements ManifestProvider {
      * npm's four dependency fields, and only the entries naming a package of this repository -
      * an external dependency is not an edge in rman's graph.
      *
+     * A peer marked `"optional": true` in `peerDependenciesMeta` is **not** an edge: an optional peer
+     * is by definition one the package works without, so it states no order. It still counts where
+     * another field declares it too - the fields are read together, and `devDependencies` naming it
+     * is a real build-time need whatever the peer block says.
+     *
      * Matched by name, which is npm's own identifier and unique by construction; an ecosystem where
      * that does not hold resolves its own way, which is why this is the provider's job.
      */
@@ -51,6 +56,11 @@ export declare class NodeManifestProvider implements ManifestProvider {
         constant?: string;
     }): string | undefined;
     write(dir: string, manifest: Manifest): void;
+    /** The peers this manifest marks `"optional": true`, which `dependencies` leaves out of the
+     *  graph. `optionalDependencies` is deliberately *not* read the same way: an optional peer says
+     *  "works without it", while an optional dependency is one the package means to use and may fail
+     *  to install. */
+    protected optionalPeerNames(manifest: Manifest): Set<string>;
 }
 /**
  * `package.json` as rman's manifest: where an npm package's name and version are written.

package/builtins/platforms/node/node-manifest.provider.js

@@ -26,17 +26,34 @@ export class NodeManifestProvider {
      * npm's four dependency fields, and only the entries naming a package of this repository -
      * an external dependency is not an edge in rman's graph.
      *
+     * A peer marked `"optional": true` in `peerDependenciesMeta` is **not** an edge: an optional peer
+     * is by definition one the package works without, so it states no order. It still counts where
+     * another field declares it too - the fields are read together, and `devDependencies` naming it
+     * is a real build-time need whatever the peer block says.
+     *
      * Matched by name, which is npm's own identifier and unique by construction; an ecosystem where
      * that does not hold resolves its own way, which is why this is the provider's job.
      */
+    /* **Measured on `panates/opra`, which is why the second half of that rule is written out.**
+     * Seven of its edges are optional peers, and *every one* of them is also a `devDependencies`
+     * entry - so excluding optional peers removed no edge at all, and the `@opra/cli` <-> `@opra/api-ui`
+     * cycle that was destroying its build order stood untouched. Reading the peer block alone would
+     * have looked like a fix and changed nothing. */
     dependencies(manifest, candidates) {
-        const declared = Object.assign({}, ...DEPENDENCY_KEYS.map(key => manifest.raw[key]));
+        const optionalPeers = this.optionalPeerNames(manifest);
         const byName = new Map(candidates.map(p => [p.name, p]));
         const result = [];
-        for (const name of Object.keys(declared)) {
-            const pkg = byName.get(name);
-            if (pkg && !result.includes(pkg))
-                result.push(pkg);
+        for (const key of DEPENDENCY_KEYS) {
+            const declared = manifest.raw[key];
+            if (!declared || typeof declared !== 'object')
+                continue;
+            for (const name of Object.keys(declared)) {
+                if (key === 'peerDependencies' && optionalPeers.has(name))
+                    continue;
+                const pkg = byName.get(name);
+                if (pkg && !result.includes(pkg))
+                    result.push(pkg);
+            }
         }
         return result;
     }
@@ -108,6 +125,16 @@ export class NodeManifestProvider {
         const raw = { ...manifest.raw, version: manifest.version };
         fs.writeFileSync(path.join(dir, 'package.json'), JSON.stringify(raw, undefined, 2) + '\n', 'utf-8');
     }
+    /** The peers this manifest marks `"optional": true`, which `dependencies` leaves out of the
+     *  graph. `optionalDependencies` is deliberately *not* read the same way: an optional peer says
+     *  "works without it", while an optional dependency is one the package means to use and may fail
+     *  to install. */
+    optionalPeerNames(manifest) {
+        const meta = manifest.raw.peerDependenciesMeta;
+        if (!meta || typeof meta !== 'object')
+            return new Set();
+        return new Set(Object.keys(meta).filter(name => meta[name]?.optional === true));
+    }
 }
 /**
  * `package.json` as rman's manifest: where an npm package's name and version are written.

package/builtins/platforms/node/services/clean.service.js

@@ -76,9 +76,22 @@ export var CleanService;
     }
     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'];
+/**
+ * Where a package's own build output lives, so the sweep below can leave it alone - the resolved
+ * `publish.npm.directory`, falling back to `build`.
+ *
+ * **Read from the config, never hardcoded.** The directory is the repository's to name: the shared
+ * preset drives it from a `vars.buildDir`, and a repository that renames it moves
+ * `publish.npm.directory`, `clean.include` and the build itself together. A literal `build` here
+ * would sweep a repository that calls it `dist` - deleting every emitted file in it, one at a time,
+ * because each sits beside nothing and the guard below would not fire. `publish`'s own generated
+ * manifest reads the same key, which is what keeps the two from disagreeing about where a package
+ * is built.
+ */
+function buildDirOf(pkg) {
+    const configured = pkg.config?.publish?.npm?.directory;
+    return typeof configured === 'string' && configured ? configured : 'build';
+}
 /** 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
@@ -157,32 +170,100 @@ async function cleanGlobs(dirname, include, exclude, dryRun) {
     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.
+ * Removes compiled TypeScript output (`.js`, `.js.map`, `.d.ts`) sitting next to its `.ts` source,
+ * anywhere in the package except `node_modules` and the build directory. Prunes directories left
+ * empty afterward.
+ *
+ * **Two tiers, because how much a directory tells you differs.** Under `src`/`test` everything is
+ * TypeScript, so a compiled file is swept whether or not its source is still there - which keeps
+ * the orphan case working, a `.js` whose `.ts` was renamed or deleted. Anywhere else in the package
+ * a file is swept **only when a matching `.ts`/`.tsx` sits beside it**, because that is the only
+ * thing that distinguishes output from something somebody wrote.
  */
-async function cleanTsArtifacts(dirname, dryRun) {
+/* **It used to look only in `src/` and `test/`**, inherited from `ts-cleanup -s src` - and that is
+ * the half this exists to fix. `tsc` writes its output beside the source whenever a config does not
+ * send it elsewhere, which is exactly the accident `clean` is reached for, and a package keeping
+ * `index.ts` at its own root was therefore never swept. Measured on `panates/opra`: ten emitted
+ * files in `examples/**` survived every `rman clean`, and `rman lint` there died inside
+ * `eslint-plugin-import-x` on one of them - a crash that looks like an eslint problem and is a stale
+ * artifact.
+ *
+ * **Widening the search without a guard outside `src`/`test` would have been destructive**, which
+ * is why the two tiers arrived together. Under `src/` a bare `.js` is deleted unconditionally and
+ * should be; over a whole package the same rule reaches `index.js`, `*.config.js`, `scripts/*.js` -
+ * hand-written files with no `.ts` behind them. The `.d.ts` rule was already the right one for that
+ * ground and now covers all three extensions there. The cost, stated rather than hidden: outside a
+ * source root, a compiled `.js` whose `.ts` has since been deleted is left alone, because nothing
+ * on disk says it was ever generated.
+ *
+ * **The build directory is excluded by name from the config, never as the literal `build`** - see
+ * `buildDirOf`. Its contents are the *point* of a build and are removed by `clean.include` when the
+ * repository asks, not by a rule about stray files. */
+async function cleanTsArtifacts(pkg, dryRun) {
+    const dirname = pkg.dirname;
+    const buildDir = buildDirOf(pkg);
+    const files = await fg('**/*.{js,js.map,d.ts}', {
+        cwd: dirname,
+        ignore: ['**/node_modules/**', `${buildDir}/**`, `**/${buildDir}/**`],
+        onlyFiles: true,
+        dot: true,
+        absolute: true,
+    });
     const removed = [];
+    for (const f of files) {
+        if (!isBuildOutput(dirname, f))
+            continue;
+        await remove(f, dryRun);
+        removed.push(path.relative(dirname, f));
+    }
+    /** Pruned from the source roots, exactly as before - `pruneEmptyDirs` with `includeSelf: false`
+     *  clears what is *under* a directory and keeps the directory itself, so `src/sub` left empty is
+     *  removed and `src` is not. Nothing is pruned elsewhere in the package: a directory that was
+     *  only searched is not one the caller asked to delete. */
     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);
+        if (fs.existsSync(dir))
+            pruneEmptyDirs(dir, false, dryRun);
     }
     return removed;
 }
+/**
+ * Whether a compiled file is this package's own build output, and so may go.
+ *
+ * Three rules, and each is a different amount of evidence:
+ *
+ * - **A `.d.ts` always needs its `.ts`/`.tsx` beside it**, everywhere including `src` - a
+ *   hand-written declaration is an ordinary thing to keep in a source tree, and this is the rule
+ *   that has always been here.
+ * - **A `.js`/`.js.map` under `src`/`test` goes regardless.** Everything there is TypeScript, so an
+ *   orphan - output whose source was renamed or deleted - is still output, and sweeping it is the
+ *   `ts-cleanup --all` behaviour this replaced.
+ * - **A `.js`/`.js.map` anywhere else needs its source beside it**, because out there it could just
+ *   as easily be `index.js`, `*.config.js` or `scripts/*.js`, which nobody generated.
+ */
+function isBuildOutput(dirname, file) {
+    if (file.endsWith('.d.ts'))
+        return hasTsSource(file, '.d.ts');
+    if (insideTsSourceDir(dirname, file))
+        return true;
+    return hasTsSource(file, file.endsWith('.js.map') ? '.js.map' : '.js');
+}
+/** Directories where everything is TypeScript, so a compiled file needs no source beside it to be
+ *  recognized as one - the two `ts-cleanup -s <dir>` was ever invoked with here. */
+const TS_SOURCE_DIRS = ['src', 'test'];
+/** Whether `file` sits under one of the package's TypeScript source roots. Compared on the path
+ *  segments rather than with `startsWith`, so a `source/` directory is not read as `src`. */
+function insideTsSourceDir(dirname, file) {
+    const rel = path.relative(dirname, file).split(path.sep);
+    return TS_SOURCE_DIRS.includes(rel[0]);
+}
+/** Whether a compiled file has its `.ts`/`.tsx` source sitting beside it - which is what makes it
+ *  compiled output rather than something somebody wrote. `suffix` is the compiled extension to
+ *  strip, passed in because `.js.map` and `.js` both end in `.js` and the caller already knows. */
+function hasTsSource(file, suffix) {
+    const base = file.slice(0, -suffix.length);
+    return fs.existsSync(base + '.ts') || fs.existsSync(base + '.tsx');
+}
 /**
  * Removes TypeScript's incremental-build cache files (`*.tsbuildinfo`) anywhere under `dirname` -
  * `tsc --build`/`composite`/`incremental` output that `ts-cleanup` never touched, but which can
@@ -206,7 +287,7 @@ async function cleanPackage(pkg, item, panelEnabled, dryRun, logger) {
     item.startedAt = Date.now();
     try {
         item.currentStep = 'ts';
-        const tsRemoved = await cleanTsArtifacts(pkg.dirname, dryRun);
+        const tsRemoved = await cleanTsArtifacts(pkg, dryRun);
         const buildInfoRemoved = await cleanTsBuildInfo(pkg.dirname, dryRun);
         item.currentStep = 'glob';
         const { include, exclude } = cleanConfig(pkg);

package/cli.js

@@ -152,7 +152,11 @@ export async function runCli(options) {
                 return { name: c.name, file: c.file, module: toCustomModule(c.custom, repository, app) };
             const declared = c.register(app);
             const meta = checkCustomCommand({ ...declared, command: declared.command?.trim() || c.name }, describeCommandSource(c.file));
-            return { name: commandName(meta.command), file: c.file, module: toYargsCommand(meta) };
+            return {
+                name: commandName(meta.command),
+                file: c.file,
+                module: toYargsCommand(meta, args => commandContext(repository, app, args)),
+            };
         });
         /**
          * **One command per name, keeping the last** - which is the precedence that already applied,
@@ -210,7 +214,7 @@ export async function runCli(options) {
         for (const meta of builtIns) {
             if (shadowed.includes(meta))
                 continue;
-            program.command(toYargsCommand(meta));
+            program.command(toYargsCommand(meta, args => commandContext(repository, app, args)));
         }
         /** Said out loud at `verbose`, for the reason the contributed-on-contributed note above gives:
          *  an override is correct and should not nag, but "rman test does something else here" needs a
@@ -550,17 +554,31 @@ function toCustomModule(custom, repository, app) {
         describe: custom.describe,
         configKeys: custom.configKeys,
         builder: custom.builder ?? ((y) => y),
-        handler: (args) => {
-            /** Resolved per invocation, not once at registration: `--log-level` is only known now. */
-            const logLevel = args.logLevel ?? resolveRootLogLevel(repository);
-            const context = {
-                repository,
-                package: repository.currentPackage,
-                runBin: (bin, argv, opts) => runBin(bin, argv, { cwd: repository.dirname, logLevel, app, ...opts }),
-                logger: new Logger(logLevel),
-            };
-            return custom.handler(context, args);
-        },
+        handler: (args) => custom.handler(commandContext(repository, app, args), args),
+    };
+}
+/**
+ * What a command is handed beside its argv - **one object, built in one place, for both authoring
+ * forms.** A `.rman/*.mjs` command takes it as its first parameter and a declared command as its
+ * second; what is in it is the same either way, so a facility added here reaches both.
+ *
+ * **Built per invocation rather than once at registration**, which is the whole reason it exists
+ * separately from `app`: `app` is the application, this is *this run*. `--log-level` is only known
+ * now, and `runBin`/`logger` carry it - an imported `runBin` knows neither, so `--log-level silent`
+ * would quietly fail to apply to the one part of a command that produces output.
+ */
+function commandContext(repository, app, args) {
+    const logLevel = args.logLevel ?? resolveRootLogLevel(repository);
+    const run = app.getService('run');
+    return {
+        repository,
+        package: repository.currentPackage,
+        runBin: (bin, argv, opts) => runBin(bin, argv, { cwd: repository.dirname, logLevel, app, ...opts }),
+        logger: new Logger(logLevel),
+        /** Bound, not passed as the service: a command should not have to know which service owns the
+         *  scheduler, and `logLevel` is this run's rather than the repository's default. */
+        forEachPackage: (packages, fn, options) => run.forEachPackage(packages, fn, { logLevel, ...options }),
+        parallel: (tasks, options) => run.parallel(tasks, options ?? {}),
     };
 }
 /**

package/constants.js

@@ -1 +1 @@
-export const version = '2.8.0';
+export const version = '2.9.0';

package/core/classes/repository.d.ts

@@ -38,6 +38,16 @@ export declare class Repository extends Package {
      * rewrites every bumped manifest and then re-interpolates its deferred hooks.
      */
     private readonly _files;
+    /**
+     * Every dependency cycle found in the **declared** graph, each one a path of package names that
+     * returns to where it started (`['@opra/cli', '@opra/api-ui', '@opra/cli']`). Empty for a graph
+     * that can be ordered.
+     *
+     * Recorded while the graph is built, from the *direct* edges - `Package.dependencies` is expanded
+     * transitively straight afterwards, and in the closure every member of a cycle depends on every
+     * other, so a path read back from it would name edges nobody declared.
+     */
+    protected _dependencyCycles: readonly (readonly string[])[];
     /**
      * The application this repository belongs to - its services, its technologies, its logger.
      *
@@ -62,6 +72,15 @@ export declare class Repository extends Package {
      * the repository root itself, or isn't inside any known package (e.g. a non-monorepo checkout,
      * or a stray directory the workspace glob doesn't cover).
      */
+    /**
+     * Every dependency cycle in the repository, each a path of package names returning to its start.
+     * Empty when the graph can be ordered.
+     *
+     * A cycle is not an error on its own - `list`, `info` and `config` answer perfectly well without
+     * an order, and refusing them would take away the commands you would use to find the cycle. It
+     * becomes one where something actually needs the order: see `getPackages({ toposort: true })`.
+     */
+    get dependencyCycles(): readonly (readonly string[])[];
     get currentPackage(): Package | undefined;
     getPackages(options?: {
         scope?: string | string[];
@@ -140,7 +159,26 @@ export declare class Repository extends Package {
      * function resolved against that package's scope.
      */
     protected _resolveConfigs(): Promise<void>;
+    /**
+     * Reorders `packages` in place so every package comes after the ones it depends on, keeping the
+     * given order among packages that do not constrain each other. Throws when they cannot be
+     * ordered - see `_describeCycle`.
+     *
+     * Only the edges *inside* `packages` count, so a `--scope` narrowing to part of the repository is
+     * ordered on its own terms.
+     */
     protected _topoSortPackages(packages: Package[]): void;
+    /**
+     * The message for a graph that cannot be ordered, naming the cycle rather than the packages that
+     * happened to be caught behind it.
+     *
+     * `stuck` is what Kahn's algorithm could not place, which is the cycle **plus everything
+     * downstream of it** - on `panates/opra` that was sixteen of twenty packages for one pair that
+     * named each other. So a recorded cycle lying entirely inside `stuck` is preferred, and the list
+     * is the fallback for the case a recorded path cannot cover: a cycle whose intermediate packages
+     * were filtered out by `--scope`, where the closure still pairs two of the survivors.
+     */
+    protected _describeCycle(stuck: Package[]): string;
     protected _packageScope(pkg: Package, targetVersion?: string): PackageScope;
     /** Built once and reused: it is the same for every package, and its `git` getter caches too, so a
      *  repository whose config never mentions git spawns none. */
@@ -161,6 +199,16 @@ export declare class Repository extends Package {
      */
     protected _resolveDeclaredPackage(entry: string): Package | undefined;
     protected _updateDependencies(): void;
+    /**
+     * Every cycle in the declared graph, as a path of names returning to its start. Depth-first, so
+     * the path is the one a reader can follow edge by edge in the manifests.
+     *
+     * Each cycle is reported once: a package is left `done` after its subtree is walked, so a second
+     * route into it is not a second finding. The cost of that is real and deliberate - two cycles
+     * sharing a package may come back as one path - and the aim here is to *name* a cycle, not to
+     * enumerate them; the first one has to be broken either way.
+     */
+    protected _findDependencyCycles(direct: ReadonlyMap<Package, Package[]>): readonly (readonly string[])[];
     /** `git` facts for a `${{ git.* }}` expression. Synchronous on purpose: it backs a lazy
      *  getter, and a getter cannot await. Everything is `undefined` outside a git checkout - not an
      *  error, just a repository without one. */

package/core/classes/repository.js

@@ -42,6 +42,16 @@ export class Repository extends Package {
      * rewrites every bumped manifest and then re-interpolates its deferred hooks.
      */
     _files = new ConfigFileScope();
+    /**
+     * Every dependency cycle found in the **declared** graph, each one a path of package names that
+     * returns to where it started (`['@opra/cli', '@opra/api-ui', '@opra/cli']`). Empty for a graph
+     * that can be ordered.
+     *
+     * Recorded while the graph is built, from the *direct* edges - `Package.dependencies` is expanded
+     * transitively straight afterwards, and in the closure every member of a cycle depends on every
+     * other, so a path read back from it would name edges nobody declared.
+     */
+    _dependencyCycles = [];
     /**
      * The application this repository belongs to - its services, its technologies, its logger.
      *
@@ -79,6 +89,17 @@ export class Repository extends Package {
      * the repository root itself, or isn't inside any known package (e.g. a non-monorepo checkout,
      * or a stray directory the workspace glob doesn't cover).
      */
+    /**
+     * Every dependency cycle in the repository, each a path of package names returning to its start.
+     * Empty when the graph can be ordered.
+     *
+     * A cycle is not an error on its own - `list`, `info` and `config` answer perfectly well without
+     * an order, and refusing them would take away the commands you would use to find the cycle. It
+     * becomes one where something actually needs the order: see `getPackages({ toposort: true })`.
+     */
+    get dependencyCycles() {
+        return this._dependencyCycles;
+    }
     get currentPackage() {
         if (path.resolve(this.cwd) === path.resolve(this.dirname))
             return undefined;
@@ -269,14 +290,85 @@ export class Repository extends Package {
         if (this.monorepo)
             this.rootPackage.config = this.config;
     }
+    /**
+     * Reorders `packages` in place so every package comes after the ones it depends on, keeping the
+     * given order among packages that do not constrain each other. Throws when they cannot be
+     * ordered - see `_describeCycle`.
+     *
+     * Only the edges *inside* `packages` count, so a `--scope` narrowing to part of the repository is
+     * ordered on its own terms.
+     */
+    /* **This was a `packages.sort(...)` comparator and it did not sort topologically.** A comparator
+     * answering `0` for two packages that do not depend on each other is not a total order, and
+     * `Array.sort` is free to never compare two elements it has placed through a third - so an order
+     * can come out that no single comparison contradicts and that is still wrong. Measured on the
+     * smallest case there is: three packages `[c, b, a]` with the one edge `c -> a` came back
+     * `c b a`, the dependency last. `publish` and `docker-publish` take this order as their publish
+     * order, so a package shipped before the sibling it is built against.
+     *
+     * Kahn's algorithm instead, taking the lowest-numbered ready package each round so the input
+     * order survives among independents - which is what makes `rman list --toposort` stable and its
+     * output diffable. `Package.dependencies` is the transitive closure by the time this runs; the
+     * closure of a DAG is a DAG with the same topological orders, so the extra edges cost a little
+     * bookkeeping and change no answer. */
     _topoSortPackages(packages) {
-        packages.sort((a, b) => {
-            if (b.dependencies.includes(a))
-                return -1;
-            if (a.dependencies.includes(b))
-                return 1;
-            return 0;
-        });
+        const inSubset = new Set(packages);
+        const position = new Map(packages.map((pkg, i) => [pkg, i]));
+        const waitingOn = new Map(packages.map(pkg => [pkg, 0]));
+        const dependents = new Map();
+        for (const pkg of packages) {
+            for (const dep of pkg.dependencies) {
+                if (!inSubset.has(dep))
+                    continue;
+                waitingOn.set(pkg, waitingOn.get(pkg) + 1);
+                const list = dependents.get(dep);
+                if (list)
+                    list.push(pkg);
+                else
+                    dependents.set(dep, [pkg]);
+            }
+        }
+        const ordered = [];
+        const ready = packages.filter(pkg => waitingOn.get(pkg) === 0);
+        while (ready.length) {
+            ready.sort((a, b) => position.get(a) - position.get(b));
+            const pkg = ready.shift();
+            ordered.push(pkg);
+            for (const dependent of dependents.get(pkg) ?? []) {
+                const left = waitingOn.get(dependent) - 1;
+                waitingOn.set(dependent, left);
+                if (left === 0)
+                    ready.push(dependent);
+            }
+        }
+        /** Anything left is in or above a cycle - the one thing a topological order cannot express. */
+        if (ordered.length < packages.length) {
+            const stuck = packages.filter(pkg => !ordered.includes(pkg));
+            throw new Error(this._describeCycle(stuck));
+        }
+        packages.length = 0;
+        packages.push(...ordered);
+    }
+    /**
+     * The message for a graph that cannot be ordered, naming the cycle rather than the packages that
+     * happened to be caught behind it.
+     *
+     * `stuck` is what Kahn's algorithm could not place, which is the cycle **plus everything
+     * downstream of it** - on `panates/opra` that was sixteen of twenty packages for one pair that
+     * named each other. So a recorded cycle lying entirely inside `stuck` is preferred, and the list
+     * is the fallback for the case a recorded path cannot cover: a cycle whose intermediate packages
+     * were filtered out by `--scope`, where the closure still pairs two of the survivors.
+     */
+    _describeCycle(stuck) {
+        const names = new Set(stuck.map(pkg => pkg.name));
+        const cycle = this._dependencyCycles.find(known => known.every(name => names.has(name)));
+        const what = cycle
+            ? `Dependency cycle: ${cycle.join(' -> ')}`
+            : `Dependency cycle among: ${stuck.map(pkg => pkg.name).join(', ')}`;
+        return (`${what}\n` +
+            `  Packages that depend on each other cannot be put in build order. Break the cycle in the\n` +
+            `  manifests (a peer marked "optional" is not an edge) or in .rmanrc "dependencies", or run\n` +
+            `  without ordering where the command offers it (--no-topo).`);
     }
     _packageScope(pkg, targetVersion) {
         // A manifest without a "name" is unusual but legal, and `info` prints such a package rather
@@ -359,10 +451,13 @@ export class Repository extends Package {
     }
     _updateDependencies() {
         const deps = {};
+        const direct = new Map();
         for (const pkg of this.packages) {
             /** Which manifest fields hold dependencies is the ecosystem's business, so the provider
              *  reads them - npm's four field names used to be spelled out right here. */
-            const dependencies = [...Manifest.dependenciesOf(pkg, this.packages)];
+            /** A package naming *itself* is dropped here, the same way the declared entries below are:
+             *  it constrains nothing, and left in it would read as a one-package cycle. */
+            const dependencies = [...Manifest.dependenciesOf(pkg, this.packages)].filter(d => d !== pkg);
             /** `.rmanrc "dependencies"` on top, and it works with no provider at all: a repository rman
              *  cannot read the manifests of can still declare its graph by hand. */
             const declared = pkg.config.dependencies ?? [];
@@ -373,7 +468,11 @@ export class Repository extends Package {
             }
             deps[pkg.name] = dependencies.map(d => d.name);
             pkg.dependencies = dependencies;
+            /** Copied, because the expansion below mutates `pkg.dependencies` in place - and what a
+             *  reader needs to see is the edge somebody wrote, not the closure's. */
+            direct.set(pkg, [...dependencies]);
         }
+        this._dependencyCycles = this._findDependencyCycles(direct);
         let circularCheck;
         const deepFindDependencies = (pkg, target) => {
             if (circularCheck.includes(pkg))
@@ -395,6 +494,38 @@ export class Repository extends Package {
             deepFindDependencies(pkg, pkg.dependencies);
         }
     }
+    /**
+     * Every cycle in the declared graph, as a path of names returning to its start. Depth-first, so
+     * the path is the one a reader can follow edge by edge in the manifests.
+     *
+     * Each cycle is reported once: a package is left `done` after its subtree is walked, so a second
+     * route into it is not a second finding. The cost of that is real and deliberate - two cycles
+     * sharing a package may come back as one path - and the aim here is to *name* a cycle, not to
+     * enumerate them; the first one has to be broken either way.
+     */
+    _findDependencyCycles(direct) {
+        const cycles = [];
+        const state = new Map();
+        const trail = [];
+        const visit = (pkg) => {
+            const seen = state.get(pkg);
+            if (seen === 'done')
+                return;
+            if (seen === 'open') {
+                cycles.push([...trail.slice(trail.indexOf(pkg)), pkg].map(p => p.name));
+                return;
+            }
+            state.set(pkg, 'open');
+            trail.push(pkg);
+            for (const dep of direct.get(pkg) ?? [])
+                visit(dep);
+            trail.pop();
+            state.set(pkg, 'done');
+        };
+        for (const pkg of this.packages)
+            visit(pkg);
+        return cycles;
+    }
     /** `git` facts for a `${{ git.* }}` expression. Synchronous on purpose: it backs a lazy
      *  getter, and a getter cannot await. Everything is `undefined` outside a git checkout - not an
      *  error, just a repository without one. */

package/core/command-builder.d.ts

@@ -1,5 +1,6 @@
 import type { CommandModule } from 'yargs';
 import type { RmanConfig } from '../interfaces/rman-config.interface.js';
+import type { CommandContext } from './interfaces/custom-command.js';
 /**
  * Turns a command's **declaration** into the yargs registration it describes.
  *
@@ -9,6 +10,13 @@ import type { RmanConfig } from '../interfaces/rman-config.interface.js';
  * switches - arrives as data now, so a typo in any of it is a compile error at the command rather
  * than a flag that silently never existed.
  */
-export declare function toYargsCommand(meta: RmanConfig.CommandMetadata): CommandModule;
+export declare function toYargsCommand(meta: RmanConfig.CommandMetadata, 
+/**
+ * Builds the `CommandContext` the handler gets as its **second** parameter, per invocation.
+ *
+ * Optional because a caller with no repository in hand (a spec listing the registrations) has
+ * nothing to build one from, and a handler that never reads it cannot tell.
+ */
+contextFor?: (args: any) => CommandContext): CommandModule;
 /** A command's own name - the first word of its `command` string, before any positional. */
 export declare function commandName(command: string): string;

package/core/command-builder.js

@@ -7,7 +7,14 @@
  * switches - arrives as data now, so a typo in any of it is a compile error at the command rather
  * than a flag that silently never existed.
  */
-export function toYargsCommand(meta) {
+export function toYargsCommand(meta, 
+/**
+ * Builds the `CommandContext` the handler gets as its **second** parameter, per invocation.
+ *
+ * Optional because a caller with no repository in hand (a spec listing the registrations) has
+ * nothing to build one from, and a handler that never reads it cannot tell.
+ */
+contextFor) {
     return {
         command: meta.command,
         aliases: meta.aliases,
@@ -51,23 +58,29 @@ export function toYargsCommand(meta) {
          * narrower one is the useful one, and this is the single place the widening is admitted -
          * previously it was an `as` per option read, in every handler.
          */
-        handler: withCommandPlatforms(meta),
+        handler: wrapHandler(meta, contextFor),
     };
 }
 /**
- * Carries `CommandMetadata.platforms` into argv, where `readPackageFilterOptions` picks it up.
+ * The handler yargs is given: carries `CommandMetadata.platforms` into argv, and hands the command
+ * its `CommandContext` as a second parameter.
+ *
+ * **`(args, context)`, not `(context, args)`** - the opposite order to `CustomCommand.handler`, and
+ * decided by compatibility rather than taste: every declared command in existence is `handler(args)`,
+ * so appending a parameter breaks none of them while prepending one breaks all of them. The two
+ * authoring forms therefore disagree about the order and agree about everything in the object,
+ * which is the cheaper of the two inconsistencies.
  *
- * Through argv rather than a parameter because `filterPackages` is called by ten *services*, none
- * of which knows which command is running - `options` is all they see. One wrap here reaches every
- * one of them and changes none.
+ * `platforms` goes through argv rather than a parameter because `filterPackages` is called by ten
+ * *services*, none of which knows which command is running - `options` is all they see. One wrap
+ * here reaches every one of them and changes none.
  */
-function withCommandPlatforms(meta) {
+function wrapHandler(meta, contextFor) {
     const handler = meta.handler;
-    if (!meta.platforms?.length)
-        return handler;
     return (args) => {
-        args.commandPlatforms = meta.platforms;
-        return handler(args);
+        if (meta.platforms?.length)
+            args.commandPlatforms = meta.platforms;
+        return handler(args, contextFor?.(args));
     };
 }
 /** A command's own name - the first word of its `command` string, before any positional. */