rman 1.3.0 → 2.0.0-beta.3

package/core/application.js

@@ -0,0 +1,160 @@
+import { DockerPublishService, dockerPublishTarget } from '../builtins/publish-targets/docker/index.js';
+import { ChangelogService } from '../services/changelog.service.js';
+import { ConfigService } from '../services/config-service.js';
+import { ExecService } from '../services/exec.service.js';
+import { GithubReleaseService } from '../services/github-release.service.js';
+import { ImportService } from '../services/import.service.js';
+import { ListService } from '../services/list.service.js';
+import { RunService } from '../services/run.service.js';
+import { VersionService } from '../services/version.service.js';
+import { Logger } from '../utils/logger.js';
+import { Registry } from './classes/registry.js';
+import { basePlatform } from './interfaces/plugin.js';
+/**
+ * **One rman invocation, and everything it holds.** Created before anything else, handed to every
+ * plugin's `init`, and the owner of every registry and service that used to be a module-level
+ * variable.
+ *
+ * The point is that nothing is process-global any more. `Manifest`, `Workspace`, `BinPath`,
+ * `RunService` and `VersionPlanService` each kept their contributions in a module-scope array, so
+ * two repositories in one process shared them - which the test suite could only survive with a
+ * root hook emptying five of them before every test, and the failure that hook prevented was:
+ * whichever spec ran first decided the answer for the rest, and the core appeared to work in tests
+ * that had registered nothing. An application starts empty and is thrown away whole, so the hook
+ * is gone.
+ */
+export class RmanApplication {
+    /**
+     * The **technologies** this invocation knows about, in `plugins` declaration order.
+     *
+     * One registry rather than the four it replaces (`manifest`, `workspace`, `binPaths`,
+     * `runSteps`): a technology is a whole, and declaring part of one was never meaningful - see
+     * `Platform`.
+     *
+     * **Flattened out of the plugins**, because this is what every seam actually iterates - a
+     * manifest is read by a platform, a workspace is laid out by a platform, a PATH is contributed by
+     * a platform. A plugin providing two of them puts two entries here, and a plugin providing none
+     * puts none.
+     */
+    platforms = new Registry();
+    /**
+     * The **plugins** themselves, in declaration order - what a config named, before the platforms
+     * were taken out of them.
+     *
+     * Kept apart from `platforms` because the two answer different questions: this is who contributed,
+     * that is what they contributed. `init` runs per plugin; nothing else reads this.
+     */
+    plugins = new Registry();
+    /**
+     * Where a package's artifact can ship, in registration order.
+     *
+     * A registry rather than a field because the answer is a *sum*: a package may ship to npm and
+     * Docker Hub at once, and `publish` runs every target a package declares. The core contributes
+     * `docker` (nobody's ecosystem), the `node` built-in contributes `npm`, and a plugin for any other
+     * technology adds its own without either of them changing - see `PublishTarget`.
+     */
+    publishTargets = new Registry();
+    /**
+     * **The planner that orchestrates a run**, not the one that answers for each package.
+     *
+     * One answer, not a sum - so a field rather than a registry, and last registration wins. What it
+     * decides is the shape of the whole plan: groups, the commit→size reading, the cross-group ripple
+     * and the root's release identity, none of which belongs to any one technology.
+     *
+     * The two decisions that *are* a technology's - `detectBoundary` and `cascade` - are asked of
+     * each package's own `Platform.versionPlanner` instead (`VersionPlanService.plannerFor`), so a
+     * polyglot repository no longer resolves both through whichever plugin registered last.
+     */
+    versionPlanner;
+    logger;
+    /** `info` until `--log-level` or `.rmanrc "logLevel"` is resolved - which cannot happen here,
+     *  since reading the config is itself work the application does. */
+    constructor(options) {
+        this.logger = new Logger(options?.logLevel ?? 'info');
+        // Register core services.
+        this.setService('config', a => new ConfigService(a));
+        this.setService('changelog', a => new ChangelogService(a));
+        this.setService('dockerPublish', a => new DockerPublishService(a));
+        this.setService('githubRelease', a => new GithubReleaseService(a));
+        this.setService('exec', a => new ExecService(a));
+        this.setService('import', a => new ImportService(a));
+        this.setService('list', a => new ListService(a));
+        this.setService('run', a => new RunService(a));
+        this.setService('version', a => new VersionService(a));
+        // Register core targets.
+        this.publishTargets.add(dockerPublishTarget);
+    }
+    /** Which platform claims a directory - the first whose manifest provider recognizes it, because
+     *  before a package is read there is nothing else to go on. `basePlatform` when none does, so the
+     *  caller needs no guard. */
+    platformFor(dir) {
+        return this.platforms.first(p => (p.manifestProvider.read(dir) ? p : undefined)) ?? basePlatform;
+    }
+    /**
+     * **Not a constructor field, and that is forced by the order things happen in.** Plugins are what
+     * *find* the packages - `Repository.create` loads them before it calls `Workspace.resolve` - so
+     * the application has to exist, and be handed to every `init`, while there is still no
+     * repository to put in it.
+     *
+     * A throwing getter rather than `undefined`: a plugin reaching for packages during `init` has
+     * made a real mistake, and `undefined` would let it write a check that silently does nothing.
+     */
+    get repository() {
+        if (!this._repository) {
+            throw new Error('The repository is not available yet - plugins are loaded before the packages they are ' +
+                "what finds. Ask for it from a command or a service, not from a plugin's init().");
+        }
+        return this._repository;
+    }
+    /**
+     * The single instance of a service, built on first use.
+     *
+     * **Lazy, and for two reasons.** `rman info` has no business constructing the changelog, version
+     * and release services, which is the same laziness the config scope's `git` getter was measured
+     * to need (0 git reads with property descriptors, 1 with a spread). And services call each other -
+     * `VersionService` reaches for `RunService` and `ChangelogService`, which reaches for
+     * `ChangeHashService` - so resolving at call time is what keeps that from being a construction
+     * cycle.
+     */
+    getService(name) {
+        const existing = this.services.get(name);
+        if (existing)
+            return existing;
+        const factory = this.factories.get(name);
+        if (!factory)
+            throw new Error(`No service registered under "${String(name)}"`);
+        const service = factory(this);
+        this.services.set(name, service);
+        return service;
+    }
+    /**
+     * Registers how a service is built. A plugin replacing one of the core's - a version planner that
+     * knows its own ecosystem's dependency ranges - does it here, which is why that no longer needs a
+     * seam of its own on the plugin interface.
+     *
+     * Refused once the service has been built: something is already holding the old instance, and
+     * swapping the factory then would leave two answers to one question in play.
+     */
+    setService(name, factory) {
+        if (this.services.has(name)) {
+            throw new Error(`Service "${String(name)}" has already been built and cannot be replaced`);
+        }
+        this.factories.set(name, factory);
+    }
+    /**
+     * Called by `Repository.create`, after the plugins that find the packages have run.
+     *
+     * **One application, one repository**, and a second is refused. It was briefly "last one wins",
+     * because a single shared application made two repositories in one test collide; each
+     * `Repository.create` makes its own now, so the rule holds again and nothing in a process is
+     * shared by accident.
+     */
+    attachRepository(repository) {
+        if (this._repository)
+            throw new Error('This application already has a repository');
+        this._repository = repository;
+    }
+    _repository;
+    services = new Map();
+    factories = new Map();
+}

package/core/classes/package.d.ts

@@ -0,0 +1,219 @@
+import type { ResolvedConfig, RmanConfig } from '../../interfaces/rman-config.interface.js';
+import type { RmanApplication } from '../application.js';
+import { Manifest } from '../interfaces/manifest.js';
+import type { Platform } from '../interfaces/plugin.js';
+import type { Repository } from './repository.js';
+import { type VersionScheme } from './version-scheme.js';
+export declare class Package {
+    readonly dirname: string;
+    /**
+     * This package's identity, read through whichever `Plugin`'s manifest members recognizes its directory.
+     *
+     * There is no `json` here any more, and that is the point: `package.json` is npm's answer to
+     * "where is a package's name and version written", not rman's. `manifest.raw` is still the whole
+     * document for a command that knows its own ecosystem - the `node` built-in reads `scripts` and
+     * `publishConfig` off it - but the core only ever touches `name`, `version` and `private`.
+     */
+    manifest: Manifest;
+    /**
+     * In-repo packages this one depends on - **the full transitive closure**, not just its direct
+     * dependencies (see `Repository._updateDependencies`).
+     *
+     * References, not names: a name is only an identifier if the ecosystem guarantees uniqueness,
+     * which npm does and others do not - Go identifies a module by import path, and nothing stops a
+     * repository from holding two packages whose short names collide. A `Package` is unambiguous
+     * whatever the ecosystem, and comparing by identity removes a lookup from every consumer.
+     */
+    dependencies: Package[];
+    /**
+     * Effective rman config for this package, cascaded from the repository root, with every
+     * `${{ ... }}` expression already evaluated.
+     *
+     * **`ResolvedConfig`, not `RmanConfig`, and that is the whole two-view split in one line.**
+     * `RmanConfig` is what an *author* writes, where a value may be a function; this is what a
+     * *reader* gets, where it has already been called. Derived from the one the author writes, so
+     * there is no second type to keep in step - see `Resolved`.
+     */
+    config: ResolvedConfig;
+    /**
+     * The same config **before** interpolation - every `${{ ... }}` and every value function still as
+     * the author wrote it.
+     *
+     * `Workspace` produces this when it cascades the directory chain; `Repository` evaluates it into
+     * {@link config}. Read `config` unless you specifically want the unevaluated text.
+     */
+    rawConfig: RmanConfig;
+    /**
+     * The repository this package belongs to - so anything holding a package can reach the whole
+     * picture (its siblings, the root's config, git) without being handed it separately.
+     *
+     * Assigned by `Repository.create` rather than taken as a constructor argument, and it has to be:
+     * `Repository extends Package`, so a repository constructing itself runs this constructor before
+     * it exists to be passed in. A repository's own is itself.
+     *
+     * **Non-enumerable, and `declare` for the same reason `parent` is** - this is the *other* half of
+     * why a package could not be serialized, and the older half. A `Repository` holds every package,
+     * so one enumerable back-reference makes `JSON.stringify(anyPackage)` a cycle whatever the tree
+     * edges do: measured before `parent` was touched at all, and the error even named it
+     * (`property 'repository' closes the circle`). Making only `parent` non-enumerable would have
+     * delivered a tree that still cannot be dumped, which is the whole reason the asymmetry exists.
+     *
+     * It is the same rule `Repository.app`, `_repoScope` and `_git` already follow: a back-reference
+     * to something that holds everything has no business in a walk of one package.
+     */
+    repository: Repository;
+    /**
+     * The package whose directory contains this one - the repository root for an ordinary member, and
+     * a genuine enclosing package for one nested inside another (which `Repository.currentPackage`
+     * already has to reason about). `undefined` for the root itself, which nothing contains.
+     *
+     * **Non-enumerable, and `children` is not** - the two halves of one edge, and only one of them
+     * can be the one a walk follows. A tree is walked downwards, so `children` has to be visible and
+     * `parent` must not be, or a `toEqual` diff climbs back to the root and down again. Assigned
+     * through `defineProperty` by `Repository._linkPackages`, the same way `Repository.app` and
+     * `ORIGINS` travel.
+     *
+     * **`declare`, and that is load-bearing.** A plain `readonly parent?: Package` is a *class field*
+     * under this target, so TypeScript emits `parent;` and every package gets an **enumerable**
+     * `undefined` that the later `defineProperty` only replaces on the packages that have a parent.
+     * Measured: `Object.keys(rootPackage)` listed `parent` while `Object.keys(pkg-a)` did not, which
+     * is the exact opposite of what either name suggests. `declare` emits nothing, so the property
+     * exists only where it is defined.
+     *
+     * **It does not make a `Package` JSON-serializable, and nothing here claims it does** - see
+     * `repository`, which is enumerable and points back at an object holding every package.
+     */
+    readonly parent?: Package;
+    /**
+     * The packages whose directories sit directly inside this one - **the tree edge**, in the order
+     * the platform that claimed this directory gave them.
+     *
+     * This is the shape discovery actually has, and it used to be flattened away: a provider was
+     * asked once at the repository root and returned one list, so a package nested inside another was
+     * only reconstructible by comparing path prefixes (which `_linkPackages` and `currentPackage`
+     * both did, separately). `Workspace.walk` descends, so the containment is known as it is found -
+     * and `Repository.packages` is now this tree flattened rather than the other way round.
+     *
+     * Empty for a leaf, and for every package in an ordinary flat monorepo - where the root's
+     * `children` is the whole member list.
+     */
+    readonly children: Package[];
+    /**
+     * How this package's versions are numbered - `pkg.versionScheme.next(pkg.version, 'minor')`.
+     *
+     * Comes from the same provider that read the manifest, because the ecosystem that decides where
+     * a version is written is the one that decides how it is numbered - a `pyproject.toml` read with
+     * semver's arithmetic would be a pair that never occurs in reality.
+     *
+     * Defaults to semver, so this seam existing changes nothing. **A group must not mix schemes** -
+     * a group is one version line, and comparing across schemes is meaningless; `assertOneScheme`
+     * refuses it rather than acting on whatever falls out.
+     */
+    versionScheme: VersionScheme;
+    /** The file the manifest was read from, absolute - for a command that has to say which file it
+     *  changed (a commit's path list). Empty when no provider recognized this directory. */
+    manifestFileName: string;
+    /**
+     * **What addresses this package**: what a `.rmanrc "[glob]"` block and `--scope`/`--ignore` match
+     * against, and what must be unique within the repository.
+     *
+     * Three sources, first one that answers:
+     *
+     * 1. the package's own `.rmanrc "name"` - the repository assigning one;
+     * 2. its platform's `manifestProvider.selector`;
+     * 3. the manifest's own `name`, which is the default that answer falls back to.
+     *
+     * **Not `name`, and the split is the point.** `name` is what the package calls itself, read from
+     * its manifest, and it is an *ecosystem's* promise that such a thing exists and identifies the
+     * package - npm's promise, not rman's. Selectors matched `pkg.name` until this existed, so a
+     * repository whose technology has no name concept had packages it could not address at all, and
+     * one whose names are not unique (or are import paths) could only address them badly. They
+     * coincide for every Node repository, which is why nothing had to change for one.
+     *
+     * **The root's is nearly unused, deliberately.** A glob never matches the root and `"[/]"` needs
+     * no name - the root is addressed structurally, which is the whole reason it is `/`. It still has
+     * one so that nothing has to special-case it.
+     *
+     * Assigned by `Repository.create`, which is what has the config; a bare `new Package(dir, app)`
+     * gets the manifest's name, which is sources 2 and 3 with no config to consult.
+     */
+    selector: string;
+    /**
+     * **The technology this package belongs to** - the platform whose manifest provider claimed the
+     * directory, or `basePlatform` when none did.
+     *
+     * Per *package*, not per repository: the question is asked per directory, so a polyglot monorepo
+     * can hold a `node` package beside a `cargo` one and a command sweeping `getPackages()` can tell
+     * them apart. It is also what carries the rest of the technology's answers - where its binaries
+     * live, where its scripts come from, how its releases are planned - so anything that used to walk
+     * four separate registries asking "is this yours?" now asks the package it already has.
+     */
+    platform: Platform;
+    /**
+     * **Which ecosystem this package belongs to** - `'node'` for one the `node` built-in read. Empty when
+     * no stack claimed the directory.
+     *
+     * The escape hatch for code that legitimately knows one technology: `if (pkg.provider === 'node')`
+     * before reaching into `manifest.raw` for something only npm has.
+     *
+     * Not a union type on purpose: the set of ecosystems is whatever the repository's `plugins`
+     * contribute, so narrowing it here would mean the core listing plugins it cannot know about.
+     */
+    get provider(): string;
+    /**
+     * **Takes the application but does not keep it.** A package needs it once, to find out which
+     * technology claims its directory; afterwards it holds only data, so nothing that has a package
+     * can reach a service through it. Data down, behaviour up - the work belongs to services, and a
+     * piece of code holding only a package is not doing any.
+     *
+     * It also keeps the package out of every spread and serialization the application would
+     * otherwise be dragged into: `{...pkg}` and `pkg.manifest.raw` are both real, and an `app` field
+     * here would carry the whole world into them.
+     */
+    constructor(dirname: string, app: RmanApplication, 
+    /**
+     * The technology that claimed this directory, when the caller already knows - which
+     * `Repository.create` does, because the walk that found the directory is what established it.
+     *
+     * Optional so a bare `new Package(dir, app)` still works: that is what the fixtures build, and
+     * it is also the honest fallback for anyone constructing a package outside a walk. It costs one
+     * search of the registry (`app.platformFor`), which is what *every* construction used to do.
+     */
+    platform?: Platform);
+    /** What this package's **platform** says addresses it, before any config is consulted - the
+     *  manifest's own name when the platform has no opinion, and the directory when it has no name
+     *  either (which is unique among siblings and is all there is to go on). */
+    platformSelector(): string;
+    get basename(): string;
+    get name(): string;
+    get version(): string;
+    get isPrivate(): boolean;
+    /**
+     * Whether this is the repository's **own root package** - what `--scope /` and `.rmanrc`'s
+     * `"[/]"` both select.
+     *
+     * **By directory, and deliberately not by name or by identity.** The documented rule is that the
+     * root package is the one whose directory *is* the repository root, because a name can be
+     * anything - and identity (`this === repository.rootPackage`) is not equivalent either:
+     * `Repository extends Package` while holding a separate `rootPackage` instance for the same
+     * directory, so a comparison by reference answers `false` for one of the two objects that are
+     * both, truthfully, the root.
+     *
+     * `false` before `Repository.create` has assigned `repository` - a bare `new Package(dir, app)`
+     * (which the test fixtures build) belongs to no repository yet, so there is no root for it to be.
+     */
+    get isRoot(): boolean;
+    /**
+     * Re-reads from disk - for a command that has just written the manifest itself and wants the
+     * package to agree with the file again.
+     *
+     * Through **its own** technology's provider, like the constructor: the package already knows
+     * which platform claimed it, and a second opinion on a re-read was never wanted.
+     */
+    reloadManifest(): Manifest;
+    /** Writes the current manifest back through its provider. */
+    writeManifest(): void;
+    /** The three fields a manifest read sets, in one place - so construction and `reloadManifest`
+     *  cannot disagree about what "reading the manifest" means. */
+    private _readManifest;
+}

package/core/classes/package.js

@@ -0,0 +1,214 @@
+import path from 'path';
+import { Manifest } from '../interfaces/manifest.js';
+import { semverScheme } from './version-scheme.js';
+export class Package {
+    dirname;
+    /**
+     * This package's identity, read through whichever `Plugin`'s manifest members recognizes its directory.
+     *
+     * There is no `json` here any more, and that is the point: `package.json` is npm's answer to
+     * "where is a package's name and version written", not rman's. `manifest.raw` is still the whole
+     * document for a command that knows its own ecosystem - the `node` built-in reads `scripts` and
+     * `publishConfig` off it - but the core only ever touches `name`, `version` and `private`.
+     */
+    manifest;
+    /**
+     * In-repo packages this one depends on - **the full transitive closure**, not just its direct
+     * dependencies (see `Repository._updateDependencies`).
+     *
+     * References, not names: a name is only an identifier if the ecosystem guarantees uniqueness,
+     * which npm does and others do not - Go identifies a module by import path, and nothing stops a
+     * repository from holding two packages whose short names collide. A `Package` is unambiguous
+     * whatever the ecosystem, and comparing by identity removes a lookup from every consumer.
+     */
+    dependencies = [];
+    /**
+     * Effective rman config for this package, cascaded from the repository root, with every
+     * `${{ ... }}` expression already evaluated.
+     *
+     * **`ResolvedConfig`, not `RmanConfig`, and that is the whole two-view split in one line.**
+     * `RmanConfig` is what an *author* writes, where a value may be a function; this is what a
+     * *reader* gets, where it has already been called. Derived from the one the author writes, so
+     * there is no second type to keep in step - see `Resolved`.
+     */
+    config = {};
+    /**
+     * The same config **before** interpolation - every `${{ ... }}` and every value function still as
+     * the author wrote it.
+     *
+     * `Workspace` produces this when it cascades the directory chain; `Repository` evaluates it into
+     * {@link config}. Read `config` unless you specifically want the unevaluated text.
+     */
+    /* A second field rather than a stage of the first, because the two have different *types*:
+     * `config` is a `ResolvedConfig` by contract and is read in a hundred places, so putting a raw
+     * config there for the window between the cascade and the bake would make the type say something
+     * untrue everywhere.
+     *
+     * There was a `rawConfig` once before and it was removed as a duplicate - `version` kept one to
+     * re-read its own hooks, which `DEFERRED_PATHS` made unnecessary. This is not that: it is the
+     * handoff between two steps that genuinely produce different things. */
+    rawConfig = {};
+    /**
+     * The packages whose directories sit directly inside this one - **the tree edge**, in the order
+     * the platform that claimed this directory gave them.
+     *
+     * This is the shape discovery actually has, and it used to be flattened away: a provider was
+     * asked once at the repository root and returned one list, so a package nested inside another was
+     * only reconstructible by comparing path prefixes (which `_linkPackages` and `currentPackage`
+     * both did, separately). `Workspace.walk` descends, so the containment is known as it is found -
+     * and `Repository.packages` is now this tree flattened rather than the other way round.
+     *
+     * Empty for a leaf, and for every package in an ordinary flat monorepo - where the root's
+     * `children` is the whole member list.
+     */
+    children = [];
+    /**
+     * How this package's versions are numbered - `pkg.versionScheme.next(pkg.version, 'minor')`.
+     *
+     * Comes from the same provider that read the manifest, because the ecosystem that decides where
+     * a version is written is the one that decides how it is numbered - a `pyproject.toml` read with
+     * semver's arithmetic would be a pair that never occurs in reality.
+     *
+     * Defaults to semver, so this seam existing changes nothing. **A group must not mix schemes** -
+     * a group is one version line, and comparing across schemes is meaningless; `assertOneScheme`
+     * refuses it rather than acting on whatever falls out.
+     */
+    versionScheme = semverScheme;
+    /** The file the manifest was read from, absolute - for a command that has to say which file it
+     *  changed (a commit's path list). Empty when no provider recognized this directory. */
+    manifestFileName;
+    /**
+     * **What addresses this package**: what a `.rmanrc "[glob]"` block and `--scope`/`--ignore` match
+     * against, and what must be unique within the repository.
+     *
+     * Three sources, first one that answers:
+     *
+     * 1. the package's own `.rmanrc "name"` - the repository assigning one;
+     * 2. its platform's `manifestProvider.selector`;
+     * 3. the manifest's own `name`, which is the default that answer falls back to.
+     *
+     * **Not `name`, and the split is the point.** `name` is what the package calls itself, read from
+     * its manifest, and it is an *ecosystem's* promise that such a thing exists and identifies the
+     * package - npm's promise, not rman's. Selectors matched `pkg.name` until this existed, so a
+     * repository whose technology has no name concept had packages it could not address at all, and
+     * one whose names are not unique (or are import paths) could only address them badly. They
+     * coincide for every Node repository, which is why nothing had to change for one.
+     *
+     * **The root's is nearly unused, deliberately.** A glob never matches the root and `"[/]"` needs
+     * no name - the root is addressed structurally, which is the whole reason it is `/`. It still has
+     * one so that nothing has to special-case it.
+     *
+     * Assigned by `Repository.create`, which is what has the config; a bare `new Package(dir, app)`
+     * gets the manifest's name, which is sources 2 and 3 with no config to consult.
+     */
+    selector;
+    /**
+     * **The technology this package belongs to** - the platform whose manifest provider claimed the
+     * directory, or `basePlatform` when none did.
+     *
+     * Per *package*, not per repository: the question is asked per directory, so a polyglot monorepo
+     * can hold a `node` package beside a `cargo` one and a command sweeping `getPackages()` can tell
+     * them apart. It is also what carries the rest of the technology's answers - where its binaries
+     * live, where its scripts come from, how its releases are planned - so anything that used to walk
+     * four separate registries asking "is this yours?" now asks the package it already has.
+     */
+    platform;
+    /**
+     * **Which ecosystem this package belongs to** - `'node'` for one the `node` built-in read. Empty when
+     * no stack claimed the directory.
+     *
+     * The escape hatch for code that legitimately knows one technology: `if (pkg.provider === 'node')`
+     * before reaching into `manifest.raw` for something only npm has.
+     *
+     * Not a union type on purpose: the set of ecosystems is whatever the repository's `plugins`
+     * contribute, so narrowing it here would mean the core listing plugins it cannot know about.
+     */
+    get provider() {
+        return this.platform.name;
+    }
+    /**
+     * **Takes the application but does not keep it.** A package needs it once, to find out which
+     * technology claims its directory; afterwards it holds only data, so nothing that has a package
+     * can reach a service through it. Data down, behaviour up - the work belongs to services, and a
+     * piece of code holding only a package is not doing any.
+     *
+     * It also keeps the package out of every spread and serialization the application would
+     * otherwise be dragged into: `{...pkg}` and `pkg.manifest.raw` are both real, and an `app` field
+     * here would carry the whole world into them.
+     */
+    constructor(dirname, app, 
+    /**
+     * The technology that claimed this directory, when the caller already knows - which
+     * `Repository.create` does, because the walk that found the directory is what established it.
+     *
+     * Optional so a bare `new Package(dir, app)` still works: that is what the fixtures build, and
+     * it is also the honest fallback for anyone constructing a package outside a walk. It costs one
+     * search of the registry (`app.platformFor`), which is what *every* construction used to do.
+     */
+    platform) {
+        this.dirname = dirname;
+        this.platform = platform ?? app.platformFor(dirname);
+        this._readManifest();
+        this.selector = this.platformSelector();
+    }
+    /** What this package's **platform** says addresses it, before any config is consulted - the
+     *  manifest's own name when the platform has no opinion, and the directory when it has no name
+     *  either (which is unique among siblings and is all there is to go on). */
+    platformSelector() {
+        const asked = this.platform.manifestProvider.selector?.(this.manifest, this.dirname);
+        return asked || this.manifest.name || this.basename;
+    }
+    get basename() {
+        return path.basename(this.dirname);
+    }
+    get name() {
+        return this.manifest.name;
+    }
+    get version() {
+        return this.manifest.version;
+    }
+    get isPrivate() {
+        return !!this.manifest.private;
+    }
+    /**
+     * Whether this is the repository's **own root package** - what `--scope /` and `.rmanrc`'s
+     * `"[/]"` both select.
+     *
+     * **By directory, and deliberately not by name or by identity.** The documented rule is that the
+     * root package is the one whose directory *is* the repository root, because a name can be
+     * anything - and identity (`this === repository.rootPackage`) is not equivalent either:
+     * `Repository extends Package` while holding a separate `rootPackage` instance for the same
+     * directory, so a comparison by reference answers `false` for one of the two objects that are
+     * both, truthfully, the root.
+     *
+     * `false` before `Repository.create` has assigned `repository` - a bare `new Package(dir, app)`
+     * (which the test fixtures build) belongs to no repository yet, so there is no root for it to be.
+     */
+    get isRoot() {
+        const repository = this.repository;
+        return !!repository && path.resolve(this.dirname) === path.resolve(repository.dirname);
+    }
+    /**
+     * Re-reads from disk - for a command that has just written the manifest itself and wants the
+     * package to agree with the file again.
+     *
+     * Through **its own** technology's provider, like the constructor: the package already knows
+     * which platform claimed it, and a second opinion on a re-read was never wanted.
+     */
+    reloadManifest() {
+        this._readManifest();
+        return this.manifest;
+    }
+    /** Writes the current manifest back through its provider. */
+    writeManifest() {
+        this.platform.manifestProvider.write(this.dirname, this.manifest);
+    }
+    /** The three fields a manifest read sets, in one place - so construction and `reloadManifest`
+     *  cannot disagree about what "reading the manifest" means. */
+    _readManifest() {
+        const { manifest, versionScheme, fileName } = Manifest.read(this.platform, this.dirname);
+        this.manifest = manifest;
+        this.versionScheme = versionScheme;
+        this.manifestFileName = fileName ? path.join(this.dirname, fileName) : '';
+    }
+}

package/core/classes/registry.d.ts

@@ -0,0 +1,30 @@
+/**
+ * An ordered collection of contributions, held **on the application** rather than in a module.
+ *
+ * Every registry rman had was a module-level array (`const providers: Provider[] = []` in
+ * `manifest.ts`, `workspace.ts`, `bin-path.ts`, `run.service.ts`), which made it process-global:
+ * two repositories in one process shared it. The test suite needed a root hook emptying five of
+ * them before every single test, and without it whichever spec ran first decided the answer for
+ * the rest - so the core appeared to work in tests that had registered nothing.
+ *
+ * An instance per `RmanApplication` closes the whole class: a new application starts empty, and
+ * nothing has to be cleaned up afterwards - the root hook is deleted.
+ *
+ * **Registry, not service.** The distinction is multiplicity: a registry is for a question whose
+ * answer is the *sum* of what was contributed (every provider's bin directories, the first provider
+ * that recognizes a directory). A question with exactly one answer is a service, replaceable
+ * through `RmanApplication.getService`.
+ */
+export declare class Registry<T> implements Iterable<T> {
+    private readonly items;
+    /** Contributions in registration order, which for a plugin is `plugins` declaration order. */
+    get all(): readonly T[];
+    get size(): number;
+    /** Idempotent by identity: a plugin may both declare a contribution and register it itself, and
+     *  the same function arriving twice would make the registry lie about what is in it. */
+    add(item: T): this;
+    /** The first contribution `ask` gives an answer for - "first that recognizes it" resolution,
+     *  which is how a directory finds the manifest reader and the workspace layout that claim it. */
+    first<R>(ask: (item: T) => R | undefined): R | undefined;
+    [Symbol.iterator](): Iterator<T>;
+}