rman 1.0.12 → 1.2.1

package/core/custom-command.d.ts

@@ -0,0 +1,133 @@
+import type { ArgumentsCamelCase, Argv } from 'yargs';
+import type { Logger } from '../utils/logger.js';
+import type { RunBinOptions, RunBinResult } from '../utils/run-bin.js';
+import type { Package } from './package.js';
+import type { Repository } from './repository.js';
+/** Where a repository keeps its own commands - one module per command, named after it. */
+export declare const CUSTOM_COMMAND_DIR = ".rman";
+/**
+ * What a repository's own command is handed. An object rather than loose parameters so later
+ * additions don't break every command already written against it.
+ */
+export interface CommandContext {
+    repository: Repository;
+    /**
+     * The package whose directory rman was invoked from, or `undefined` at the repository root (and
+     * in a single-package repository, which is always "at the root") - the same
+     * `Repository.currentPackage` the built-in commands scope themselves by. A command that only
+     * makes sense inside a package should say so itself rather than assume.
+     */
+    package: Package | undefined;
+    /**
+     * Runs one of the repository's locally installed binaries - `runBin` (see
+     * `../utils/run-bin.ts`), already carrying **this run's** settings: `cwd` defaults to the
+     * repository root, and `logLevel` to the level resolved from `--log-level` and `.rmanrc
+     * logLevel`. Either can still be overridden per call.
+     *
+     * Handed over here rather than left to be imported, because those settings are the whole point:
+     * importing `runBin` straight from `'rman'` gets a helper that knows neither, so
+     * `--log-level silent` would quietly not apply to the one part of the command that produces
+     * output. Anything else a run turns out to carry is added here the same way, and no command
+     * written against this breaks.
+     */
+    runBin: (bin: string, argv: string[], options?: RunBinOptions) => Promise<RunBinResult>;
+    /** Logger at this run's resolved level, for a command's own narration. */
+    logger: Logger;
+}
+/**
+ * Which `.rmanrc` keys a command reads, for `--config` to print instead of running it - a dotted
+ * path each (`'run.build'`, `'publish.docker'`), or a function of the parsed argv when the answer
+ * depends on it (`run <script>` reads `run.<script>`).
+ *
+ * **Declared beside the command rather than in a list somewhere central**, so it cannot drift out
+ * of step with the code that does the reading, and so a plugin's command or a `.rman/*.mjs` one can
+ * say it too. Omitted, `--config` prints the whole effective config - the honest answer when
+ * nothing has said which part matters.
+ */
+export type ConfigKeys = string[] | ((args: ArgumentsCamelCase) => string[]);
+export interface CustomCommand {
+    /** yargs command string, for a command taking positionals (`'deploy <stage>'`). Defaults to the
+     *  module's own file name, which is the whole point of the directory. */
+    command?: string;
+    /** Required: without it `rman --help` has nothing to list the command by. */
+    describe: string;
+    builder?: (argv: Argv) => Argv;
+    handler: (context: CommandContext, args: ArgumentsCamelCase) => void | Promise<void>;
+    /** See `ConfigKeys` - what `rman <this command> --config` narrows its output to. */
+    configKeys?: ConfigKeys;
+}
+/**
+ * The same field on **yargs's own** command object, which is what the built-in commands pass.
+ *
+ * By augmentation rather than a wrapper type of ours: `program.command({ ... })` takes a literal,
+ * and TypeScript's excess-property check fires on a literal however the parameter is typed - so a
+ * field yargs does not know about is a compile error even though it is ignored at runtime
+ * (measured, on nine commands at once). One block, here, beside `ConfigKeys` itself.
+ */
+declare module 'yargs' {
+    interface CommandModule<T = {}, U = {}> {
+        configKeys?: ConfigKeys;
+    }
+}
+/**
+ * Identity helper for authoring a `.rman/<name>.mjs` command with full type-checking and
+ * autocomplete - the same `defineConfig` pattern, for the same reason. Returns `command`
+ * unchanged.
+ *
+ * ```js
+ * // .rman/deploy.mjs
+ * import { defineCommand, VersionService } from 'rman';
+ *
+ * export default defineCommand({
+ *   describe: 'Ships what was just published to the staging cluster',
+ *   builder: y => y.option('stage', { choices: ['dev', 'prod'], demandOption: true }),
+ *   async handler({ repository, runBin, logger }, args) {
+ *     const plan = await VersionService.getPlan(repository);
+ *     for (const entry of plan.filter(e => e.status === 'bump')) {
+ *       logger.info(`${entry.package.name} -> ${args.stage}`);
+ *     }
+ *     await runBin('helm', ['upgrade', '--install', args.stage, './chart']);
+ *   },
+ * });
+ * ```
+ *
+ * Take `runBin` from the context rather than importing it: the one on the context already carries
+ * this run's `cwd` (the repository root) and log level.
+ *
+ * This is for **one repository-level operation with logic of its own** - branching, its own CLI
+ * options, rman's services. Running a shell step across every package is what `.rmanrc
+ * "run.<script>"` already does, with the scheduling, topological order, `bail` and progress panel
+ * that come with it; reimplementing that loop here would only lose them.
+ */
+export declare function defineCommand(command: CustomCommand): CustomCommand;
+export interface LoadedCommand extends CustomCommand {
+    /** The command's name - its file's basename, or the first word of an explicit `command`. */
+    name: string;
+    file: string;
+}
+/** A module that couldn't be loaded or doesn't look like a command. Reported, never thrown: one
+ *  unparseable file must not take `rman publish` down with it. */
+export interface CommandLoadError {
+    file: string;
+    reason: string;
+}
+/**
+ * Loads every command module in `<root>/.rman`. A repository without that directory pays nothing -
+ * no scan, no imports - which matters because this runs on *every* rman invocation, `info`
+ * included.
+ *
+ * Each failure is collected rather than thrown, so the rest of the CLI keeps working; the caller
+ * warns about them. What is *not* tolerated is a module that would shadow a built-in - see
+ * `assertNoBuiltinShadowing`.
+ */
+export declare function loadCustomCommands(rootDir: string): Promise<{
+    commands: LoadedCommand[];
+    errors: CommandLoadError[];
+}>;
+/**
+ * Refuses a command that would take a built-in's name. Unlike a module that simply fails to load,
+ * this one is thrown: the file is fine, the *name* is the mistake, and there is no reading of
+ * `rman publish` that is safe to guess at. Silently preferring either one would leave whoever typed
+ * it unable to tell which ran.
+ */
+export declare function assertNoBuiltinShadowing(commands: LoadedCommand[], builtins: readonly string[]): void;

package/core/custom-command.js

@@ -0,0 +1,99 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+/** Where a repository keeps its own commands - one module per command, named after it. */
+export const CUSTOM_COMMAND_DIR = '.rman';
+/** Loadable module forms, matching what a `.rmanrc.cjs`/`.mjs`/`.js` config already accepts. A
+ *  `.ts` command would need a loader registered in rman's own process, which is a separate
+ *  question from this one. */
+const EXTENSIONS = ['.js', '.mjs', '.cjs'];
+/**
+ * Identity helper for authoring a `.rman/<name>.mjs` command with full type-checking and
+ * autocomplete - the same `defineConfig` pattern, for the same reason. Returns `command`
+ * unchanged.
+ *
+ * ```js
+ * // .rman/deploy.mjs
+ * import { defineCommand, VersionService } from 'rman';
+ *
+ * export default defineCommand({
+ *   describe: 'Ships what was just published to the staging cluster',
+ *   builder: y => y.option('stage', { choices: ['dev', 'prod'], demandOption: true }),
+ *   async handler({ repository, runBin, logger }, args) {
+ *     const plan = await VersionService.getPlan(repository);
+ *     for (const entry of plan.filter(e => e.status === 'bump')) {
+ *       logger.info(`${entry.package.name} -> ${args.stage}`);
+ *     }
+ *     await runBin('helm', ['upgrade', '--install', args.stage, './chart']);
+ *   },
+ * });
+ * ```
+ *
+ * Take `runBin` from the context rather than importing it: the one on the context already carries
+ * this run's `cwd` (the repository root) and log level.
+ *
+ * This is for **one repository-level operation with logic of its own** - branching, its own CLI
+ * options, rman's services. Running a shell step across every package is what `.rmanrc
+ * "run.<script>"` already does, with the scheduling, topological order, `bail` and progress panel
+ * that come with it; reimplementing that loop here would only lose them.
+ */
+export function defineCommand(command) {
+    return command;
+}
+/**
+ * Loads every command module in `<root>/.rman`. A repository without that directory pays nothing -
+ * no scan, no imports - which matters because this runs on *every* rman invocation, `info`
+ * included.
+ *
+ * Each failure is collected rather than thrown, so the rest of the CLI keeps working; the caller
+ * warns about them. What is *not* tolerated is a module that would shadow a built-in - see
+ * `assertNoBuiltinShadowing`.
+ */
+export async function loadCustomCommands(rootDir) {
+    const dir = path.join(rootDir, CUSTOM_COMMAND_DIR);
+    const commands = [];
+    const errors = [];
+    if (!fs.existsSync(dir))
+        return { commands, errors };
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+        if (!entry.isFile() || !EXTENSIONS.includes(path.extname(entry.name)))
+            continue;
+        const file = path.join(dir, entry.name);
+        try {
+            const mod = await import(pathToFileURL(file).href);
+            const command = mod?.default ?? mod?.command;
+            if (!command || typeof command !== 'object') {
+                throw new Error('no default export - end the module with `export default defineCommand({ ... })`');
+            }
+            if (typeof command.handler !== 'function')
+                throw new Error('"handler" is missing, or is not a function');
+            if (typeof command.describe !== 'string' || !command.describe) {
+                throw new Error('"describe" is missing - `rman --help` has nothing to list the command by without it');
+            }
+            const declared = command.command?.trim();
+            commands.push({
+                ...command,
+                command: declared || path.basename(entry.name, path.extname(entry.name)),
+                name: (declared || path.basename(entry.name, path.extname(entry.name))).split(/\s+/)[0],
+                file,
+            });
+        }
+        catch (e) {
+            errors.push({ file, reason: e?.message ?? String(e) });
+        }
+    }
+    return { commands, errors };
+}
+/**
+ * Refuses a command that would take a built-in's name. Unlike a module that simply fails to load,
+ * this one is thrown: the file is fine, the *name* is the mistake, and there is no reading of
+ * `rman publish` that is safe to guess at. Silently preferring either one would leave whoever typed
+ * it unable to tell which ran.
+ */
+export function assertNoBuiltinShadowing(commands, builtins) {
+    const clash = commands.find(c => builtins.includes(c.name));
+    if (!clash)
+        return;
+    throw new Error(`"${path.relative(process.cwd(), clash.file)}" would shadow rman's built-in "${clash.name}" command.\n` +
+        `  Rename the file, or give it its own name with \`command: '<name>'\`.`);
+}

package/core/extends-config.d.ts

@@ -0,0 +1,27 @@
+import type { RmanConfig } from '../interfaces/rman-config.interface.js';
+/** The key naming configs to inherit from, the way eslint and tsconfig spell it. */
+export declare const EXTENDS_KEY = "extends";
+/**
+ * Resolves `config`'s own `extends` into it: every named config is loaded, merged in declaration
+ * order, and `config`'s own keys land on top. Returns a new object with no `extends` left in it.
+ *
+ * The point is a shared package - `extends: "@panates/rman-monorepo"` - so a repository declares
+ * its house rules once instead of restating them. `+key` is what makes that liveable (see
+ * `mergeConfig`): without it, adding one step to a base's list means copying the list.
+ *
+ * `from` is the file the `extends` was written in, and everything resolves relative to **it**: a
+ * bare specifier through that file's own `node_modules`, a relative path against its directory.
+ * Resolving from rman's own location instead would look in rman's dependencies, where a
+ * repository's shared config has no reason to be.
+ *
+ * `seen` carries the chain being resolved, so a config that extends its way back to itself is
+ * reported rather than recursed into forever.
+ */
+export declare function resolveExtends(config: RmanConfig, from: string, seen?: string[]): Promise<RmanConfig>;
+/**
+ * Refuses `extends` inside a `"[selector]"` block. A selector block is typed as a whole
+ * `RmanConfig`, so writing one there looks valid and would simply never be resolved - and a config
+ * that quietly does nothing is worse than one that won't load. Inheritance is a statement about
+ * the file, not about the packages it happens to name.
+ */
+export declare function assertNoSelectorExtends(config: RmanConfig, file: string): void;

package/core/extends-config.js

@@ -0,0 +1,89 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import * as yaml from 'js-yaml';
+import { isSelectorKey } from './config.js';
+import { mergeConfig } from './merge-config.js';
+import { resolveConfigTarget } from './resolve-target.js';
+/** The key naming configs to inherit from, the way eslint and tsconfig spell it. */
+export const EXTENDS_KEY = 'extends';
+/**
+ * Resolves `config`'s own `extends` into it: every named config is loaded, merged in declaration
+ * order, and `config`'s own keys land on top. Returns a new object with no `extends` left in it.
+ *
+ * The point is a shared package - `extends: "@panates/rman-monorepo"` - so a repository declares
+ * its house rules once instead of restating them. `+key` is what makes that liveable (see
+ * `mergeConfig`): without it, adding one step to a base's list means copying the list.
+ *
+ * `from` is the file the `extends` was written in, and everything resolves relative to **it**: a
+ * bare specifier through that file's own `node_modules`, a relative path against its directory.
+ * Resolving from rman's own location instead would look in rman's dependencies, where a
+ * repository's shared config has no reason to be.
+ *
+ * `seen` carries the chain being resolved, so a config that extends its way back to itself is
+ * reported rather than recursed into forever.
+ */
+export async function resolveExtends(config, from, seen = []) {
+    const declared = config[EXTENDS_KEY];
+    if (declared === undefined)
+        return config;
+    const targets = Array.isArray(declared) ? declared : [declared];
+    for (const target of targets) {
+        if (typeof target !== 'string' || !target.trim()) {
+            throw new Error(`"extends" in "${from}" must be a config name or path, or an array of them`);
+        }
+    }
+    const base = {};
+    for (const target of targets) {
+        const file = resolveConfigTarget(target, from, EXTENDS_KEY);
+        if (seen.includes(file)) {
+            throw new Error(`"extends" forms a cycle: ${[...seen, file].map(f => path.basename(f)).join(' -> ')}`);
+        }
+        const loaded = await loadConfigFile(file);
+        assertNoSelectorExtends(loaded, file);
+        // Recursive: a shared config may itself be built on another.
+        mergeConfig(base, await resolveExtends(loaded, file, [...seen, file]));
+    }
+    const own = { ...config };
+    delete own[EXTENDS_KEY];
+    return mergeConfig(base, own);
+}
+/**
+ * Refuses `extends` inside a `"[selector]"` block. A selector block is typed as a whole
+ * `RmanConfig`, so writing one there looks valid and would simply never be resolved - and a config
+ * that quietly does nothing is worse than one that won't load. Inheritance is a statement about
+ * the file, not about the packages it happens to name.
+ */
+export function assertNoSelectorExtends(config, file) {
+    for (const [key, value] of Object.entries(config)) {
+        if (!isSelectorKey(key) || !value || typeof value !== 'object')
+            continue;
+        if (EXTENDS_KEY in value) {
+            throw new Error(`"${key}" in "${file}" cannot use "extends" - it belongs at the top level, where it is a ` +
+                `statement about this config rather than about the packages the selector names.`);
+        }
+    }
+}
+/** Loads one resolved target. YAML and JSON are read directly; anything else goes through the
+ *  module loader, so a shared config can be a `defineConfig` module with real logic in it. */
+async function loadConfigFile(file) {
+    const ext = path.extname(file);
+    if (ext === '.yml' || ext === '.yaml') {
+        const obj = yaml.load(fs.readFileSync(file, 'utf-8'));
+        return asConfig(obj, file);
+    }
+    if (ext === '.json')
+        return asConfig(JSON.parse(fs.readFileSync(file, 'utf-8')), file);
+    const mod = await import(pathToFileURL(file).href);
+    return asConfig(mod?.default ?? mod, file);
+}
+function asConfig(value, file) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error(`"${file}" does not export an rman config object`);
+    }
+    const config = { ...value };
+    // Editor tooling only - meaningless once merged, and `additionalProperties` would reject it
+    // wherever it ended up.
+    delete config.$schema;
+    return config;
+}

package/core/manifest.d.ts

@@ -0,0 +1,222 @@
+import type { Package } from './package.js';
+import { type VersionScheme } from './version-scheme.js';
+/**
+ * A package's identity, however its ecosystem happens to record it.
+ *
+ * Three fields rman genuinely needs of every package, plus the raw document for the commands that
+ * know what ecosystem they are in. Everything rman's core does - grouping, tagging, changelogs,
+ * release identity - is expressed in terms of these three and nothing else.
+ */
+export interface Manifest {
+    name: string;
+    version: string;
+    /** Excluded from publishing by the package's own declaration (`package.json#private`). Not the
+     *  same as `.rmanrc "publish.skip"`, which is the *repository's* declaration about it. */
+    private?: boolean;
+    /** The document as the ecosystem wrote it. `rman-node`'s own commands read `package.json` fields
+     *  the core has no opinion about (`scripts`, `publishConfig`, `engines`) off this. */
+    raw: any;
+}
+/**
+ * Where a package's identity is written, and how to change it.
+ *
+ * **The core has no provider.** "The name and version live in a `package.json`" is true of npm and
+ * of nothing else - a `Cargo.toml`, a `pyproject.toml` and a `go.mod` each say the same thing
+ * differently, and the version is not even in the same *kind* of place in all of them.
+ * `rman-node` contributes the `package.json` one.
+ *
+ * Paired with `VersionScheme` on purpose: the ecosystem that decides *where* a version is written
+ * is the one that decides *how* it is numbered, so a provider supplies both and a package gets a
+ * matching pair rather than a `pyproject.toml` read with semver's arithmetic.
+ */
+export interface ManifestProvider {
+    /**
+     * **The ecosystem this provider speaks for**, surfaced on every package it reads as
+     * `Package.provider` - `'node'` for `rman-node`. Short and about the technology, not about the
+     * file: `fileName` already says `package.json`, and a name repeating it would tell a caller
+     * nothing it did not have.
+     *
+     * This is what lets code that *does* know one ecosystem check before acting on a package -
+     * `if (pkg.provider === 'node')` - which matters most in a repository holding more than one,
+     * since `read` is asked per directory and two packages can legitimately answer to different
+     * providers.
+     */
+    readonly name: string;
+    /** The file this looks for, relative to a package directory - `'package.json'`. Used to report
+     *  what was missing, and by `import` when grafting an external repository in. */
+    readonly fileName: string;
+    /** `undefined` when this directory holds no package of this kind, so another provider gets a
+     *  turn rather than this one having to throw. */
+    read(dir: string): Manifest | undefined;
+    /** Writes `manifest` back. Only ever called with a manifest this provider produced. */
+    write(dir: string, manifest: Manifest): void;
+    /** How this ecosystem numbers versions. Defaults to semver when a provider has no opinion -
+     *  which is right for Cargo and Go, and wrong for PEP 440, whose provider should say so. */
+    readonly versionScheme?: VersionScheme;
+    /**
+     * The version of `pkg` this ecosystem's registry currently reports, or `undefined` for anything
+     * that is not an answer (never published, no network, private with no access).
+     *
+     * **Read for exactly one purpose, and it is not "has this been published"**: `detectChangeHash`
+     * borrows the version string to *guess a tag name*, and uses it only if a tag by that name
+     * actually exists in git. The case it covers is rman being adopted onto a repository whose
+     * releases predate it - a tag exists but is not in HEAD's ancestry (cut on another branch,
+     * rewritten history, a shallow clone), so `git describe` cannot see it. Never compare this
+     * against the local manifest version; that is `publish`'s question, and mixing the two is the
+     * measured bug the A/B split exists to prevent.
+     *
+     * Here rather than behind a repository-wide hook because a registry belongs to an *ecosystem*: a
+     * polyglot repository asks npm about its `node` packages and crates.io about its `cargo` ones, and
+     * only a per-package provider can do that. Optional - an ecosystem with no registry to ask (or a
+     * repository that would rather not reach the network) simply leaves git tags as the only source,
+     * which is the honest answer rather than a diminished one.
+     */
+    publishedVersion?(pkg: Package): Promise<string | undefined>;
+    /**
+     * Rewrites `content` so the version it hard-codes reads `version`, for a file `.rmanrc
+     * "version.stamp"` lists - returning `undefined` when there is nothing to change, so the caller
+     * writes nothing and can report a file that matched nothing.
+     *
+     * **Here because how a version is *declared* is the language's**, and this provider is already
+     * the ecosystem's representative for exactly that: `write` says where the manifest keeps it,
+     * `versionScheme` says how it is numbered, and this says what it looks like in source. Measured
+     * before it moved: the core's one pattern stamped a Go `const version = "…"` and a Gradle
+     * `version = "…"` but silently missed `const Version`, `__version__`, Rust's
+     * `pub const VERSION: &str = "…"` and `pom.xml`'s `<version>` - and "silently" is the part that
+     * mattered, since a listed file that matches nothing looked exactly like a file with no version
+     * in it.
+     *
+     * `file` is the absolute path, for a provider that keys off the extension (a `.ts` constant and a
+     * `Chart.yaml` are both npm-adjacent and are not the same rewrite). `options.constant` is the
+     * identifier the repository says holds it, from the config - a provider whose format has no
+     * identifier ignores it.
+     *
+     * `stampVersionConstant` is exported for the common case; delegating to it is one line.
+     */
+    stampVersion?(file: string, content: string, version: string, options?: {
+        constant?: string;
+    }): string | undefined;
+    /**
+     * Which of `candidates` this package declares a dependency on.
+     *
+     * The *field names* are the ecosystem's: npm spreads four of them
+     * (`dependencies`/`devDependencies`/`peerDependencies`/`optionalDependencies`), Cargo has
+     * `[dev-dependencies]` and `[build-dependencies]`, `go.mod` has one `require` block. rman only
+     * wants the edges of the graph, so the provider reads its own manifest and returns the packages.
+     *
+     * Returning **packages rather than names** for the same reason `Package.dependencies` holds
+     * them: a name identifies a package only where the ecosystem guarantees uniqueness, and the
+     * provider is the only thing that knows how its own ecosystem refers to a dependency.
+     *
+     * Omit it and a package has no declared dependencies beyond `.rmanrc "dependencies"`.
+     */
+    dependencies?(manifest: Manifest, candidates: readonly Package[]): Package[];
+    /**
+     * Splits a package name into the parts a config expression can ask for - `${{ pkg.scope }}` and
+     * `${{ pkg.unscopedName }}`.
+     *
+     * npm's `@scope/name` is a convention, not a universal: a Go module path (`github.com/x/y`)
+     * split on `/` would report a scope of `github.com/x`, and a Cargo crate has no such notion at
+     * all. Omit it and a name has no scope and is its own unscoped form, which is the honest answer
+     * for an ecosystem without the concept.
+     */
+    splitName?(name: string): {
+        scope?: string;
+        unscopedName: string;
+    };
+    /**
+     * Rewrites this manifest's references to in-repo packages that just got a new version.
+     *
+     * `bumped` maps a package to the version it is being given. What a "reference" looks like is
+     * entirely the ecosystem's: npm has four dependency fields and a `"workspace:"` protocol whose
+     * bare selectors resolve at publish time and must *not* be rewritten; Cargo has `path`
+     * dependencies that carry no version at all. rman only knows that a bump may leave siblings
+     * pointing at the old number.
+     *
+     * Mutates `manifest.raw` in place - the caller writes it out afterwards, in the same pass that
+     * wrote the new version, so there is one file write rather than two.
+     *
+     * Omit it and nothing is rewritten, which is correct for an ecosystem that references siblings
+     * by path.
+     */
+    updateDependencyVersions?(manifest: Manifest, bumped: ReadonlyMap<Package, string>): void;
+}
+/**
+ * The registry, merged onto the `Manifest` interface so one name carries both the shape and the
+ * operations - `Manifest.read(dir)` returns a `Manifest`.
+ *
+ * A namespace rather than loose `addManifestProvider`/`readManifest` functions because a namespace
+ * is what a plugin can *augment*: `declare module 'rman' { namespace Manifest { ... } }` is how
+ * `rman-node` already adds to `SystemInfo`, and anything this seam grows later can arrive the
+ * same way instead of as another top-level export.
+ */
+export declare namespace Manifest {
+    /** Registers a provider. Called by `loadPlugins` for each plugin's `manifest`, in `plugins`
+     *  declaration order - so which one answers is a function of the repository's own config. */
+    function addProvider(provider: ManifestProvider): void;
+    /** For tests, which would otherwise leak a provider into every later case in the process. */
+    function clearProviders(): void;
+    /**
+     * Reads `dir`'s manifest through the first provider that recognizes it, with the scheme that
+     * provider brings.
+     *
+     * **With no provider registered, or none recognizing the directory**, the fallback is a package
+     * named after its own directory at version `0.0.0`. That is deliberately the least it can claim:
+     * the directory name is a fact, and `0.0.0` is the version a thing has when nothing says
+     * otherwise. The alternative - refusing to construct a package at all - would make `rman info` and
+     * `rman list` fail in a repository whose `.rmanrc` simply names no plugin yet, which is exactly
+     * when someone needs to run them.
+     */
+    function read(dir: string): {
+        manifest: Manifest;
+        versionScheme: VersionScheme;
+        fileName: string;
+        provider: string;
+    };
+    /** Writes through whichever provider recognizes `dir`. Throws when none does: a write that lands
+     *  nowhere is worse than one that fails, since the caller has already decided the new version. */
+    function write(dir: string, manifest: Manifest): void;
+    /**
+     * The packages `pkg` declares a dependency on, via whichever provider recognizes it.
+     *
+     * No provider, or one with no opinion, means no declared dependencies - `.rmanrc "dependencies"`
+     * is then the only source, which is exactly right: a repository rman cannot read the manifests
+     * of can still describe its own graph by hand.
+     */
+    function dependenciesOf(pkg: Package, candidates: readonly Package[]): Package[];
+    /** `${{ pkg.scope }}`/`${{ pkg.unscopedName }}`, by whichever provider recognizes `dir` - and
+     *  "no scope, the name is its own unscoped form" when none has an opinion. */
+    function splitName(dir: string, name: string): {
+        scope?: string;
+        unscopedName: string;
+    };
+    /**
+     * Refreshes `pkg`'s references to the packages in `bumped`, via whichever provider recognizes it.
+     *
+     * No provider, or one without an opinion, means nothing to rewrite - a repository whose packages
+     * reference each other by path has nothing here to go stale.
+     */
+    function updateDependencyVersions(pkg: Package, bumped: ReadonlyMap<Package, string>): void;
+    /**
+     * Rewrites a hard-coded version in `content` through `pkg`'s own ecosystem - see
+     * `ManifestProvider.stampVersion`.
+     *
+     * `undefined` covers three cases the caller has to tell apart from each other, and cannot: no
+     * provider claimed the package, the provider has no opinion about stamping, or it looked and found
+     * nothing to change. All three mean "this file was not stamped", which is what `version` reports.
+     */
+    function stampVersion(pkg: Package, file: string, content: string, version: string, options?: {
+        constant?: string;
+    }): string | undefined;
+    /**
+     * What `pkg`'s own ecosystem's registry says its current version is - see
+     * `ManifestProvider.publishedVersion` for the one thing this is for and the one thing it must
+     * never be used for.
+     *
+     * `undefined` when the provider has no opinion, which includes every repository that names no
+     * plugin: git tags then answer the boundary question alone.
+     */
+    function publishedVersion(pkg: Package): Promise<string | undefined>;
+    /** The file names providers look for, for an error message that can say what was expected. */
+    function fileNames(): string[];
+}