rman 1.3.0 → 2.0.0-beta.3

package/builtins/platforms/node/commands/clean.command.d.ts

@@ -0,0 +1,185 @@
+import type { ArgsOf } from '../../../../index.js';
+import type { ConfigValue } from '../../../../interfaces/rman-config.interface.js';
+/** Hoisted for `ArgsOf` - see `ci.command.ts` and `RmanConfig.ArgsOf`. */
+declare const COMMAND: "clean";
+declare const config: {
+    progress: {
+        target: "cli";
+        describe: string;
+        type: "boolean";
+    };
+    dryRun: {
+        target: "cli";
+        cliName: string;
+        describe: string;
+        type: "boolean";
+    };
+    /** Config-only: `.rmanrc "clean.skip"` excludes a package from `clean` entirely. Not a flag -
+     *  a single run narrows with `--scope`/`--ignore`, which every command already has. */
+    skip: {
+        target: "config";
+        describe: string;
+        type: "boolean";
+    };
+    fromRoot: {
+        target: "cli";
+        cliName: string;
+        alias: string;
+        describe: string;
+        type: "boolean";
+    };
+    allowBranch: {
+        target: "cli";
+        cliName: string;
+        describe: string;
+        type: "string";
+    };
+    ignoreBranch: {
+        target: "cli";
+        cliName: string;
+        describe: string;
+        type: "string";
+    };
+    scope: {
+        target: "cli";
+        describe: string;
+        type: "string";
+    };
+    ignore: {
+        target: "cli";
+        describe: string;
+        type: "string";
+    };
+    platform: {
+        target: "cli";
+        describe: string;
+        type: "string";
+    };
+    deps: {
+        target: "cli";
+        describe: string;
+        type: "boolean";
+    };
+    dependents: {
+        target: "cli";
+        describe: string;
+        type: "boolean";
+    };
+};
+/**
+ * The rest of `clean.*` - the two keys an option cannot describe.
+ *
+ * `include`/`exclude` are each **a glob or a list of them**, and a `CommandOption` says one or the
+ * other: `type: 'string'` is a string, `array: true` beside it is a `string[]`. Neither is the
+ * union, and the union is what a config author actually writes (`include: 'build'` as often as
+ * `include: ['build', '*.tsbuildinfo']`). So they are written out and intersected in, which is what
+ * `Extra` is for - `skip` above is an ordinary option and is derived like everything else.
+ */
+export interface CleanExtraKeys {
+    /** Extra files and directories to remove, beyond TypeScript's own output - globs relative to
+     *  each package's own directory. Per-package cascaded; a package declaring its own `clean` block
+     *  replaces the root's entirely for itself, rather than combining with it. */
+    include?: ConfigValue<string | string[]>;
+    /** Globs to keep, applied after `include`. */
+    exclude?: ConfigValue<string | string[]>;
+}
+type Args = ArgsOf<typeof config, typeof COMMAND>;
+/**
+ * `rman clean` - contributed by the `node` built-in rather than always present, because what
+ * it deletes is TypeScript's output. See `CleanService.clean`.
+ *
+ * Declared the same way `ci` is - see that file for why a plugin uses `declareCommand` rather than
+ * `registerCommand`.
+ */
+export declare const cleanCommand: (app: import("../../../../index.js").RmanApplication) => {
+    command: "clean";
+    /** npm's alone: it deletes TypeScript build output, which no other ecosystem has. */
+    platforms: string[];
+    describe: string;
+    /**
+     * **No `configKeys`, because `clean` is this command's *own* key now** - derived from the
+     * `config` block above and contributed to `RmanConfig` by `CommandContribution`, exactly as a
+     * built-in contributes its own. It used to be hand-written in `NodeConfigKeys` *and* named
+     * here, which is two statements about one key.
+     *
+     * **The contribution itself is in `augmentation/rman.augmentation.ts`, not here**, and that is
+     * not a stylistic choice: one `declare module 'rman'` block per package is the limit, and a
+     * second silently disables the first. Measured again while moving this - a second block left
+     * `SystemInfo.PackageManager` unresolved at four call sites, with nothing pointing at the
+     * cause. rman's own commands declare theirs beside themselves because they augment a *module
+     * path*, which has no such limit.
+     */
+    config: {
+        progress: {
+            target: "cli";
+            describe: string;
+            type: "boolean";
+        };
+        dryRun: {
+            target: "cli";
+            cliName: string;
+            describe: string;
+            type: "boolean";
+        };
+        /** Config-only: `.rmanrc "clean.skip"` excludes a package from `clean` entirely. Not a flag -
+         *  a single run narrows with `--scope`/`--ignore`, which every command already has. */
+        skip: {
+            target: "config";
+            describe: string;
+            type: "boolean";
+        };
+        fromRoot: {
+            target: "cli";
+            cliName: string;
+            alias: string;
+            describe: string;
+            type: "boolean";
+        };
+        allowBranch: {
+            target: "cli";
+            cliName: string;
+            describe: string;
+            type: "string";
+        };
+        ignoreBranch: {
+            target: "cli";
+            cliName: string;
+            describe: string;
+            type: "string";
+        };
+        scope: {
+            target: "cli";
+            describe: string;
+            type: "string";
+        };
+        ignore: {
+            target: "cli";
+            describe: string;
+            type: "string";
+        };
+        platform: {
+            target: "cli";
+            describe: string;
+            type: "string";
+        };
+        deps: {
+            target: "cli";
+            describe: string;
+            type: "boolean";
+        };
+        dependents: {
+            target: "cli";
+            describe: string;
+            type: "boolean";
+        };
+    };
+    examples: ({
+        command: string;
+        description?: undefined;
+    } | {
+        command: string;
+        description: string;
+    })[];
+    handler: (args: Args) => Promise<void>;
+};
+export {};

package/builtins/platforms/node/commands/clean.command.js

@@ -0,0 +1,74 @@
+import { declareCommand } from '../../../../interfaces/rman-config.interface.js';
+import { assertAllowedBranch, branchGuardOptions, readBranchGuardOptions } from '../../../../utils/branch-guard.js';
+import { fromRootOption, packageFilterOptions, readPackageFilterOptions } from '../../../../utils/package-filter.js';
+import { CleanService } from '../services/clean.service.js';
+/** Hoisted for `ArgsOf` - see `ci.command.ts` and `RmanConfig.ArgsOf`. */
+const COMMAND = 'clean';
+const config = {
+    ...packageFilterOptions,
+    ...branchGuardOptions,
+    /** A group of one, and a function because its text is this command's own word for what it does. */
+    ...fromRootOption('Clean'),
+    progress: {
+        target: 'cli',
+        describe: 'Show a live progress panel (default: true; auto-disabled when not a TTY)',
+        type: 'boolean',
+    },
+    dryRun: {
+        target: 'cli',
+        cliName: 'dry-run',
+        describe: 'Report what would be removed without actually removing anything',
+        type: 'boolean',
+    },
+    /** Config-only: `.rmanrc "clean.skip"` excludes a package from `clean` entirely. Not a flag -
+     *  a single run narrows with `--scope`/`--ignore`, which every command already has. */
+    skip: {
+        target: 'config',
+        describe: 'Excludes this package from clean entirely',
+        type: 'boolean',
+    },
+};
+/**
+ * `rman clean` - contributed by the `node` built-in rather than always present, because what
+ * it deletes is TypeScript's output. See `CleanService.clean`.
+ *
+ * Declared the same way `ci` is - see that file for why a plugin uses `declareCommand` rather than
+ * `registerCommand`.
+ */
+export const cleanCommand = declareCommand(app => {
+    const repository = app.repository;
+    return {
+        command: COMMAND,
+        /** npm's alone: it deletes TypeScript build output, which no other ecosystem has. */
+        platforms: ['node'],
+        describe: 'Removes compiled TypeScript output and any extra files/dirs configured via .rmanrc "clean"',
+        /**
+         * **No `configKeys`, because `clean` is this command's *own* key now** - derived from the
+         * `config` block above and contributed to `RmanConfig` by `CommandContribution`, exactly as a
+         * built-in contributes its own. It used to be hand-written in `NodeConfigKeys` *and* named
+         * here, which is two statements about one key.
+         *
+         * **The contribution itself is in `augmentation/rman.augmentation.ts`, not here**, and that is
+         * not a stylistic choice: one `declare module 'rman'` block per package is the limit, and a
+         * second silently disables the first. Measured again while moving this - a second block left
+         * `SystemInfo.PackageManager` unresolved at four call sites, with nothing pointing at the
+         * cause. rman's own commands declare theirs beside themselves because they augment a *module
+         * path*, which has no such limit.
+         */
+        config,
+        examples: [
+            { command: '$0 clean' },
+            { command: '$0 clean --dry-run', description: '# Preview what would be removed' },
+        ],
+        handler: async (args) => {
+            await assertAllowedBranch(repository, readBranchGuardOptions(args));
+            await CleanService.clean(repository, {
+                ...readPackageFilterOptions(args),
+                progress: args.progress,
+                dryRun: args.dryRun,
+                fromRoot: args.fromRoot,
+                logLevel: args.logLevel,
+            });
+        },
+    };
+});

package/builtins/platforms/node/index.d.ts

@@ -0,0 +1,8 @@
+export * from './augmentation/rmanrc.augmentation.js';
+export * from './augmentation/system-info.augmentation.js';
+export * from './commands/ci.command.js';
+export * from './commands/clean.command.js';
+export * from './node.platform.js';
+export * from './node-config.interface.js';
+export * from './node-manifest.provider.js';
+export * from './utils/workspace-range.js';

package/builtins/platforms/node/index.js

@@ -0,0 +1,8 @@
+export * from './augmentation/rmanrc.augmentation.js';
+export * from './augmentation/system-info.augmentation.js';
+export * from './commands/ci.command.js';
+export * from './commands/clean.command.js';
+export * from './node.platform.js';
+export * from './node-config.interface.js';
+export * from './node-manifest.provider.js';
+export * from './utils/workspace-range.js';

package/builtins/platforms/node/node-config.interface.d.ts

@@ -0,0 +1,76 @@
+import type { ConfigValue, RmanConfig, ScopedVars } from '../../../interfaces/rman-config.interface.js';
+import type { CiService } from './services/ci.service.js';
+/**
+ * The `.rmanrc` keys that only mean something because the repository is a Node one.
+ *
+ * **One key, and it is here because no single command owns it**: `packageManager` is read by `ci`
+ * *and* by the `npm` publish target, so neither can contribute it. Everything else this package
+ * adds to `.rmanrc` is declared by whoever reads it - `clean.*` by `clean.command.ts` (through
+ * `CommandContribution`), `publish.npm.*` by the target, below.
+ *
+ * **Two surfaces, and they are not alternatives:**
+ *
+ * - the `declare module 'rman'` block in [`../augmentation/rman.augmentation.ts`] merges this into
+ *   `RmanConfigKeys`, so `repository.config.packageManager` stays typed wherever it is read with no
+ *   cast. It lives there because one such block per package is the limit;
+ * - `RmanNodeConfig` is the name a *config author* annotates with, which is what makes the import
+ *   carrying that augmentation explicit instead of a side effect someone has to remember.
+ */
+export interface NodeConfigKeys {
+    /**
+     * Which package manager `ci`/`publish` shell out to, and whose version `info` reports under
+     * `Binaries`. Root level only. Default `npm`.
+     *
+     * It used to be a core key, on the grounds that `info` read it - and that stopped being true the
+     * moment `SystemInfo`'s npm half moved here: measured, **nothing in rman's core reads it at
+     * all**, only the declaration was left behind. The value set was npm's tooling the whole time.
+     */
+    packageManager?: CiService.PackageManager;
+}
+export declare namespace RmanNodeConfig {
+    /**
+     * **`publish.npm.*`** - the `npm` publish target's own block, contributed through the
+     * `PublishTargetConfigs` slot rman's `publish` command exports for any target.
+     *
+     * Named after the target, the way `publish.docker.*` already was. It used to be `publish.directory`
+     * - a bare key sitting directly beside `target`, `skip` and `docker`, so the one block that was
+     * *not* a target's read as though it belonged to publishing in general. `target` and `skip` are
+     * genuinely `publish`'s own; `directory` never was.
+     */
+    interface NpmPublishOptions extends NpmPublishOptionsKeys, ScopedVars {
+    }
+    interface NpmPublishOptionsKeys {
+        /** Where this package's publishable output lives, relative to its own directory (e.g.
+         *  `"build"`). Per-package cascaded, so a root `"[*]"` block can say it once for the whole
+         *  repository instead of repeating `publishConfig.directory` in every `package.json` - which
+         *  still wins when a package declares it, being the more specific statement.
+         *
+         *  Publishing from such a directory means the manifest there is **generated by `publish`**,
+         *  from the package's own - see `PublishService`. There is nothing to configure about it. */
+        directory?: ConfigValue<string>;
+    }
+}
+/**
+ * `.rmanrc` for a repository using this plugin: rman's own keys plus the ones above.
+ *
+ * ```js
+ * // .rmanrc.mjs
+ * import { defineConfig } from 'rman';
+ *
+ * export default defineConfig({
+ *   plugins: ['node'],
+ *   '[*]': { clean: { include: 'build' }, publish: { npm: { directory: 'build' } } },
+ * });
+ * ```
+ *
+ * `.mjs`, not `.ts`: rman loads `.rmanrc.cjs`/`.mjs`/`.js` and no TypeScript form, so the type
+ * reaches a config file through the editor rather than through a compiler. The JSON and YAML forms
+ * carry no type at all - since the JSON Schema was removed, they are unchecked.
+ */
+export interface RmanNodeConfig extends RmanConfig {
+}
+/**
+ * Identity helper for authoring a `.rmanrc.mjs`/`.cjs`/`.js` config with this plugin's keys checked
+ * - rman's own `defineConfig` with a narrower parameter, nothing more. Returns `config` unchanged.
+ */
+export declare function defineConfig(config: RmanNodeConfig): RmanNodeConfig;

package/builtins/platforms/node/node-config.interface.js

@@ -0,0 +1,7 @@
+/**
+ * Identity helper for authoring a `.rmanrc.mjs`/`.cjs`/`.js` config with this plugin's keys checked
+ * - rman's own `defineConfig` with a narrower parameter, nothing more. Returns `config` unchanged.
+ */
+export function defineConfig(config) {
+    return config;
+}

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

@@ -0,0 +1,68 @@
+import type { Package } from '../../../core/classes/package.js';
+import type { ManifestProvider } from '../../../core/interfaces/manifest.js';
+import { Manifest } from '../../../core/interfaces/manifest.js';
+export declare class NodeManifestProvider implements ManifestProvider {
+    name: string;
+    fileName: string;
+    read(dir: string): Manifest | undefined;
+    /**
+     * 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.
+     *
+     * 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.
+     */
+    dependencies(manifest: Manifest, candidates: readonly Package[]): Package[];
+    /** npm's `@scope/name`. A name with no `/` has no scope and is its own unscoped form; the
+     *  *last* `/` splits it, so `@scope/a/b` keeps `@scope/a` as the scope the registry would. */
+    splitName(name: string): {
+        scope?: string;
+        unscopedName: string;
+    };
+    /**
+     * Rewrites a sibling's range in all four fields after it was bumped.
+     *
+     * **A bare `"workspace:*"`/`"^"`/`"~"` selector is left alone**, and that is the load-bearing
+     * case: it resolves to the dependency's *current* version at publish time (see
+     * `resolveWorkspaceRange`), so rewriting it would replace a live reference with a frozen one.
+     * Only an explicit version after `workspace:` needs bumping, like a plain range.
+     */
+    updateDependencyVersions(manifest: Manifest, bumped: ReadonlyMap<Package, string>): void;
+    /**
+     * What the npm registry says this package's current version is - used *only* by
+     * `detectChangeHash`, to guess a tag name for a package that has no git tag yet. See
+     * `Plugin.publishedVersion` for why that is not a "has this been published" check.
+     *
+     * No `--registry`/`--userconfig`: a bare `npm view` run in the package's own directory already
+     * honours the repository's `.npmrc`, and the flags exist for `publish`'s CLI overrides, which
+     * this path has none of.
+     */
+    publishedVersion(pkg: Package): Promise<string | undefined>;
+    /**
+     * npm's source shape: a quoted string assigned to an identifier, which is what a `.ts`/`.js`
+     * version constant looks like. `constant` comes from the repository's own `version.stamp` entry,
+     * for a file whose identifier is not literally `version`.
+     *
+     * One line, because `stampVersionConstant` is exported for it - the *pattern* is shared by most
+     * languages, while *choosing* it is this ecosystem's call. A provider for a format with no
+     * identifier at all (a `pom.xml`) would ignore `constant` and match its own way.
+     */
+    stampVersion(file: string, content: string, version: string, options?: {
+        constant?: string;
+    }): string | undefined;
+    write(dir: string, manifest: Manifest): void;
+}
+/**
+ * `package.json` as rman's manifest: where an npm package's name and version are written.
+ *
+ * This is the deepest npm assumption that used to be in rman's core - `Package.name`,
+ * `Package.version`, `Package.json` and `Package.isPrivate` all read this file directly, which
+ * meant every command that asked a package what it was called was asking npm.
+ *
+ * The version scheme is left unset, so packages get the core's semver default: npm versions *are*
+ * semver, and saying so again here would only be a second place for the two to disagree.
+ */
+export declare const packageJsonManifest: {};
+/** npm's four dependency fields. Was `rman`'s `DEPENDENCY_KEYS`, which made the core carry npm's
+ *  field names - `publish` imports it from here now. */
+export declare const DEPENDENCY_KEYS: readonly ["dependencies", "devDependencies", "peerDependencies", "optionalDependencies"];

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

@@ -0,0 +1,125 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { Manifest } from '../../../core/interfaces/manifest.js';
+import { stampVersionConstant } from '../../../utils/version-stamp.js';
+import { npmViewVersion } from '../../publish-targets/npm/npm-view.js';
+import { parseWorkspaceRange } from './utils/workspace-range.js';
+export class NodeManifestProvider {
+    name = 'node';
+    fileName = 'package.json';
+    read(dir) {
+        const file = path.join(dir, 'package.json');
+        if (!fs.existsSync(file))
+            return undefined;
+        const raw = JSON.parse(fs.readFileSync(file, 'utf-8'));
+        return {
+            /** A `package.json` with no `name` is unusual but legal, and `info` prints such a package
+             *  rather than refusing it - so the directory name stands in, as it does for a package with
+             *  no manifest at all. */
+            name: typeof raw?.name === 'string' && raw.name ? raw.name : path.basename(dir),
+            version: typeof raw?.version === 'string' && raw.version ? raw.version : '0.0.0',
+            private: !!raw?.private,
+            raw: raw ?? {},
+        };
+    }
+    /**
+     * 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.
+     *
+     * 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.
+     */
+    dependencies(manifest, candidates) {
+        const declared = Object.assign({}, ...DEPENDENCY_KEYS.map(key => manifest.raw[key]));
+        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);
+        }
+        return result;
+    }
+    /** npm's `@scope/name`. A name with no `/` has no scope and is its own unscoped form; the
+     *  *last* `/` splits it, so `@scope/a/b` keeps `@scope/a` as the scope the registry would. */
+    splitName(name) {
+        const at = name.lastIndexOf('/');
+        return at > 0 ? { scope: name.slice(0, at), unscopedName: name.slice(at + 1) } : { unscopedName: name };
+    }
+    /**
+     * Rewrites a sibling's range in all four fields after it was bumped.
+     *
+     * **A bare `"workspace:*"`/`"^"`/`"~"` selector is left alone**, and that is the load-bearing
+     * case: it resolves to the dependency's *current* version at publish time (see
+     * `resolveWorkspaceRange`), so rewriting it would replace a live reference with a frozen one.
+     * Only an explicit version after `workspace:` needs bumping, like a plain range.
+     */
+    updateDependencyVersions(manifest, bumped) {
+        const versionByName = new Map([...bumped].map(([pkg, version]) => [pkg.name, version]));
+        for (const depKey of DEPENDENCY_KEYS) {
+            const deps = manifest.raw[depKey];
+            if (!deps)
+                continue;
+            for (const depName of Object.keys(deps)) {
+                const to = versionByName.get(depName);
+                if (!to)
+                    continue;
+                const workspace = parseWorkspaceRange(deps[depName]);
+                if (workspace) {
+                    if (workspace.selector === 'explicit')
+                        deps[depName] = `workspace:^${to}`;
+                    continue;
+                }
+                deps[depName] = '^' + to;
+            }
+        }
+    }
+    /**
+     * What the npm registry says this package's current version is - used *only* by
+     * `detectChangeHash`, to guess a tag name for a package that has no git tag yet. See
+     * `Plugin.publishedVersion` for why that is not a "has this been published" check.
+     *
+     * No `--registry`/`--userconfig`: a bare `npm view` run in the package's own directory already
+     * honours the repository's `.npmrc`, and the flags exist for `publish`'s CLI overrides, which
+     * this path has none of.
+     */
+    publishedVersion(pkg) {
+        return npmViewVersion(pkg.name, pkg.dirname);
+    }
+    /**
+     * npm's source shape: a quoted string assigned to an identifier, which is what a `.ts`/`.js`
+     * version constant looks like. `constant` comes from the repository's own `version.stamp` entry,
+     * for a file whose identifier is not literally `version`.
+     *
+     * One line, because `stampVersionConstant` is exported for it - the *pattern* is shared by most
+     * languages, while *choosing* it is this ecosystem's call. A provider for a format with no
+     * identifier at all (a `pom.xml`) would ignore `constant` and match its own way.
+     */
+    stampVersion(file, content, version, options) {
+        return stampVersionConstant(content, version, options?.constant);
+    }
+    write(dir, manifest) {
+        /**
+         * The version is written back into `raw` before serializing, because `raw` is the document and
+         * `manifest.version` is rman's view of one field in it. Writing only the view would produce a
+         * file whose `version` never changed; writing only `raw` would leave the two disagreeing for
+         * anything still holding the manifest.
+         */
+        const raw = { ...manifest.raw, version: manifest.version };
+        fs.writeFileSync(path.join(dir, 'package.json'), JSON.stringify(raw, undefined, 2) + '\n', 'utf-8');
+    }
+}
+/**
+ * `package.json` as rman's manifest: where an npm package's name and version are written.
+ *
+ * This is the deepest npm assumption that used to be in rman's core - `Package.name`,
+ * `Package.version`, `Package.json` and `Package.isPrivate` all read this file directly, which
+ * meant every command that asked a package what it was called was asking npm.
+ *
+ * The version scheme is left unset, so packages get the core's semver default: npm versions *are*
+ * semver, and saying so again here would only be a second place for the two to disagree.
+ */
+export const packageJsonManifest = {};
+/** npm's four dependency fields. Was `rman`'s `DEPENDENCY_KEYS`, which made the core carry npm's
+ *  field names - `publish` imports it from here now. */
+export const DEPENDENCY_KEYS = ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies'];

package/builtins/platforms/node/node.platform.d.ts

@@ -0,0 +1,53 @@
+import type { Package } from '../../../core/classes/package.js';
+import type { Platform } from '../../../core/interfaces/plugin.js';
+import type { RunService } from '../../../services/run.service.js';
+import { NodeManifestProvider } from './node-manifest.provider.js';
+import { NodeVersionPlanService } from './services/version-plan.service.js';
+export declare class NodePlatform implements Platform {
+    /** The ecosystem, not the file - this is what every package it reads reports as
+     *  `pkg.provider === 'node'`. `manifestProvider.fileName` already says `package.json`. */
+    name: string;
+    manifestProvider: NodeManifestProvider;
+    versionPlanner: NodeVersionPlanService;
+    /**
+     * npm's `workspaces` globs, resolved against `dir` - the directories directly below it that hold
+     * a `package.json`.
+     *
+     * **Asked of every directory the walk reaches, not only of the repository root**, which is what
+     * the seam changing from a layout to a per-directory question bought: a `package.json` naming
+     * `workspaces` is a workspace root wherever it sits, so a Node sub-workspace inside a larger
+     * repository is now found by the same code that finds the top one. `deep: 0` already made the
+     * globs one level, so nothing here had to change to make that true.
+     */
+    getWorkspace(dir: string): string[] | undefined;
+    /**
+     * Teaches `run` about `package.json#scripts`.
+     *
+     * rman's core resolves a script from `.rmanrc` alone - `before`/`exec`/`after`. That a script might
+     * *also* live in `package.json`, that `prebuild` and `postbuild` run around `build`, and that
+     * `a && b` is two steps rather than one, are all facts about npm, so they are here.
+     *
+     * Registered as a `RunService` step source rather than by wrapping anything: the npm part of `run`
+     * is inside step resolution, not at its entry point, so there is nothing a wrapper could reach.
+     * The core decides what to do with what this returns - see `getScriptSteps` for the precedence.
+     */
+    getRunSteps(pkg: Package, script: string): RunService.ScriptSlots | undefined;
+    /**
+     * Where npm puts a repository's locally installed executables: `node_modules/.bin`, at **every**
+     * level from `cwd` up to the filesystem root - which is how npm itself resolves a binary, so a
+     * package's `eslint` is found whether it was installed in that package or hoisted to the workspace
+     * root.
+     *
+     * Adapted from [npm-run-path](https://github.com/sindresorhus/npm-run-path), and it used to sit in
+     * rman's core. It is npm's directory layout from end to end: a Cargo or Go repository has no
+     * `node_modules` to walk, and nothing here would ever fire for it.
+     *
+     * **The running `node`'s own directory goes last**, after the walk, and its position is
+     * load-bearing. It is there so a script calling `node` gets the interpreter rman itself runs on
+     * rather than whatever the shell would pick. It also puts rman's own bin directory ahead of the
+     * inherited PATH, which is a measured trap: a nested `rman` invocation inside a `run` script
+     * resolves to the globally installed one, not to the repository's. Shim it in
+     * `<root>/node_modules/.bin` when that has to be overridden - the walk above reaches there first.
+     */
+    getBinPaths(cwd: string): string[];
+}